Render a raw PDF

The same render endpoint, asked for a different representation. Send Accept: application/pdf and Pagr streams the PDF binary as the response body rather than wrapping it in a JSON envelope — so you skip Base64-decoding a JSON field. The document metadata travels in X-Pagr-* response headers instead.

Single document only

A raw PDF body can only represent one document. Asking for application/pdf with more than one entry in documents is rejected with 406 NotAcceptable before anything renders or any credit is charged.

Endpoint

POST /v1/render/{templateId}
POST /v1/render/{templateId}/versions/{version}

Identical to Render a document — only the Accept header differs. The response shape is decided solely by content negotiation, never by flags or by how many documents happened to render.

Example

Python

import asyncio
from pagr import PagrApiClient

async def main():
    async with PagrApiClient("pagr_prod_xxxxxxxx") as client:
        result = await client.render_pdf(
            "8bec66ff-6f3d-4c1e-9a2b-1f0e5d7c4a90",
            {"Title": "Acme Q3 Invoice", "Amount": 42},
        )

        if result.ok:
            doc = result.document
            print(doc.document_name, doc.page_count, doc.render_duration)
            doc.save("out/")               # or: pdf_bytes = doc.to_bytes()
        else:
            # No PDF to stream — the reasons come back as data, not an exception.
            print(result.status, result.message)
            for issue in result.issues:
                print(issue)

asyncio.run(main())

TypeScript

import { PagrApiClient } from 'pagr';

const client = new PagrApiClient('pagr_prod_xxxxxxxx');

const result = await client.renderPdf(
  '8bec66ff-6f3d-4c1e-9a2b-1f0e5d7c4a90',
  { Title: 'Acme Q3 Invoice', Amount: 42 },
);

if (result.ok) {
  const doc = result.document!;
  console.log(doc.documentName, doc.pageCount, doc.renderDuration);
  await doc.save('./out');               // or: doc.content (Uint8Array)
} else {
  console.log(result.status, result.issues);
}

Java

import org.example.PagrApiClient;
import org.example.models.PdfDocument;
import org.example.models.PdfRenderResult;
import java.nio.file.Path;

PdfRenderResult result = client.renderPdf(
    templateId, "{\"Title\": \"Acme Q3 Invoice\", \"Amount\": 42}");

if (result.isOk()) {
    PdfDocument doc = result.getDocument();
    System.out.println(doc.getDocumentName() + " — " + doc.getPageCount() + " page(s)");
    doc.save(Path.of("out"));          // or: byte[] pdf = doc.toBytes();
} else {
    System.out.println(result.getStatus() + " " + result.getMessage());
    result.getIssues().forEach(System.out::println);
}

PagrAsyncApiClient mirrors this as renderPdf(…) returning CompletableFuture<PdfRenderResult>.

C#

var result = await client.RenderPdfAsync(
    templateId,
    new { Title = "Acme Q3 Invoice", Amount = 42 });

if (result.Ok)
{
    var doc = result.Document!;
    Console.WriteLine($"{doc.DocumentName} — {doc.PageCount} page(s)");
    await doc.SaveAsync(@"C:\out");     // or: byte[] pdf = doc.ToBytes();
}
else
{
    Console.WriteLine($"{result.Status} {result.Message}");
    foreach (var issue in result.Issues) Console.WriteLine(issue);
}

Ruby

require "pagr"

client = Pagr::Client.new("pagr_prod_xxxxxxxx")

result = client.render_pdf(
  "8bec66ff-6f3d-4c1e-9a2b-1f0e5d7c4a90",
  { "Title" => "Acme Q3 Invoice", "Amount" => 42 },
)

if result.ok?
  doc = result.document
  puts "#{doc.document_name} — #{doc.page_count} page(s)"
  doc.save("out/")                       # or: doc.content (String, binary)
else
  warn result.status
  result.issues.each { |issue| warn issue }
end

C++

#include "pagr/PagrApiClient.hpp"

pagr::PagrApiClient client("pagr_prod_xxxxxxxx");

auto result = client.render_pdf(
    std::string("8bec66ff-6f3d-4c1e-9a2b-1f0e5d7c4a90"),
    R"({"Title": "Acme Q3 Invoice", "Amount": 42})");

if (result.ok()) {
    auto& doc = *result.document;
    std::cout << doc.document_name << " — " << doc.page_count << " page(s)\n";
    doc.save("out/");
} else {
    for (auto& issue : result.issues) { /* handle */ }
}

A render_pdf_async form returning std::future<PdfRenderResult> is also available.

cURL

