Skip to main content

​
Current version

The AgentMark Gateway API is v1. Every endpoint is prefixed with /v1/ (except GET /health, which is unversioned). The current version will remain available as /v1/* for the foreseeable future.

​
Versioning strategy

Breaking changes are released under a new path prefix. When a future /v2/ is introduced, /v1/ will continue to work in parallel — you upgrade when you’re ready, not when we ship. 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 will keep 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; we accept more)
  • Adding a new response status code (documented)
  • Widening a response field’s type (e.g. from integer to number)
  • Relaxing a validation rule (accepting inputs that were previously rejected)
If you use the AgentMark SDK, 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 we need them:
  • Removing an endpoint
  • Removing a response field
  • Removing a request parameter
  • Changing a response field’s type in a narrowing way (e.g. string → number)
  • Adding a new enum value to a response field (you parse; we send 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 will not ship to /v1/ without a deprecation window (see below).

​
Deprecation policy

When we need to break something, the timeline is:
  1. Announce in the changelog with the date the change will land.
  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. We’d 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 (we add new error codes when we add new behaviors). Code the message for human display; code the code for programmatic dispatch — and always have a fallback branch for codes you don’t recognize yet.
  • Error response extras. Some errors include additional fields (retry_after, 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 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 is supported for custom integrations, but the SDK is the path of least friction.

​
Questions or migration help