> ## Documentation Index
> Fetch the complete documentation index at: https://puzzlet-9ba7bb98.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# API versioning & stability

> How the AgentMark Gateway API versions itself, what counts as a breaking change, and how AgentMark communicates deprecations.

## Current version

The AgentMark Gateway API is **v1**. Every endpoint carries the `/v1/` prefix (except `GET /health`, which is unversioned). The current version remains available as `/v1/*` for the foreseeable future.

## Versioning strategy

AgentMark releases breaking changes under a **new path prefix**. When a future `/v2/` arrives, `/v1/` continues to work in parallel. You upgrade when you're ready, not when a new version ships.

This matches how Stripe, Twilio, and most mature public APIs version their endpoints. A path-based scheme is visible in every request, trivial to grep for in consumer code, and easy to pin in configuration.

## What's non-breaking

The following are **safe to ship within a version**. Client code written today keeps working:

* Adding a new endpoint
* Adding a new optional response field
* Adding a new optional request parameter
* Adding a new enum value to a **request** parameter (you send more; the API accepts more)
* Adding a new response status code (documented)
* Widening a response field's type (for example, from `integer` to `number`)
* Relaxing a validation rule (accepting inputs that were previously rejected)

If you use the [AgentMark SDK](/introduction/overview), these changes surface as non-breaking SDK releases (`sdk@1.x → sdk@1.y`).

## What's breaking

The following changes require a new version (`/v2/`) if they're needed:

* Removing an endpoint
* Removing a response field
* Removing a request parameter
* Changing a response field's type in a narrowing way (for example, `string → number`)
* Adding a new enum value to a **response** field (you parse; the API sends something you don't recognize)
* Tightening a validation rule (rejecting inputs that were previously accepted)
* Changing authentication requirements
* Changing the required `Content-Type` of a request or response
* Changing an HTTP status code for an existing response class

Changes in this list won't ship to `/v1/` without a deprecation window (see below).

## Deprecation policy

When a breaking change becomes necessary, the timeline is:

1. **Announce** in the [changelog](/changelog) with the date the change lands.
2. **Add a deprecation notice** to the endpoint's OpenAPI entry (`deprecated: true`) and include a `Deprecation` header in live responses pointing at the replacement.
3. **Wait at least 90 days** between announcement and removal, longer for auth or billing-affecting changes.
4. **Ship the new version alongside the old.** Both work in parallel during the transition.
5. **Remove** after the notice window, only if telemetry shows usage has migrated.

Breaking changes are rare. AgentMark would rather deprecate slowly than ship fast.

## What's not versioned

A few things are intentionally outside the version contract. They can change without a `/v2/` bump:

* **Error response body contents.** The shape is stable: every error returns `{ error: { code: string, message: string } }`. But the set of `code` values may grow over time (AgentMark adds new error codes when it adds new behaviors). Code the `message` for human display and code the `code` for programmatic dispatch, always with a fallback branch for codes you don't recognize yet.

* **Error response `extras`.** Some errors include additional fields (`retry_after_seconds`, `required_permission`, etc.). New fields may appear; existing ones won't change shape.

* **Rate limit values.** Throughput caps adjust based on plan and infrastructure. The `429` response is stable; the exact threshold isn't.

* **Performance characteristics.** Latency targets, batch size guarantees, and read-after-write consistency windows are SLOs, not API contract.

## Using the SDK insulates you from most of this

The [AgentMark SDK](/introduction/overview) handles version negotiation, retries, and response parsing. If you use the SDK, most of this page is transparent: a minor SDK bump follows a minor gateway release, a major SDK bump follows a major gateway release.

The direct HTTP API works for custom integrations, but the SDK is the easier path.

## Questions or migration help

* Changelog: [/changelog](/changelog)
* Contact: [hello@agentmark.co](mailto:hello@agentmark.co)