Embedded document editor API

How it fits together

Three moving parts. Your backend holds the API key and decides who may edit what; the browser only ever holds a short-lived token scoped to a single template.

  Your backend                      pdfs.build                Your frontend
  ────────────                      ──────────                ─────────────
  1. POST /v2/.../templates   ──▶   template created
     (once per doc type)             externalId: invoice-42

  2. POST /v2/.../embed-sessions  ──▶  emb_ token
     tenant, user                        (1 hour at most, one template)
                                              │
                                              └──▶  3. PdfReportProvider
                                                       <PdfReportEditor />

Quick start

A complete Next.js integration. The route handler runs on your server and is the only place your API key appears.

import { auth } from '@/lib/auth'

export async function POST() {
  // Your own authorization — decide who may edit what.
  const user = await auth()
  if (!user) return new Response('Unauthorized', { status: 401 })

  // Your pdfs.build organization ID (API keys page), not your own tenant id.
  const orgId = process.env.PDFS_BUILD_ORG_ID
  const templateId = `invoice-${user.orgId}`
  const res = await fetch(
    `https://api.pdfs.build/v2/organizations/${orgId}/templates/${templateId}/embed-sessions`,
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.PDFS_BUILD_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        externalTenantId: user.orgId,
        externalUserId: user.id,
        expiresInSeconds: 3600,
      }),
    },
  )

  if (!res.ok) return new Response('Editor unavailable', { status: 502 })

  const { token } = await res.json()
  // Return only the token — never the API key or the full session.
  return Response.json({ token })
}

'use client'

import { PdfReportProvider, PdfReportEditor } from '@pdfsbuild/react'
import '@pdfsbuild/react/styles.css'

async function fetchToken() {
  const res = await fetch('/api/pdfs-session', { method: 'POST' })
  if (!res.ok) throw new Error('Could not start an editor session')
  const { token } = await res.json()
  return token
}

export function ReportDesigner() {
  return (
    <div style={{ height: '100vh' }}>
      <PdfReportProvider
        fetchSessionToken={fetchToken}
        // Called again before the token runs out, so a long edit is not interrupted.
        refreshSessionToken={fetchToken}
        theme={{ primary: '#6366f1' }}
      >
        <PdfReportEditor />
      </PdfReportProvider>
    </div>
  )
}

PDFS_BUILD_ORG_ID and PDFS_BUILD_API_KEY both come from the API keys page of your pdfs.build workspace. The organization in the URL must be the one the key belongs to, or the call fails with 403 organization_scope_mismatch.

Give the provider a container with a real height. It fills its parent, so a parent of height auto collapses the editor to nothing.

Provision a template

A session needs a template to point at. Create one per document type with the REST API, using an externalId you derive from your own records — then you never have to store a pdfs.build identifier. Drafts are editable, so there is no need to publish before embedding.

import os, requests

API = "https://api.pdfs.build"
HEADERS = {"Authorization": f"Bearer {os.environ['PDFS_BUILD_API_KEY']}"}

def get_or_create_template(org_id: str, external_id: str):
    existing = requests.get(
        f"{API}/v2/organizations/{org_id}/templates/{external_id}",
        headers=HEADERS,
    )
    if existing.status_code == 200:
        return existing.json()

    created = requests.post(
        f"{API}/v2/organizations/{org_id}/templates",
        headers=HEADERS,
        json={
            "externalId": external_id,
            "name": "Invoice",
            "code": '#let render(company: "") = [Invoice for #company]',
            "schema": {
                "type": "object",
                "properties": {"company": {"type": "string"}},
            },
            "sampleData": {"company": "Acme Corp"},
            # Optional: freeze the host-provided data contract for embedded editing.
            "schemaLocked": True,
        },
    )
    created.raise_for_status()
    return created.json()

Creating with an externalId that already exists returns 409 external_id_conflict, which is what makes the get-or-create pattern above safe to run on every request. See the API reference for the full request body.

Freezing the schema

If your backend only ever sends one data shape, pass "schemaLocked": true next to schema. Users keep the full design conversation — layout, typography, color, wording — but the agent cannot add, remove, or retype a data field, and sample data cannot introduce keys the schema does not declare. Without it, an agent that invents a discountCode field produces a template that previews correctly and then fails on your render call, where that field is never present.

