# brapi.dev API versioning and deprecation policy

## Versioning

Use `/api/v2` endpoints for new integrations. Legacy routes remain available during the published compatibility window.

The API uses URL versioning. Each version keeps its response contract stable during its support window.

## Deprecation signals

When brapi.dev deprecates a route, the response includes these HTTP headers:

- `Deprecation: true`
- `Sunset: <HTTP-date>`
- `Link: <https://brapi.dev/docs/versioning>; rel="deprecation"`

The `Sunset` value gives the planned removal date. Clients should migrate before that date.

## Client procedure

1. Prefer the current `/api/v2` endpoint.
2. Read `Deprecation`, `Sunset`, and the deprecation `Link` header.
3. Migrate before the announced sunset date.
4. Contact `contato@brapi.dev` if the replacement endpoint is unclear.