curl -X POST "https://api.pagr.eu/v1/render/8bec66ff-6f3d-4c1e-9a2b-1f0e5d7c4a90" \
  -H "Authorization: Bearer pagr_prod_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/pdf" \
  -d '{ "documents": [ { "Title": "Acme Q3 Invoice", "Amount": 42 } ] }' \
  --output invoice.pdf --dump-header headers.txt

--dump-header captures the X-Pagr-* metadata headers alongside the file.

The 422 body is a result, not an exception

render_pdf is the one call where a 422 is not raised. A blocked render has no PDF to stream, so the SDKs read the JSON error envelope off the 422 and hand it back as ok == false with status/issues populated — the same business-outcome-as-data rule the JSON-envelope renders follow. See When the render is blocked.

Path parameters

Parameter	Type	Required	Description
templateId	string (UUID)	Yes	The template to render.
version	integer	Only for the specific-version form	The template version number to render.

Query parameters

Parameter	Type	Default	Description
persist	boolean	true	Whether to store the rendered document. When false, X-Pagr-Document-Id and X-Pagr-View-Url are omitted.
language	string	—	Language variant to render, for multilingual templates.

Request headers

Header	Value	Description
Accept	application/pdf	Required to get the raw stream. A wildcard (*/*) does not count — the JSON envelope is the default representation.

Request body

Exactly the same body as Render a document, with exactly one entry in documents. includeDocument is ignored — the bytes are always streamed.

{
  "documents": [
    { "Title": "Acme Q3 Invoice", "Amount": 42 }
  ]
}

Response

200 OK with Content-Type: application/pdf — the response body is the PDF. The filename comes back in Content-Disposition, and the metadata the JSON envelope would have carried is split across headers:

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="Acme Q3 Invoice.pdf"
X-Pagr-Document-Id: f61aeff4-2c9d-4b7a-8e10-3a5b9c2d1e00
X-Pagr-Page-Count: 1
X-Pagr-Render-Duration-Ms: 412.7
X-Pagr-View-Url: https://…

Response headers

Header	Description
Content-Disposition	attachment; filename="<documentName>.pdf". The SDKs strip the extension so document_name matches the JSON envelope’s no-extension convention.
X-Pagr-Document-Id	The stored document id. Omitted when persist=false.
X-Pagr-Page-Count	Number of pages.
X-Pagr-Render-Duration-Ms	Render time in milliseconds.
X-Pagr-View-Url	Signed download URL. Omitted when persist=false.
X-Pagr-Issue-Count	Number of non-blocking issues. Omitted when there were none.

Fields the headers don’t carry

templateId, versionNumber, environment, renderedAt, documentType and language are not in the headers. The SDKs’ PdfDocument deliberately leaves them out rather than fabricating values — use the JSON envelope (Render a document) when you need them. Only X-Pagr-Issue-Count (a count) is reported, not the issues themselves.

When the render is blocked

A blocked or failed render has no PDF to stream, so the API does not silently change shape. It returns 422 Unprocessable Entity with the ordinary JSON envelope as the body:

{
  "status": "failed",
  "message": "0 document(s) rendered; 1 skipped.",
  "requestedCount": 1,
  "renderedCount": 0,
  "missingCount": 1,
  "issues": [
    { "type": "MissingBinding", "severity": "Warning", "description": "…", "documentIndex": 0 }
  ],
  "documents": []
}

The SDKs treat this as a result, not an exception: result.ok is false and the reasons are in result.status / result.issues. Only genuine protocol failures raise.

SDK reference

SDK	Method
Python	await client.render_pdf(template_id, json_data, *, version=None, language=None, persist=True, timeout=None) → PdfRenderResult
TypeScript	await client.renderPdf(templateId, data, options?) → PdfRenderResult
Java	client.renderPdf(templateId, data[, RenderOptions]) → PdfRenderResult — data is a JSON String, JsonObject or Map
C#	await client.RenderPdfAsync(templateId, data, version, language, persist, timeout, cancellationToken) → PdfRenderResult
Ruby	client.render_pdf(template_id, json_data, version:, language:, persist:, timeout:) → PdfRenderResult
C++	client.render_pdf(template_id, json_data, RenderOptions) / render_pdf_async(…) → PdfRenderResult

Errors

Status	When
406 NotAcceptable	Accept: application/pdf on a request with more than one document.
422	The render was blocked — body is the JSON envelope (see above), not an error envelope.

Everything else matches Render a document. See Errors for the full table.

Related articles

• Render a document — the JSON-envelope form of this endpoint.
• Render and save a PDF — a step-by-step walkthrough of both forms.
• Choose a rendering shape — how the raw-PDF representation fits alongside single, batch and async renders.
• Errors — the full status code reference.