Documentation
Render PDFs from JSON over one REST API, from n8n, Make, Zapier, or an AI agent. The machine-readable reference is at /openapi.json and rendered below.
Quickstart
Four steps from sign-up to a PDF link. Use a test key while you build: test renders carry a TEST mark and never count against your plan.
- Sign in and pick a starter template, for example Invoice.
- Paste JSON from your workflow into the sample panel. The editor lists any field your data is missing.
- Click Publish. The template is now version 1 and callable by its id.
- Create an API key under API keys, then send a request:
curl https://docspout.com/v1/renders \
-H "Authorization: Bearer sk_test_…" \
-H "Idempotency-Key: order-1182" \
-H "Content-Type: application/json" \
-d '{
"template": "tpl_your_template",
"data": {
"number": "INV-1182",
"customer": {
"name": "Acme GmbH",
"email": "[email protected]"
},
"items": [
{
"description": "Brand identity design",
"qty": 1,
"price": 1200
}
]
}
}'The call waits for the PDF (usually under a second) and returns a render with a url. Send "output": "pdf" to get the file bytes instead, or "wait": false to return at once and poll or use a webhook.
Renders
Base URL https://docspout.com. Authenticate with Authorization: Bearer sk_live_… or a sk_test_… key.
| Endpoint | What it does |
|---|---|
POST /v1/renders | Render one PDF. Waits by default; returns 202 when it takes longer than 25 s. |
GET /v1/renders/:id | A render's status, link, pages, timing, and error. |
POST /v1/batches | Queue up to 10,000 rows. Returns at once with a batch id. |
GET /v1/batches/:id | Counts by status. |
GET /v1/batches/:id/renders | Every row with its status and error. Filter with ?status=failed. |
POST /v1/batches/:id/retry | Re-run failed rows, optionally with corrected data. |
POST /v1/batches/:id/cancel | Stop rows that have not started. |
GET /v1/batches/:id/zip | Every succeeded PDF in one ZIP. |
GET /v1/templates | Published templates. |
GET /v1/templates/:id | One template with its fields as JSON Schema. |
GET /v1/usage | Documents used this month, your limit, and the soft cap. |
Request body for a render:
| Field | Type | Notes |
|---|---|---|
template | string | Template id. Required. |
version | integer | Pin a published version. Defaults to the latest. |
data | object | Your JSON. Checked against the template's fields before rendering. |
output | "url" | "pdf" | Default "url". |
filename | string | Name for the downloaded file. |
wait | boolean | Default true. |
webhook_url | string | Public https URL called when the render finishes. |
metadata | object | Up to 10 string pairs, echoed back on the render and its webhook. |
Idempotency
Automations retry. Send an Idempotency-Key header, such as the order id or the execution id, and a retry returns the original render instead of making a second PDF. The document counts once, even when two retries arrive at the same moment. Reusing a key with a different body returns 409 idempotency_conflict. Keys are kept for 24 hours.
Batches
curl https://docspout.com/v1/batches \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{
"template": "tpl_certificate",
"filename_pattern": "certificate-{{name}}",
"webhook_url": "https://hooks.example.com/pdf-done",
"rows": [ { "name": "Priya Sharma", "course": "n8n Level 2" }, … ]
}'Rows render in the background. If a worker stops mid-batch, its rows return to the queue and finish on another worker. When every row is done you get one webhook with the counts. Fix failed rows and retry only those:
POST /v1/batches/bat_…/retry
{ "rows": [ { "row": 2, "data": { "name": "Lena Vogel", "email": "[email protected]" } } ] }Webhooks
Events: render.succeeded, render.failed, batch.completed. Each delivery is signed with your webhook secret (Settings) in a Webhook-Signature: t=…,v1=… header, where v1 is the hex HMAC-SHA256 of `${t}.${body}`. Failed deliveries are retried after 1, 5, 30, 120, and 600 minutes.
import { createHmac, timingSafeEqual } from "node:crypto";
function verify(body, header, secret) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const expected = createHmac("sha256", secret).update(`${parts.t}.${body}`).digest("hex");
const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
return fresh && timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}Errors
Every error has the same shape: { "error": { "code", "message", ... } }. Data errors name the field.
| Code | HTTP | Meaning |
|---|---|---|
missing_field | 422 | A field the template needs is missing. paths lists each one, like customer.email. |
wrong_type | 422 | A field has the wrong type, for example text where a number is needed. |
asset_failed | 422 | An image URL could not be loaded: timeout, too large, blocked, or not an image. |
too_many_pages | 422 | The document passed 200 pages. |
quota_exceeded | 402 | Past 150% of this month's plan. Includes upgrade_url. |
idempotency_conflict | 409 | The key was used with a different body. |
batch_too_large | 413 | More rows than your plan allows per batch. |
template_not_found | 404 | No published template with that id. |
rate_limited | 429 | Too many requests. Wait for Retry-After seconds. |
body_too_large | 413 | The request body is over 5 MB (renders) or 50 MB (batches). |
timeout | 500 | The render took longer than 15 s. Retried automatically. |
Template syntax
Text blocks bind fields with double braces: {{customer.name}}. Add a format after a bar: {{total | currency:EUR}}, {{issued | date:long}}, {{qty | number:0}}, {{name | upper}}. Rupees use Indian grouping ({{total | currency:INR}} prints ₹1,25,000.00), and {{total | words:INR}} prints "Rupees One Lakh Twenty-Five Thousand Only". Add a locale as a last part: {{total | currency:EUR:es-ES}}, {{issued | date:long:hi-IN}}. Inside a table or repeat section, paths are relative to the current item; start with $. to reach the top level. {{page}} and {{pages}} print the page number and count.
n8n, Make, Zapier
n8n. Install the community node n8n-nodes-docspout. Pick a template from the dropdown and its fields appear for mapping. Choose “PDF as binary data” to attach the file to an email node. On n8n Cloud before the node is verified, use the HTTP Request recipe.
Make and Zapier. Use the HTTP module or Webhooks by Zapier with the recipes in the snippet tabs above. Map the url field from the response into Gmail, Drive, or Slack.
MCP for agents
Add the remote MCP server to Claude, Cursor, or any client that speaks MCP over HTTP. Tools: list_templates, get_template, render_pdf, get_render.
{
"mcpServers": {
"docspout": {
"url": "https://docspout.com/mcp",
"headers": { "Authorization": "Bearer sk_live_…" }
}
}
}
Then ask your agent: "Render the invoice template for this order."
Tools: list_templates, get_template, render_pdf, get_renderAPI reference
Every endpoint, generated from the OpenAPI 3.1 document at /openapi.json. Import it into Postman, Insomnia, or an SDK generator.
Renders
Batches
Templates
Account
Limits
| Limit | Value |
|---|---|
| Request body | 5 MB for renders, 50 MB for batches |
| Pages per document | 200 |
| Render time | 15 s, then the render fails with timeout |
| Images | Public https only, 5 MB each |
| Rate | 2 to 25 requests per second depending on plan, with bursts of twice that |
Changelog
November 2026, languages. Ten language starters (GST invoices in Hindi, Marathi, Bengali, Tamil, Telugu, Kannada, Malayalam and Gujarati, an Arabic quotation, a Spanish invoice), Kannada, Malayalam, Gujarati, Punjabi and Odia fonts, a document language setting with right-to-left layout for Arabic and Hebrew, Indian grouping for rupees, and amounts in words.
November 2026. First release: block editor, ten starters, renders, batches with resume and retry, webhooks, n8n node, MCP server.