External API overview

The Routerra Teams External API is a JSON REST API over your team's plans, stops, drivers and delivery data — the same engine the dashboard runs on, driven by your code instead of the UI.

One contract serves both kinds of integration. Direct calls from a CRM, a WMS or a nightly script use the REST endpoints. AI assistants use the MCP connector, and almost every MCP tool is a thin wrapper over one of those same endpoints; the handful of real differences are listed in MCP connector. You also don't have to poll for delivery progress — webhooks push plan, route and stop changes to you as they happen.

The facts

A key belongs to exactly one team and every response is scoped to it. Another team's plans, drivers and addresses answer 404, as if they did not exist.

Your first request

Create a key in the dashboard under Settings → Developer → API keys — see API keys — then call GET /team:

curl -H "X-API-Key: rtk_…" \
  https://teams-api.routerra.io/api/v1/external/team

This is the call to start every integration with. It returns everything you need before a plan can be built: the drivers with the coordinates the solver will actually start and finish from, your depots and zones, the team's routing defaults, and how much of today's optimization quota is left.

{
"team": { "id": 87, "name": "Hudson Bakery Supply" },
"timezone": "America/New_York",
"defaults": { "serviceTimeSeconds": 300, "stopSide": "ANY", "stopLimit": 200 },
"optimizationQuota": { "capacity": 34, "available": 26, "availableForApi": 14 },
"depots": [ { "id": 12, "name": "Greenpoint Depot", "latitude": 40.7297, "longitude": -73.9542 } ],
"zones": [ { "id": 3, "name": "East", "driverIds": [91, 93] } ],
"drivers": [ { "id": 91, "name": "Maya R.", "vehicleType": "VAN", "zoneIds": [3] } ]
}

The full response, field by field, is in Team, driver & analytics endpoints.

The shape of an integration

Most integrations are the same four moves, and they follow the plan's two-step lifecycle: dispatch computes routes that only your office sees, approve sends them to drivers.

• Create and optimize. POST /optimize takes your stops and answers 202 — the plan goes to DISPATCHING_IN_PROGRESS. See Plan endpoints.
• Poll for the result. GET /plans/{planId} until the status leaves DISPATCHING_IN_PROGRESS, usually 5 to 30 seconds later. See Plan lifecycle & statuses.
• Approve. POST /plans/{planId}/approve puts the routes in the driver app. See Plan operation endpoints.
• Follow the day. Webhooks for push, GET /statistics for the summary.

Every mutating call in that loop accepts a clientRequestId, so a timeout can be retried without dispatching twice — see Idempotent API requests.

REST and MCP are the same API

The MCP connector takes the same key, reads the same data and enforces the same rules. It is a sessionless Streamable HTTP server: each tool call is a self-contained JSON-RPC POST, with no handshake to keep alive. Eighteen tools cover the endpoint surface, and a tool's answer is the endpoint's own JSON.

Two differences are worth knowing before you choose a transport:

• A key without the dispatch scope doesn't get a 403 on MCP. The call is queued as a proposal for a dispatcher to apply — see Proposed changes.
• The five-token optimize rate-limit tier is bound to REST URIs, but MCP does not escape it: the tools that start an optimization take a token from it by hand, on top of the general-tier token the URI filter already charged. The daily optimization quota is spent identically on both — see API limits & quotas.

The reference

Before you call anything

• API keys — create, disable and revoke keys in the dashboard
• API authentication & scopes — how a key authenticates, and what read, write and dispatch each unlock
• API limits & quotas — the four independent limiters, all of them 429
• Idempotent API requests — clientRequestId and safe retries
• API error reference — every error code, plus the date, time and unit conventions
• Plan lifecycle & statuses — the state machine you are integrating against

Endpoints

• Team, driver & analytics endpoints — /team, /drivers, /address-book, /statistics
• Plan endpoints — /optimize, listing, reading, cancelling and duplicating plans
• Plan operation endpoints — stops, dispatch, approve, revoke, preview
• Proposed changes — queueing a dispatch-class operation for a human to apply

Connectors and events

• MCP connector — the endpoint, the eighteen tools, and every REST difference
• Webhooks — plan, route and stop events pushed to your endpoint

Lookup

• Response objects & enums — shared object shapes, enum values, known limits and what changed

If you arrived here from the old Optimize API reference, its content now lives in Plan endpoints.