Lumail versions the REST API with a major version in the URL path: `/api/v1` and `/api/v2`. The same `lum_` Bearer token works on both.

## Current versions

| Version  | Status | Use it for                                                                 |
| -------- | ------ | -------------------------------------------------------------------------- |
| `/api/v2` | Active | Every new integration. See [API v2](/docs/api-reference/v2).               |
| `/api/v1` | Frozen | Existing integrations only. No new features, no scheduled sunset date yet. |

To move an existing integration, follow [Migration to V2](/docs/api-reference/v2/migration).

## What can change inside a version

Inside a major version, Lumail only ships additive changes:

- new endpoints
- new optional request fields
- new response fields
- new error codes documented in the [OpenAPI specification](https://lumail.io/openapi.json)

Clients should ignore unknown response fields. Removing or renaming a field, changing a type, or making an optional field required only happens in a new major version.

## How deprecation and sunset are announced

Before a version or an endpoint is retired, Lumail:

1. Announces the deprecation and the retirement date in the [changelog](/changelog) and on this page.
2. Returns a `Deprecation` header ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)) on every response from the deprecated surface, with a `Link` to this policy (`rel="deprecation"`).
3. Adds a `Sunset` header ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)) with the retirement date once it is scheduled.

Monitor these headers in your client to detect deprecations automatically. `/api/v1` does not return them today because it has no retirement date.

## Related

- [API limits](/docs/api-reference/api-limits): rate-limit headers and `Retry-After`
- [MCP server](/docs/api-reference/mcp): the MCP tools follow the same API surface