Skip to main content

​
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, 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 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 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