Skip to main content
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: 
curl "https://api.dealroom.co/api/entities?sort=-launch_year&limit=1" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "API-Version: 2026-03-16" \
  -H "User-Agent: MyApp/1.0 (you@example.com)" \
  -H "X-Client-Id: YOUR_CLIENT_ID"
If omitted, the latest version is used automatically.

​
Response headers

Every response includes version metadata:
HeaderDescriptionExample
API-VersionThe version applied to this request2026-03-16
DeprecationDate the version was deprecated (if applicable)2026-09-01
SunsetDate 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

VersionStatusNotes
2026-03-16CurrentLaunch version

​
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

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

​
Version no longer supported

{
  "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

VersionTypeChange
2026-03-16—Initial launch version