Skip to navigation

Build with an agent

How a coding agent reads these docs, an AGENTS.md snippet and prompts for building an integration.
View as Markdown
The API prints on real paper

The API is live and a key prints on real printers. An agent must not call the Tillcast API, create a job or open a printer URL unless you asked it to and told it which printer to use. Give it a key only through an environment variable, never in a prompt or a file. Fetching these docs is fine. An agent installs only @tillcast/sdk from npm and tillcast from PyPI, and no other package named after Tillcast. The npm package called tillcast is empty.

What exists today

These docs are built for agents as well as people. This is what exists now.

  • llms.txt. The page index is at https://docs.tillcast.com/llms.txt. It lists the pages and what each one covers. Each section also has its own llms.txt.
  • Markdown of every page. Add .md to a page URL. For example, https://docs.tillcast.com/concepts/documents.md returns the page on receipt documents as Markdown. The Markdown starts with a short note about the state of Tillcast.
  • Page actions. Every page has Copy page and View as Markdown, and can be opened in Claude or ChatGPT.
  • Docs MCP server. https://docs.tillcast.com/_mcp/server, run by Fern. It searches these docs only and cannot call the Tillcast API.
  • The Tillcast MCP server. https://api.tillcast.com/mcp, with an API key as a bearer token. It is a different server: it calls the Tillcast API for the person who owns the key, and its tools print on real paper. It is for an assistant that its owner connected on purpose, not for an agent that is only writing code. See Connect an AI assistant (MCP).
  • The contract. The API reference is built from the OpenAPI contract of the service, so an agent can read every operation, field and error code there.
  • A short description on the website. https://tillcast.com/llms.txt says what Tillcast is, how to create a job (the endpoint, the key and its scope, the blocks, the idempotency key) and what is not available. The docs are more complete and are the source of truth: when the two differ, trust the docs and tell us.

The first lines of https://docs.tillcast.com/llms.txt invite an agent to connect to https://docs.tillcast.com/_mcp/server. That is Fern’s own text, and the server is the docs search server: it answers from these docs only and cannot call the Tillcast API. It is not the Tillcast MCP server of the entry above, and connecting to it gives an agent no way to print.

Fern does not serve one file with the whole site: llms-full.txt redirects to llms.txt. Read llms.txt first, then fetch only the pages you need. Every page is written to be understood on its own.

Not available

There is no installable skill and no CLI. A template language and stored templates are in development, and OAuth sign-in for the MCP server, OAuth connections, connectors for Make, Zapier and n8n, and webhooks are planned. None of them exists, so an agent must not write code that depends on any of them. The TypeScript and Python SDKs are published as pre-1.0 versions (@tillcast/sdk on npm, tillcast on PyPI), so an agent can use them or call the API over HTTP. See the roadmap.

Testing without printing

There is no safe way to test against the live API

There are no webhooks, and there is no preview call over HTTP. Every key is live and a job prints on a real printer. An organization can use a free trial on real printers, one per organization and per person: 1 month, 250 printed jobs in total, no card to start (terms of service, section 8a). The MCP server has a tool, preview_document, that draws a receipt without printing it, for an assistant that its owner connected. Nothing else it does is a test. Outside an MCP client, draw a receipt with the npm package @tillcast/preview or @tillcast/html-render, which need no key and make no call to Tillcast: see Preview a receipt in your app.

An agent can write and type-check an integration. It cannot run it against Tillcast without a key and a printer that only a person can make. So:

  • Write and type-check the code. Build the receipt as a pure function of the order and test that function on its own.
  • Test with a fake client of your own. Pass your code an object with the same methods that records its calls, or point an SDK client at a stand-in server of your own with baseUrl (TypeScript) or base_url (Python). A client built with only a key calls the live API. See Which server the SDK calls.
  • Do not call the live API to find out what it does, and do not create a job or open a printer URL, unless the owner of the key gave you the key and named the printer. A job that you create and cancel at once is not a test: a printer takes a job within about 5 seconds, so it can print before the cancel.
  • Leave the human steps to a person: sign-up, making the API key (an e-mailed code), adding the printer, typing its URL into the printer, pressing Test print and looking at the paper. The first real call is the owner’s.

