Skip to content
Browse docs
esc
  • Try "webhook signature", "chunkSize" or "rate_limited".

Guides

Versioning and deprecation

How the Vermin API is versioned, what can change without notice, and how deprecations are announced.

The API's major version is in the URL path. Every endpoint today lives under /v1, and the OpenAPI spec describes exactly that surface.

What can change within /v1#

Only additive, backwards-compatible changes:

  • New endpoints and new optional request fields.
  • New fields in responses. Ignore fields you don't recognise.
  • New error codes. Treat an unknown error.code like the HTTP status it came with.
  • New values for open-ended fields such as tier.

Anything else (removing or renaming a field, changing a type, making an optional field required, changing what an error code means) is a breaking change and ships as a new path version, /v2, alongside /v1.

How deprecations are announced#

When an endpoint or field is going away:

  1. It is marked deprecated: true in the OpenAPI spec and flagged in these docs.
  2. Its responses carry a Deprecation header (RFC 9745) and a Sunset header (RFC 8594) with the removal date, plus Link: <…>; rel="deprecation" pointing at migration notes.
  3. Account owners whose keys still call it get an email.

The sunset date is at least 90 days after the first Deprecation header. Log those headers and you will never be surprised.

SDKs#

The SDKs follow semantic versioning. A new API path version arrives in a new major SDK version; minor and patch releases only add features and fixes.