Version Information

These docs describe Printercow version 2 published 03 November 2025.

REST API

Integrate Printercow’s AI-assisted thermal printing into your product with a predictable, secure REST API designed for automation and human-in-the-loop workflows alike.

Last updated: November 10, 2025

Base URL

Production Endpoint

https://api.printercow.com

Keep requests on HTTPS only and prefer relative paths when calling from the same origin in browser-based clients.

Authentication

Printercow authenticates requests with bearer tokens. Create an API key in the dashboard and send it on every request that is not explicitly documented as public.

Authorization: Bearer <your_api_key>

Rotate Keys Regularly

Keys inherit the permissions of their team. Rotate them and remove unused keys to reduce exposure.

Quick Start

1. Create an API key in the Printercow dashboard.
2. Locate your printer ID (prt_*) and optional template IDs (tpl_*).
3. Call /magic for automatic template selection or /print for precise template control.
4. Poll /print-jobs/:publicId/png or subscribe to webhooks to pick up render output.

Endpoints

Each endpoint below lists purpose, parameters, and sample requests. All examples assume JavaScript environments using the native fetch API; replace process.env.PRINTERCOW_KEY with your key management strategy.

GET /magic

Automatically select a template based on freeform input. Ideal for LLM function calls and voice assistant integrations that prefer simple query parameters.

Query Parameters

Name	Type	Required	Description
text	string	Yes	Raw content to print.
printerId	string	Yes	Target printer ID (prt_*).
token	string	Yes	API key or short-lived token.
templateId	string	No	Force a specific template when you do not want automatic selection.

Example Request

curl

curl "https://api.printercow.com/magic" \
  --get \
  --data-urlencode "text=Today’s specials" \
  --data-urlencode "printerId=prt_123" \
  --data-urlencode "token=$PRINTERCOW_KEY"

JavaScript

const response = await fetch(
  `/magic?text=${encodeURIComponent(text)}&printerId=${printerId}&token=${process.env.PRINTERCOW_KEY}`,
  { method: 'GET' }
);
const job = await response.json();

Responses

• 200 OK: Job created and returned in the body.
• 400 Bad Request: Missing required query parameter.
• 403 Forbidden: Invalid token.

POST /print

Render a specific template by providing structured parameters.

Request Body

{
  "printerId": "prt_XU...",
  "templateId": "tpl_JG...",
  "params": [
    {
      "uuid": "questionText",
      "params": {
        "text": "How tall is Mount Everest?"
      }
    },
    {
      "uuid": "answerText",
      "params": {
        "hidden": true,
        "text": "Mount Everest stands at 29,032 feet (8,849 meters)."
      }
    }
  ]
}

Fields

Field	Type	Required	Description
printerId	string	Yes	Printer receiving the job.
templateId	string	Yes	Template to render.
params	array	Yes	Template slot data keyed by uuid.

Example Request

curl

curl "https://api.printercow.com/print" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PRINTERCOW_KEY" \
  -d '{
    "printerId": "prt_XU...",
    "templateId": "tpl_JG...",
    "params": []
  }'

JavaScript

const response = await fetch('https://api.printercow.com/print', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.PRINTERCOW_KEY}`
  },
  body: JSON.stringify(payload)
});
const { publicId } = await response.json();

Responses

• 200 OK: { "publicId": "pjb_waj4CqDxfFCxDhZz" }.
• 400 Bad Request: Template UUID mismatch or malformed body.
• 402 Payment Required: Insufficient print credits.
• 403 Forbidden: Invalid API key or printer outside your team.

GET /print-jobs/:publicId/png

Retrieve a base64-encoded PNG for a finished job.

Path Parameters

Name	Type	Description
publicId	string	Public identifier returned from /print or /magic.

Example Request

curl

curl "https://api.printercow.com/print-jobs/pjb_waj4CqDxfFCxDhZz/png" \
  -H "Authorization: Bearer $PRINTERCOW_KEY"

JavaScript

const response = await fetch(`https://api.printercow.com/print-jobs/${publicId}/png`, {
  headers: {
    Authorization: `Bearer ${process.env.PRINTERCOW_KEY}`
  }
});
const base64Png = await response.text();

Responses

• 200 OK: Returns base64 PNG, e.g. "data:image/png;base64,iVBORw0...".
• 200 OK: Returns null if no PNG buffer is available.
• 403 Forbidden: Missing or invalid credentials.
• 404 Not Found: Print job does not exist or belongs to another team.

GET /printers/:printerId/heartbeats

Fetch device telemetry for monitoring and alerting.

Path & Query Parameters

Name	Type	Required	Description
printerId	string	Yes	Printer ID (prt_*).
page	number	No	1-indexed page (default 1).
limit	number	No	Page size (default 10, max 100).

Example Request

curl

curl "https://api.printercow.com/printers/prt_123/heartbeats?page=1&limit=10" \
  -H "Authorization: Bearer $PRINTERCOW_KEY"

JavaScript

const response = await fetch(`https://api.printercow.com/printers/${printerId}/heartbeats?page=1&limit=10`, {
  headers: {
    Authorization: `Bearer ${process.env.PRINTERCOW_KEY}`
  }
});
const { data, meta } = await response.json();

Sample Response

{
  "data": [
    {
      "id": 123,
      "softwareId": "pcw-agent",
      "timestamp": 1640995200000,
      "version": "1.0.0",
      "osVersion": "Linux 5.10",
      "cpuInPercent": 45.5,
      "memoryInMB": 512,
      "storageInPercent": 75.0,
      "uptimeSeconds": 3600,
      "createdAt": "2025-01-01T00:00:00.000Z"
    }
  ],
  "meta": {
    "total": 100,
    "page": 1,
    "limit": 10,
    "lastPage": 10
  }
}

Responses

• 200 OK: Paginated telemetry.
• 403 Forbidden: Printer outside your team.
• 404 Not Found: Printer ID is invalid.

Error Reference

Status	Meaning	Common Fix
400 Bad Request	Request failed validation.	Check required parameters and template UUIDs.
402 Payment Required	Balance exhausted.	Top up credits or adjust plan.
403 Forbidden	Authentication failed or printer mismatch.	Rotate key, verify printer ownership.
404 Not Found	Resource missing or inaccessible.	Confirm identifiers belong to your team.

Validate Before Sending

Server-side schema validation rejects unknown fields. Trim payloads to the required shape to avoid 400 responses.

Support

Need help or want to report an incident? Email hello@printercow.com or reach out via the dashboard messenger.

---

Happy printing!