REST API

Complete REST API reference for Sematryx. Use HTTP requests to interact with all optimization features and configure the AEAO Tetrad.

Base URL

https://api.sematryx.com/v1

All API endpoints are prefixed with /v1. Note: Some endpoints use paths like /optimization/instead of /optimize - refer to the endpoint table below for exact paths.

Authentication

Include your API key in the Authorization header for all requests:

Authorization header
Authorization: Bearer YOUR_API_KEY

Get your API key from the API Keys page.

Optimization Endpoints

Run Optimization

Upload your objective function first, then run optimization:

POST /v1/functions - Upload objective function
curl -X POST https://api.sematryx.com/v1/functions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "sphere",
    "code": "def sphere(x): return sum(xi**2 for xi in x)",
    "language": "python"
  }'
POST /v1/optimize - Run optimization
curl -X POST https://api.sematryx.com/v1/optimize \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "objective_function_id": "func_1234567890",
    "bounds": [[-5, 5], [-5, 5], [-5, 5]],
    "max_evaluations": 1000,
    "preset": "production"
  }'

Configure AEAO Tetrad

Enable tetrad pillars and configure intelligence features:

POST /v1/optimize - With Tetrad configuration
curl -X POST https://api.sematryx.com/v1/optimize \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "objective_function_id": "func_1234567890",
    "bounds": [[-5, 5], [-5, 5]],
    "max_evaluations": 1000,
    "tetrad_config": {
      "use_agentic_intelligence": true,
      "use_expository_intelligence": true,
      "use_autodidactic_intelligence": true,
      "explanation_level": 3
    }
  }'

Get Optimization Status

GET /v1/optimize/{id}
curl -X GET https://api.sematryx.com/v1/optimize/opt_1234567890 \
  -H "Authorization: Bearer YOUR_API_KEY"

List Optimizations

GET /v1/optimize
curl -X GET "https://api.sematryx.com/v1/optimize?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Domain-Specific Optimization

Use specialized endpoints for domain-specific problems:

POST /v1/domains/{domain}/optimize
curl -X POST https://api.sematryx.com/v1/domains/financial/optimize \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "problem_type": "portfolio",
    "config": {
      "assets": ["AAPL", "GOOGL", "MSFT"],
      "risk_tolerance": 0.15
    },
    "max_evaluations": 2000
  }'

Available Domains

  • financial - Portfolio optimization, trading strategies
  • healthcare - Drug discovery, clinical trials
  • supply_chain - Vehicle routing, inventory optimization
  • ai_ml - Hyperparameter tuning, architecture search
  • marketing - Campaign optimization, pricing

Response Format

Successful responses return JSON with optimization results:

Success response
{
  "id": "opt_1234567890",
  "status": "completed",
  "best_solution": [0.001, -0.002, 0.003],
  "best_fitness": 0.000014,
  "evaluations": 847,
  "duration_seconds": 2.34,
  "strategy_used": "shgo",
  "tetrad_config": {
    "use_agentic_intelligence": true,
    "use_expository_intelligence": true,
    "use_autodidactic_intelligence": false,
    "use_domain_extension": true
  },
  "features_active": {
    "agentic_intelligence": true,
    "expository_intelligence": true,
    "explanation_level": 2
  },
  "created_at": "2024-01-01T00:00:00Z",
  "completed_at": "2024-01-01T00:00:02Z"
}

Error responses include an error object:

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

API Endpoints Reference

Click on any endpoint to view detailed parameter information, request/response examples, and cURL commands.

Advanced

Analytics

Batch

Configuration

Context

Data Lake

Examples

Federated Learning

Health

Identity

Learning

Optimization

Request Parameters

Optimization Request

  • objective_function_id (required): ID of uploaded function
  • bounds (required): Search bounds [[min1, max1], [min2, max2], ...]
  • max_evaluations (optional): Maximum function evaluations (default: 1000)
  • preset (optional): Preset config ("development", "production", "research", "enterprise", "minimal")
  • tetrad_config (optional): Custom tetrad configuration object

Tetrad Configuration

  • use_agentic_intelligence (boolean): Enable multi-agent coordination
  • use_expository_intelligence (boolean): Enable explainability
  • use_autodidactic_intelligence (boolean): Enable self-improvement
  • use_domain_extension (boolean): Enable domain libraries
  • explanation_level (integer 0-5): Explanation detail level
  • use_gpu_acceleration (boolean): Enable GPU/CUDA
  • use_visual_intelligence (boolean): Enable visual analysis

HTTP Status Codes

200
OK

Request successful

201
Created

Resource created successfully

400
Bad Request

Invalid request parameters

401
Unauthorized

Invalid or missing API key

429
Too Many Requests

Rate limit exceeded

500
Internal Server Error

Server error - contact support

Rate Limiting

API requests are rate-limited. Check response headers for rate limit information:

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

Pagination

List endpoints support pagination with limit and offset parameters:

Pagination example
GET /v1/optimize?limit=20&offset=40