On this page

Versioning

Beta

What can change under you, what cannot, and where changes are announced.

2 min read

The API is versioned in its path. Today there is one version:

https://api.ghostsms.io/v1

What we may change without warning

Additive things, which a correct client ignores:

  • New fields on existing objects.
  • New endpoints and new resources.
  • New optional parameters, and new values for an existing optional parameter.
  • New event types, and new fields inside an event payload.
  • New error codes, for situations that previously had a less specific one.
  • The text of title and detail in a problem, and the exact wording of any human-readable string.

Two consequences for how you write a client: parse JSON permissively — an unknown field is not an error — and switch on code rather than on a message, with a default branch for a code you have not seen.

What we will not change inside a version

  • Removing or renaming a field, an endpoint, or a parameter.
  • Changing a field's type, or the meaning of an existing value.
  • Adding a required parameter to an existing endpoint.
  • Changing which scope an endpoint needs.
  • Changing an existing error code, or the status it comes with.

A change of that kind means a new version in the path, with the old one kept running while integrations move.

How to see a change coming

The OpenAPI document is the contract, and it is committed to our repository, which means every change to it is a diff somebody reviewed before it shipped. If you want to know when the API changes, watch that document: fetch it with the ETag you already hold and you get a 304 until something actually moves.

The reference in this section is generated from that same document, so it cannot describe a version of the API that does not exist.

While the API is in beta

Every account has access, but the surface is still settling. We will not break the rules above, but a beta is the time when the additive changes come quickly — and if something here turns out to be wrong for real integrations, we would rather change it now than carry it into a v2.

So tell us: what is missing, what surprised you, what you had to work around. Write to support and say it is about the API.