AGENTS.md snippet

Add this to the AGENTS.md of a project that will integrate with Tillcast.

## Tillcast (print API for receipt printers)
- The Tillcast API is live at https://api.tillcast.com/v1 and a
key prints on real printers. Do not call it, create a job or
open a printer URL unless asked, and never send a job to a
printer you were not told to use. Fetching the docs is fine.
- Read the docs as Markdown. Fetch
https://docs.tillcast.com/llms.txt for the page index, then
add .md to a page URL.
- The key is in the environment variable TILLCAST_API_KEY. Never
write a real key into code, logs, tickets or prompts.
- A job body has "document", an array of blocks, or
"receiptline", a string of ReceiptLine text. Send exactly one
of the two; both or neither is 422 document_invalid. Use
blocks. Each block has a "type": text, table, row, rule, cut,
feed, barcode, qr or image. For example
{"document": [{"type": "text", "text": "Harbour Cafe",
"align": "center", "bold": true}, {"type": "table",
"columns": ["*", 9], "rows": [["Flat white", "3.40"]]}]}
Put text that is not yours, such as a name or an item, into a
block as it is: nothing in a block is markup, so do not escape
it. Only the "receiptline" text needs escaping, with the
helpers in /concepts/documents. The earlier body
{"document": {"type": "receiptline", "content": "..."}} is
refused with 400. Read /concepts/documents for every block.
- Send an Idempotency-Key header when you create something.
A Star printer gets each job at least once, so a print can
repeat: make a repeated print harmless. An Epson is not
offered a job again, but a job can end failed after it printed.
- Put your own id for an object (an order number, a venue code)
in client_reference_id. It is not unique. Find objects with
GET /v1/jobs?client_reference_id=... Do not send reference or
external_id: those names are refused with 400.
- A printer URL has the form
https://<customer code>.print.tillcast.com/<secret>
The secret in it is a credential. Use a placeholder.
- To set printers up for a vendor's customers (customer,
location, printer), read /provision-a-venue: find before you
create with client_reference_id, a different Idempotency-Key
for each create, the printer URL is shown only in an answer
that issues it (the 201 of the create, a rotation, a move to
another customer; a replay has url null), and a person types
the URL into the printer. Keys are made in the dashboard, never through the API.
- To show a receipt in a web page without printing, use the npm
package `@tillcast/preview` (`npm install @tillcast/preview`,
0.x, no API key, no call to Tillcast to draw). A page with a
strict Content-Security-Policy needs 'wasm-unsafe-eval' in its
script-src, or the receipt is drawn on the integrator's own server
with @tillcast/html-render. Read /preview-a-receipt.
- SDKs (pre-1.0, pin the version, 0.2.0 or later for blocks):
`npm install @tillcast/sdk` for TypeScript and
`pip install tillcast` for Python. The old npm package named
tillcast is empty and points to @tillcast/sdk. In Python write
the blocks as plain dicts. In TypeScript give a document that
is built in a variable the type Tillcast.Block[]. Calling the
API over HTTP also works.
- There is no safe way to test against the live API: no test
mode, no webhooks, no preview call over HTTP. Write and
type-check the code, test it with a fake client of your own,
and leave the first real call to the owner, who gives the
key and names the printer.
- An SDK client built with only a token calls the LIVE API and
prints on paper. Always pass the base URL from a setting that
must be present (baseUrl in TypeScript, base_url in Python,
the address without /v1): a missing value means the live API.
Tillcast has no test server. In tests use a fake client.
- In TypeScript, read the request id of an error from
err.body.error.request_id. err.requestId is undefined,
because it reads a header that the API does not send.
- The SDKs do not retry a timeout or a dropped connection, and
they wait for Retry-After inside the call (queue_full sends
30 seconds). Record the print before the call, retry yourself
with the same Idempotency-Key and the same body, and set
maxRetries (max_retries in Python) to 0 in a request handler.
- The Tillcast MCP server, https://api.tillcast.com/mcp, takes an
API key as a bearer token and acts on the live account: its
tools print on real paper. Do not add it to a project's MCP
configuration or call its tools unless the owner asked you to.
Setup is in /connect-an-ai-assistant. (The docs have another MCP
server, https://docs.tillcast.com/_mcp/server, that searches the
docs and cannot call the API.)
- These do not exist yet and must not be coded against: stored
templates, a "template" or "data" field on a job, OAuth
connectors for Make, Zapier or n8n, OAuth sign-in for the MCP
server and webhooks.
- Verify against https://docs.tillcast.com/llms.txt before you
code against any field, header or method. The docs are the
source of truth and they change: if something is not on a
page there, it does not exist.

