Guides

API Versioning

URL-based versioning with /api/v1 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. v1 is the current version across both API surfaces:

https://api.coinbax.com/api/v1/transactions
https://core.coinbax.com/api/v1/workspaces

Every response includes the version header:

X-API-Version: v1

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

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/v1
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/v1 catches surprises early. See staging and testnets.

Next steps