Skip to main content
The API is versioned in the path. Everything documented lives under /api/v1/.

What will not change within v1

These are a contract. Nothing in v1 will break them:
  • An endpoint’s path, once documented
  • A parameter’s name and meaning
  • A field’s name and type in a response
  • The {"data": ...} and {"error": ...} envelopes
  • An error code’s meaning
  • An HTTP status for a given outcome

What can change

These may change without a new version, so write code that tolerates them:
  • New fields in responses. Ignore fields you do not recognise rather than failing on them.
  • New optional parameters. Existing calls keep their current behaviour.
  • New endpoints and new error codes. Treat an unrecognised code as a generic failure of its HTTP status.
  • Message wording. message is written for people and is reworded and translated. Branch on code.
  • Ordering, where you did not specify it. Pass sort_by if order matters to you.
The most common way an integration breaks is strict response parsing — a schema validator set to reject unknown fields, or a deserialiser that throws on them. Adding a field is not a breaking change here.