> ## Documentation Index
> Fetch the complete documentation index at: https://developers.beta.dealroom.co/llms.txt
> Use this file to discover all available pages before exploring further.

# API versioning

> Learn how the Dealroom API uses Stripe-style date-based versioning to handle breaking changes while keeping existing integrations stable.

The Dealroom API uses **date-based versioning** (Stripe-style). Every breaking change is
assigned a calendar date. Clients pin a version; the API downgrades responses and upgrades
requests automatically so your integration keeps working without immediate code changes.

## Specifying a version

Send the `API-Version` header with a `YYYY-MM-DD` date:

```bash theme={null}
curl "https://api.beta.dealroom.app/data/entities?sort=-launch_date&limit=1" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "API-Version: 2026-03-16" \
  -H "X-Client-Id: YOUR_CLIENT_ID"
```

If omitted, the **latest version** is used automatically.

## Response headers

Every response includes version metadata:

| Header        | Description                                        | Example      |
| ------------- | -------------------------------------------------- | ------------ |
| `API-Version` | The version applied to this request                | `2026-03-16` |
| `Deprecation` | Date the version was deprecated (if applicable)    | `2026-09-01` |
| `Sunset`      | Date the version will stop working (if applicable) | `2026-10-01` |

`Deprecation` and `Sunset` only appear when you're on an older version than the latest.
When you see these headers, you have **30 days** to migrate before the version is retired.

The Dealroom API is in Early Access and under active development. A pinned version is supported
for **30 days** past the date it is superseded; after that it returns `400`. (This window widens
to 90 days at general availability.)

## Current versions

See the [Changelog](/changelog) tab for the full list of API versions, their status
(current, deprecated, sunset), and migration notes for each release.

## Pinning a version

Pin a version by sending the `API-Version` header on each request (see
[Specifying a version](#specifying-a-version) above). Omit it to use the latest version.

## Error responses

### Invalid format

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid API-Version header: \"bad-date\". Expected format: YYYY-MM-DD"
  }
}
```

### Version no longer supported

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "API version \"2020-01-01\" is no longer supported. Minimum supported version is 2026-03-16"
  }
}
```

## Migration guide

When a new version is released:

1. Check the changelog (below) to understand what changed.
2. Update your integration to use the new field names, params, or error handling.
3. Test against the new version by sending `API-Version: <new-date>` in requests.
4. Update your pinned version once you're confident the migration is complete.

You have **30 days** from when `Deprecation` and `Sunset` headers first appear to complete
your migration.

## Changelog

See the full [Changelog](/changelog) tab for all version changes, migration guides, and affected endpoints.