> ## Documentation Index > Fetch the complete documentation index at: https://docs.alterscope.org/llms.txt > Use this file to discover all available pages before exploring further. # Versioning Policy > How the Alterscope Developer API signals breaking changes, deprecations, and stability stages. This page documents how the Alterscope Developer API signals breaking changes, deprecations, and stability stages. ## SemVer at two levels The API uses semantic versioning at two distinct levels. **Path-level major version** lives in the URL: `/v2/` today, future `/v3/`. A new path-level major ships only when a breaking change is unavoidable. **Envelope schema version** lives at `meta._agentic.schema_version` on every `/v2/*` response and is mirrored by the `X-Schema-Version` response header. The current value is `1.0.0`. Patch and minor bumps ship in place; a major bump on `schema_version` always coincides with a new path-level major (for example `/v3/`). | Level | Today | Bumps when | | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------- | | Path major | `/v2` | Removing a field, narrowing an enum, changing a type, tightening request validation, removing an endpoint. | | Envelope minor | `1.0.0` | Adding an optional field, a new `_links` entry, a looser validation rule, a new error code in an existing category. | | Envelope patch | `1.0.0` | A bug fix that does not change response shape. | ## Stability stages | Stage | Path prefix | Stability | SLA coverage | | ----------- | ---------------------- | ------------------------------------------------------------------------------------------- | -------------------------------- | | Stable (GA) | `/v2//` | Subject to the breaking-change policy below. | Yes, per [SLA](/operations/sla). | | Beta | `/v2/beta//` | Schema may change without notice. Promoted to stable after roughly 90 days of customer use. | No. Excluded by design. | Beta endpoints are clearly labeled in the [OpenAPI reference](/api-reference). Promotion to stable always ships as `### Added`, never as a breaking change. ## What is breaking and what is not ### Breaking These changes require a new path-level major version (for example `/v3/`) and a deprecation window on the old version: * Removing a field from a response. * Changing a field's type or unit (for example seconds to milliseconds). * Narrowing an enum (removing a value). * Tightening request validation in a way that previously valid requests would be rejected. * Removing an endpoint. * Changing authentication or authorization requirements on an existing endpoint (for example requiring a higher tier). * Changing default sort order, default page size, or pagination semantics. * Renaming a query parameter. * Changing the format of an existing header (for example `X-RateLimit-Reset` from epoch seconds to RFC 1123 date). ### Non-breaking These ship under the same path-level major: * Adding an optional response field. * Adding a new endpoint. * Adding an optional query parameter. * Loosening request validation. * Adding a new error code within an existing error category, with a new `code` value but the same HTTP status class. * Adding entries to `meta._agentic._links`. * Adding new response headers. Clients are expected to ignore unknown headers. * Adding new enum values. Clients are expected to handle unknown enum values gracefully; this is documented per-field. ## Deprecation window A breaking change carries a **180-day** (approximately 6-month) deprecation window before the old endpoint is removed. Five steps: 1. **Announce.** A changelog entry under `### Deprecated` with a `Sunset` date at least 180 days in the future. 2. **Header roll-out.** Every response on the affected endpoint emits the RFC 8594 header triple: ``` Deprecation: true Sunset: Link: https://docs.alterscope.org/changelog#; rel="deprecation" ``` `Deprecation: true` flags the response as deprecated. `Sunset:` carries the removal date in RFC 1123 format. `Link:` with `rel="deprecation"` points to the changelog anchor where the migration is documented. 3. **SDK signal.** Every response on a deprecated endpoint carries the RFC 8594 `Deprecation` / `Sunset` / `Link` header triple — inspect them in your client to detect deprecation. In the TypeScript and Python SDKs, the corresponding request methods and types are marked `@deprecated`, so editors and compilers surface the hint at build time. 4. **Direct contact.** Customers whose API keys hit the deprecated endpoint in the prior 30 days receive an email the day announcement ships and again 30 days before sunset. 5. **Removal.** On the sunset date the endpoint returns `410 Gone` with a body of the form: ```json theme={null} { "error": "endpoint_removed", "removed_at": "", "replacement": "/v2/", "changelog": "https://docs.alterscope.org/changelog#" } ``` The worked example of a path-level major deprecation is the v1 to v2 migration. ## What is not promised To keep the policy honest: * **No fixed release cadence.** Work ships when ready, not on a calendar. * **No zero-breaking-change guarantee below major.** Security fixes may force a faster path. Security fixes ship without the 180-day window and are announced retroactively under `### Security`. * **Experimental fields under `meta._agentic.experimental.*` are not stable.** They may move, rename, or disappear without a sunset clock. They exist so the team can preview shape changes in production traffic before committing to them. * **Infrastructure-level identifiers (request IDs, trace IDs, internal cache keys) are not stable.** Treat them as opaque. ## Envelope rollout in progress The envelope shape (`{data, meta, error}` with `meta._agentic`) is the contract this policy defends. The rollout across the API is in progress: a subset of `/v2/*` endpoints emit the full `_agentic` extension, and the rest emit the base `{data, meta, error}` envelope. Both shapes are valid under this policy. ## Cross-references * [Changelog](/changelog) * [Service Level Agreement](/operations/sla) * [API Reference](/api-reference/overview)