CleanedWeb
Markdown

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.

On this page

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 · example
{
  "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 · example
{ "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 · example
{
  "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 · example
{
  "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 · example
{
  "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.

Updated Get help
Search across the documentation · Esc to close