Versioning
The API is versioned by path. /v1 is the current — and only — surface,
and it stays stable: additive changes land on it, while a change that would
break an integration ships under a new prefix such as /v2 or after a
deprecation window on /v1.
Every /v1 response also carries a calendar stamp:
Agentency-Version: 2026-08-14
The stamp is informational. It names the contract the response was built
against, and the same value appears as api_version on webhook event payloads.
It is not a second URL and not something you send: no request header selects a
version, nothing is pinned per key, and every key sees the same /v1.
`/v2` does not exist yet. A new prefix is only introduced for an approved
breaking change, and it will be announced in the
[Changelog](/developers/changelog) before it ships.
What counts as breaking
The distinction decides whether a change can appear on /v1 at any time or
needs a new prefix or a deprecation window, so it is worth being precise.
Not breaking — can appear on /v1 at any time:
- A new field on a response.
- A new optional request parameter.
- A new endpoint.
- A new event type.
- A new value in an enum or list you already have to handle unknown members of.
Breaking — needs a new path prefix or a deprecation window:
- Removing or renaming a response field.
- Removing an endpoint, or changing its path or method.
- Changing what an existing field means.
- Making an optional request field required.
- Narrowing what a field accepts.
- Changing the type of an existing field.
Because additive changes ship without warning, ignore fields and enum values you do not recognise rather than erroring on them. A strict parser that rejects unknown keys will break on a change that was designed to be safe.
Deprecation
When an operation is on its way out it keeps working, unchanged, and starts announcing itself on every response:
Deprecation: true
Sunset: Sat, 01 Jan 2028 00:00:00 GMTDeprecation: trueis set on every response of a deprecated operation.Sunsetis the HTTP date after which the operation stops working. It is sent only once a date has been set, and there is one sunset date for the whole API, so every deprecated operation carries the same value.- A retired path stays up for 12 months after
Deprecation: trueis first served. The deprecation is recorded in the Changelog the same day the header ships, and the operation is markeddeprecated: truein the OpenAPI document.
No /v1 operation is deprecated today.
The cheapest possible early warning: if your client logs a Deprecation
header, you find out months ahead instead of on the day it stops. Nobody reads
a changelog for an integration that is working.
Worth logging
Three values make a support conversation short instead of long:
Agentency-Version— the contract stamp of the response.X-Request-ID— a response header, repeated asrequest_idin every error body. This is the single most useful thing to quote when reporting a problem.error.code— the machine-readable failure, e.g.RATE_LIMITED.
The spec is the contract
The published OpenAPI document is generated from the API's own routes and request and response definitions, and a check fails the build when the committed document drifts from the code. An endpoint, field or error code that is not in it is not part of the contract.
curl https://api.agentency.com/v1/openapi.json -o agentency.jsonDiff it between releases to see exactly what changed, or generate a typed client from it. Both official SDKs generate their endpoint tables from it.