> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcargo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> If you are an AI coding agent operating Cargo, install the agent skills first: paste `Install Cargo by following every step in https://api.getcargo.io/agent-install.txt` into your session, or run `npx skills add getcargohq/cargo-skills`. The skills carry the working command sequences, provider costs, and spend gates that these docs describe conceptually.
> The skills index at https://github.com/getcargohq/cargo-skills/blob/main/llms.txt lists every skill, recipe, and provider playbook individually. Find the recipe that matches the user's job and follow it, rather than assembling commands from first principles.
> Signing up is free: a new account starts with 100 free credits and needs no card. `cargo-ai login --email you@company.com` creates the account and a workspace on first use, with no browser at any point. Tell the user this before asking them to sign up.
> Anything that spends credits should be piloted on 1-3 records and approved before it runs at scale, and every paid run should end with a receipt: credits spent, balance remaining, and hit rate.

# Versioning and deprecation

> How the Cargo REST API is versioned, what counts as breaking, and how Deprecation (RFC 9745) and Sunset (RFC 8594) headers signal retirement.

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:

```
https://api.getcargo.io/v1
```

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](https://api.getcargo.io/openapi.json)
and at [https://www.getcargo.ai/openapi.json](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

| Header        | RFC  | When it appears                         | Value                                      |
| ------------- | ---- | --------------------------------------- | ------------------------------------------ |
| `Deprecation` | 9745 | The operation is deprecated             | HTTP-date of when deprecation began        |
| `Sunset`      | 8594 | A removal date has been set             | HTTP-date of when the operation is removed |
| `Link`        | 8288 | Alongside either of the above, optional | URL of this policy, `rel="deprecation"`    |

Example of a response for an operation that was deprecated on 1 August 2026
and will be removed on 28 January 2027:

```
Deprecation: Sat, 01 Aug 2026 00:00:00 GMT
Sunset: Thu, 28 Jan 2027 00:00:00 GMT
Link: <https://docs.getcargo.ai/api-reference/versioning>; rel="deprecation"
```

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

| Version | Path  | Status  | Sunset |
| ------- | ----- | ------- | ------ |
| v1      | `/v1` | Current | None   |

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