Versioning

The version in the path

Every endpoint is served under /v1. That prefix is part of the contract: while it stays, the existing behaviour stays.

What we may change without notice

These are additive and your integration should tolerate them:

New endpoints.

New optional fields in a request body.

New fields in a response.

New values in an enum — new validation factors, sign mark types, signer actions or webhook events.

New error metadata keys.

Reworded error messages.

The last two are worth stating plainly: branch on the status code and the metadata keys, never on message text. Messages are written for people and get improved.

What we will not change under `/v1`

Removing an endpoint, a field or an enum value.

Renaming anything.

Changing a field's type.

Making an optional field required.

Changing the meaning of an existing status code.

Anything in that list needs a new version prefix.

Writing a client that survives

Ignore unknown fields rather than failing on them.

Treat an unknown enum value as "something new", not as an error — a switch over signer actions or sign mark types needs a default branch.

Do not assume the set of webhook events is closed; ignore what you do not handle.

Store X-Signater-Telemetry-Operation-Id from every response. It is what turns a support conversation into a lookup.

Deprecations

When something has to go, it is announced before it is removed, and the reference marks the affected endpoint or field as deprecated while it still works. LegacyRectangleRubric is an example already visible in the sign mark types: it is retained so existing envelopes keep rendering, and new envelopes should use Rubric.

The version in the path#

What we may change without notice#

What we will not change under /v1#

Writing a client that survives#

Deprecations#

The version in the path

What we may change without notice

What we will not change under `/v1`

Writing a client that survives

Deprecations