Static images stay allowed: a logo or signature the user uploads lives in the template, so you never have to send it. The flag belongs to the template rather than the session, so it binds the agent, the MCP tools, and the template API alike — and GET on the template returns schemaLocked so you can confirm what you provisioned. It is set at create time only.

Choosing a template granularity

Create a session

Always from your backend — never the browser, because the API key must stay server-side. Addressing matches the rest of the public v2 API: externalId is the template's org-scoped external ID when one is set, its internal ID otherwise. Create a fresh session each time the editor opens.

Request body

requests.post(
    f"https://api.pdfs.build/v2/organizations/{org_id}/templates/{external_id}/embed-sessions",
    headers=HEADERS,
    json={"externalTenantId": tenant_id, "externalUserId": user_id},
).json()

Response

{
  "sessionId": "9eabee26-7d56-4d67-96e0-9387c5a462c0",
  "token": "emb_...",
  "templateId": "550e8400-e29b-41d4-a716-446655440000",
  "expiresAt": "2026-07-15T12:15:00.000Z",
  "tenantLimit": { "monthlyLimitCents": 750, "action": "block", "source": "default" }
}

tenantLimit is the spend cap the tenant has after this mint. source is explicit (this request set it), default (this request seeded it from the plan: see Billing & attribution) or existing (it was there already). It is null when nothing caps the tenant: the plan seeds no default, or the cap was removed.

Return only token to the browser. templateId in the response is always the resolved internal id. The token is restricted to the selected template and the editor APIs — it cannot list your other templates, mint API keys, or read your organization settings.

Errors

What the token cannot do

The token belongs to your end user, not to you. It edits its template's design and sample data and can rename it, but it cannot:

• change the template's externalId, the address your backend publishes, renders and creates sessions by (403 embedded_scope);
• send blocks (designerDocument) in a save, so it can neither detach a visual template to code editing nor turn a code template into blocks (403 embedded_scope). The assistant still edits a visual template's blocks;
• create a public share link (403 embedded_share_not_allowed). A render from the editor comes back to the browser, and no PDF or link is stored;
• publish, or promote a version;
• reach anything else: a route outside the editor's list answers 403;
• manage your organization's AI policy or billing. The editor is not sent the policy, offers a choice of model only when you let members choose one (Settings → AI models), and when your credits run out offers no way to buy credits or turn on pay as you go: those are for your admins. Billing details are not shown to end users. No gate an embedded token is sent carries your plan name, credit figures or pay-as-you-go figures, whatever the request asks for: the SDK asks for the neutral shape (credit-gate-neutral), and any other request gets the older shape with those values empty. A tenant's limit is sent with its amounts at 0, the server's message does not mention upgrading, and the usage sent after each turn leaves out your credit balance. The lists of your organization's images and fonts, and a template's versions, leave out your organization's id, where a file is stored and which of your members added it.

Change the external id and publish from your backend with your API key (PATCH and POST …/publish on /v2/organizations/:organizationId/templates/:externalId), and render the PDFs you hand your users there through the v2 API. Converting to code, share links and promoting a version are done in the pdfs.build app. A publish that answers 409 publish_conflict found the template changed while it was being checked and published nothing: send it again, which checks the current version.

Two things every session of your organization or template shares, which you may want to know before you choose how to lay out your templates:

• The organization's assets. A token can list and download your organization's fonts and images, and the assistant can copy one of those images into the template it is editing. Every tenant's users can see the whole library by name, so keep nothing there that one tenant should not see of another.
• The template's chat. A template has one chat history, and everyone who opens it can read its messages and the images in them (see Tenant and user identifiers).

Concurrent edits

