Skip to main content
The API is versioned by its /v1 path prefix, which is the contract you code against. This page says what we may change inside it without telling you, what we may not, and how you find out before something goes away.

​
What the version covers

/v1 is the whole data plane. There is no date-pinned version, no Api-Version header and no per-account pin — one live contract, and the machine-readable description of it is at /openapi.json. That document’s own info.version is its revision, not the API’s; branch on the path prefix, never on that number.

​
What we may change without notice

Anything a correctly written client already tolerates. Write your client to ignore fields it does not recognise — that single habit is what makes every change below safe for you.
  • New endpoints, and new optional request fields.
  • New fields in a response body, and new values in a field that is already documented as open-ended.
  • New error codes, within a status you already handle. Branch on the code, treat an unknown one as the class its status implies.
  • New response headers.
  • Rate-limit defaults, and the per-unit rates — rates are published at Pricing and always render from the live price list. A change there is a price change, not an API change.
  • Wording of any message. It is written for a person and may be rewritten at any time.

​
What counts as breaking

  • Removing or renaming an endpoint, a request field, a response field or an error code.
  • Narrowing what a request field accepts, or making an optional field required.
  • Changing the type or the meaning of an existing field.
  • Changing which scope an operation requires.
  • Changing the unit an operation is metered in — the rate may move freely; what the unit counts may not.
Service identifiers never change even when display names do. scrape, toolsapi and tasks are written into live API keys, usage records and scope strings — the name a page shows you and the identifier the contract uses are allowed to disagree, and tasks / Superagent already do.

​
Notice, and the headers that carry it

A breaking change ships as a new path prefix — /v2 — and never as an edit to /v1. Once a successor exists, the older operation is marked deprecated and stays serving for the notice period below. The notice period is twelve months between the first Deprecation header and the Sunset date, and we will mail the technical contact on every organization whose keys called the affected operation in the preceding ninety days. Nothing is withdrawn without both.
An automated caller should log a Deprecation header rather than ignore it: it is the one signal that arrives long before anything breaks, and an unattended integration is exactly the kind that finds out on the sunset date otherwise.

​
The two exceptions

Security. If serving an operation is actively unsafe — a vulnerability, a credential exposure, an upstream provider withdrawing something under us — we will change or withdraw it faster than twelve months, and say why. This is the only case in which notice is shortened. Third-party catalogues. ToolsAPI runs tools published by other vendors. Which tools exist, what they cost and what their inputs look like is the vendor’s decision, not ours, and none of it is covered by this policy — discover and inspect tell you the current state, which is why the docs tell you to read them rather than cache what they returned.