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

# List printers

GET https://api.tillcast.com/v1/printers

Every printer of your organization (or of the key's customer), with its
status, in the order of customer, location and creation. A list across the
whole organization is slow and costs more than the others: add `customer`
or `location` when you can (the lists under `/customers/{customer}/printers`
and `/locations/{location}/printers` are the same lists), and use `status`
with either. With `client_reference_id` the list holds every printer that
carries that value (it is not unique), by id, narrowed to the `customer`
and the `location` when you name them; an unknown value is an empty list. A
customer or a location that is not yours is `404`. A list does not carry
`profile` or `print_options`: retrieve the printer for them.
A search reads only so many rows in one request: it may answer fewer
than `limit` objects, even none, with `has_more` true and a
`next_cursor`, which you send as `starting_after` (or `ending_before`)
to go on until `has_more` is false.

**Scope:** `printers:read`.

Reference: https://docs.tillcast.com/api-reference/printers/list

## Authentication

- `Authorization` header (bearer token, required) — A restricted API key, `tc_rk_live_` and 32 characters. Send it as `Authorization: Bearer <key>`. A key lists its scopes, and each operation below names the one it needs; a key may also be limited to one customer. An owner or a developer of the organization makes a key in the dashboard, under API keys, after a code sent to their e-mail. The key is shown once, when it is made. An owner or a developer can revoke it there, and a revoked key stops working within a minute.

## Request

### Query parameters

- `limit` (integer, optional) — How many objects a page holds, 1 to 100. The default is 10.
- `starting_after` (string, optional) — The id of the last object of the page you hold: returns the page that follows it. In a search by `client_reference_id` the answer can be a short page, or none, with `has_more` true and a `next_cursor`: send that instead, and go on until `has_more` is false.
- `ending_before` (string, optional) — The id of the first object of the page you hold: returns the page that precedes it. Not together with `starting_after`. In a search by `client_reference_id` read backward, the `next_cursor` of the answer when it has one.
- `client_reference_id` (string, optional) — Only the printers that carry this client reference id (1 to 128 characters). It is not unique, so the list can hold many; an unknown value is an empty list.
- `customer` (string, optional) — Only the printers of this customer: its id.
- `location` (string, optional) — Only the printers of this location: its id.
- `status` (enum, optional) — Only printers with this status. Needs `customer` or `location`.
  - Allowed values: `never_connected`, `online`, `offline`, `wrong_host`, `mac_mismatch`, `customer_suspended`, `location_suspended`

## Response

### 200

A page of printers.

- `data` (list of PrinterObject, required)
- `has_more` (boolean, required) — Whether another page follows. Ask for it with `starting_after` set to the id of the last object here, or, when the answer has a `next_cursor`, with that. A search by `client_reference_id` can answer a short page, or none, with `has_more` true: it reads only so many rows in one request, and `next_cursor` is the way on.
- `object` (string, required) — Always `list`.
- `next_cursor` (string, optional) — Only in the answer to a search (`client_reference_id`) that stopped before it could fill the page: it read all the rows it may in one request. Then `data` holds what it found so far, possibly nothing, `has_more` is true, and this is the position to continue from: pass it as `starting_after` (or as `ending_before`, if you page backward) in place of the id of the last object. It is an id of the kind of the list, but not necessarily the id of an object in `data`. Left out otherwise.

## Errors

### 400 Bad Request Error

The request is malformed or a parameter is invalid.

- `error` (ErrorObject, required)

### 401 Unauthorized Error

The key (or token) is missing or not valid.

- `error` (ErrorObject, required)

### 403 Forbidden Error

Not allowed.

- `error` (ErrorObject, required)

### 404 Not Found Error

There is no such object, or it is another organization's.

- `error` (ErrorObject, required)

### 500 Internal Server Error

A problem on Tillcast's side.

- `error` (ErrorObject, required)

## Types

### PrinterObject

A printer. The secret of its URL is not here: it is shown once, when the printer is created.

- `allowed_mac` (string, required, nullable) — The one device allowed to use this printer's address; `null` means that any device that holds the address is accepted. See `allowed_mac` of the request that sets it.
- `auth_error_at` (string, required, nullable) — When a refused request last left a hint: `wrong_host` (the host is not the printer's) or `mac_mismatch` (the address names an allowed device and another device connected). `null` when there is none.
- `brand` (string, required, nullable) — Read from the printer itself; `null` until it has connected and answered. It cannot be set through the API. Text the printer sent, kept to ASCII letters, digits and `. _ - + ( ) /`: a claim of whoever holds the printer's address, not verified. Treat it as untrusted text.
- `client_reference_id` (string, required, nullable) — The id of this printer in your own system, such as `kitchen-1`, or `null`. Not unique: the same value can be on many objects, and `GET /v1/printers?client_reference_id=` lists every printer that carries it. `null` for every printer made before the field existed.
- `condition` (list of string, required) — What the printer reports is wrong: `paper_low`, `paper_out`, `cover_open`, `jam` or `error`.
- `connection` (string, required) — `never_connected`, `connected` or `disconnected` (the printer has connected and has not polled for about 4 minutes: its `status` is `offline` unless a suspension or a refused request comes first).
- `created_at` (string, required)
- `customer` (string, required)
- `id` (string, required)
- `location` (string, required)
- `mac` (string, required, nullable) — The MAC address the printer reported on its last accepted poll. For display only: it never addresses or authenticates a printer, and it is a claim by whoever polled with the address secret, not a verified fact. `null` until the first poll, and for a printer that does not report one.
- `mode` (string, required)
- `model` (string, required, nullable) — Read from the printer itself; `null` until it has connected and answered. It cannot be set through the API. Text the printer sent, kept to ASCII letters, digits and `. _ - + ( ) /`: a claim of whoever holds the printer's address, not verified. Treat it as untrusted text.
- `name` (string, required)
- `object` (string, required)
- `pending_jobs` (integer, required) — Jobs waiting for the printer that have not expired.
- `reported_mac` (string, required, nullable) — While `status` is `mac_mismatch`: the MAC address of the device that was refused, taken from the refused request. Also a claim: compare it with the label of your printer before you allow it. `null` otherwise.
- `status` (string, required) — `never_connected`, `online`, `offline` (the printer has connected and has not polled for about 4 minutes), `wrong_host`, `mac_mismatch` (the address names an allowed device and another device connected), `customer_suspended` or `location_suspended`.
- `status_code` (string, required, nullable) — The printer's last status code, such as `200 OK`.
- `vendor` (string, required) — `star` or `epson`: set when the printer is made and never changed (see `vendor` of the request that adds a printer), with one exception: a printer made with `paper_width` and no maker reads `star` until its first connection names the maker, once (`vendor_source` says which case it is).
- `detection` (string, optional, nullable) — What is left for the server to settle on the printer. `pending`: it was made with `paper_width` and nothing that names its maker, and has not been settled yet (its maker is set by its first connection, and a Star's width by what the printer reports). `undetected`: a Star reported something Tillcast cannot print on yet (Star Line mode, 104 mm paper), or nothing usable, so it prints with the default of its paper. `done`: every other printer, one made before this field included. A plain string and not an enum. Only in the answer to a single printer, not in a list.
- `domain` (string, optional, nullable) — The printer domain the printer's URL is on: `print.tillcast.com`, or a domain that Tillcast has set up for your organization. The host of the URL is `<code of the customer>.<domain>`: the code is Tillcast's own random code of the customer (the part of the customer's id after `cus_`), never an id of yours. It is recorded when the printer is made and kept when its secret is replaced. Only in the answer to a single printer, not in a list.
- `last_seen_at` (string, optional, nullable) — When the printer last polled us. Only in the answer to a single printer.
- `paper_width` (string, optional, nullable) — The paper the printer was made for: `58mm`, `80mm`, or `null` when it was made without `paper_width`. Set when the printer is made and never changed. Only in the answer to a single printer, not in a list.
- `print_options` (PrintOptions, optional, nullable) — What can be set on top of a profile, each field optional. A field left out keeps the profile's own value. The ranges are checked when the printer is made or changed: a value outside its range, or an `encoding` the profile does not take, is `422 print_options_invalid` naming the field.
- `profile` (string, optional, nullable) — The profile documents are rendered for (command set, paper width in characters and text encoding): the id of a preset, the one set with `profile` or, while none is set, the default of the printer's `vendor` (`star-starprnt-utf8-80mm` for a `star` printer, `epson-80mm-48` for an `epson` one). It is the profile the printer prints with, also for a printer made before profiles could be chosen, and, for a printer made with `paper_width` and no profile, the one detected from the printer or confirmed on paper (`profile_source` says which). A plain string and not an enum, so that a profile that is retired never breaks a client; `x-tillcast-profiles` of the contract lists the ones a printer can be set to. Only in the answer to a single printer, not in a list.
- `profile_source` (string, optional, nullable) — Where `profile` comes from. `default`: nobody chose, so the default of the paper and the maker applies. `detected`: a Star's own report chose the width. `confirmed`: a calibration code chose it. `explicit`: a request or an edit named it, and every printer made before this field existed. A plain string and not an enum, so that a word added later never breaks a client. Only in the answer to a single printer, not in a list.
- `vendor_source` (string, optional, nullable) — Where `vendor` comes from. `default`: no maker was named, so the printer reads `star` until its first connection names the maker. `detected`: the first connection decided it. `explicit`: the request that made the printer named it, or the printer was made without `paper_width`, or before that field existed: the server never changes an explicit maker. A plain string and not an enum, so that a word added later never breaks a client. Only in the answer to a single printer, not in a list.
- `welcome_print` (boolean, optional, nullable) — Whether the printer prints a welcome receipt on its first connection. An `epson` printer prints none: it reads `false`. Only in the answer to a single printer.

### ErrorObject

- `code` (string, required) — A stable code to branch on. The ones known today are listed in `x-codes` of this schema; a new one can be added, so a client treats a code it does not know by the HTTP status.
- `message` (string, required) — A sentence for a person. Do not parse it.
- `param` (string, required, nullable) — The request parameter the error is about, if one.
- `request_id` (string, required) — Quote it when you ask for help.
- `type` (string, required) — The kind of error: `invalid_request_error`, `authentication_error`, `permission_error`, `conflict_error`, `idempotency_error`, `rate_limit_error` or `api_error`.

### PrintOptions

What can be set on top of a profile, each field optional. A field left out keeps the profile's own value. The ranges are checked when the printer is made or changed: a value outside its range, or an `encoding` the profile does not take, is `422 print_options_invalid` naming the field.

- `cpl` (long, optional, nullable) — Characters per line, 16 to 96. Left out, the profile's own width, which is the one that fits the paper of the profile.
- `cutting` (boolean, optional, nullable) — Cut the paper at the end of the document. On, unless the profile says otherwise.
- `encoding` (enum, optional, nullable) — The character set of the text sent to the printer. A character the set does not have prints as `?`, and a warning says where.
  - Allowed values: `cp437`, `cp852`, `cp858`, `cp860`, `cp863`, `cp865`, `cp866`, `cp1252`, `multilingual`
- `gamma` (double, optional, nullable) — The gamma of images, 0.1 to 10.
- `gradient` (boolean, optional, nullable) — Dither images with error diffusion, which is smoother, instead of a plain threshold.
- `margin` (long, optional, nullable) — The left margin in characters, 0 to 24.
- `margin_right` (long, optional, nullable) — The right margin in characters, 0 to 24. The renderer reads it for a few kinds of content only (mostly images and QR codes printed upside down); where it does not, a value is accepted and changes nothing.
- `spacing` (boolean, optional, nullable) — Wider line spacing.
- `threshold` (long, optional, nullable) — The brightness at which an image pixel prints black, 1 to 255.
- `upside_down` (boolean, optional, nullable) — Print the document turned by 180 degrees.

## Examples

**Response**

```json
{
  "data": [
    {
      "allowed_mac": "00:11:62:00:00:01",
      "auth_error_at": null,
      "brand": "Star",
      "client_reference_id": "kitchen-1",
      "condition": [],
      "connection": "connected",
      "created_at": "2026-10-11T09:25:00Z",
      "customer": "cus_c3x9k2m3",
      "id": "prn_01M44X7TQ0A9R2H5J8K1M4N7P0",
      "location": "loc_01M42YMFP03Q1P9N7M5K3H1G0F",
      "mac": "00:11:62:00:00:01",
      "mode": "live",
      "model": "mC-Print3",
      "name": "Reception left",
      "object": "printer",
      "pending_jobs": 0,
      "reported_mac": null,
      "status": "online",
      "status_code": "200 OK",
      "vendor": "star",
      "domain": "print.tillcast.com",
      "profile": "star-starprnt-utf8-80mm"
    }
  ],
  "has_more": false,
  "object": "list"
}
```

**SDK Code**

```python
import requests

url = "https://api.tillcast.com/v1/printers"

querystring = {"client_reference_id":"kitchen-1","customer":"cus_c3x9k2m3","limit":"25","location":"loc_01M42YMFP03Q1P9N7M5K3H1G0F","starting_after":"cus_c3x9k2m3","status":"online"}

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript
const url = 'https://api.tillcast.com/v1/printers?client_reference_id=kitchen-1&customer=cus_c3x9k2m3&limit=25&location=loc_01M42YMFP03Q1P9N7M5K3H1G0F&starting_after=cus_c3x9k2m3&status=online';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tillcast.com/v1/printers?client_reference_id=kitchen-1&customer=cus_c3x9k2m3&limit=25&location=loc_01M42YMFP03Q1P9N7M5K3H1G0F&starting_after=cus_c3x9k2m3&status=online"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.tillcast.com/v1/printers?client_reference_id=kitchen-1&customer=cus_c3x9k2m3&limit=25&location=loc_01M42YMFP03Q1P9N7M5K3H1G0F&starting_after=cus_c3x9k2m3&status=online")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.tillcast.com/v1/printers?client_reference_id=kitchen-1&customer=cus_c3x9k2m3&limit=25&location=loc_01M42YMFP03Q1P9N7M5K3H1G0F&starting_after=cus_c3x9k2m3&status=online")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.tillcast.com/v1/printers?client_reference_id=kitchen-1&customer=cus_c3x9k2m3&limit=25&location=loc_01M42YMFP03Q1P9N7M5K3H1G0F&starting_after=cus_c3x9k2m3&status=online', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.tillcast.com/v1/printers?client_reference_id=kitchen-1&customer=cus_c3x9k2m3&limit=25&location=loc_01M42YMFP03Q1P9N7M5K3H1G0F&starting_after=cus_c3x9k2m3&status=online");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.tillcast.com/v1/printers?client_reference_id=kitchen-1&customer=cus_c3x9k2m3&limit=25&location=loc_01M42YMFP03Q1P9N7M5K3H1G0F&starting_after=cus_c3x9k2m3&status=online")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```