Making Requests

Learn how to make API requests to Sematryx, handle responses, and work with errors.

Base URL

All API requests should be made to the following base URL:

https://api.sematryx.com

The API uses versioned endpoints. The current version is v1.

Authentication

All API requests require authentication using a Bearer token in the Authorization header:

Authorization header format
Authorization: Bearer YOUR_API_KEY

You can obtain an API key from the API Keys page.

Request Format

Sematryx uses JSON for request and response bodies. All requests should include the Content-Type: application/json header.

Using cURL

Basic optimization request with cURL
curl -X POST https://api.sematryx.com/v1/optimize \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "objective_function": "sphere",
    "bounds": [[-5, 5], [-5, 5], [-5, 5]],
    "max_evaluations": 1000
  }'

Using Python

Python request example
import requests

url = "https://api.sematryx.com/v1/optimize"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "objective_function": "sphere",
    "bounds": [[-5, 5], [-5, 5], [-5, 5]],
    "max_evaluations": 1000
}

response = requests.post(url, json=data, headers=headers)
result = response.json()
print(result)

Using JavaScript/Node.js

JavaScript request example
const response = await fetch('https://api.sematryx.com/v1/optimize', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    objective_function: 'sphere',
    bounds: [[-5, 5], [-5, 5], [-5, 5]],
    max_evaluations: 1000
  })
})

const result = await response.json()
console.log(result)

Response Format

Successful API responses return JSON with the requested data. The structure varies by endpoint, but typically includes:

Example successful response
{
  "id": "opt_1234567890",
  "status": "completed",
  "best_solution": [0.001, -0.002, 0.003],
  "best_fitness": 0.000014,
  "evaluations": 1000,
  "strategy_used": "cma_es",
  "execution_time": 2.45,
  "created_at": "2024-01-01T00:00:00Z",
  "completed_at": "2024-01-01T00:00:02Z"
}

Response Fields

  • id: Unique identifier for the optimization job
  • status: Current status (pending, running, completed, failed)
  • best_solution: The best solution found
  • best_fitness: The fitness value of the best solution
  • evaluations: Number of function evaluations performed
  • strategy_used: Optimization algorithm that was selected
  • execution_time: Time taken in seconds

Error Handling

When an error occurs, the API returns an error response with appropriate HTTP status codes:

Example error response
{
  "error": {
    "code": "invalid_request",
    "message": "The 'bounds' parameter is required",
    "field": "bounds"
  }
}

HTTP Status Codes

  • 400 Bad Request: Invalid request parameters or malformed JSON
  • 401 Unauthorized: Missing or invalid API key
  • 403 Forbidden: API key doesn't have permission for this operation
  • 404 Not Found: Resource not found
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server error - contact support

Rate Limiting

API requests are rate-limited to ensure fair usage. Rate limits vary by plan:

  • Free Plan: 100 requests per hour
  • Pro Plan: 1,000 requests per hour
  • Enterprise Plan: 10,000+ requests per hour (custom limits)

Rate limit information is included in response headers:

Rate limit headers
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1640995200

Best Practices

✅ Do

  • Always include error handling in your code
  • Store API keys securely (environment variables, secrets management)
  • Use appropriate timeout values for long-running operations
  • Implement retry logic with exponential backoff for transient errors
  • Monitor rate limit headers to avoid hitting limits

❌ Don't

  • Commit API keys to version control
  • Make synchronous requests for long-running optimizations
  • Ignore error responses - always check status codes
  • Make unnecessary requests - use polling for status updates
  • Exceed rate limits without implementing backoff strategies