> ## Documentation Index
> Fetch the complete documentation index at: https://developers.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-next.dealroom.co/api/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) | `2027-09-01` |

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

## Current versions

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

## Pinning a version

We recommend pinning your API key to a specific version. This is done during API key creation
or via the dashboard. Pinned versions are applied automatically — you don't need to send the
`API-Version` header on every request.

## 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 **365 days** from when `Deprecation` and `Sunset` headers first appear to complete
your migration.

## Changelog

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