PUT /api/templates/:id takes an optional expectedUpdatedAt: the template's updatedAt as the caller read it (ISO 8601). If the row has moved since, nothing is written and the reply is 409 with { "error": "template_conflict", "message": "...", "updatedAt": "..." }. A value that is not a date is 400 invalid_expected_updated_at. Without the field a save goes in whatever has happened. The SDK sends it on every save, and sends the same write without it when the user chooses to keep their copy. A visual template's expectedRevision still applies, answered with 409 design_conflict. updatedAt moves when what an editor holds changes (the code, the schema, the sample data, the page settings, the blocks or the name), and only if the write really changes them. So your backend can publish, unpublish, promote a version and PATCH the externalId or scopePath while somebody is editing, and their next save goes in. A generated title moves nothing. A name sent with a publish does move it. A save naming an older version still goes in when its body is the whole document and the row holds exactly that already, and the reply gives the row's updatedAt.

Limits

What a session can send and store is bounded. Over any of these the request changes nothing:

• Request bodies: 149 MB for a save, a checkpoint or a render's data, 229 MB for a chat message (20 images of 8 MB each), 1 MB for generating a title (413 payload_too_large).
• Images in sample data: 5 MB each once decoded (400 image_too_large) and 50 new ones per save (400 too_many_images). A picture the template already holds counts for neither, so a template that has more than that still saves.
• Image keys: sample data may name images stored for its own template, and any key the template already holds (a copy keeps its source's). Anything else is 400 foreign_image_key.
• Checkpoints: 200 per template, the oldest removed when another is made. A label is at most 200 characters, and the code, the schema and the sample data at most 2 MB each, not counting images, which are stored apart (400 invalid_checkpoint, 413 payload_too_large). An id that exists is 409 checkpoint_exists.
• Pictures in memory: past what the server can hold of them at once, overall, per organization or per externalTenantId, a read still answers 200, with storage keys where the pictures were and imagesPartial: true, as does a chat turn's data_update. The SDK reads the template once more after a moment. A client of your own loads again.
• Compiles: the compiler is shared fairly per organization and per embedded session. A session compiling once with two more waiting, or an organization holding its whole share, gets 429 compile_share_exceeded with Retry-After; other sessions and customers go on compiling. A compiler that is full for everybody is a 503, also with Retry-After. During a turn the assistant is told; the compile check at the end of a turn tries three times, 1 and 3 seconds apart, before the turn ends with that message and the document saved unchecked.

Rate limits

Every request a token makes is counted against its session and against its tenant (externalTenantId), so minting more sessions for a tenant buys no more allowance. Per minute:

The whole minute's limit can be used at once, and it comes back steadily over the minute. Past it the reply is 429 with a Retry-After header and { "error": "rate_limited", "message": "...", "retryAfterSeconds": 6 }. A refused request counts against neither limit. Use one externalTenantId per customer: all of a tenant's users share its limits. These limits apply to the editor's token, not to your API key.

A token that does not authenticate (mistyped, expired or revoked) is counted against the address it came from, 60 a minute. Past that, every emb_ token from that address gets the same 429 for the second or so until the next one comes back, without being looked up.

A higher limit is available per organization on request. We set it, for any row above and for the tenant's multiple, and it takes effect within 30 seconds. It is counted the same way, per API process.

Your organization's owners and admins can see how far each tenant goes. GET /api/usage/embedded/tenants gives each tenant its requests, throttled (both { total, byClass }, by kind: chat, render, save, checkpoint, title, read), compileRefusals, activeSessions and lastSeenAt, and lists a tenant that made requests and never used the assistant as well. GET /api/usage/embedded/throttles?days=N&tenant=<id> gives the same numbers day by day: at most 90 days and 200 tenants, the most refused first and then the busiest. A day is a UTC day, today included. A compile refused inside a chat turn is the turn's own to retry or report and is not counted as a refusal, being no 429.

Links in a document

A link may go to an http:, https:, mailto: or tel: address. The rule is held in three places, because each sees what the others cannot:

• In the code, when it is written. A write that adds a link to any other scheme changes nothing and is 400 unsafe_link_target, with a message naming the link: a save, a checkpoint, and the API's POST /v1/templates and POST /v2/organizations/:organizationId/templates. The assistant's tools refuse it too, and tell the assistant why. Only what a write adds is refused, so a template stored with an sms: link before the rule goes on saving, and a copy of a stored template adds nothing.
• On the compiled pages, at a gate. A text scan cannot see a link called under another name (#let go = link, (link)("…")), or an address built in the code or read from the data (#link("sms:" + phone)). POST …/publish compiles with the sample data and answers 400 unsafe_link_target for such a link. At the end of a turn, one the turn brought gets up to two repair attempts, which are billed like any other model step, and if it is still there the user is told; the turn still saves. One the document had before the turn is pointed out and costs nothing. A link the code writes out in full is exempt here, as the scan has already answered for it, so a stored #link("sms:…") goes on publishing.
• In the browser. The SDK's preview takes every other address off the page, and keeps the four schemes as links that open in a new tab. This is what holds for an address that only arrives with a render's data.

A scheme is read as the browser will read it, character references included (javascript:x). A host and a port (example.com:8080/x, localhost:3000) is an address with no scheme: nothing refuses it, and the preview does not draw it as a link, as it does not draw www.example.com. A render is never refused for a link: a PDF your API call renders carries the address your data gave it.

A Word import (in the app or over MCP; an embedded session cannot reach it) keeps the text of a hyperlink to any other scheme and drops its address, and says which went: droppedLinks in the response, and in the tool's result over MCP. It refuses only what it could not take down, such as prose that reads like a call (link("sms:9")).

Checkpoints

A checkpoint is a saved copy of the document that the editor's History tab can go back to. The SDK makes and reads them for you, through routes the token may call:

• POST /api/templates/:id/checkpoints with { id, label, typstCode, schema, sampleData }. id is a UUID the client generates. The answer is 400 invalid_checkpoint for a body that does not parse, 400 unsafe_link_target and 400 foreign_image_key as for a save, 413 payload_too_large past the limits above, and 409 checkpoint_exists for an id in use.
• GET /api/templates/:id/checkpoints?light=1 lists them, oldest first, with their id, label and date and no code, data or blocks.
• GET /api/templates/:id/checkpoints/:checkpointId has one whole, its pictures as data: URLs, or a 404.
• GET /api/templates/:id/checkpoints without light sends every picture of every checkpoint, which is what an SDK from before the light list reads. Do not use it in new code: at the cap it nears the largest string a browser can parse.

Tenant and user identifiers

externalTenantId and externalUserId are opaque identifiers that you choose — we never interpret them, and they don't have to be anything we'd recognize. Use whatever your own system already uses to tell a customer and an end-user apart: a database id, a UUID, or a hash. They should not be email addresses, names, or any other personal data — a stable pseudonymous id is all the platform needs, and it keeps you from handing us PII you don't have to.

Each one buys you something concrete:

• externalUserId records which of your end-users sent each AI turn, so usage can be drilled down to a person. It does not split the conversation: a template has one chat history, and everyone who opens it sees the same thread. Give each tenant its own template (the one-template-per-tenant pattern above) and a tenant's users share history only with each other.
• externalTenantId is the axis your AI-spend breakdown is grouped by, so you can see which customer consumed what. It's also stored on every billable turn for attribution.

Checkpoints and generation logs keep the same two ids and the session's id, so a checkpoint or a render from an embedded editor says who made it after the session itself has been cleaned up, a week after it expires or is revoked. The token's own reads do not return them.

Revoke a session

Sessions expire on their own, so revoking is only needed when you want a token dead sooner — a user signs out, loses access, or you detect abuse. Keep the sessionId from the create call if you plan to do this. No template id needed here — the session already resolved to one when it was created.

requests.delete(
    f"https://api.pdfs.build/v2/organizations/{org_id}/embed-sessions/{session_id}",
    headers=HEADERS,
).raise_for_status()

Render what your users designed

The render API serves published templates, and "version": "draft" renders the draft your users are editing. A template that is not published answers 403 draft_not_renderable, except a "version": "draft" render on a plan with no published-template limit by a key whose creator owns the template or is an owner or admin of the organization. Users in the embedded editor cannot publish, so publish from your backend when the design is ready for the renders that leave out version:

requests.post(
    f"https://api.pdfs.build/v2/organizations/{org_id}/templates/{external_id}/publish",
    headers=HEADERS,
).raise_for_status()

Publishing freezes the current design as a version, and renders keep using that version while the user goes on editing the draft. Publish again to ship their later edits; with nothing new since, the call changes nothing, so it is safe to call whenever the user saves.

Install

npm install @pdfsbuild/core @pdfsbuild/react

Import @pdfsbuild/react/styles.css once, anywhere in your app. All SDK styles live in @layer pdfs and are scoped to .pdfs-root, so they will not leak into the rest of your interface and your own styles win by default.

Provider reference

PdfReportProvider scopes one editor instance — one set of stores, one API client, one document compiler. Multiple providers on the same page stay fully isolated, so you can mount two editors side by side.

There is deliberately no templateId prop in the embedded flow — the session decides the template.

Composable parts

PdfReportEditor is a convenience layout built entirely from public parts. Assemble your own when you want a different arrangement, or drop pieces you do not want to offer.

<PdfReportProvider ...>
  <EditorToolbar />
  <div className="flex flex-1">
    <EditorChat>
      <EditorChat.Messages />
      <EditorChat.Input />
    </EditorChat>
    <EditorPreview>
      <EditorPreview.Tab value="preview" />
      <EditorPreview.Tab value="data" />
    </EditorPreview>
  </div>
</PdfReportProvider>

Common shapes

// Data-entry only — your team designed the template, customers fill it in.
<PdfReportEditor chat={false} previewTabs={['preview', 'data']} />

// Preview only — read-only document viewer.
<PdfReportEditor chat={false} toolbar={false} previewTabs={['preview']} />

// Full designer.
<PdfReportEditor />

Theming

The SDK ships a neutral light theme. Override any token to match your product, and pass dark to switch palettes.

<PdfReportProvider
  theme={{
    primary: '#6366f1',
    primaryForeground: '#ffffff',
    background: '#fafafa',
    border: '#e5e7eb',
    radius: '0.5rem',
  }}
  dark={resolvedTheme === 'dark'}
>

Available keys: background, foreground, card, cardForeground, popover, popoverForeground, primary, primaryForeground, secondary, secondaryForeground, muted, mutedForeground, accent, accentForeground, destructive, destructiveForeground, border, input, ring, success, warning, radius, plus sidebar, chart, and font tokens.

For anything the tokens do not reach, override the CSS variables on .pdfs-root in your own stylesheet. Because the SDK's rules sit in @layer pdfs, unlayered host styles beat them without needing !important.

Headless hooks

For full UI ownership, read state straight from the hooks and render whatever you like.

function MyComposer() {
  const { sendMessage, isGenerating, cancelGeneration } = useEditor()
  const [text, setText] = useState('')

  return (
    <form onSubmit={(e) => {
      e.preventDefault()
      sendMessage(text)
      setText('')
    }}>
      <input value={text} onChange={(e) => setText(e.target.value)} />
      <button disabled={isGenerating}>Send</button>
      {isGenerating && <button onClick={cancelGeneration}>Stop</button>}
    </form>
  )
}

Billing & attribution

AI spend from an embedded editor is attributed to the externalTenantId and externalUserId you passed when creating the session. That is how you attribute cost back to your own customers. Those values are recorded for accounting only — they never grant access and are never trusted as authorization claims, so your backend remains the sole authority on who may open which template.

Credits are consumed in a fixed order: monthly subscription credits first, then any non-expiring purchased packs, then pay-as-you-go overage. On the Platform plan pay-as-you-go starts switched on, capped by the monthly and per-request spend limits you set under Settings → AI models; an owner can switch it off.

Default tenant spend cap. On the Platform and custom plans, a session minted for a tenant with no spend limit gives it one: a tenth of the plan's monthly AI budget ($7.50 on Platform), with action block. Past it, that tenant's AI turns stop until the period resets, while your other tenants carry on, so a leaked token can spend about that much (the limit is soft at the edges, below). To set the limit yourself, pass tenantMonthlyLimitCents and tenantLimitAction when creating the session, which replaces whatever the tenant has, or change it under your organization's embedded usage settings. The default is only ever written where nothing is there: it does not overwrite a limit you set, and it does not come back after you remove one.

Spend so far this period counts, so a tenant already past a tenth of the budget has its AI turns stopped by the first mint that gives it the cap. A tenant is whatever you pass as externalTenantId: one id for all your customers is one cap and one set of rate limits between them. The limit is checked when a turn starts, so turns running together, or one long turn, can end somewhat above it. It covers AI spend only: renders and storage are organization-wide.

Image generation, web search and title generation are metered like chat: each draws on the same credits and pay-as-you-go overage, at the same markup, is attributed to the same tenant and user, and counts toward that tenant's spend limit.

When credits run out, the editor renders a credit gate instead of accepting new AI turns. Your end user is not shown your billing: by default the gate says the assistant is unavailable and when the allowance resets, with no plan name, credit figures or pay-as-you-go figures, and those figures are not sent to the browser either. The editor names credit-gate-neutral on each message and on GET /api/chat/access, and the 402 is then { "code": "ai_credits_exhausted", "neutral": true, "message": "...", "periodEnd": "..." }, with periodEnd left out when there is no allowance to reset. You choose what else it does:

A tenant past its spend limit gets a panel of its own, with no action: it says the limit has been reached and when access resumes, without the amount. That 402 has monthlyLimitCents and spentCents at 0, so blocker from useEditorChat does not carry the tenant's real figures. They are under Settings → Tenants.

Session expiry

Tokens last 15 minutes by default and never more than an hour, so a long editing session will outlive its token. Mint them for the 3600-second maximum and give the provider a way to get the next one.

<PdfReportProvider
  fetchSessionToken={fetchToken}
  refreshSessionToken={fetchToken}
>

refreshSessionToken is called a minute before the token runs out. It is also called when a request is refused anyway, and that request then goes again with the new token, so nobody sees an interruption. It must return a token for the same template, and it counts as failed if it rejects or takes more than 15 seconds. A tab that is not showing waits until it is shown before renewing on a timer, so one left open in the background does not keep minting sessions.

If you would rather hold the token yourself, pass the new one as the sessionToken prop. The next request carries it, and a change refused by the old one is saved again.

When a token is refused and no new one comes, editing can go on but nothing can be saved. The editor shows a banner saying the session has expired, with a Reconnect button that calls refreshSessionToken again, or onUnauthorized if there is none. onUnauthorized is called once per expiry, not once per request, and refused saves wait for the next token instead of being retried on a timer. Replace the banner with renderSessionExpired, or read the state yourself:

const { expiresAt, expired, refreshing, refresh, canReconnect } = useEmbeddedSession()

After a new token, whatever the old one could not do goes again once: unsaved edits, a rename, a checkpoint. A chat message is not sent by itself, as the user may have gone on: the chat offers Send again once the session is back.

Remounting the provider with a new key also starts a new session, but it discards anything not yet saved, so keep it for when you want to start over.

Save state

The editor saves on its own, two seconds after the last edit, and EditorToolbar says how the last save went: Saving…, Saved, or Not saved: <the server's message> with a Retry button. A failed save goes again by itself after a 5xx, a 408, a 425, a 429 or no answer at all, up to three times. A refusal that would only be repeated (schema_locked, too large, a conflict) is not sent again by itself.

If another editor, a second tab or your backend has written since the editor loaded, the save is refused with a 409. The toolbar says This template changed since you opened it. and offers Keep mine, which saves this copy over theirs, and Discard mine and reload. Nothing more is saved until one is chosen, and what is on screen stays. If Keep mine itself gets no answer, both stay on offer and Retry sends it again.

A chat message waits for the save it is owed, because a turn edits the server's copy and hands back a replacement for what the editor holds. Edits still inside the debounce go first. If that save fails the message is not sent: the chat says why and offers Send again. A 429 from the chat is said the same way, with how long to wait.

Replace the indicator with renderSaveState, draw it elsewhere with <SaveStateIndicator />, or read the state yourself:

const { status, error, lastSavedAt, conflict, busy, retry, reload, keepMine } = useSaveState()

Bundler setup

Troubleshooting

Still stuck? Email hello@pdfs.build or see the API reference for the rest of the platform.

FAQ