Start building

Start with the sandbox

paperboy is the printer for AIs. The API gives your application, script or agent a structured path from a document to a printing order for a person.

Current stage: sandbox beta. File registration, preflight, prices and fulfilment are simulated. The sandbox does not accept document bytes, charge a payment method, contact a printer or book a delivery. Live purchasing requires explicit activation.

1. Create your credentials

Sign in to the developer console with an organization account. Create a project, then a sandbox application. Create a key with catalog:read, files:write, quotes:write, orders:write and orders:read. Copy the secret immediately and store it in your server's secret manager as PAPERBOY_API_KEY.

If your account has no organization, contact support@paperboy.now to arrange a developer workspace. Organization provisioning is currently assisted. The same API base serves both environments. The application and key determine the environment; pb_test_ identifies sandbox credentials. A live key does not enable live purchasing.

2. Discover a product

Request the catalog and use its product IDs, attribute keys and allowed values. Then check /v1/capabilities with product_id and country_code. Catalog inclusion describes a product; the capability response describes the current ordering gate.

curl https://api.paperboy.now/v1/catalog/products \
  -H "Authorization: Bearer $PAPERBOY_API_KEY"

3. Register and check a simulated file

Create a metadata-only sandbox file. Save the returned id. Run POST /v1/files/{id}/preflight with a different idempotency key and check the returned status. A sandbox pass describes the simulation, including any selected failure scenario.

curl https://api.paperboy.now/v1/files \
  -H "Authorization: Bearer $PAPERBOY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-file-001" \
  -d '{"filename":"brief.pdf","mime_type":"application/pdf","size_bytes":12000,"checksum_sha256":"0000000000000000000000000000000000000000000000000000000000000000"}'

4. Quote, order and observe

Create a quote using the current catalog's product/configuration, destination country and postal code, quantity, and your file_ids. Read its total_minor, currency, expires_at and status. Quote amounts use integer minor units.

Create an order with quote_id and a new idempotency key. Save its id. POST /v1/orders/{id}/advance moves a sandbox lifecycle one step. Read the order and /v1/events to observe the outcome. Use a fresh key for each intended advance; reuse the original key to recover an uncertain request.

The API reference contains the complete request bodies and response schemas. The agent setup guide provides MCP configuration. Every mutation requires an Idempotency-Key header.