REST API

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

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 Intelligence

Enable core pillars and configure intelligence features:

POST /v1/optimize - With Intelligence 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,
    "intelligence_config": {
      "use_agentic_intelligence": true,
      "use_interpretable_intelligence": true,
      "use_adaptive_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
conversational - Natural language problem creation

Conversational Optimization

Create optimization problems through natural language conversation with an AI agent. Perfect for users who want to optimize but aren't familiar with technical optimization concepts.

Start Conversation

POST /v1/domains/conversational/create

curl -X POST https://api.sematryx.com/v1/domains/conversational/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "I want to optimize my marketing budget across Google, Facebook, and LinkedIn to maximize ROI"
  }'

Get Conversation Status

Poll this endpoint to check if the agent has questions ready. Status will be "waiting_for_input" when a question is available.

GET /v1/domains/conversational/status/{conversation_id}

curl -X GET https://api.sematryx.com/v1/domains/conversational/status/conv_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Continue Conversation

Provide a response to the agent's question.

POST /v1/domains/conversational/continue/{conversation_id}

curl -X POST https://api.sematryx.com/v1/domains/conversational/continue/conv_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "response": "$50000"
  }'

Complete and Optimize

Once all parameters are collected (status is "ready_to_optimize"), complete the conversation and execute the optimization.

POST /v1/domains/conversational/complete/{conversation_id}

curl -X POST https://api.sematryx.com/v1/domains/conversational/complete/conv_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "max_evaluations": 2000,
    "mode": "balanced"
  }'

Learn more: See the Conversational Optimization guide for detailed examples and best practices.

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",
  "intelligence_config": {
    "use_agentic_intelligence": true,
    "use_interpretable_intelligence": true,
    "use_adaptive_intelligence": false,
    "use_domain_extension": true
  },
  "features_active": {
    "agentic_intelligence": true,
    "interpretable_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

ContextComing Soon

These endpoints are planned for a future release. Contact us if you need early access.

Conversational

Data LakeComing Soon

These endpoints are planned for a future release. Contact us if you need early access.

ExamplesComing Soon

These endpoints are planned for a future release. Contact us if you need early access.

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")
intelligence_config (optional): Custom intelligence configuration object

Intelligence Configuration

use_agentic_intelligence (boolean): Enable multi-agent coordination
use_interpretable_intelligence (boolean): Enable explainability
use_adaptive_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

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