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. Accepts a template ID, a team slug (e.g., shipping-label), or a library-qualified slug (e.g., carbon:product-2x1). See Template Libraries.
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 raster output. Default: 300 for PNG, 203 for ZPL. Ignored for PDF and HTML.
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 (by slug)

curl -X POST https://api.binderypress.dev/v1/render \
  -H "Authorization: Bearer bp_sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "shipping-label",
    "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",
    "dpi": 203,
    "delivery": "inline"
  }' \
  -o label.zpl

ZPL output is bitmap-based

ZPL output is rendered as a full-page bitmap using ZPL ^GFA (Graphic Field ASCII) encoding. The template is rendered to HTML, rasterized to PNG at the specified DPI, then converted to a 1-bit monochrome bitmap. This means every template feature (fonts, gradients, rounded corners, images) renders identically on thermal printers. Typical output is 100-150 KB for a 4x6“ label at 203 DPI. Set dpi to match your printer (203 for standard thermal, 300 for high-resolution).

Render a library 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": "carbon:product-2x1",
    "data": { "sku": "WIDGET-001", "name": "Widget A" },
    "format": "pdf"
  }'

Library templates use the librarySlug:templateSlug format. See Template Libraries for details.

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.