Integrating with an AI coding agent

Use this when you tell a coding agent, in the project of a point of sale such as a Next.js app, to integrate Tillcast so that a paid order prints a receipt. Give the agent the brief below as its task. It names the pages to read first and the facts that the pages do not make obvious. If the agent is to set printers up for a vendor’s customers instead, add https://docs.tillcast.com/provision-a-venue.md to the pages to read.

Task: integrate Tillcast, a print API for receipt printers, into this Next.js
point of sale so that a paid order prints a receipt.
Read first, as Markdown: https://tillcast.com/llms.txt, then
https://docs.tillcast.com/llms.txt, then
https://docs.tillcast.com/create-a-print-job.md,
https://docs.tillcast.com/concepts/documents.md,
https://docs.tillcast.com/api/errors.md,
https://docs.tillcast.com/api/idempotency.md,
https://docs.tillcast.com/integrate-a-pos.md and
https://docs.tillcast.com/build-with-an-agent.md. Copy the AGENTS.md snippet of
build-with-an-agent into this repository's AGENTS.md. The docs are the source
of truth.
Facts the pages do not make obvious:
1. The API is https://api.tillcast.com. Use @tillcast/sdk pinned to an exact
version (0.2.0 or later sends blocks). A client built with only a token
calls the LIVE API and prints on real paper: always pass baseUrl (no /v1)
from configuration that must be present, and in tests use a fake client.
2. The key is TILLCAST_API_KEY on the server only (a route handler or a server
action), never NEXT_PUBLIC_ and never in the browser. It needs jobs:write,
jobs:read and printers:read (the Printing preset). The printer id (prn_...)
is in configuration. Send one Idempotency-Key for each print you intend, for
example order-<id>-receipt. A cashier's reprint gets a new key.
3. There is no preview, no dry run and no webhooks over HTTP.
Poll GET /v1/jobs/{id} for the status, no faster than every 5 seconds. Send
only the fields, headers and query parameters the docs list: every create
queues a real job.
4. The SDK does not retry a timeout or a dropped connection. Record the print
before the call, and retry yourself with the same key and the same body. It
waits for Retry-After inside the call (queue_full sends 30 seconds), so use
maxRetries 0 in a request handler (max_retries=0 in Python). On a TypeScript error read
err.body.error.request_id (err.requestId is undefined). queue_full, or a job
that stays queued, means tell a person: do not loop. Delivery is at least
once, so make a repeated print harmless.
5. Some steps only a person can do, and you must not try them: sign-up, making
the API key (an e-mailed code), adding the printer, typing its URL into the
printer, pressing Test print. Do not call the live API, create a job or open
a printer URL unless the owner gave you a key and named the printer. A key
and a printer URL (the last part of it) are passwords: never put one in code,
a log or a prompt. Write the code and type-check it. The first real call is
the owner's.
6. If tools named after Tillcast are among the tools you were given, for
example from a connector the owner added, do not call any that creates,
changes, rotates, moves, suspends or deletes something, or that queues a job
or a test page: they act on the live account and can print on paper.
(preview_document prints nothing, and the tools that only read are fine.)

