Versioning
The version header
The API is versioned by date. A request names its version in the Tillcast-Version header. The current version is 2026-10-01, the only one so far.
- A request without the header gets the current version.
- A date the API does not speak is
400 api_version_unsupported. - Every response says the version it was answered in, in the same header.
- The path prefix
/v1stays. The date is what changes.
Pin your integration to the version you tested, and move to a newer one when you are ready. This is the same approach as Stripe’s Stripe-Version. Send the header from the start. A request without it is answered in whichever version is the current one when it arrives, so the header is what keeps your integration on the behavior you tested when a newer version appears.
No breaking changes within a version date
From the day this page was published, a version date does not change in a way that breaks code written for it. A change that would break such code comes only with a new version date.
These are breaking changes:
- Removing or renaming a field, in a request or in an answer.
- Changing the type of a field.
- A new required field or parameter.
- A different HTTP status code, or a different error
code, for a case that already has one.
These are not breaking changes. They come under the same date:
- A new optional field, in a request or in an answer.
- A new endpoint.
- New detail in an error, including a new error
codefor a case that is new, such as a request that uses a new field.
So write your code to ignore fields it does not know, and to treat an error code it does not know by its HTTP status. See Errors.
Why the rule is written down
The rule did not always hold. On 2026-10-16 the body of a job changed from an object to an array of blocks, under the same date, 2026-10-01. The earlier body is refused. There was no alias and no migration period, and the changelog entry of that day says it was a breaking change. That change is the reason this rule is written down.
When a version or a field goes away
A field is removed or renamed only in a new version date. The older date keeps the field, and a request that names the older date is answered as before, until Tillcast removes that version.
For the REST API at https://api.tillcast.com/v1, Tillcast makes two promises. They are the promises of section 17 of the Terms of service.
- Notice. A breaking change takes effect no earlier than 6 months after Tillcast e-mails the owners of the organization. The change is listed in the changelog.
- Old version dates. A version date that a newer one has replaced stays available for at least 12 months. The date in the
Tillcast-Versionheader picks the version, so a request that names the older date is answered as before for that long. A request without the header is answered in the current version.
After a version is removed, a request that names its date is 400 api_version_unsupported.
What the promises do not cover
The promises are for the REST API at /v1 and for nothing else. These are outside them:
- The MCP server at
https://api.tillcast.com/mcp. It can change without a new version date. - The answer for an address outside
/v1and/mcp. It can change without a new version date. - Limits. A change of a limit, and the enforcement of a rate limit, have their own notice: Tillcast e-mails the owners of the organization at least 30 days before (section 17 of the Terms). See Rate limits and retention.
Webhook endpoints keep their version
Webhooks are planned and not built. A webhook endpoint will keep the version it was created with, and its events will be shaped for that version. See Webhooks and events.
SDK versions
SDKs for TypeScript and Python are generated from the API contract. They are 0.x versions: method names can still change before 1.0, and the changelog says when one does. The promises above are about the REST API, not the SDKs, so pin the SDK version you use. See SDKs.
Changes
Changes to the API are listed in the changelog.