# Catalog API versions

Pin a catalog API to a major version so that a change to the listing cannot break your workflow, and know when a version stops answering.

## Majors and minors

A listing has **majors**: 1, 2, 3. You pin a major. Inside a major, every change is a **minor** (1.0, 1.1, 1.2). Minors are internal: you never select one, and every call on a major runs its newest minor.

- A **minor** keeps the major's contract. It covers repairs when the source changes its markup, added fields, added optional inputs and added options.
- A **major** is a change the old contract cannot answer truthfully: a field removed or retyped, an input removed, an input that became required with no default, an option value removed, a default that changes results, or a changed value format (for example a price `"1 234 kr"` that becomes `1234`).

CleanedWeb avoids majors. Before a change becomes one, it keeps the old contract answering where it can: a field the source stopped showing stays in the contract as `null`, a renamed field keeps its old name beside the new one, and a new required input ships with a default.

## Pin a major

Send `version` as an integer in the run body:

```json
{
  "input": {},
  "max_items": 25,
  "version": 2
}
```

The listing page shows the versions that answer, and every request example on it carries `"version": N`. Read a major's contract with `GET .../contract?version=1`.

A call with no `version` runs the latest major. Pin one in production so a new major cannot change your results.

The response names the version that ran:

```json
{ "version": "2.3" }
```

`version` is the major and its newest minor. The listing's contract and page also carry `versions` (each major, its newest minor, its status and its sunset date) and a `changelog`, newest first, with major entries marked.

## Deprecation and sunset

When a new major goes live, the previous major is **deprecated**. It keeps answering for **60 days**, then it is **sunset**. A deprecated major's listing page shows its sunset date and links to the current major.

Retired minors are kept 14 days for rollback and replay. You never call one.

Workspaces that ran a deprecated major in the last 30 days get an email when the next major goes live and again 7 days before the sunset.

## After a sunset

A call pinned to a sunset major is not refused. It runs on the latest major, and the response says so:

```json
{
  "version": "3.1",
  "version_requested": 1,
  "rerouted": "sunset"
}
```

A call pinned to a deprecated major, and a rerouted call, also carry these headers on the run answer and on reading its result:

| Header | Meaning |
| --- | --- |
| `Deprecation: true` | The major you pinned is deprecated, or was sunset and rerouted. |
| `Sunset: <HTTP date>` | When the major stops answering, for example `Sun, 17 Jan 2027 00:00:00 GMT`. Left out when the major has no sunset date. |
| `Link: <https://cleanedweb.com/catalog/API_ID#changelog>; rel="deprecation"` | The listing's changelog. |

The website session relays all three. A call on the latest major, or on a major that is current, carries none of them.

Check `rerouted` in your code. A rerouted call has the latest major's inputs and fields, which can differ from the ones you pinned.

## Unknown major and invalid version

A major that never existed is an error, not a reroute. The answer is `404`, and `available` lists the majors that answer, oldest first:

```json
{
  "detail": {
    "code": "catalog_version_not_found",
    "message": "This API has no such version. The available versions are listed.",
    "available": [1, 2]
  }
}
```

`GET .../contract?version=7` answers the same. A `version` that is not a whole number of at least 1 (`0`, `-1`, `"2"`, `1.5`, `true`, a list) is a `422`, and nothing runs:

```json
{
  "detail": {
    "code": "catalog_version_invalid",
    "message": "version must be a whole number of at least 1."
  }
}
```

The body is the same whether you call with an API key or through a signed-in website session: the website relays the error object unchanged and only fills in `message` when the answer has none. On the MCP server the same codes arrive in `error.data.code`.

## Schedules

A schedule keeps the major it was created on and runs it until that major is sunset. After that it runs the latest major, with the same headers and fields as any rerouted call.

## Related

- [Run a catalog API](/docs/run-catalog-api/)
- [Published catalog APIs](/docs/catalog-apis/)
- [Errors and retries](/docs/errors/)
