PDFs

POST /v1/pdf is the endpoint you will use most: it turns a stored template plus your data, or a piece of HTML, into a PDF. By default the request waits for the PDF and returns it; with "async": true it returns at once and tells you by webhook when the PDF is ready. GET /v1/pdf/:id returns a document's record and a fresh download link later. New to the API? Start with the Quickstart, and see the overview for what every request has in common.

POST /v1/pdf

Generates a PDF and returns it, either as the response body (binary, the default) or as a signed link (url). Rendering is limited to 30 seconds and 50 pages.

curl https://api.castpdf.com/v1/pdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-INV-042" \
  -d '{
    "template_id": "8d1f2c3b-4a5e-4f60-9b7a-1c2d3e4f5a6b",
    "data": {"number": "INV-042", "customer": {"name": "Acme Ltd"}, "total": 1234.5},
    "filename": "invoice-042",
    "response": "url"
  }'

const res = await fetch('https://api.castpdf.com/v1/pdf', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'Idempotency-Key': 'invoice-INV-042',
  },
  body: JSON.stringify({
    template_id: '8d1f2c3b-4a5e-4f60-9b7a-1c2d3e4f5a6b',
    data: { number: 'INV-042', customer: { name: 'Acme Ltd' }, total: 1234.5 },
    filename: 'invoice-042',
    response: 'url',
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.url, body.expires_at);

import requests

res = requests.post(
    "https://api.castpdf.com/v1/pdf",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Idempotency-Key": "invoice-INV-042"},
    json={
        "template_id": "8d1f2c3b-4a5e-4f60-9b7a-1c2d3e4f5a6b",
        "data": {"number": "INV-042", "customer": {"name": "Acme Ltd"}, "total": 1234.5},
        "filename": "invoice-042",
        "response": "url",
    },
    timeout=60,
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["url"], body["expires_at"])

{
  "id": "3f0c9a4e-6b1d-4c2a-9a57-0d8e4b7f21c3",
  "status": "succeeded",
  "pages": 2,
  "bytes": 48213,
  "mode": "print",
  "test": false,
  "template_id": "8d1f2c3b-4a5e-4f60-9b7a-1c2d3e4f5a6b",
  "template_version": 4,
  "error_code": null,
  "created_at": "2026-09-30T10:15:02.123Z",
  "expires_at": "2026-10-07T10:15:02.123Z",
  "url": "https://api.castpdf.com/v1/files/3f0c9a4e-6b1d-4c2a-9a57-0d8e4b7f21c3?exp=1791368102&sig=Jx0k...",
  "thumbnail_url": "https://api.castpdf.com/v1/thumbnails/documents/3f0c9a4e-6b1d-4c2a-9a57-0d8e4b7f21c3.png?exp=1790935200&sig=Qm4t...",
  "filename": "invoice-042.pdf",
  "metadata": null,
  "delivery": null,
  "blocked_resources": [],
  "warnings": []
}

{
  "error": {
    "code": "template_render_error",
    "message": "Template error: undefined filter: moneyy",
    "docs_url": "https://castpdf.com/docs/errors#template_render_error",
    "details": { "line": 12, "column": 5 }
  }
}

Send exactly one of template_id or html, or neither when you send e_invoice (the built-in invoice template renders it).

The HTML after Liquid, with the CSS, may be at most 5 MB. Page options you set in the request override the template's settings.

The binary response

200 with the PDF as the body (response: "binary", the default):

HTTP/1.1 200 OK
content-type: application/pdf
content-disposition: attachment; filename="invoice-042.pdf"
x-document-id: 3f0c9a4e-6b1d-4c2a-9a57-0d8e4b7f21c3
x-pages: 2
x-blocked-resources: 0
x-warnings: []
cache-control: no-store

With a test key, a binary response without an Idempotency-Key is not stored: nothing could fetch it later. The document still appears in the log, with url: null. A live binary response is stored too, but when your team's stored-PDF limit is full the PDF is still returned, just without a stored copy.

The url response

200 with JSON (response: "url"), as in the example above. The PDF is stored for your plan's retention period (test documents: 1 day), and url is a signed link that works without an API key until expires_at. The JSON has every field of the document object, plus:

A replayed Idempotency-Key request reports no blocked resources (x-blocked-resources: 0, blocked_resources: []) and no warnings, even if the first response had some: they are not stored with the document.

Example: HTML and CSS to a PDF

From HTML and CSS, returning the PDF itself (A5, landscape, print mode):

curl https://api.castpdf.com/v1/pdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1>Certificate</h1><p>Awarded to {{ name }}</p>",
    "css": "h1 { font-size: 32pt; text-align: center; }",
    "data": {"name": "Ada Lovelace"},
    "format": "A5",
    "orientation": "landscape",
    "margins": "15mm",
    "mode": "print"
  }' \
  --output certificate.pdf

