Skip to main content
The Tomorro Public API uses date-based versioning with a codename: YYYY-MM-DD.codename. You send the desired version in a header; the API validates it, runs the matching behavior, and returns the version and any deprecation info in the response.

​
Version format

Versions follow this pattern:
  • Date: YYYY-MM-DD (e.g. 2025-01-29)
  • Codename: lowercase label (e.g. alpha, init, …)
Example: 2025-01-29.alpha.

​
How to specify a version

Send the tomorro-version header on every request: 
curl -X GET "https://api.tomorro.com/v2/members" \
  -H "x-api-key: your-api-key" \
  -H "tomorro-version: 2025-01-29.alpha"
If you omit tomorro-version, the API uses the latest version. We recommend setting the header explicitly so upgrades are intentional.

​
Version lifecycle

Each version has a status:
StatusMeaning
supportedActively supported; use this for new integrations.
deprecatedStill works but scheduled for removal. Migrate to a supported version.
sunsetNo longer available; requests with this version return 410 Gone.
When you call the API with a deprecated version, we still process the request but add extra response headers so you can detect and plan migration:
  • x-api-deprecation-warning: Sent on every response when using a deprecated version. Contains a message (e.g. “This version is deprecated. Please upgrade to 2025-01-29.alpha.”).
  • sunset: The date when the version will be removed. After that date, the same version will return 410 Gone instead of a successful response.
The following timeline illustrates how versions move from release through current, deprecation, and sunset, with new versions introduced at breaking changes:

​
Strategy in short

  1. Header-based: Version is chosen via tomorro-version, not the URL path.
  2. Default to latest: Omitted header implies the current latest version.
  3. Explicit versions: New versions are introduced when we make breaking changes; existing versions stay available until deprecated then sunset.
  4. Stable contract per version: Once a version is released, we do not change its behavior; use a newer version for new features or breaking changes.

​
Current versions

Check the API Reference (version selector in the docs) for the list of available versions and their OpenAPI specs. The docs and reference are split by version so you see the right request/response shapes for each.

​
Best practices

Pin your version

Set tomorro-version explicitly in your client so behavior stays predictable until you choose to upgrade.

Handle deprecation

Read x-api-deprecation-warning and sunset and plan migration before a version is sunset.