Skip to main content
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 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 (and its Atom feed) 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) with the date the deprecation took effect, a Sunset header (RFC 8594) 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.
  • 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.