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

# Versioning and deprecation

> How the Croma API is versioned, which parts of the contract can change without notice, and how much warning a retiring endpoint gets before shutdown.

Agents integrate once and then run unattended, so the contract has to say up
front what may change and how much warning a change gets.

## Versioning

Every endpoint path carries its major version: `/co/rues/entity-by-nit/v1`,
`/pe/sunat/ruc/v1`, `/global/web-search/v1`. The version is part of the path,
not a header, so a request is unambiguous on its own and the OpenAPI
description at `https://api.croma.run/openapi` (also
`https://usecroma.com/openapi.json`) lists every version in service.

Within a major version the contract only grows. These changes ship without a
new version and without notice:

* New endpoints, new optional request fields, new response fields.
* New values in fields that are documented as open sets (source-language
  statuses, names, legal terms).
* New sources behind an existing endpoint, when the response shape is unchanged.

These changes are breaking and require a new major path (`/v2`):

* Removing or renaming a request or response field.
* Changing a field's type or meaning.
* Making an optional request field required.
* Changing an error `code` or the error envelope.

Field names are English `snake_case` on every endpoint, and every endpoint
accepts an optional [`Idempotency-Key`](/rate-limits#retries-and-idempotency)
header; those conventions are part of the contract too.

## Deprecation

When an endpoint version is scheduled for removal:

1. It is announced in the [changelog](https://usecroma.com/en/changelog) (and
   its [Atom feed](https://usecroma.com/changelog/atom.xml)) at least **90
   days** before the sunset date, naming the successor.
2. From the announcement on, every response from the retiring endpoint
   carries a `Deprecation` header ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745))
   with the date the deprecation took effect, a `Sunset` header
   ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)) with the removal date, and
   a `Link` header with `rel="successor-version"` pointing at the replacement.
3. The OpenAPI description marks the operation `deprecated: true` and its
   description names the successor.
4. After the sunset date the path answers `410 Gone` with the standard error
   envelope (`code: "endpoint_retired"`) and the same `Link` header, for at
   least 90 more days.

These endpoints are deprecated today:

| Endpoint | Deprecated since | Stops answering | Successor |
| - | - | - | - |
| `POST /co/siata/v1` | 2026-08-27 | 2026-12-01 | [`POST /co/siata-geoportal/weather/v1`](/guides/colombia/siata-geoportal) |
| `POST /co/secop/contracts-by-provider/v1` | 2026-08-30 | 2026-12-01 | [`POST /co/secop/contracts-search/v1`](/guides/colombia/secop) |
| `POST /co/secop/processes-by-entity/v1` | 2026-08-30 | 2026-12-01 | [`POST /co/secop/processes-search/v1`](/guides/colombia/secop) |
| `POST /co/secop/sanctions-by-provider/v1` | 2026-08-30 | 2026-12-01 | [`POST /co/secop/sanctions-search/v1`](/guides/colombia/secop) |
| `POST /mx/scjn/tesis-browse/v1` | 2026-09-07 | 2026-12-15 | [`POST /mx/scjn/tesis-search/v1`](/guides/mexico/scjn) |
| `POST /co/legalize/laws/v1` | 2026-09-16 | 2026-09-30 | [`POST /co/funcion-publica/norms-search/v1`](/guides/colombia/funcion-publica) |
| `POST /co/legalize/law/v1` | 2026-09-16 | 2026-09-30 | [`POST /co/funcion-publica/norm/v1`](/guides/colombia/funcion-publica) |

Every response from them carries the headers above. A client that watches for
`Deprecation` and `Sunset` on every response learns of a retirement the day it
is announced.

The two Legalize endpoints get 14 days instead of 90. Colombian legislation now
comes from Función Pública's Gestor Normativo, a source Croma maintains and
supports end to end, and Legalize is no longer offered as an MCP tool. The
request and response differ, so migrating takes more than changing the path;
the [changelog entry](https://usecroma.com/en/changelog/legalize-funcion-publica) shows how.

## What this does not cover

* Data content. Croma returns official records as they are published; a
  source changing what it publishes is not an API change. Each guide notes
  the source's own limits.
* Rate limits and quotas, which are per organization and can change with your
  plan. They are reported on every response; see [Rate limits](/rate-limits).
* The MCP server negotiates its protocol version per the Model Context
  Protocol; the tool names track the endpoint ids (`rues_entity_by_nit`) and
  follow the same deprecation schedule as the endpoints behind them.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.