Versions of the API

How the API changes, what never changes, and how you hear about it before anything you depend on goes away.

What /api/v1 promises

Every address starts with /api/v1. Inside version 1 a change is additive: new endpoints, new optional fields in a request, new fields in an answer, new values in a list that says it can grow. Your integration keeps working without a change of yours, as long as it:

• ignores fields in an answer it does not know;
• branches on code or number of an error, never on the message, which may be reworded;
• treats an unknown value of an open list (an event type, a warning code) as something to log, not as a failure.

What never changes

Thing	Promise
Error codes and numbers	A code keeps its name and its number. A number is never reused for something else, even after a code is retired. See Outcomes and error codes.
The answer's shape	One output object with one section per product (compose, sign, flow); an error is always the same envelope with code, number, message and retryable.
Idempotency	The same Idempotency-Key with the same body never does the work, or charges, twice.

When something is deprecated

Sometimes a better way replaces an old one. The old way is then deprecated: it keeps working exactly as before, and it says so.

1. Announced in the release notes and on the guide page that describes it, with what to use instead.
2. Marked in every answer. A call on a deprecated address carries the standard headers Deprecation (the date it was deprecated, RFC 9745) and Link: <the new address>; rel="successor-version". A deprecated field in an answer is marked in the guide.
3. Removed only in a new major version (/api/v2 or the product's 2.0), never inside version 1, and never earlier than six months after the announcement. From that point the answers also carry Sunset with the date (RFC 8594), and we write to every organisation's addresses.

Deprecated today

Old	Use instead	Since
/api/v1/documents/*	/api/v1/compose/documents/*	2026-09-19
/api/v1/templates/*	/api/v1/compose/templates/*	2026-09-19
/api/v1/signatures/*	/api/v1/sign/*	2026-09-19
organisation.deliveryMode, thisMonth.documentsSucceeded, thisMonth.documentsFailed in GET /api/v1/usage	See Tracing a call, and watching your usage	1.1

None of them has a removal date: they will go with version 2, which is not scheduled.

How you hear about a change

• The release notes list every change a customer can notice, with the version it shipped in (MAJOR.MINOR.PATCH: a patch fixes, a minor adds, a major may remove).
• The generated reference, /openapi.json, always describes the current version; deprecated addresses are not in it.
• A change that needs something from you is also mailed to your organisation's addresses.