> ## Documentation Index
> Fetch the complete documentation index at: https://docs.solvice.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning and deprecation

> How the V3 Routing API is versioned, what counts as a breaking change, and how deprecations are announced.

> [!NOTE]
>
> **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](#changes) table starts at GA; changes made during the beta are in the
[Changelog](https://docs.solvice.io/changelog/vrp-v3.md).

## 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 `code`s.
  Authentication and rate-limit errors come from the gateway in its own shape (see
  [Authentication](https://docs.solvice.io/guides/platform/authentication.md)).
* 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

| Can ship inside `/v3` at any time | Waits for a new major |
| - | - |
| A new endpoint | Removing or renaming a field, endpoint or enum value |
| A new optional request field whose absence keeps today's behaviour | Making an optional field required |
| A new response field | Changing a field's type, unit or meaning |
| A new value in a response code or type (see below) | Changing a default |
| A new request enum value | Rejecting input that used to be accepted |
| Accepting input that used to be a 400 | Lowering a limit |
| Raising a limit | Returning a different HTTP status for the same case |

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):

```http theme={null}
Deprecation: @1798761600
Link: <https://docs.solvice.io/guides/vrp/v3/versioning>; rel="deprecation"
```

`Deprecation` ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)) 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](https://www.rfc-editor.org/rfc/rfc8594)), the date after which it is no longer
served (example values):

```http theme={null}
Deprecation: @1798761600
Sunset: Sat, 01 Jan 2028 00:00:00 GMT
Link: <https://docs.solvice.io/guides/vrp/v3/versioning>; rel="sunset"
```

## V2

`/v2/vrp/...` predates this policy. Its retirement schedule is announced to V2 accounts separately;
see [Migration from V2](https://docs.solvice.io/guides/vrp/v3/migration-from-v2.md).

## Changes

| Date | Change | Kind |
| - | - | - |
| | None yet: V3 is in beta. | |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.