Guides

API Versioning

URL-based versioning with /api/v2 current, the deprecation policy for unversioned routes, and how breaking versus additive changes are handled.

Last updated 2026-07-16View as Markdown

Coinbax APIs are versioned in the URL path. The two surfaces are on different versions:

https://api.coinbax.com/api/v2/transactions     Payments API   — v2, current
https://core.coinbax.com/api/v1/workspaces/me   Workspace API  — v1, current

Every response includes the version header for the surface you called:

X-API-Version: v2

Always build against versioned paths. The version in the URL is the contract: within a version, we do not break you.

Payments API v1 sunsets 1 November 2026

/api/v1 on the Payments API is deprecated. It keeps working until 1 November 2026 and then stops. Every v1 response says so, so you can detect this in code rather than from a calendar:

Deprecation: true
Sunset: Sun, 01 Nov 2026 00:00:00 GMT
Link: <https://api.coinbax.com/api/v2>; rel="successor-version"

v2 documents 36 operations against v1’s 73. Nothing was deleted to get there: one endpoint merged into another, webhook and OAuth-client management moved to the Workspace API where they now have a single home, and the rest were operator or first-party surfaces that no integrator should have been calling.

Four renames matter if you are migrating:

v1 v2
POST /transactions/{id}/submit-hash POST /transactions/{id}/hash
POST /transactions/{id}/submit-escrow-hash POST /transactions/{id}/escrow-hash
POST /transactions/{id}/authorize-release POST /transactions/{id}/release/attest
POST /transactions/{id}/release-early/authorize POST /transactions/{id}/release-early/attest

Plus transactions/batch became transactions/batches, and controls/verify-twilio-sms became controls/twilio-sms/verify.

Two behavioural changes to check rather than assume:

  • v2 is OAuth-only. API keys are not accepted on /api/v2. See Authentication.
  • Scopes changed. Money movement now needs move:transactions and reversals reverse:transactions. A token minted with v1’s cancel:/rescind: scopes will be refused on the v2 equivalents. See Scopes.

Deprecation: unversioned Workspace API routes

Unversioned /api/* routes on the Workspace API predate the versioning scheme. They are deprecated with a sunset of June 2026. They continue to work until then, and every response on a deprecated route carries standard deprecation headers (RFC 8594):

Deprecation: true
Sunset: 2026-06-01
Link: </api/v1>; rel="successor-version"

Migration is mechanical: insert /v1 after /api in your base URL. The handlers are the same; only the path changes.

# Deprecated
https://core.coinbax.com/api/workspaces/me

# Current
https://core.coinbax.com/api/v1/workspaces/me

If your HTTP client can log response headers, alert on Deprecation: true so a deprecated call path cannot hide in your codebase until the sunset date.

How changes are handled

Additive changes (no new version)

Within v1, changes are backward compatible only:

  • New endpoints
  • New optional request fields
  • New response fields
  • New enum values where the field is documented as extensible
  • New webhook event types

Two consequences for your integration:

  1. Ignore unknown response fields. Deserialize leniently; a new field appearing in data is normal and expected.
  2. Subscribe to webhook events by name. New event types will not be delivered to you unless you subscribe to them.

Breaking changes (new version)

Changes that would break a correct client get a new version:

  • Removing or renaming fields or endpoints
  • Changing a field’s type or semantics
  • Restructuring request or response formats

A new version means the old one enters a deprecation window, not an immediate cutoff. The standard timeline:

  1. Day 0. The new version ships; the old version is marked deprecated and starts returning Deprecation and Sunset headers.
  2. Transition window (90 days minimum). Both versions work side by side. Migrate at your pace within the window.
  3. Sunset. The old version is removed on the date in the Sunset header.

Usage of deprecated endpoints is monitored, and integrations still on a deprecated surface near its sunset are contacted before removal.

Practical guidance

  • Pin the versioned base URL in configuration, not in call sites:

    export COINBAX_API_URL=https://api.coinbax.com/api/v2
export COINBAX_CORE_URL=https://core.coinbax.com/api/v1

  • Check for deprecation headers in responses as part of routine monitoring.

  • Test against staging first. Staging receives changes before production, so exercising your integration at https://api-staging.coinbax.com/api/v2 catches surprises early. See staging and testnets.

Next steps