Versioning

API v1 is frozen from the launch. Code written against it keeps working: it gains endpoints and fields, and loses nothing.

What may change in v1

• New endpoints, and new optional request fields and options, off by default.
• New fields in responses and in webhook events. Ignore fields you don't know.
• New error codes, for new features only; an existing request never gets a new code for an old reason.
• New webhook event types, sent only to endpoints that ask for them.
• Error messages, which are for people: branch on the code, never on the message.
• Higher limits, more formats, faster answers.

What never changes in v1

• An endpoint's path, method, or the meaning of its fields and answers.
• A field's name or type, a default, or an error code's status and meaning.
• What counts as a mark, as the pricing page states it, without notice to existing customers.
• The signing scheme of webhooks (Kennmarq-Signature) and the transparency log's formats.

A breaking change

It would come as v2, at its own paths, announced at least 12 months ahead in the changelog and by email to every organisation's owners. v1 keeps answering for those 12 months at least. A fix for a security problem is the one exception: if a request is unsafe as it is, we change it at once and say so in the changelog.

OpenAPI

v1 is described as an OpenAPI 3.1 document at https://api.kennmarq.com/v1/openapi.json, for client generators and API tools. It lists every endpoint, field and error code this reference does.