Skip to main content
V3 is in beta. General availability (GA) is planned for January 2027.

​
Status

V3 is in beta. Until the GA date published on this page it can change in breaking ways. GA date: 1 January 2027. The Changes table starts at GA; changes made during the beta are in the Changelog.

​
The version is in the path

The major version is the first path segment: /v3/routing/solve. There is no version header and no date-pinned version. After GA a breaking change ships only in a new major (/v4/...), never inside /v3.

​
What the contract covers

  • Every operation in the published OpenAPI document (today POST /v3/routing/solve, /evaluate and /suggest), with its request and response schemas.
  • HTTP statuses and, in the routing service’s error body, the status, code and error item codes. Authentication and rate-limit errors come from the gateway in its own shape (see Authentication).
  • Documented headers: X-Request-Id, Retry-After, Deprecation, Sunset.
  • Documented defaults and limits.
Not covered: the plan the solver finds (routes, order and cost can differ between releases, like any search result), message texts, field order and whitespace, response times, and undocumented routes.

​
After GA: additive changes only

A rename inside a major adds the new name and keeps the old one working as a deprecated alias. Two exceptions ship at any time and are listed under Changes: security fixes, and bugs where the service does not do what these docs say (the documented behaviour wins).

​
What your client must do

  • Ignore response fields it does not know.
  • Accept unknown values in every response code or type, including stop type (route stops and suggestions), violation and reason code, reason constraint, unassigned category, suggest reason.code, relaxation op and unit (also a violation’s unit), cost components keys, warnings[].code (also on a validate response), and the error status, code and error item code. Branch on the HTTP status first, then on the codes you handle; treat the rest generically.
  • If you generate a client from the OpenAPI document: the response codes above are published as open sets, a type: string whose known values are listed in its description and in x-extensible-enum, so generated clients read them as strings and accept a new value. Request enums are closed. Still configure the generator to accept unknown properties, and unknown values wherever it still builds a closed enum (for example openapi-generator’s enumUnknownDefaultCase=true): the listed values are those at publication time. The plan in a solve response reuses the request’s Plan schema, whose additionalProperties: false applies to requests only.
  • Never parse message.
  • Send only documented request fields. Requests are strict: an unknown field is a 400 invalid_request with an unknown_field error item.

​
Deprecation

A deprecated field or endpoint keeps working until its major is retired. It is marked deprecated: true in the OpenAPI document and listed under Changes. Responses from a deprecated endpoint carry (example values):
Deprecation (RFC 9745) is the moment of deprecation in Unix seconds.

​
Retiring a major version

When a new major reaches GA, the previous one is deprecated and stays served for at least 12 months. From that day every response of the retiring major carries Deprecation and Sunset (RFC 8594), the date after which it is no longer served (example values):

​
V2

/v2/vrp/... predates this policy. Its retirement schedule is announced to V2 accounts separately; see Migration from V2.

​
Changes