Optimize API reference

The Optimize API lets your own systems run the same optimization engine the web app uses: send stops and a driver selection, get back optimized routes. It's three endpoints — one to submit work, one to poll for the result, one to look up your drivers.

All requests go to the production base URL:

https://teams-api.routerra.io/api/v1

Authentication

Every request needs an API key in the X-API-Key header. Keys start with rtk_ and are created under Settings → Developer → API keys — see API keys for the create/revoke flow. A key is scoped to the team that created it: every plan, stop, and driver you touch through the API belongs to that team.

curl "https://teams-api.routerra.io/api/v1/external/drivers" \
  -H "X-API-Key: rtk_your_key_here"

A missing header fails with 401 {"code": "invalid_api_key", "message": "Missing X-API-Key header"}; a wrong, disabled, or expired key fails with the same code and "Invalid, disabled, or expired API key."

The endpoints

POST /external/optimize

One call does the whole job: it creates a plan, adds your stops to it, and starts optimization across the drivers you selected. Optimization runs asynchronously — the response comes back immediately with a planId you poll.

curl -X POST "https://teams-api.routerra.io/api/v1/external/optimize" \
  -H "X-API-Key: rtk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tuesday deliveries",
    "date": "2026-07-28",
    "stops": [
      {
        "name": "Customer A",
        "address": "123 Main St, Chicago, IL",
        "latitude": 41.8781,
        "longitude": -87.6298
      },
      {
        "name": "Customer B",
        "address": "456 Oak Ave, Chicago, IL",
        "latitude": 41.92,
        "longitude": -87.65,
        "serviceTime": 600,
        "arrivalRangeFrom": "09:00",
        "arrivalRangeTo": "12:00",
        "metadata": { "orderId": "ORD-123" }
      }
    ],
    "driverIds": [101, 102],
    "strategy": "BALANCED_MIX"
  }'

Request fields

Stop fields

Distribution strategies

The same four strategies as the Assign drivers & optimize dialog — see Optimize routes for when to pick which:

Response — 202 Accepted

{
  "planId": 4567,
  "status": "DISPATCHING_IN_PROGRESS",
  "stopsCount": 2,
  "createdAt": "2026-07-28T08:30:00Z"
}

GET /external/plans/{planId}

Poll this endpoint until status leaves DISPATCHING_IN_PROGRESS. While optimization is running you get the plan header only; once it finishes, the response includes every route with its stops in visit order.

curl "https://teams-api.routerra.io/api/v1/external/plans/4567" \
  -H "X-API-Key: rtk_your_key_here"

Fields that are null are omitted from the response entirely.

Plan fields

Plan statuses

Route fields

A Location is { "address", "latitude", "longitude" }.

Stop fields (response)

Stop error types

When the optimizer can't fit a stop, it lands in unassignedStops with one of:

GET /external/drivers

Lists all drivers in your team, with the IDs you pass as driverIds when optimizing. Drivers themselves are managed in the web app — see Manage drivers.

curl "https://teams-api.routerra.io/api/v1/external/drivers" \
  -H "X-API-Key: rtk_your_key_here"

[
  {
    "id": 101,
    "name": "John Smith",
    "vehicleType": "VAN",
    "vehicleCapacity": 100,
    "maxStops": 30,
    "shiftStartTime": "08:00",
    "shiftEndTime": "17:00",
    "startLocation": {
      "address": "456 Depot Rd, Chicago, IL",
      "latitude": 41.85,
      "longitude": -87.65
    },
    "liveRoadData": true,
    "avoidTolls": false,
    "avoidHighways": false
  }
]

As everywhere in the API, null fields are omitted — a driver without a shift simply has no shiftStartTime.

Errors

Every error is JSON with a code and a human-readable message:

{ "code": "validation_error", "message": "stops[0].name: must not be blank" }

Validation failures list each offending field in the message, separated by semicolons.

Limits

Two per-team limits apply, both checked before any work starts:

• Optimization runs per day — each successful POST /external/optimize consumes one run from the same daily quota the web app uses (default 30 per day). A run whose optimization fails is refunded. Exceeding it returns 429 too_many_requests.
• Stops per plan — one plan holds at most your team's stop limit (default 200 stops). Exceeding it returns 409 stop_limit_exceeded.

What's next

• API keys — create and manage the keys this API authenticates with
• Webhooks — get pushed a signed event when routes start, complete, or fail instead of polling
• Optimize routes — what the optimizer respects, in product terms