POST /v1/render

Render a document from a template and data. Returns either a download URL or the rendered output inline.

Endpoint:

POST /v1/render

Request Body

You can render either a saved template (by ID) or an inline template (passed directly in the request).

Option A — Saved template:

{
  "templateId": "your-template-id",
  "data": { "orderNumber": "ORD-9876", "customer": "Acme Corp" },
  "format": "pdf"
}

Option B — Inline template:

{
  "template": {
    "formatVersion": 1,
    "meta": { "name": "Badge" },
    "dimensions": { "width": "3in", "height": "2in" },
    "elements": [
      {
        "id": "name",
        "type": "text",
        "position": { "mode": "absolute", "x": "10mm", "y": "15mm" },
        "width": "60mm",
        "height": "10mm",
        "contentExpression": "attendeeName",
        "style": { "fontSize": "14pt", "fontFamily": "Arial" }
      }
    ]
  },
  "data": { "attendeeName": "Jane Smith" },
  "format": "png"
}

Fields

Field	Type	Required	Description
templateId	string	One of templateId or template is required	ID of a published template (from the dashboard or GET /v1/templates).
template	object	One of templateId or template is required	Inline template object. See Templates for the full schema.
data	object	Yes	Data to bind into the template. Top-level keys become variables in contentExpression bindings.
format	string	Yes	Output format: "pdf", "png", "zpl", or "html".
dpi	number	No	Resolution for PNG output. Default: 300. Ignored for other formats.
delivery	string	No	"url" (default) returns a JSON response with a download URL. "inline" returns the rendered output directly as the response body.

Note

If both templateId and template are provided, the inline template takes precedence.

Response — URL Delivery (default)

Status: 200 OK

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "complete",
  "format": "pdf",
  "url": "https://api.binderypress.dev/v1/render-outputs/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "sizeBytes": 12345,
  "renderTimeMs": 450
}

Field	Type	Description
id	string	Unique render job ID (UUID).
status	string	"complete".
format	string	The output format.
url	string	Download URL. Valid for 7 days.
sizeBytes	number	Output file size in bytes.
renderTimeMs	number	Time spent rendering in milliseconds.

The response also includes rate limit headers.

Response — Inline Delivery

Status: 200 OK

The response body contains the rendered document directly. The Content-Type header matches the format:

Format	Content-Type
pdf	application/pdf
png	image/png
zpl	text/plain
html	text/html

Examples

Render with a saved template

curl -X POST https://api.binderypress.dev/v1/render \
  -H "Authorization: Bearer bp_sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "abc123",
    "data": {
      "orderNumber": "ORD-9876",
      "customer": "Acme Corp",
      "items": [
        { "name": "Widget A", "qty": 10 },
        { "name": "Widget B", "qty": 5 }
      ]
    },
    "format": "pdf"
  }'

Render inline template as PNG

curl -X POST https://api.binderypress.dev/v1/render \
  -H "Authorization: Bearer bp_sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": {
      "formatVersion": 1,
      "meta": { "name": "Badge" },
      "dimensions": { "width": "3in", "height": "2in" },
      "elements": [
        {
          "id": "name",
          "type": "text",
          "position": { "mode": "absolute", "x": "10mm", "y": "15mm" },
          "width": "60mm",
          "height": "10mm",
          "contentExpression": "attendeeName",
          "style": { "fontSize": "20pt", "fontFamily": "Arial", "fontWeight": "bold" }
        }
      ]
    },
    "data": { "attendeeName": "Jane Smith" },
    "format": "png",
    "dpi": 150
  }'

Render ZPL for label printer (inline delivery)

curl -X POST https://api.binderypress.dev/v1/render \
  -H "Authorization: Bearer bp_sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "label-template-id",
    "data": { "sku": "WIDGET-001", "quantity": 50 },
    "format": "zpl",
    "delivery": "inline"
  }' \
  -o label.zpl

Errors

Status	Code	Cause
400	BAD_REQUEST	Missing required fields or invalid format.
400	INVALID_TEMPLATE	Template failed validation. Check details.errors.
401	AUTH_REQUIRED	Missing or invalid API key.
404	NOT_FOUND	Template ID not found (when using templateId).
413	PAYLOAD_TOO_LARGE	Request body exceeds 1 MB.
429	RATE_LIMITED	Too many requests. Retry after the Retry-After period.
429	QUOTA_EXCEEDED	Monthly quota exceeded (hard-capped plans only).
502	RENDER_ERROR	Rendering failed in the container.