Best Practices
Guidelines for building reliable, secure, and efficient integrations with the Printago API.
Scope API Keys to the Minimum Permissions Needed
API keys inherit Printago's full permission model. When you create a key, scope it to exactly the permissions that integration needs — nothing more.
A key for an order automation script gets order and queue permissions. A key for a read-only dashboard gets view-only access. A contractor building an integration gets a key scoped to what they need for that project, revoked when the project ends. If the built-in roles don't fit, individual permissions can be mixed and matched.
One API Key Per Integration
Never share a single API key across multiple integrations. Each integration — an order automation script, a monitoring dashboard, a developer's custom tool — should get its own key.
The reason is isolation. If one integration starts misbehaving — hammering the rate limit, producing errors — you can identify it, revoke just that key, and leave everything else running. With a shared key, you're debugging in the dark and your only option is to kill all access at once.
Lock Down Keys with IP Restrictions
API keys support CIDR-based IP allowlisting. A key can be restricted to specific IP ranges — your server, your office network, a contractor's known IP. Requests from outside the allowlist are rejected regardless of whether the key itself is valid.
Even if a key is exposed, it's only usable from trusted network locations. For production automation running from a fixed server, there's no reason not to lock it down.
Use Push, Not Poll
Printago provides two push-based mechanisms for staying in sync with your print farm. Use them instead of polling.
Polling is inefficient, eats into rate limits, and gives you data that's only as fresh as your poll interval. Push and stream instead.
Build Against the OpenAPI Spec
The API is versioned, and Printago maintains backwards compatibility within versions. Integrations you build today won't break because of a platform update.
The live OpenAPI specification is always available for download from the API Keys portal. It's generated from the running platform, not maintained separately — so it's always accurate. If you're building against the API, start with the spec. It's the authoritative source for endpoint behavior, field names, and data types.
This developer portal is also auto-generated from the live platform, so it stays current as the API evolves.
AI Agent Integration
Printago's structured API, consistent conventions, and comprehensive documentation are designed to be consumed by AI agents as much as by humans. The OpenAPI spec and this developer portal are oriented toward machine consumption.
Printago publishes a Claude Code skill that lets you manage your print farm through natural language — query queue status, manage parts, fulfill orders, generate reports. It's an example of what's possible when the underlying API is built for programmatic consumption, and a practical tool for operators who want to work faster without writing custom scripts.
Retry Safely
Networks fail, and a request that times out may or may not have been applied. Apart from the endpoint below, the API
does not support an Idempotency-Key header, so whether a retry is safe depends on the operation:
GET requests and POST …/search only read data. Requesting signed URLs (POST /v1/storage/signed-upload-urls, POST /v1/storage/signed-urls) is also safe — each call just returns fresh URLs — as is repeating the PUT of a file to the same upload URL.PUT and PATCH requests that set a record's fields to values you supply (e.g. PATCH /v1/parts/{id}) end in the same state however many times they run.DELETE is harmless. Most delete endpoints succeed again when the record is already gone; some answer 404 instead, so treat a 404 on a retried delete as success.POST requests that create something — parts, orders, builds (POST /v2/builds queues print jobs) — are not idempotent: a blind retry can create a duplicate. The same goes for action endpoints that change state, such as PATCH /v1/print-jobs/cancel, …/retry or POST /v1/print-jobs/{id}/send-to-printer. Before retrying, look for the result of the first attempt (for example list records filtered on createdAt.gte and a name or external ID you set), and only resend if it is not there.POST /v1/qr-tags/execute takes an Idempotency-Key header (up to 128 characters). Send one key per action and reuse it on retries: a key that already finished returns its first response without running again, a key still running answers 409, and a failed attempt frees its key. Keys expire after 24 hours. No other endpoint reads this header.
Retry 429 and 5xx responses and network errors with exponential backoff and jitter, applying the rules above to decide whether a write can be resent.
Summary
- Scope every API key to the minimum permissions required
- Create one API key per integration — never share keys
- Use CIDR-based IP restrictions on production keys
- Revoke keys immediately when an integration is decommissioned
- Use webhooks for event-driven workflows, MQTT for real-time state
- Never poll when a push mechanism is available
- Back off exponentially on 429 and 5xx; check before retrying a create
- Build against the OpenAPI spec — it's always up to date
- Rely on API versioning for backwards compatibility