API Reference

Introduction

Print Studio exposes a JSON HTTP API for rendering designs from saved templates. You provide a template_id and a set of field values (text, colors, image URLs) — the service substitutes them into the template, renders a print-ready PDF with optional CMYK conversion, and returns a signed CDN URL.

The API is plain HTTP + JSON, which means you can drive it from n8n, Make.com, Zapier, Pipedream, Activepieces, Retool Workflows, or any cURL-friendly tool — no SDK to install. Every endpoint card below ships with a dedicated n8n / Make tab that you can copy straight into an HTTP Request node.

Two rendering modes are available: synchronous (POST /api/process) which blocks until the PDF is ready and returns the URL directly, and asynchronous (POST /api/jobs) which returns a jobId immediately and lets you poll for completion. Use sync for low-volume / user-facing flows and most n8n workflows; use async for bulk batches, scheduled runs, or long-running renders that exceed the platform's HTTP timeout.

Use with n8n / Make / Zapier

Every endpoint below ships with a paste-ready cURL on its n8n / Make tab. The flow is the same on every platform: copy the cURL, paste it into your HTTP step, replace YOUR_API_SECRET_KEY with your real key (or a credential reference), and hit run.

Security: the API_SECRET_KEY is a server-side credential. Always store it as an n8n Header Auth credential / Make connection / Zapier hidden field and reference it from the workflow — never paste the raw key into a shared scenario or a browser-side automation.

Authentication

All integration endpoints require a server-side API key, passed as a Bearer token:

Authorization: Bearer ps_live_<your-key>

Keys are managed from the operations dashboard at /dashboard. From there you can generate keys, set per-endpoint scopes (render, external-jobs, templates:read, jobs:read), revoke keys, and see lifetime usage per key. The plaintext value is shown only once at creation — store it in your partner's secret manager.

A request that authenticates but lacks the scope a route requires returns 403 Insufficient scope. A request with no or an invalid token returns 401 Unauthorized.

Legacy env-var values (API_SECRET_KEY, MAGENTO_API_KEY) are auto-seeded into the dashboard's key database on first run, so any partner already integrated against those tokens keeps working — the values now show up as "Legacy" entries in the dashboard and can be revoked once partners have rotated to a freshly generated key.

Conventions

• All requests and responses use JSON with UTF-8 encoding.
• Field tags must be lowercase snake_case: ^[a-z0-9_]+$.
• Colors can be expressed as { rgb: "#RRGGBB" } or with an explicit CMYK override { rgb: "#RRGGBB", cmyk: { c, m, y, k } }. The renderer picks the right space based on the template's colorProfile.
• Asset URLs (logo, pic) must be publicly reachable HTTPS endpoints returning image/png, image/jpeg, or image/webp under 10 MB.
• Timestamps are ISO 8601 UTC strings.

Errors

Errors return a non-2xx status code and a JSON body of the shape{ error: string, details?: object[] }. Validation errors include adetailsarray with per-field messages.

{
  "error": "Validation failed",
  "details": [
    { "field": "fields.0.tag", "message": "tag must be lowercase letters, numbers, and underscores only" }
  ]
}

Partner Integrations — Magento

A separate intake endpoint for the client's Magento storefront. The web team posts a fixed payload (ContactInfo1–8, Logo / AltLogo, Photo / AltPhoto, ComplimentsOf, CustomerId) and the design is queued under the CustomerId they supplied — so the identifier is the same on both sides.

Field mapping

Alt images & overflow values

• If Logo/Photo HEAD-validates successfully, the corresponding AltLogo/AltPhoto rides along as a visible: false hidden layer on the saved PST. The rendered PDF does NOT include hidden content.
• If the primary URL fails (404, wrong content-type, >10 MB), the alt is promoted into the primary slot. The job is flagged Manual Review and the reason is recorded on the job record.
• Text fields whose tag is not present in the chosen template (e.g. custom_1/2/3 when the template only has company_name and phone) become hidden text layers in the same way. Manual Review is flagged.
• All such jobs appear in the Operations dashboard with an amber Review badge so the print team can open the PST and decide what to keep, move, or delete before sending to press.

CustomerId rules

• The value of CustomerId is used verbatim as the BullMQ job id, the S3 storage prefix, and the identifier returned to the partner.
• Allowed characters: [a-zA-Z0-9_-] (max 128 chars).
• Posting the same CustomerId twice returns 409 Conflict — the partner must mint a new id to retry. We never silently overwrite a prior design.

Retries

A 5xx response means our backend was temporarily unavailable — retry the same request with exponential backoff (e.g. 1s, 5s, 30s). Retries are safe because of CustomerId deduplication: a CustomerId that was already queued by an earlier attempt returns 409 instead of creating a second job, so you will never accidentally render the same design twice.