Versioning & deprecation

This page is policy, not description. Partners plan roadmaps against it, so it is stated as a commitment rather than an intention.

The major version is in the URL

https://api.vaki.co/v1

There is no version header, no date-pinned version, and no per-account version. The prefix in the URL is the version, and /v1 means the same thing tomorrow as it does today.

Additive changes ship without a version bump

We add to /v1 without warning and without a new prefix. Your client must tolerate all of the following, because all of them will happen:

• New fields in a response. Ignore fields you do not recognise. Do not deserialise into a struct that throws on unknown keys, and do not assert on an exact object shape in tests.
• New optional request fields. Never required, never changing the meaning of what you already send.
• New enum values. New status values on a checkout link, new state values on a vaki. Handle the values you care about and have a default branch for the rest — never a switch that throws on an unknown case.
• New error codes. Branch on the codes you handle, and fall back to the HTTP status class for the rest. See Errors.
• New endpoints and new permissions. Existing keys are unaffected; a key never silently gains a capability.
• Higher rate limits. Never lower without notice.

If a client breaks on any of these, that is a bug in the client, and the fix is the tolerant-reader habit above. It is also the single cheapest thing you can do today to avoid an emergency later.

Breaking changes get a new prefix

Anything that could break a correct client gets /v2, never a change to /v1:

• Removing or renaming a field, or changing its type.
• Removing an enum value, or changing what an existing one means.
• Making an optional request field required, or tightening validation on it.
• Changing the meaning of a status code on an existing route.
• Removing an endpoint.

/v1 and /v2 then run side by side. You migrate when you are ready.

A superseded version is supported for 12 months

When /v2 ships, /v1 keeps working for at least 12 months from the day /v2 becomes generally available. During that window /v1 gets security fixes and correctness fixes. It does not get new features — those land on the current version only.

Twelve months is a floor, not a target. We will not shorten it, and we will not quietly stop fixing bugs in it.

Deprecation is announced in headers, in the changelog, and by email

When a version or an endpoint is scheduled for removal, its responses start carrying RFC 8594 headers:

HTTP/1.1 200 OK
Deprecation: Sat, 15 Aug 2026 00:00:00 GMT
Sunset: Sun, 15 Aug 2027 00:00:00 GMT
Link: <https://developers.vaki.co/changelog/>; rel="deprecation"

Header	Meaning
Deprecation	When the endpoint or version became deprecated. It still works.
Sunset	When it stops working. After this instant, requests fail.
Link with rel="deprecation"	Where the change is documented, including what to migrate to.

Alongside the headers: a dated changelog entry, and an email to the technical contact on record for every client whose key has actually called the affected route in the preceding 90 days. If your contact details go stale, you lose the email and keep the headers — so keep them current.

Minimum notice before removal: 90 days. For a whole major version, the 12-month window above applies instead, and it is longer.

Log the Deprecation header

The cheapest possible early warning is one line in your HTTP client:

const deprecation = res.headers.get('Deprecation');
if (deprecation) {
  console.warn('vaki_endpoint_deprecated', {
    url: res.url,
    deprecation,
    sunset: res.headers.get('Sunset')
  });
}

It costs nothing and it turns a sunset into a ticket you file with months to spare, instead of an outage.

Security is the one exception

If a field or behaviour is actively being exploited, or leaks data it should not, we will change it faster than these windows allow. We will tell you what changed and why, in the changelog and by email, at the time.

We would rather break your build than leak your donors’ data. This is the only case where we will.

What is not covered by this policy

• Coming soon endpoints. A published contract for an endpoint that is not callable is a design, not a commitment. It can change before the endpoint ships, and the changelog will say so. Once an endpoint is live, this policy covers it.
• The URL of a hosted checkout page. url on a checkout link is an opaque value we resolve for you; its host and query string are not part of the API contract and will change. Redirect to it, never construct it — see Known limitations.
• Cosmetics of this documentation site. Page URLs may move; the changelog will not.