Skip to main content
The Cargo REST API is versioned in the URL path. Breaking changes ship as a new path; they never mutate an existing version. When an operation is retired it is signalled with the Deprecation (RFC 9745) and Sunset (RFC 8594) headers, and it keeps answering until the sunset date. This is the deprecation policy. Agents can rely on it.

​
Versioning

The current version is v1, addressed at:
The version is in the path, not in a header. A breaking change is published as /v2 (or later) rather than by changing /v1. Clients pin the path they were built against. The OpenAPI description of this version is at https://api.getcargo.io/openapi.json and at https://www.getcargo.ai/openapi.json.

​
What is not a breaking change

These are additive and can appear on /v1 without a new version:
  • A new endpoint.
  • A new optional request field. Existing clients that do not send it keep working.
  • A new field on a response. Clients must ignore fields they do not recognise; treating the JSON as a closed object is the thing that breaks.
  • A new optional header.
A change is breaking when a request that worked keeps the same path and stops working, or when a field a client already reads changes type or meaning.

​
Deprecation policy

When an operation on a published version is going to be removed:
  1. The operation is marked deprecated in the OpenAPI document.
  2. Every response from that operation carries the Deprecation header (RFC 9745). The value is an HTTP-date: the moment deprecation began.
  3. Once a removal date is fixed, the same responses also carry the Sunset header (RFC 8594). The value is an HTTP-date: the moment the operation will stop being served.
  4. There are at least 180 days between the Deprecation date and the Sunset date. The operation keeps answering, with both headers, until sunset.
  5. After sunset the path returns 410 Gone. A new version of the same capability, if any, lives on a new path.
No currently published /v1 operation is deprecated. The headers above appear only when one is. A Link header with rel="deprecation" or rel="sunset" may point at this page for the human-readable explanation of a specific retirement.

​
Headers

Example of a response for an operation that was deprecated on 1 August 2026 and will be removed on 28 January 2027:
Do not keep calling an operation after its Sunset date. Prefer its replacement, named in the OpenAPI description of that operation, as soon as Deprecation appears.

​
Current versions

There is no v0 and no unversioned REST surface. /v1 is the first public version and it is not deprecated.