Synchronously render a template and stream the file back in the response. The request blocks until the render finishes (typically 2–15 seconds).

POST/v1/renderAuth required

Body parameters

template_idrequired

string (uuid)

ID of a template in your workspace.

actionrequired

string

What to render. Use pdf for the final PDF, preview for a fast raster preview.

pdfpreview

format

string

Output format. Defaults from action (pdf → pdf, preview → png).

pdfpngwebp

datarequired

object

Nested object keyed by field key or section id. The keys a template accepts come from Templates & fields.

scale

number

default: 1

Output scale multiplier for raster formats. Ignored for PDF.

size

string

Render the design at one of the template’s saved sizes (pass the size id). The layout reflows to that box.

width

number

Custom output width in pixels, 16–8000. Must be sent together with height.

height

number

Custom output height in pixels, 16–8000. width × height must be at most 40,000,000 px.

form_schema_id

string (uuid)

Optional. If the template is schema-bound, pass the schema id to resolve friendly field keys.

watermark

boolean

Force watermark on/off. Defaults to plan rules.

save_to_renders

boolean

default: false

When true, the render is queued, stored under your Renders history, and the response is JSON with a hosted URL instead of raw bytes.

use_sample_data

boolean

default: false

HTML templates only. By default, a field you do not supply renders empty — we never substitute the template’s sample values into a billed document. Set true to fall back to the template’s saved sample and declared defaults. An entirely empty data object always renders the sample, so you can preview a template with one call.

Example request

bash

curl -X POST https://api.pixldocs.com/v1/render \
  -H "Authorization: Bearer pxd_YOUR_KEY" \
  -H "Content-Type: application/json" \
  --output invoice.pdf \
  -d '{
    "template_id": "d8a4c9f2-1b3e-4a1f-9c0b-1234567890ab",
    "format": "pdf",
    "data": {
      "customerName": "Acme Corp",
      "amount": 1250.00,
      "items": [
        { "description": "Design retainer", "qty": 1, "unit_price": 1000 },
        { "description": "Print production", "qty": 5, "unit_price": 50 }
      ]
    }
  }'

Response — default (raw bytes)

The Content-Type header matches the requested format (application/pdf, image/png, or image/webp). Every response also carries:

http

Content-Type: application/pdf
X-Pixldocs-Request-Id: 4c5d0b23-8c8e-4c8a-9d7d-2a1c31e5b0a7

On an HTML template, any declared field you did not supply is named back to you, so a blank in the document is never a surprise:

http

X-Pixldocs-Unsupplied-Fields: purchase_order_no,delivery_notes

Multi-page raster renders return JSON with base64 data URLs instead of raw bytes:

json

{
  "id": "4c5d0b23-8c8e-4c8a-9d7d-2a1c31e5b0a7",
  "page_count": 3,
  "width": 1080,
  "height": 1350,
  "pages": ["data:image/png;base64,iVBOR...", "..."]
}

Rendering at another size

Pass size (a saved size id) or an explicit width + height and the design reflows to that box — one template, every format. Both dimensions are required together and must be between 16 and 8000 px; anything else returns 400 invalid_size and costs no credits. An unsupported format returns 400 invalid_format rather than quietly falling back to PNG. Custom sizes need a live key.

json

{
  "template_id": "d8a4c9f2-1b3e-4a1f-9c0b-1234567890ab",
  "format": "webp",
  "width": 1080,
  "height": 1920,
  "data": { "headline": "Season Sale" }
}

Response — with `save_to_renders: true`

json

{
  "id": "d1e2f3a4-5b6c-7d8e-9f0a-b1c2d3e4f5a6",
  "url": "https://cdn.pixldocs.com/renders/...",
  "file_size": 184320,
  "width": 1080,
  "height": 1350,
  "page_count": 2
}

If the render is still processing when the sync window elapses, you get a 202 with the render id — poll GET /v1/renders/:id or watch the Renders page.

Timeout

The synchronous window is 90 seconds (configurable per-deployment). If the render doesn't finish in time you receive a 202 and the job continues in the background. For very heavy renders, prefer POST /v1/renders.

Body parameters

Example request

Response — default (raw bytes)

Rendering at another size

Response — with save_to_renders: true

Response — with `save_to_renders: true`