Optimiciti API

Optimiciti turns a real-world routing problem — vehicles, stops, time windows, capacities, and costs — into an optimized plan: who goes where, in what order, and at what time. This API gives you direct, programmatic access to the same solvers that power the Optimiciti app. It's a good fit for scheduling deliveries, field service, home visits, or any fleet that has to visit many places efficiently.

Beta. Endpoints and fields may still change. Using the API requires accepting our terms of service.

How it works

A real optimization can take longer than a single request should wait, so solving is asynchronous — you submit, then poll:

1. (Optional) Build a travel-cost matrix. POST /cost_matrix computes the distance and/or duration between every pair of your locations. Skip it if you already have your own travel costs.
2. Submit the problem. POST /problem with your locations, vehicles, and constraints. You get an id back right away (the response calls it run_id); the solver runs in the background.
3. Poll for status. GET /problem/{problemId} — the same id — or POST /run_status, until the run reaches a terminal state: succeeded, failed, or cancelled. A status response stays small: it carries status, progress, and any error — never the routes.
4. Fetch the results. Once the run is succeeded, get the optimized routes with POST /run_results_by_run_id. Results are a separate call on purpose — route payloads are large, and polling is frequent.

(problemId in the path and run_id in responses are the same identifier — the two names refer to one run.)

You can also save a scenario, list your past runs, and re-open results at any time — see the History section.

Authentication

Send your Clerk-issued JSON Web Token as a bearer credential on every request:

Code
Authorization: Bearer <token>

The token is verified on each call (signature, expiry, and issuer), and your identity is taken from the token — never from a value in the request body.

One thing that trips people up: api.optimiciti.com sits behind a gateway. A request that arrives with no Origin header — a curl call, a script, or any server-to-server request — must carry a gateway API key, and without one it gets a 401 on authenticated tiers. That's expected, not a broken token. Get access →

Requests and responses

Every response uses the same envelope. On success:

Code
{ "success": true, "data": { "...": "..." } }

On failure:

Code
{ "success": false, "error": { "code": "PLAN_LIMIT_EXCEEDED", "message": "A human-readable reason." } }

Branch on error.code (stable), not the message text (which may change).

Plans and limits

Your plan sets how large a problem can be, how many runs you can have in flight at once, and which premium features (such as road-network travel costs) you can use. See API access plans. When a request exceeds your plan, you get a 4xx with one of the codes below — each tells you exactly what to change or upgrade.

Common error codes

Transient 429, 502, 503, and 504 responses are safe to retry with backoff.

Links

• Optimiciti homepage
• API access plans
• Questions: [email protected]