DocsVersioning and changelog
Docs/Developer API·Last reviewed

Versioning and changelog

This page says what can change inside /v1 without notice, what cannot, how much warning you get before anything is removed, and lists every API release.

Versions

The version is the path. Every endpoint lives under /v1. There is no version header and no date pinning, so a call always meets the current /v1.

The API spec has its own version number, shown at the top of the API reference. It is 1.0.0 at launch and goes up by a minor number for each release that adds something, for example 1.1.0.

Additive changes

These can arrive at any time inside /v1, with a line in the changelog:

  • →a new endpoint
  • →a new optional request parameter or field
  • →a new field in a response, including a new key in a webhook payload
  • →a new value in a response enum, such as a new changed_fields name
  • →a new error code or detail code
Inside /v1, changes are additive only. Ignore fields you do not know, and treat an enum value you do not know as other. Error messages may change. Error codes may not.

Write your client to match: read the fields you use, skip the rest, and give an unknown enum value a safe default.

Breaking changes

These are breaking:

  • →removing or renaming an endpoint, a parameter, a request field or a response field
  • →changing the type of a parameter or a field
  • →a response field that can now be null, or is no longer always present
  • →narrowing an enum a request accepts, or removing a value from a response enum
  • →removing a state or a variant from a response
  • →a new required request parameter or field
  • →changing what an error code means

A breaking change comes only in a new version path such as /v2. An operation in /v1, or /v1 itself, is retired only after the notice below.

Deprecation

You get at least 6 months' notice before anything is removed. The notice is a Deprecated line in the changelog below, and an email to each company with a live key.

From the day of the notice, every response to a call with a recognised key to a deprecated operation carries three headers. Deprecation is @ and the Unix seconds the operation was deprecated. Sunset is the date it may stop working, at least 6 months later. Link points at the changelog entry with rel="deprecation".

Deprecation: @1798761600
Sunset: Thu, 01 Jul 2027 00:00:00 GMT
Link: <https://www.issuesid.com/docs/api-versioning/>;
  rel="deprecation"; type="text/html"

The values are an example, and the Link header is one line on the wire, wrapped here to fit. Watch for Deprecation in your logs and move before the Sunset date.

Changelog

Newest release first. Each release has a heading with its date and version, then a flat list. Each line starts with one label: Added, Changed, Deprecated or Fixed.

The 1.0.0 entry is dated the day the API went live.

2026-11-13, 1.0.0

  • →Added The first release. Everything in the API reference is part of it.

The current spec, with its version, is at the top of the API reference.

IssuesId