API reference
Developer docs
Read-only programmatic access to the routes you create in the dashboard. To try a live request and see the actual JSON your app will get back, open the playground.
Introduction
Single endpoint: GET https://discover.travories.com/api/v1/routes/{id}. Listing, search, create, update, and delete are dashboard-only — the public API is intentionally narrow.
Authentication
HTTP Basic auth. Username = your clientId (starts with cid_), password = your clientSecret (starts with sk_). Manage keys at /dashboard/api-keys.
IP allowlist
Each API key can be locked to one or more source IPs. If the key has an allowlist set and the request comes from a different IP, the response is 403 IP_NOT_ALLOWED even with valid credentials. Edit allowlists from the API keys page. Leave the field blank to allow any IP.
Rate limits
Quota is shared across all your API keys per company — creating more keys does NOT increase your cap. Sliding window, per minute:
- Free — 100 requests/minute total
- Premium — 500 requests/minute total (5× the free quota)
Every response carries:
X-RateLimit-Limit/-Remaining/-Reset/-Tier- On 429:
Retry-After(seconds)
CORS
GET /routes/{id} accepts cross-origin requests (Access-Control-Allow-Origin: *, preflight allows the Authorization header). The dashboard surface (/api/dashboard/*) is session-cookie protected and does NOT enable CORS.
Errors
Errors come back with a { error: { code, message, details? } } envelope and the appropriate HTTP status:
| Status | Code | When |
|---|---|---|
| 400 | VALIDATION_ERROR | Body or query failed parsing — `details` carries field errors |
| 401 | UNAUTHORIZED | Missing or invalid Basic auth credentials |
| 403 | IP_NOT_ALLOWED | Credentials valid, but request IP not on this key's allowlist |
| 404 | NOT_FOUND | Route does not exist or belongs to a different company |
| 422 | NO_ROUTE_FOUND | Mapbox could not connect the given waypoints |
| 429 | RATE_LIMITED | Over your quota for this minute (100 free / 500 premium) |
| 500 | INTERNAL_ERROR | Unexpected server error — retry with backoff |
Get a route
GET/routes/{id}
Returns the route's name, mode, distance, duration, the GeoJSON geometry (a FeatureCollection for segmented routes, or a single Feature for legacy ones), and per-segment metadata when present.
Try it live in the playground — pick one of your routes, click Run, see the actual JSON.
Embed in your site
Each route can be embedded as an iframe on any external page. No API key is needed — the URL carries a signed long-lived token tied to that specific route. Generate the embed URL via the Embed button on the route detail page; the dialog gives you the URL, a ready-to-paste iframe snippet, and a live preview. Tokens expire after 365 days.
Zoom parameter: append &zoom=N to the embed URL to override the auto-fit zoom. N=100 is the default fit; values below 100 zoom out (e.g. 50 ≈ one level further away), values above 100 zoom in (200 ≈ one level closer). The math is log2(N/100) as a zoom offset on top of the auto-fit. The Embed dialog has a Zoom field that bakes the value into the copied URL/iframe automatically.