> ## 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, what can change without notice, and how a retiring endpoint is announced.

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.

No endpoint is deprecated today, so no response carries these headers yet;
a client that watches for `Deprecation` and `Sunset` on every response will
learn of a retirement the day it is announced.

## 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.