# Nextstep API — Versioning and deprecation policy

The Nextstep job tracker public API uses major versions in URL paths. Version 1 is available at /api/v1/capabilities, /api/v1/stages, /api/v1/sandbox/applications and /api/v1/health. Responses include API-Version: 1. The OpenAPI document version describes the contract release; it is distinct from the major version in the URL.

## Compatibility and existing clients

The existing /api/public/capabilities, /api/public/stages, /api/public/sandbox/applications and /api/health URLs remain supported aliases for version 1 without redirects. They share the same quota. New clients should use /api/v1/. Additive response fields and new endpoints may arrive within a major version; clients should tolerate unknown fields. Removing fields, changing field types or changing the meaning of an operation requires a new major URL version such as /api/v2/.

## Retirement notice

No public API version or legacy alias currently has a scheduled retirement. Before retiring one, Nextstep will publish a migration guide and provide at least 180 days of notice. Affected responses will carry Deprecation as an RFC 9745 Structured Field Date (an @ followed by Unix seconds), Sunset as an RFC 8594 HTTP-date, and a Link with rel="deprecation" pointing to that guide. Deprecation marks the start of the notice period; Sunset marks the planned retirement. These headers are omitted while no retirement is scheduled. Agents should record notices and migrate before Sunset rather than waiting for failures.

- [API reference](https://nextstep.fans/docs): Current endpoints and schemas
- [Errors and limits](https://nextstep.fans/docs/errors): Handling temporary failures
- [Contact Nextstep](https://nextstep.fans/contact): Integration and migration questions