Stability policy

This is the promise the HTTP API makes to a client that is already working.

What may ship at any time

Additive changes — new endpoints, new optional fields, new statuses on existing endpoints — may ship at any time, without notice.

Write clients that tolerate them:

• Ignore fields you do not recognise. Do not fail on an unexpected key in a JSON object, and do not validate responses against a closed schema.
• Branch on the status codes you know, and treat the rest by class: any other 4xx is a client mistake worth failing loudly on, any 5xx is worth retrying.
• Do not depend on the order of a list beyond what the contract states, or on the exact text of an error string. Branch on the status code; the text is for a human reading a log.

What requires a new prefix

A change that removes or renames a field, changes what an existing status means, or otherwise breaks a working client requires a new path prefix — /v2/ — and the prefix it replaces keeps working for six months.

There is no version header and no version query parameter. The path is the version.

What this covers

The policy covers everything documented in the HTTP API contract and the API reference: paths, methods, request bodies, response bodies and status codes.

It does not cover the numbers in the pricing tiers — caps change with your plan, and a tier's caps may be revised with notice to subscribers — nor the technical limits listed under "Limits and caps" in the contract, which are bounds on the service rather than promises to a client. The rate limit is an abuse guard: it may be tightened if it is abused, and it is not a purchasable feature of any tier.

Deprecation, when it happens

Removing a /v1 prefix would be announced to the account addresses of every account that has called it, at the start of the six months and again before the end. Nothing is scheduled for removal.