Skip to content
Esc
↑↓navigate↵open⌘Jpreview
On this page

Versioning

How the Modem API is versioned and how changes are rolled out.

The Modem API is versioned in the URL path. The current version is v1, served at https://api.modem.dev/v1.

What counts as a breaking change

We treat these as breaking, and they will not happen within a version:

  • Removing an endpoint, or removing a field from a response.
  • Renaming a field, or changing its type.
  • Adding a new required request parameter.
  • Changing authentication or error semantics in a way that breaks existing clients.

What can change without a new version

These are backward-compatible and may ship at any time, so build your integration to tolerate them:

  • Adding new endpoints.
  • Adding new optional request parameters.
  • Adding new fields to a response.
  • Adding new values to an existing enum where the response already documents that the set may grow.

Deprecation policy

When we need to make a breaking change, we introduce a new version (for example v2) and run it alongside v1. We will:

  1. Announce the change and publish migration notes in the changelog.
  2. Keep the previous version available for a minimum of 6 months after the successor is generally available.
  3. Mark deprecated endpoints in this reference and, where possible, return a Deprecation header on responses from the deprecated version.

We will not remove or break v1 without this notice period.

Changelog

Notable API changes are recorded here. During the initial rollout the surface may expand additively (new endpoints and fields) under v1.

Date Change
2026-10-14 GET /topics/{topicId}/people serves topics from the current pipeline only. A topic archived in the v1 to v2 migration returns 404 with data.reason set to archived_in_v1_to_v2_migration. The response shape is unchanged.
2026-10-10 POST /topics/merge is not supported for current topics. It changes nothing and returns 501 NOT_IMPLEMENTED until a merge for the current pipeline ships. To retire a duplicate, archive it with POST /topics/{topicId}/archive.
2026-10-10 PATCH /topics/{topicId}, PATCH /topics/bulk, GET /topics/{topicId}/groups and GET /topics/{topicId}/history serve topics from the current pipeline, so the IDs GET /topics returns work with them. Request and response shapes are unchanged. issueType and keywords on PATCH /topics/{topicId} are now set by the pipeline and return 400. The history response’s actions list is always empty.
2026-10-10 A topic archived in the v1 to v2 migration returns 404 with data.reason set to archived_in_v1_to_v2_migration from the topic update, bulk update, merge, groups and history endpoints, instead of a bare 404.
2026-10-07 GET /topics: the view query parameter is deprecated and ignored. Both values are still accepted, and topics come from the current pipeline.
— Initial v1 release.

Was this page helpful?