Developer portal
POST /optimize
Submit a schedule, route, or staffing problem and receive a ranked plan with summary, metrics, and method details.
Summary
Submit a schedule, route, or staffing problem and receive a ranked plan with summary, metrics, and method details.
Rate limit: 120 requests per minute per API key (default)
Example
curl -X POST "https://sparkling-vibrancy-production-1a7a.up.railway.app/optimize" \
-H "Authorization: Bearer 811f31d4-5b8e-4ed0-a7a2-8176e05eba63" \
-H "Content-Type: application/json" \
-d '{
"type": "schedule",
"tasks": [
{
"id": "A",
"duration": 3
},
{
"id": "B",
"duration": 2
}
],
"constraints": [
"A must happen before B"
]
}'Try it live
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| type | string | Yes | Problem family: schedule, scheduling (alias), routing, or allocation. e.g. schedule |
| tasks[] | ScheduleTaskInput[] | No | Work items for scheduling problems. e.g. { "id": "A", "duration": 3, "crew": "Crew A" } |
| constraints[] | string[] | No | Hard rules the plan must satisfy (dependencies, blocked windows). e.g. "A must happen before B" |
| stops[] | RoutingStopInput[] | No | Stops for routing problems. e.g. { "id": "hospital", "serviceWindow": "08:30-10:00" } |
| vehicles[] | VehicleInput[] | No | Fleet units and capacity for routing. |
| shifts[] | ShiftInput[] | No | Shifts to cover for allocation problems. |
| staff[] | StaffInput[] | No | People, skills, and hour limits for allocation. |
| data | object | No | Extension bag for forward-compatible fields. e.g. {} |
Response
| Field | Type | Required | Description |
|---|---|---|---|
| status | "success" | Yes | Job completed with a feasible plan. |
| summary | string | Yes | Plain-English explanation for operators. |
| solution | array | object | Yes | Executable plan: task timeline, route assignments, or staffing grid. |
| metrics | object | Yes | constraintViolations, savingsEstimate, and problem-specific KPIs. |
| method | "classical" | "hybrid" | Yes | Honest solver path label. |
| details | object | Yes | solver, backend, and diagnostics for engineering review. |
| visualization | object | null | No | Optional UI-friendly timeline or grid payload. |
Errors
| Code | Meaning | Typical cause | Suggested fix |
|---|---|---|---|
| 401 | Unauthorized | Missing or invalid API key in Authorization or x-api-key header. | Send Bearer <key> or x-api-key with a valid pilot token. |
| 422 | Unprocessable entity | Invalid payload shape, unsupported problem type, or infeasible constraints. | Fix field errors in the response detail; relax constraints and retry. |
| 429 | Too many requests | Per-key rate limit exceeded (default 120 requests per minute). | Backoff with jitter; cache results; request a higher limit for production. |
| 500 | Internal server error | Unexpected backend failure. | Retry with exponential backoff; contact support if persistent. |
| 501 | Not implemented | Problem type not yet supported on the live solver path (routing, allocation). | Use type schedule for live jobs, or follow the roadmap for routing/allocation. |
See the full errors reference.
Related
Found an issue? Report documentation feedback