Skip to main content
Routal

Changelog

Notable changes to the Routal API and the developer portal. Subscribe to the RSS feed to track every release.

This is the running log of changes to the Routal API. Subscribe to the RSS feed to track every entry without coming back here.

The format is loosely Keep a Changelog. Entries are dated, grouped by type, and link to the relevant docs or endpoints. Breaking changes never ship on the current major — see Versioning below.

Versioning

Routal uses path-based versioning: the major version is the first segment after the host (/v2/, /v3/). The version you call is the contract you get — never silently upgraded under your feet.

Active versions

VersionStatusNotes
v2Stable — covers the full API surface used in production today.Default for every endpoint in the API Reference unless otherwise noted.
v3Selective — a small set of endpoints that re-shape v2 ergonomics (bulk creation, mostly).Track the entries below for additions.

What lives on v3 today

v3 endpointUse instead of
POST /v3/vehicles (create many vehicles in one call)Multiple calls to POST /v2/vehicle

Everything else is on v2. v2 is not deprecated.

What counts as a breaking change

These changes only ship in a new major version:

  • Removing or renaming a field in a response.
  • Tightening a constraint (e.g. an optional field becomes required).
  • Removing or renaming an enum value.
  • Removing an endpoint.
  • Changing an HTTP status code for an existing success path.
  • Changing the shape or signing scheme of webhook payloads.

These are not breaking and can ship at any time on the current major:

  • Adding a new optional request field.
  • Adding a new field to a response.
  • Adding a new endpoint.
  • Adding a new enum value (handle unknowns defensively — see Forward compatibility).
  • Adding a new webhook event type.
  • Changing the human-readable message text of an error (use message_id for branching — see Errors).

Forward compatibility

Even on the same major version, your code should:

  1. Ignore unknown response fields. Deserializers should not reject payloads with extra keys.
  2. Handle unknown enum values defensively. A webhook can carry type: "stop.something_new"; a stop status field can return a value you don't know yet. Treat unknown as "ignore" or "route to a dead-letter queue", not "throw".
  3. Dedup webhook deliveries using (event_id, data.id, data.updated_at) — the envelope doesn't carry a unique delivery ID today (Idempotency).
  4. Don't hard-code response order unless the endpoint guarantees it. Stops in a route are ordered by chain_position; other arrays are not guaranteed to keep their order between requests.

Deprecation — current status

Routal does not yet publish a formal deprecation timeline (notice period, sunset SLA, automatic 410 Gone responses). When an endpoint or field is going away we will:

  • Announce it in the changelog entries below before the change ships.
  • Mark it deprecated: true in the OpenAPI spec.
  • Email customers whose tenants have called the deprecated surface recently.

If your integration depends on a behaviour that isn't covered by the changelog or the OpenAPI spec, contact us — we'd rather extend the contract than have you build around undocumented quirks.

OpenAPI spec — the source of truth

The machine-readable spec covers both versions:

If you generate clients, point your codegen at this URL. The Routal backend also serves the same spec at https://api.routal.com/swagger.json (Swagger 2.0); the OpenAPI 3.0 version above is the recommended one for modern tooling.

2026-05-21 — Documentation accuracy pass

Changed

  • Authentication: aligned the documented API-key fields and format with what the API actually returns (label, active, created_at, keys prefixed api_key_). The single auth error code is highway.apiKey.error.not_found.
  • Errors: the machine-code table is now grouped by domain and lists only codes the API actually returns today. A handful of codes that had been documented without ever shipping are gone.
  • Rate limits: updated to the real cap — 2,000 requests per minute per credential, global. The previous per-method breakdown and Retry-After header claim were not accurate to what the platform exposes.
  • Webhooks: rewritten against the real delivery behaviour — envelope ({ created_at, project_id, event_id, meta, data }), event catalog (8 events with routal.<context>.2.<resource>.<action> naming), and failure handling (5 → owner email, 50 → auto-disable). The previous mention of HMAC signing, X-Routal-* headers, and a retry-schedule table was aspirational; none of that is implemented today.
  • Quickstart: corrected example responses against the real VehicleData / PlanResponseData schemas. project_id is required for both GET /v2/vehicles and POST /v2/plan.

Added

  • <EnumTable>, <SchemaFieldsTable>, <OperationQueryParams> — components that pull values straight from the OpenAPI spec at build time, so enums and defaults can never drift silently from /openapi.json.
  • A build-time drift check that fails CI if any prose claim no longer matches the spec — 27 claims tracked at launch.

2026-05-21 — Developer portal launch

Added

Changed

  • The recommended OpenAPI surface is now https://developers.routal.com/openapi.json (OpenAPI 3.0). The backend still serves Swagger 2.0 at https://api.routal.com/swagger.json, but tooling should consume the converted 3.0 version.

Subscribe

Reporting a regression

If a recent release broke your integration, email developers@routal.com with the endpoint, the request, and the response. Tag it [regression] in the subject line — those go to the on-call queue.

On this page

VersioningActive versionsWhat lives on v3 todayWhat counts as a breaking changeForward compatibilityDeprecation — current statusOpenAPI spec — the source of truth2026-05-21 — Documentation accuracy pass2026-05-21 — Developer portal launchSubscribeReporting a regression