Quickstart

This guide covers issuing a credential, making an authenticated request, and interpreting the response.

1. Obtain a key

The Open Platform must be enabled on the account by a Superroute administrator. Once enabled, keys are created in the client portal. Every key is a production key, prefixed sr_live_ so a disclosed credential is identifiable on sight.

The secret is displayed once, at the moment the key is created, and cannot be retrieved afterwards. This secret is the API token. If it is lost, the key must be rotated.

2. Issue a request

Requests are authenticated with a single header:

curl -sS https://open.superroute.ca/v1/geo/forward \
  -H "Authorization: Bearer $OPEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"address1":"4200 Rue Sainte-Catherine O","city":"Montreal","country":"CA"}'

No timestamp, nonce or request signature is required.

3. Interpret the response

{
  "request_id": "req_01J8Q…",
  "capability": "geo.forward",
  "billing": { "unit": "point", "quantity": 1, "counted": true },
  "data": { "matched": true, "lat": 45.4972159, "lng": -73.578668, "…": "…" }
}

billing is present on every billable response so that a period's charges can be reconciled from client-side logs independently of the invoice.

request_id is present on every response, successful or not. It identifies the redacted diagnostic record retained for the call and should be quoted in support requests.

4. Next steps

Route optimization — POST /v1/routing/optimize. Problems above a small size return 202 with a job reference; see Asynchronous solves and webhooks.
Alternative transports — GraphQL and MCP expose the same capabilities under the same billing and the same credentials.
Entitlement discovery — GET /v1/capabilities reports, for the presented key, which capabilities are enabled, which are not, and the reason in each case.

5. Vehicle profiles

Routing, directions, distance matrix and plan re-costing accept an optional profile that sets the vehicle the roads are costed for:

`profile`	Costing
`car` (default)	Car
`van`	Car
`truck`	Truck
`motorcycle`	Motorcycle
`bike`	Bicycle
`foot`	Pedestrian

truck, motorcycle, bike and foot use the road costing for that vehicle. A motorcycle avoids roads motorcycles may not use, and toll and highway avoidance applies where the road data carries those options. Road preferences (for example avoiding tolls or highways) are not exposed by the Open Platform today, so each profile's defaults apply.

6. Routing rules

Optimize, refine and what-if accept optional routing rules in your own terms: coordinates, ISO-8601 times with an offset, and your own ids.

Per job or shipment: release_at, group, goods_class, alternatives (other places a job may be served at), and max_ride_seconds on a shipment.
Per vehicle: latest_departure_at, ev_range_meters and ev_reserve_meters, shifts, and skip_policy and places on a break.
Per request, under constraints: incompatible_goods_classes, deliveries_before_pickups, waiting_cost, use_all_vehicles, merge_stops and reload.

Not every engine plans every rule. A rule the chosen engine cannot plan is refused with VALIDATION_FAILED before anything is solved or billed; the detail code is UNSUPPORTED, or UNSUPPORTED_ENGINE_VERSION when the engine is older than the rule. A rule the engine only approximates is accepted with a RULE_APPROXIMATED warning and an entry in meta.rule_notices, on optimize only. GET /v1/routing/presets and each routing capability page list, per engine, which rules are native, approximated or not supported, and from which engine version. A request without these fields behaves exactly as before.