Versioning Policy

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.

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/).

​

Stability stages

Beta endpoints are clearly labeled in the OpenAPI 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: <RFC 1123 date>
   Link: https://docs.alterscope.org/changelog#<anchor>; 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:
   {
     "error": "endpoint_removed",
     "removed_at": "<RFC 3339 date>",
     "replacement": "/v2/<replacement-path>",
     "changelog": "https://docs.alterscope.org/changelog#<anchor>"
   }
   

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
• Service Level Agreement
• API Reference