Reference

API stability & versioning

What we promise about the v1 contract — and how you'll find out when something changes.

This page is the contract between Clarifo and any code you write against the /api/v1/data/* surface. It exists so you can build on us without fear of silent breakage.

What "v1" means

The version segment in the URL (/api/v1/) is major: it gates the shape of the contract. As long as you are calling a /api/v1/... URL, the rules on this page apply.

If we ever need to make a breaking change we cannot do non-disruptively, it will land on /api/v2/... — never as a silent edit to v1.

What we will NOT do without ≥6 months' notice

Inside v1, we promise not to do any of the following without prior deprecation:

  • Remove an endpoint that is currently documented at /docs/api/*.
  • Remove a field from a documented response shape.
  • Rename a field in a documented response shape.
  • Change the type or unit of a documented field (e.g. EUR → SEK, ISO date → epoch, single object → array).
  • Tighten validation on a request field in a way that would reject payloads that were previously accepted.
  • Change a default in a way that would alter the response shape for callers who relied on the previous default.

If any of these is unavoidable, you will get at least six months of notice and a Deprecation HTTP header on every response from the endpoint in question.

What we WILL do without notice

These are non-breaking by definition — you can rely on us doing them whenever they make the API more useful:

  • Add a new endpoint under /api/v1/data/....
  • Add a new field to a response. Your client must ignore fields it doesn't know.
  • Add a new optional request parameter with a backwards-compatible default.
  • Loosen validation to accept inputs that previously errored.
  • Improve data quality, freshness, or coverage — the same query may legitimately return different numbers next month if a filer restates earnings, a new period is published, or we ingest a market we didn't have before.
  • Roll out internal performance, ranking, or relevance improvements that don't change the documented contract.

How deprecation works

When a documented endpoint or field enters its 6-month sunset window, two things happen at the same time:

  1. A Deprecation header is added to every response from the affected endpoint. The header carries an ISO 8601 timestamp of the shutdown date:

    text
    Deprecation: true
Sunset: Wed, 04 Dec 2026 00:00:00 GMT
Link: <https://clarifo.com/docs/api/companies-screen>; rel="successor-version"

    The Sunset value is the earliest moment we will stop serving the old behaviour. The Link header points to the migration target when one exists.

  2. An entry appears in the changelog describing what is changing, when, and what to do instead.

Scrape the Deprecation/Sunset headers in your client and alert on them — that is the contract-level signal. The changelog is the human-readable companion.

What is explicitly NOT part of the contract

Some surfaces are useful but not load-bearing. We may change these without notice:

  • Free-text strings inside error responses (detail, error_message). The HTTP status code, the documented error code, and the structured fields are stable; the prose may improve.
  • Field ordering in JSON responses. Parse by key, not by position.
  • Whitespace and exact formatting of strings such as company names ("Neste Oyj" vs "Neste Corporation").
  • The MCP tool surface at mcp.clarifo.com/mcp — this follows the MCP protocol's own versioning, not the REST API's.
  • Beta features explicitly marked as beta in the docs (none today).

What we ask of your client

To get the full benefit of these promises, your code should:

  • Send Accept: application/json so future content negotiation doesn't surprise you.
  • Ignore unknown response fields rather than rejecting them.
  • Read the X-Clarifo-Request-Id header on every response and include it in support requests — it lets us trace what your client actually saw.
  • Watch Deprecation and Sunset headers and alert when they appear.
  • Cite the version that was current when you integrated in your changelog or release notes, so you have a baseline to diff against.

Questions?

Anything ambiguous on this page is a documentation bug — email support@clarifo.com and we'll clarify it here.