API Overview

Pagr is built to be driven from your own application. You design templates in the workspace, then render them on demand through the Pagr Public API: send JSON data, get back a rendered PDF. This section documents the API itself — the same contract every official SDK wraps.

Prefer an SDK

Unless you have a reason to call the raw HTTP endpoints directly, use one of the official SDKs instead — they attach your API key, parse responses into typed objects, turn HTTP errors into exceptions you can catch, retry transient read failures, and validate list filters client-side. You get everything below without hand-rolling it.

Base URL and versioning

All requests go to a single versioned base URL:

https://pagr-prd-api-public.azurewebsites.net/v1

The /v1 segment is the API version and changes only on a breaking contract change. Endpoints are appended to it — for example POST /v1/render/{templateId} to render a single document. Every request must carry a bearer API key; see Authentication. (The two service probes are the only exception — they’re anonymous.)

Every SDK defaults to this base URL, so you normally pass nothing but a key. For the deployed build version, call GET /v1/meta/version.

What you can do

Area	What it covers	Reference
Rendering	Turn a template + data into a PDF — a single document, a synchronous batch, an async job, or a stateless render from an inline template.	Render a document
Validation	Check data against a template before rendering — no render, no credit consumed.	Validate data
Templates & versions	List templates, fetch a template, list its versions, and fetch a specific version (or the latest published one) with its sample data. One write: the document-name template.	Templates & versions
Document browsing	List, inspect, and download previously rendered documents.	Documents
Fonts	List the font families available to your templates.	Fonts
Organisation stats	Read your remaining pages, AI tokens, and tier for the current period.	Organisation stats
Service probes	Health and deployed-version checks. Anonymous.	Service status

The API is read-focused outside of rendering: creating, renaming and publishing templates happens in the workspace, not here. The one exception is a version’s document-name template, which you can PATCH.

Test vs Production

The API key you send decides the environment — there is no separate flag.

	Test (pagr_test_*)	Production (pagr_prod_*)
Output	Watermarked	Full, unwatermarked
Page credit	Not consumed	Consumed
Batch cap	10 documents per request	No fixed cap
Blocks rendering on	Error issues only	Warning and Error issues

That last row is the one that surprises people: a payload that renders on a test key can be rejected on a production key. See Validate before rendering and API Keys.

Rendering shapes

Pagr offers four ways to render, depending on how many documents you need and whether you want to wait for the result:

Shape	Endpoint	Response	Use it when
Single	POST /v1/render/{templateId}	JSON envelope (or a raw PDF with Accept: application/pdf)	You need one document and want the result immediately.
Synchronous batch	POST /v1/render/{templateId} with an array	JSON envelope covering every document	You have several documents and can wait for them all.
Async job	POST /v1/render/{templateId}/async	202 Accepted with a jobId; results via webhook or polling GET /v1/render/jobs/{jobId}	You have a large batch and don’t want to hold a request open.
Stateless	POST /v1/render	Raw PDF bytes	You want to render from an inline template DSL with nothing stored.

The response shape is decided by content negotiation, never by how many documents rendered: send Accept: application/json (the default) for the JSON envelope, or Accept: application/pdf for the raw binary (single document only — a batch returns 406).

For help choosing, see Choose a rendering shape.

The response envelope

Every JSON render response — single, batch, or an async job’s poll and completion callback — reports the same fields with the same meanings:

Field	Meaning
status	ok, partial, failed, or insufficient_credit
requestedCount	Documents submitted
renderedCount	Documents that actually rendered
missingCount	requestedCount − renderedCount — everything not rendered, whatever the reason
issues	Per-document RenderIssue objects, each carrying its documentIndex

Learn it once and it applies everywhere. Full field reference: Render a document → Response.

Outcomes are not errors

A document that fails validation, or a job that stops on insufficient credit, is a normal outcome reported in the envelope with 200 OK — not an HTTP error. Inspect status, missingCount and issues rather than relying on the status code alone. The SDKs mirror this: outcomes are data on the result object, only protocol failures raise.

Data limits

Limit	Value
Payload size, per document	50 MB of JSON
JSON nesting depth, per document	32 levels
Render time, per document	60 seconds
Batch size, test keys	10 documents per request
Page size on list endpoints	25 default, clamped to 1–200

Per-document limits don’t relax in a batch. Full table, including what each violation returns: Errors → Data limits.

Errors and rate limits

Transport and protocol failures come back as an HTTP error status with a { "error": { "code", "message" } } body. code is stable and safe to switch on; message is not.

Rate limits are per organisation over a sliding 60-second window, tracked separately for reads (600), writes (120) and renders (300) — and one request costs one permit regardless of how many documents it carries, which makes batching the cheapest way to stay under them.

See Errors for the full status code table and every render issue type. The SDKs map each status to a typed exception and retry transient server-side failures on read-only requests automatically — but never on writes, since the API has no idempotency keys.

Related articles

• Quickstart — get a key and render your first PDF.
• Choose a rendering shape — a guided tour of the four shapes.
• Authentication — the bearer API key and the Authorization header.
• Errors — every HTTP status code and render issue type.
• Listing & pagination — the shared contract for every list endpoint.
• Webhooks — get notified when async render jobs finish.
• SDKs — official client libraries for six languages.
• API Keys — generate and manage your keys.