An agent should not integrate against a surface that can change without warning. This is what we promise about changes, and how you find out about them in the response itself rather than from a blog.
The API is versioned in the URL path. Every endpoint lives under /v1/, on both https://api.agentcost.tech/v1/… and the cached mirror at https://agentcost.tech/api/v1/….
Within a version we only make additive changes: new endpoints, new optional request fields, new fields in a response. Existing field names keep their meaning and their type. A change that would break a working client — removing a field, narrowing a type, changing a status code — means a new version path, not an edit to this one.
Treat unknown response fields as forward compatibility, not as errors. Your client should ignore fields it does not recognise.
Every API response carries a link to this page, so a client can find the policy without knowing where to look:
Link: <https://agentcost.tech/docs/api-versioning>; rel="deprecation"; type="text/html"
That link alone does not mean anything is deprecated — it points at the policy. When an endpoint is actually retiring, two more headers appear on its responses:
Deprecation: @1782864000
Sunset: Wed, 01 Jul 2026 00:00:00 GMT
Link: <https://agentcost.tech/docs/api-versioning>; rel="deprecation"; type="text/html",
<https://api.agentcost.tech/v2/pricing>; rel="successor-version"Deprecation is a Structured Fields Date — an @ followed by whole seconds since the Unix epoch — marking when the endpoint was announced as deprecated. It keeps working.Sunset (RFC 8594) is an HTTP-date marking when it stops working. It is never earlier than the deprecation instant.successor-version link points at the replacement, when there is one.If your client sees a Sunset header, you have until that date. Log it, and migrate.
At least 180 days between the Deprecation date and the Sunset date on any public endpoint. The headers are the notice — you do not have to be subscribed to anything to receive it.
Nothing. No endpoint in /v1/ is deprecated or scheduled for retirement, so no response currently carries a Deprecation or Sunset header.
This page is about the AgentCost API retiring. Providers also retire models, and that is tracked separately — see GET /api/v1/pricing/deprecations or the list_model_deprecations MCP tool.
Related: REST API reference · MCP server · OpenAPI spec