Build with an agent
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 ownllms.txt. - Markdown of every page. Add
.mdto a page URL. For example,https://docs.tillcast.com/concepts/documents.mdreturns 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.txtsays 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.
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 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) orbase_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.
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.
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.