Documents

Every render made with persist=true (the default) is stored and shows up here — the same records visible in the workspace under Renders. Renders made with persist=false never appear.

Endpoints

Operation	Endpoint
List documents	GET /v1/documents
Get a document	GET /v1/documents/{id}
Download the PDF	GET /v1/documents/{id}/file

Example

List the most recent documents, then download one to disk.

cURL

# Most recent 20 documents
curl -G "https://pagr-prd-api-public.azurewebsites.net/v1/documents" \
  -H "Authorization: Bearer pagr_prod_xxxxxxxx" \
  --data-urlencode "take=20" \
  --data-urlencode "sortBy=renderedAt" \
  --data-urlencode "sortDirection=desc"

# Download one
curl "https://pagr-prd-api-public.azurewebsites.net/v1/documents/f61aeff4-2c9d-4b7a-8e10-3a5b9c2d1e00/file" \
  -H "Authorization: Bearer pagr_prod_xxxxxxxx" \
  --output invoice.pdf

Python

import asyncio
from pagr import PagrApiClient

async def main():
    async with PagrApiClient("pagr_prod_xxxxxxxx") as client:
        page = await client.get_documents(
            take=20, sort_by="renderedAt", sort_direction="desc",
        )
        for doc in page.items:
            print(doc.document_name, doc.rendered_at, doc.is_pdf_deleted)

        pdf_bytes = await client.download_document(page.items[0].id)
        with open("invoice.pdf", "wb") as f:
            f.write(pdf_bytes)

asyncio.run(main())

TypeScript

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

const client = new PagrApiClient('pagr_prod_xxxxxxxx');

const page = await client.getDocuments({
  take: 20,
  sortBy: 'renderedAt',
  sortDirection: 'desc',
});
for (const doc of page) {
  console.log(doc.documentName, doc.renderedAt, doc.isPdfDeleted);
}

const pdfBytes = await client.downloadDocument(page.items[0].id);
await writeFile('invoice.pdf', pdfBytes);

Java

import org.example.*;
import org.example.models.*;
import java.nio.file.Files;
import java.nio.file.Path;

try (PagrApiClient client = new PagrApiClient("pagr_prod_xxxxxxxx")) {

    PagedResult<RenderDocument> page = client.getDocuments(ListOptions.builder()
        .take(20)
        .sortBy("renderedAt")
        .sortDirection(SortDirection.DESCENDING)
        .build());

    for (RenderDocument doc : page.getItems()) {
        System.out.println(doc.getDocumentName() + " " + doc.getRenderedAt()
            + " " + doc.isPdfDeleted());
    }

    byte[] pdf = client.downloadDocument(page.getItems().get(0).getId());
    Files.write(Path.of("invoice.pdf"), pdf);
}

C#

using Pagr.Sdk;

using var client = new PagrApiClient("pagr_prod_xxxxxxxx");

var page = await client.GetDocumentsAsync(new ListOptions
{
    Take = 20,
    SortBy = "renderedAt",
    SortDirection = SortDirection.Descending,
});

foreach (var doc in page)
    Console.WriteLine($"{doc.DocumentName} {doc.RenderedAt} {doc.IsPdfDeleted}");

byte[] pdf = await client.DownloadDocumentAsync(page.Items[0].Id);
await File.WriteAllBytesAsync("invoice.pdf", pdf);

Ruby

require "pagr"

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

page = client.documents(take: 20, sort_by: "renderedAt", sort_direction: "desc")
page.each do |doc|
  puts "#{doc.document_name} #{doc.rendered_at} #{doc.pdf_deleted?}"
end

pdf = client.download_document(page.items.first.id)
File.binwrite("invoice.pdf", pdf)

C++

#include <fstream>
#include "pagr/PagrApiClient.hpp"

pagr::PagrApiClient client("pagr_prod_xxxxxxxx");

const auto page = client.get_documents(
    {.take = 20, .sort_by = "renderedAt",
     .sort_direction = pagr::SortDirection::Descending});

for (const auto& doc : page.items) {
    std::cout << doc.document_name << " " << doc.rendered_at << "\n";
}

const auto pdf = client.download_document(page.items.front().id);
std::ofstream out("invoice.pdf", std::ios::binary);
out.write(reinterpret_cast<const char*>(pdf.data()), pdf.size());

Every call also has a _async form returning std::future<T>.

List documents

GET /v1/documents

Query parameters

The shared skip / take / sortBy / sortDirection / search / filters[i] set.

