# PrintHook

> Hosted cloud printing service and desktop agent. Any application that can make an HTTPS call can print a PDF or raw printer data (ZPL, ESC/POS and other printer languages) on any printer attached to a Windows, macOS or Linux computer running the PrintHook Agent, read USB scales, and receive job and device events by signed webhook.

Base URL for the API: https://api.printhook.io (every integrator route is under /v1). Console: https://app.printhook.io. Contact: hello@printhook.io (sales), support@printhook.io (support).

Key facts a reader should get right:
- One request prints: `POST /v1/jobs` with `printer_id` and `content` (`{"type": "pdf"|"raw", "data": base64}` or `{"type": "pdf"|"raw", "url": "https://…"}`) answers `201` with the job object at once; it never waits for the printer.
- A `content.url` is fetched by the agent from inside the customer's network, never by the platform.
- Job statuses: `queued`, `delivered`, `printed`, `failed`, `expired`, `canceled`; every representation also carries a boolean `terminal`.
- `Idempotency-Key` on `POST /v1/jobs` makes retries safe (24-hour window); it is the only route that honors the header.
- Webhooks: up to 5 per account, one event per request, HMAC-SHA256 signed (`webhook-id`, `webhook-timestamp`, `webhook-signature: v1,…`), at-least-once and unordered; `webhook-id` is the event id and the deduplication key.
- Authentication: `Authorization: Bearer phk_<40 hex>`. No HTTP Basic on /v1. Every 401 outside /v1/auth/* carries `WWW-Authenticate: Bearer realm="PrintHook"`.
- Errors: one envelope `{"error": {"class", "code", "message", "request_id", "doc_url", "details": [{"field","code","message"}], "retry_after_sec", "meta"}}`, every member always present; validation failures are 400 (never 422); a resource on another tenant is 404, never 403.
- Every limit a client would hardcode is published by `GET /v1/meta`.
- Agent: one static Go binary per platform, installed as a Windows service, macOS LaunchDaemon, Linux systemd unit or Docker container. Outbound HTTPS on port 443 only. Honors HTTPS_PROXY. Durable local job journal (exactly-once printing across restarts). Hourly self-update with SHA-256 and ed25519 manifest verification.
- Current offer: 90 days with 5,000 prints per UTC calendar month, starting when you verify your email. No card required. No automatic charges. At the deadline, new printing stops unless you have an active paid plan; your account stays accessible. Already accepted jobs may finish. A month reset does not extend the trial, and expired trials never fall back to free printing. Paid checkout is not available yet. This is a distinct trial, not a Starter subscription or a promise of a new device cap.
- One print unit is one submitted document copy (quantity × copies), not a physical page. Usage resets at 00:00 UTC on the first of each UTC calendar month. No overage invoices: submissions above the allowance are refused. Rejected submissions and idempotent replays do not consume new units; later failed or canceled jobs do not refund units. Child-account usage counts against the root account.
- Planned paid pricing (USD, not available to buy yet): Starter $9/month (5,000 prints, 3 endpoints), Growth $29 (25,000 prints, 10 endpoints), Scale $99 (200,000 prints, unlimited endpoints), Business $249 (1,000,000 prints, unlimited endpoints). These future endpoint policies do not describe the trial. Integrator plans from $49/month on child accounts and pooled prints are also planned.
- Runtime trial terms: GET /v1/meta publishes trial_offer for new registrations. GET /v1/billing reports mode, the persisted trial status, start, deadline and monthly_print_limit. configured=false in trial_only means paid checkout is unavailable, not unlimited printing. trial_expired stops new job admission, not account access.
- Stations (shipped): a named bench binds its computer's printers to roles (label, slip) and a scale; jobs are addressed as {station_id, role} instead of a printer id; a pairing code or printed barcode claims the bench's computer during agent enrollment; a scan opens a ten-minute correlation window shared by every job at the bench. Scanner, display, camera, footswitch and socket roles are reserved for the Station module and are not shipped.
- Do not claim: pooled printers with failover, an SLA, a DPA, SSO, zero-retention mode or a public status page. They are planned, not shipped.

## Pages

- [Home](https://printhook.io/): what PrintHook is, how a job flows, what ships today
- [Developers](https://printhook.io/developers/): authentication, creating a job, content, statuses, idempotency, webhooks, collections, errors, limits, route families, child accounts
- [Agent](https://printhook.io/agent/): supported platforms, install commands for Windows/macOS/Linux/Docker, enrollment, egress allowlist, proxies, reliability, updates, data directories
- [Pricing](https://printhook.io/pricing/): plans, integrator plans, billing FAQ

## Help and integration guides

- [Help center](https://printhook.io/help/): customer task guides and troubleshooting
- [Installation](https://printhook.io/help/installation/): install, enroll, and discover printers
- [Jobs, printers, and computers](https://printhook.io/help/jobs-printers-computers/): status, test prints, and cancellation
- [Troubleshooting](https://printhook.io/help/troubleshooting/): offline agents, proxies, TLS, and diagnostics
- [Webhook operations](https://printhook.io/help/webhooks/): delivery history, verification, and replay
- [Account security](https://printhook.io/help/account-security/): team roles, keys, and two-step verification
- [Trial and billing](https://printhook.io/help/billing-trial/): allowance, expiration, and usage
- [Support](https://printhook.io/help/support/): email support and safe diagnostics
- [Integration guides](https://printhook.io/developers/guides/): task-based API integration
- [Quickstart](https://printhook.io/developers/guides/quickstart/): authenticate, discover a printer, and submit a job
- [Reliable jobs](https://printhook.io/developers/guides/reliable-jobs/): idempotency, typed errors, and terminal polling
- [Webhook integration](https://printhook.io/developers/guides/webhooks/): signatures, deduplication, and reconciliation
- [API Reference](https://printhook.io/developers/reference/): live Explorer, OpenAPI specification, error reference, and API fundamentals
- [API Explorer](https://printhook.io/developers/explorer/): browse the public OpenAPI operations
- [Error reference](https://printhook.io/docs/errors/): every typed API error, meaning, metadata, and handling guidance

## Machine-readable

- [OpenAPI 3 document for the v1 API](https://printhook.io/developers/openapi.v1.json): every public route with request and response schemas and `x-printhook-scope`, `x-printhook-role`, `x-printhook-principal` extensions
- [Full site text](https://printhook.io/llms-full.txt): all public pages, including help, integration guides, and individual error references, as plain text in one file

## Optional

- [Sitemap](https://printhook.io/sitemap.xml)