> Tillcast is live: the API at https://api.tillcast.com/v1 and the dashboard at https://dashboard.tillcast.com. A key prints on real printers, so do not call the API unless asked. A job carries its receipt as "document", an array of blocks (the recommended way), or as "receiptline", ReceiptLine text, exactly one of the two: read https://docs.tillcast.com/create-a-print-job.md and https://docs.tillcast.com/concepts/documents.md before you write a job body. Do not code against what does not exist yet: webhooks, a template language, stored templates (a job has no template field), OAuth connections and connectors for Make, Zapier and n8n, and OAuth sign-in for the MCP server. SDKs for TypeScript (@tillcast/sdk, version 0.2.0 or later for blocks) and Python (tillcast) exist as pre-1.0 versions. To show a receipt in a web page without printing, there are the npm packages @tillcast/preview and @tillcast/html-render (0.x, no API key, no call to Tillcast to draw): read https://docs.tillcast.com/preview-a-receipt.md. The docs are the source of truth: check the index https://docs.tillcast.com/llms.txt and https://docs.tillcast.com/roadmap.md before you code against anything. For clean Markdown of any page, append .md to the page URL. The Tillcast MCP server is live at https://api.tillcast.com/mcp and takes an API key as a bearer token (setup: https://docs.tillcast.com/connect-an-ai-assistant.md). It acts on the live account and its tools print on real paper, so do not connect to it or call its tools unless the owner asked you to. The MCP server at https://docs.tillcast.com/_mcp/server is a different one: it only searches these docs and cannot call the Tillcast API.

# Versioning

> How Tillcast API versions work: the dated Tillcast-Version header, what counts as a breaking change, 6 months' notice before one, and 12 months for an old version date.

## 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.

```bash wordWrap
curl https://api.tillcast.com/v1/printers \
  -H "Authorization: Bearer $TILLCAST_API_KEY" \
  -H "Tillcast-Version: 2026-10-01"
```

* 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 `/v1` stays. 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 `code` for 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](/api/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](/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](https://tillcast.com/legal/terms/).

* **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](/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-Version` header 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 `/v1` and `/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](/api/rate-limits).

## 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](/events/webhooks).

## 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](/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](/getting-started/sdks).

## Changes

Changes to the API are listed in the [changelog](/changelog).