Skip to content
Documentation menu

API

API Overview

The render endpoint, API keys, responses and errors (RFC 9457 problem details).

The Prynt API renders published templates on demand. It is a JSON over HTTPS API: requests carry an API key, successful renders return the document itself, and every failure is a machine-readable problem document.

Base URL

All endpoints live under /api/v1 of the Prynt API, https://api.prynt.it. It is served over HTTPS only, from the European Union. The API reference lists every endpoint.

API keys

Servers authenticate with an API key in the Authorization header, as a bearer token. Keys belong to one workspace, and test keys can never render with production data (see Authentication).

Authorization: Bearer prynt_live_...
  • Create keys in Developers → API keys. The full key is shown once; Prynt stores only a hash.
  • Live keys start with prynt_live_, test keys (development and staging) with prynt_test_: a leaked key is easy to recognize, and secret scanners can find it.
  • Keep keys on the server side: in configuration or a secret manager, never in browser or mobile code.
  • Rotate by creating a new key, deploying it, then revoking the old one. Revocation is immediate.

Never expose a key in a browser

Anyone holding a key can render documents with the data of its environment. If a key leaks, revoke it at once.

Render a document

POST https://api.prynt.it/api/v1/render renders the version of a template published to an environment, with the parameters you pass.

Request body
{  "template": "invoice",  "environment": "production",  "parameters": { "invoiceId": 18425 }}
Fields of the render request
FieldTypeDescription
templaterequiredstringCode of the template, as set when it was created (e.g. invoice).
environmentstringEnvironment whose data sources are used: development, staging or production. Omitted = the key's default environment.
parametersobjectValues of the template parameters, by name. Types are checked against the template before any query runs. Omit it for templates without parameters.

Examples

1curl -X POST https://api.prynt.it/api/v1/render \2  -H "Authorization: Bearer prynt_live_..." \3  -H "Content-Type: application/json" \4  -d '{5    "template": "invoice",6    "environment": "production",7    "parameters": { "invoiceId": 18425 }8  }' \9  -o invoice-18425.pdf

Responses

A successful render answers 200 OK with the document as the body: application/pdf for documents, application/zpl for label templates. Headers carry the suggested file name and the correlation ID.

Response headers
HTTP/1.1 200 OKContent-Type: application/pdfContent-Length: 48213Content-Disposition: attachment; filename="invoice-18425.pdf"X-Correlation-ID: 4bf92f3577b34da6a3ce929d0e0e4736

Errors

Errors follow RFC 9457 (Problem Details for HTTP APIs), with Content-Type: application/problem+json. Besides the standard members, every problem carries a stable errorCode to branch on and the correlationId of the request. Do not parse title or detail: they are meant for people and may change.

400 Bad Request
{  "type": "about:blank",  "title": "Invalid parameter",  "status": 400,  "detail": "Parameter invoiceId must be an integer.",  "errorCode": "PARAMETER_INVALID",  "correlationId": "4bf92f3577b34da6a3ce929d0e0e4736"}
Error codes of the render endpoint
StatuserrorCodeMeaning
400VALIDATION_FAILEDThe request body is malformed or a field is missing.
400PARAMETER_INVALIDA parameter is missing or its value does not match its declared type.
401API_KEY_INVALIDThe API key is missing, malformed or unknown (also API_KEY_REVOKED, API_KEY_EXPIRED).
403SCOPE_MISSINGThe key is valid but lacks the scope of the endpoint (also ENVIRONMENT_NOT_ALLOWED, WORKSPACE_MISMATCH).
404TEMPLATE_NOT_FOUNDNo template with this code in the key's workspace.
404TEMPLATE_NOT_PUBLISHEDThe template has no published version.
409TEMPLATE_DISABLEDThe template is disabled.
422RENDER_FAILEDThe data was read but the document could not be produced (expression or layout error).
422DATASET_FAILEDA dataset could not be read from the data source.
429RATE_LIMITEDToo many requests. Wait for the seconds in the Retry-After header.
503RENDER_BUSYThe render capacity is saturated. Retry with exponential backoff, or render asynchronously.
500INTERNAL_ERRORUnexpected failure. Quote the correlationId to support.

Retry only 429 and 503 (and network failures), with exponential backoff. Other 4xx errors need a change in the request or in the template.

Correlation IDs

Every response carries an X-Correlation-ID header, also present in problem documents. Send your own with the request header of the same name to follow a document from your logs to Prynt's run history; otherwise one is generated.