API Reference

The Paperbase REST API lives at https://api.paperbase.dev. The full OpenAPI 3.1 spec is available at api.paperbase.dev/openapi.json.

Authentication

Pass your API key as a Bearer token:

Authorization: Bearer pb_live_…

Free tier: 100 renders/month, no credit card required.

POST /v1/pdf/generate

Generate a PDF from Markdown or HTML.

Request body

{
  input: InputMarkdown | InputHtml;   // required
  template: "report";                  // required
  theme?: Theme;                       // optional
  options?: RenderOptions;             // optional
}

Input types

Markdown:

{ "type": "markdown", "content": "# My Doc\n\nBody text." }

HTML:

{ "type": "html", "content": "<h1>My Doc</h1><p>Body text.</p>" }

Theme

{
  logo_url?: string;      // Absolute URL to SVG or PNG logo (≥ 512px recommended)
  accent_color?: string;  // Hex color, e.g. "#ff4e8c"
  primary_color?: string; // Body text and headings
  body_font?: string;     // Font name from Paperbase's cache — see /docs/fonts
  heading_font?: string;  // Heading font override
}

RenderOptions

{
  idempotency_key?: string; // Up to 64 chars — makes request idempotent
  inline_assets?: boolean;  // Base64-inline external images (default: false)
  sanitize_html?: boolean;  // Sanitize raw HTML in Markdown (default: false)
}

Response `200`

{
  "job_id": "job_01HZXYZ",
  "url": "https://storage.paperbase.dev/…",
  "preview_url": "https://storage.paperbase.dev/…",
  "page_count": 8,
  "warnings": [],
  "created_at": "2026-07-01T12:00:00Z"
}

A 200 with non-empty warnings is still a success — the PDF was rendered. See Warning catalog for what each warning means and how to fix it.

Error responses

Status	Code	Meaning
`400`	`INVALID_REQUEST`	Malformed body
`401`	`UNAUTHORIZED`	Missing or invalid API key
`422`	`RENDER_FAILED`	Rendering failed; details in `error.details`
`429`	`QUOTA_EXCEEDED`	Monthly render limit reached

GET /v1/pdf/:jobId

Retrieve a previously generated PDF by job ID.

GET /v1/pdf/job_01HZXYZ
Authorization: Bearer pb_live_…

Returns the same shape as the generate response.

POST /v1/keys

Create a new API key for the authenticated workspace.

{ "name": "Production", "type": "live" }

The key field in the response is returned once only — store it securely.

OpenAPI spec

GET https://api.paperbase.dev/openapi.json

The spec is also served locally at /api/openapi during development.

On this page