The sixth fact is about an agent that has tools and not only docs. A connector to a live account acts with the owner’s rights, so an agent that was only asked to write code must not use it to try the integration. The docs are the source of truth for the rest: if a fact in the brief and a page differ, trust the page and tell us.

Prompts

Give one of these prompts to your agent. The first three and the last one read these docs and your code and produce a plan, a checklist or a list of findings, with no calls to Tillcast. The fourth writes code, and runs nothing against Tillcast.

Plan an integration

Give this prompt to your agent:

Read `https://docs.tillcast.com/llms.txt`, then read these pages as Markdown: `https://docs.tillcast.com/concepts/overview.md`, `https://docs.tillcast.com/concepts/printer-url.md`, `https://docs.tillcast.com/concepts/jobs.md`, `https://docs.tillcast.com/concepts/documents.md`, `https://docs.tillcast.com/concepts/suspension.md`, `https://docs.tillcast.com/api/errors.md`, `https://docs.tillcast.com/api/authentication.md` and, if my software will set printers up for its own customers, `https://docs.tillcast.com/provision-a-venue.md`. Then write a plan for printing receipts from my software through Tillcast. Cover which of my records map to organization, customer, location and printer, which key and scope each step needs, how my software will create and track jobs, what it must do when a job is delivered twice, and which steps only a person can do. Do not call the Tillcast API. List every assumption that the docs call planned.

Plan a printer installation

Give this prompt to your agent:

Read these pages as Markdown: `https://docs.tillcast.com/printers/supported-printers.md`, `https://docs.tillcast.com/printers/star-setup.md`, `https://docs.tillcast.com/printers/epson-setup.md`, `https://docs.tillcast.com/printers/first-connection.md` and `https://docs.tillcast.com/printers/troubleshooting.md`. Write a checklist that a person installing a Star or an Epson printer in a hotel can follow with a Tillcast printer URL. Mark every step that the docs say has not been checked on a device. Use placeholders for the URL and never invent a real one.

Review a flow for duplicate prints

Give this prompt to your agent:

Read the Jobs page as Markdown at `https://docs.tillcast.com/concepts/jobs.md` and the Idempotency page at `https://docs.tillcast.com/api/idempotency.md`. Then review the print flow in my code for the case where a printer prints a job twice or a job ends failed after it printed. Show where a duplicate would do harm, such as a kitchen ticket printed twice, and propose a design that detects or tolerates it. Do not call any API.

Write the receipt code

Give this prompt to your agent:

Read `https://docs.tillcast.com/concepts/documents.md` and `https://docs.tillcast.com/api/errors.md` as Markdown. Then write a function in my language that turns one of my orders into a Tillcast job body, `{"document": [...]}`, an array of blocks. Use a text block for the title and a table block for the items, and put every string that comes from my data into the blocks as it is, without escaping it. Write a test that checks a name with braces, underscores and a leading space comes out of the function unchanged. Do not send the request anywhere: stop at the body, and show how the `Idempotency-Key` would be chosen.

Check an integration against the docs

Give this prompt to your agent:

Read `https://docs.tillcast.com/llms.txt`, then `https://docs.tillcast.com/create-a-print-job.md` and `https://docs.tillcast.com/concepts/documents.md` as Markdown. Then read the code in my project that talks to Tillcast. List every endpoint, header, field, block type and SDK method it uses, and for each one the page of the docs that describes it. Flag anything that the docs do not describe, or that they call planned, in development or not available: stored templates, a template or data field, OAuth connectors, OAuth sign-in for the MCP server and webhooks do not exist. Check that a body has `document` or `receiptline`, never both, and that every create call sends an `Idempotency-Key` that is the same on a retry and different for a different request. Do not call the Tillcast API.

When more exists

When webhooks and stored templates exist, these pages will add verifying webhooks with a Standard Webhooks library, templates and the installable skill to the prompts. The Tillcast MCP server has its own page: Connect an AI assistant (MCP). See the roadmap and the Quickstart.