# API Versioning

> URL-based versioning with /api/v1 current, the deprecation policy for unversioned routes, and how breaking versus additive changes are handled.
> Source: https://developers.coinbax.com/docs/resources/versioning
> Last updated: 2026-07-16

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.

```bash
# 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:

  ```bash
  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](/docs/resources/staging-and-testnets).

## Next steps

- [Errors and the response envelope](/docs/api/errors): the stable response contract within a version
- [Payments API reference](/reference/coinbax-api/): the current v1 surface