Versioning

Dated API versions, the Listener-Version header, and what counts as a breaking change.

1 min read

The API is versioned by date. The current and only version is 2026-10-14.

Pinning a version#

Send the Listener-Version header to pin the behaviour your code was written against:

curl

curl https://api.listener.com/v1/me \
  -H "Authorization: Bearer $LISTENER_API_KEY" \
  -H "Listener-Version: 2026-10-14"

Without the header you get the latest version. Every response echoes the version that served it in Listener-Version. An unknown version answers 400 version_invalid.

Pin the version in production code. When a new version ships, your integration keeps working until you choose to move.

What changes without a new version#

Additive changes ship continuously and do not get a new version. Write your code to tolerate them:

New endpoints.
New optional request parameters.
New fields in responses, and new values in meta.
New event types. Webhook endpoints subscribed to specific types never receive new ones; endpoints subscribed to * do, so ignore types you do not handle.
New error codes within an existing type.
Changes to human-readable message text.

What gets a new version#

Breaking changes ship only as a new dated version, announced in the changelog: removing or renaming a field, changing a field’s type or meaning, changing defaults, or making an optional parameter required.

Webhook endpoints record the version they were created with (api_version), and every event carries api_version too, so you always know which version shaped a payload.

The /v1 path prefix changes only for a complete redesign, which is not planned.