import { writeFile } from 'node:fs/promises';

const res = await fetch('https://api.castpdf.com/v1/pdf', {
  method: 'POST',
  headers: { Authorization: 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    html: '<h1>Certificate</h1><p>Awarded to {{ name }}</p>',
    css: 'h1 { font-size: 32pt; text-align: center; }',
    data: { name: 'Ada Lovelace' },
    format: 'A5',
    orientation: 'landscape',
    margins: '15mm',
    mode: 'print',
  }),
});
if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message}`);
}
await writeFile('certificate.pdf', Buffer.from(await res.arrayBuffer()));

import requests

res = requests.post(
    "https://api.castpdf.com/v1/pdf",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "html": "<h1>Certificate</h1><p>Awarded to {{ name }}</p>",
        "css": "h1 { font-size: 32pt; text-align: center; }",
        "data": {"name": "Ada Lovelace"},
        "format": "A5",
        "orientation": "landscape",
        "margins": "15mm",
        "mode": "print",
    },
    timeout=60,
)
res.raise_for_status()
with open("certificate.pdf", "wb") as f:
    f.write(res.content)

Set your HTTP client's timeout to at least 60 seconds: a render may take up to 30 seconds, plus time in the queue when the service is busy.

Errors

All codes, including internal_error, are on the errors page.

Background rendering

With "async": true the request returns at once, which suits automation tools with short timeouts and pages that should not wait:

curl https://api.castpdf.com/v1/pdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template_id": "8d1f2c3b-4a5e-4f60-9b7a-1c2d3e4f5a6b", "data": {"number": "INV-042"}, "async": true}'

{ "id": "3f0c9a4e-6b1d-4c2a-9a57-0d8e4b7f21c3", "status": "queued", "created_at": "2026-10-03T10:15:02.123Z" }

The answer is 202 with a Location header pointing at GET /v1/pdf/:id. The id is the future document's id. Until the PDF exists, GET /v1/pdf/:id shows status: "queued" or "processing"; then it shows the document as usual. When it is done, a pdf.created or pdf.failed webhook is sent, so you do not have to poll. A missing template and an invalid e_invoice are reported right away (404, 400); everything that happens while rendering is reported in pdf.failed.

• The PDF is always stored (a background PDF can only be fetched later) and, with a live key, counted once like any other document. response is ignored.
• Background PDFs use your workspace's concurrent render slots too, and leave one free for direct requests when your plan has more than one. On the Free plan (one slot) a running background PDF takes the only slot, so a direct request at the same moment gets rate_limited with details.reason: "concurrency" and should retry after a second.
• A workspace can have Free 50, Starter 1,000, Growth 2,000, Pro 5,000 and Scale 10,000 background PDFs waiting or rendering at once (twice its batch size), and can queue Free 100, Starter 2,000, Growth 4,000, Pro 10,000 and Scale 20,000 test-mode background PDFs in 24 hours. Above that, new background work gets rate_limited (429) with details.limit open_jobs or test_jobs_per_day.
• A render that times out or meets a busy service is tried again, 3 attempts in all (waits of 30 seconds and 2 minutes). Other errors fail at once.
• An Idempotency-Key works as for direct requests: the same key and body within 24 hours return the first request's id.
• Queued work survives restarts of our servers: it continues where it stopped, without making or counting a PDF twice.

Warnings

A PDF that was made but deserves a look comes with warnings (in the JSON response, and as the x-warnings header of a binary one). They never fail the request, and there are at most 20:

"warnings": [
  { "code": "missing_variable", "path": "customer.vat_id" },
  { "code": "missing_variable", "path": "items[].discount" },
  { "code": "overflow", "selector": "td.desc", "page": 2 }
]

• missing_variable: the template prints {{ customer.vat_id }}, but your data has no such field, so that spot of the PDF is empty. In a loop the path names the list: items[].discount means at least one item has no discount. Values you test with {% if %}, print with a default filter, or send as null are not reported.
• overflow (print mode): content runs past the left or right edge of a page and is cut off sideways, usually a long word or URL in a table cell. selector is the element's tag and up to two classes; page is the page number.

Warnings name fields and elements of your template, never your data. The x-warnings header is kept under 4 KB, so on a binary response a warning that does not fit is left out; the JSON of a url response has them all. The dashboard's Activity log keeps them, with the status, timing and page count of every render, for 30 days.

GET /v1/pdf/:id

Returns a document's record and, while the PDF is stored, a freshly signed download link. Test keys can read test documents only; a live document requested with a test key is document_not_found.

curl https://api.castpdf.com/v1/pdf/3f0c9a4e-6b1d-4c2a-9a57-0d8e4b7f21c3 \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch('https://api.castpdf.com/v1/pdf/3f0c9a4e-6b1d-4c2a-9a57-0d8e4b7f21c3', {
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
});
const doc = await res.json();
console.log(doc.status, doc.url);

import requests

res = requests.get(
    "https://api.castpdf.com/v1/pdf/3f0c9a4e-6b1d-4c2a-9a57-0d8e4b7f21c3",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=30,
)
doc = res.json()
print(doc["status"], doc["url"])

{
  "id": "3f0c9a4e-6b1d-4c2a-9a57-0d8e4b7f21c3",
  "status": "succeeded",
  "pages": 2,
  "bytes": 48213,
  "mode": "print",
  "test": false,
  "template_id": "8d1f2c3b-4a5e-4f60-9b7a-1c2d3e4f5a6b",
  "template_version": 4,
  "error_code": null,
  "created_at": "2026-09-30T10:15:02.123Z",
  "expires_at": "2026-10-07T10:15:02.123Z",
  "url": "https://api.castpdf.com/v1/files/3f0c9a4e-6b1d-4c2a-9a57-0d8e4b7f21c3?exp=1791368102&sig=Jx0k...",
  "thumbnail_url": "https://api.castpdf.com/v1/thumbnails/documents/3f0c9a4e-6b1d-4c2a-9a57-0d8e4b7f21c3.png?exp=1790935200&sig=Qm4t...",
  "delivery": null
}

{
  "id": "3f0c9a4e-6b1d-4c2a-9a57-0d8e4b7f21c3",
  "status": "queued",
  "pages": null,
  "bytes": null,
  "mode": null,
  "test": false,
  "template_id": "8d1f2c3b-4a5e-4f60-9b7a-1c2d3e4f5a6b",
  "template_version": null,
  "error_code": null,
  "created_at": "2026-10-03T10:15:02.123Z",
  "expires_at": null,
  "url": null,
  "delivery": null
}

{
  "error": {
    "code": "document_not_found",
    "message": "Document 3f0c9a4e-6b1d-4c2a-9a57-0d8e4b7f21c3 not found",
    "docs_url": "https://castpdf.com/docs/errors#document_not_found"
  }
}

The response has cache-control: no-store, because it carries a signed link.

The document object

GET /v1/pdf/:id and every item of GET /v1/documents have these fields:

Document records are kept for 120 days; the PDF itself only for your plan's retention period. See usage and billing for retention per plan.