• Sortable: documentName, versionNumber, fileSizeBytes, pageCount, renderedAt (the default), renderDuration, environment, createdAt, updatedAt.
• Filterable: documentName, template.guid, versionNumber, fileSizeBytes, pageCount, renderedAt, createdAt, updatedAt, environment, language — see Filterable fields → Documents for each field’s operators.
• search matches documentName.

Response

200 → a paged result of document metadata:

{
  "items": [
    {
      "id": "f61aeff4-2c9d-4b7a-8e10-3a5b9c2d1e00",
      "documentName": "Acme Q3 Invoice",
      "templateId": "8bec66ff-6f3d-4c1e-9a2b-1f0e5d7c4a90",
      "versionNumber": 3,
      "environment": "production",
      "fileSizeBytes": 24815,
      "pageCount": 1,
      "renderedAt": "2026-07-24T09:46:01Z",
      "renderDuration": 412.7,
      "viewUrl": "https://…",
      "documentType": "Template",
      "isPdfDeleted": false,
      "language": null
    }
  ],
  "total": 1,
  "skip": 0,
  "take": 25
}

Field	Type	Description
id	string (UUID)	The document id — pass it to Get a document or Download the PDF.
documentName	string	The document’s name, from the version’s document-name template. No file extension.
templateId	string (UUID)	The template it was rendered from.
versionNumber	number	The template version used.
environment	string	test or production, decided by the API key that rendered it.
fileSizeBytes	number	Size of the stored PDF.
pageCount	number	Number of pages.
renderedAt	string (ISO 8601)	When it rendered.
renderDuration	number	Server-side render time in milliseconds.
viewUrl	string	Signed, time-limited download link.
documentType	string	Template or Invoice.
isPdfDeleted	boolean	true when the stored PDF was purged by retention while the metadata remains.
language	string or null	The language variant rendered, or null.

Prefer the API over viewUrl for programmatic access

TODO: Is it a time limited link, tought it was accessible till the pdf was deleted form the db?

viewUrl is a signed, time-limited link. It’s the right thing to hand to a browser; it’s the wrong thing to store or to rely on hours later. For programmatic downloads use Download the PDF, which re-authorises on every call.

Get a document

GET /v1/documents/{id}

Parameter	Type	Required	Description
id	string (UUID)	Yes	The document’s id.

Response: 200 → a single document object, same shape as one items entry above. This returns metadata only — no PDF bytes. 404 if it doesn’t exist or belongs to a different organisation.

Download the PDF

GET /v1/documents/{id}/file

Parameter	Type	Required	Description
id	string (UUID)	Yes	The document’s id.

Response: 200 with Content-Type: application/pdf — the raw file bytes. Every SDK returns them as its native byte type (bytes, Uint8Array, byte[], String, std::vector<std::uint8_t>).

Status	code	When
404	DocumentNotFound	No such document, or it belongs to another organisation.
410	PdfDeleted	The metadata still exists but the PDF was purged by your organisation’s retention policy.

Predict a 410 without making the call

Check isPdfDeleted on the document metadata first. It’s true exactly when the download would fail with 410 PdfDeleted, so a listing pass can filter out purged documents before you try to fetch any of them.

Large files: raise the timeout, not the client default

Downloads share the client’s 30-second default timeout. Rather than raising it globally, pass a per-call override — timeout= (Python/Ruby), timeoutMs (TypeScript), timeout: (C#), the timeout argument (C++). See Configure the client.

SDK reference

TODO: Work here with a language selection. Maybe a text without toggle that changes based on the language you have selected from the snippet.

Operation	Python	TypeScript	Java	C#	Ruby	C++
List documents	get_documents	getDocuments	getDocuments	GetDocumentsAsync	documents	get_documents
Get a document	get_document	getDocument	getDocument	GetDocumentAsync	document	get_document
Download the PDF	download_document	downloadDocument	downloadDocument	DownloadDocumentAsync	download_document	download_document

The purged-PDF flag follows each language’s convention: is_pdf_deleted (Python), isPdfDeleted (TypeScript), isPdfDeleted() (Java), IsPdfDeleted (C#), pdf_deleted? (Ruby), is_pdf_deleted (C++).

Errors

See Errors for the full status code table.

Related articles

• Browse and download documents — paging, filtering and downloading, step by step.
• Listing & pagination — the shared query contract and every filterable field.
• Render a document — where these documents come from; persist=false renders never appear here.
• Renders — the workspace view of the same data.