Embedded editor

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                        (15 min, 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 })

  const templateId = `invoice-${user.orgId}`
  const res = await fetch(
    `https://api.pdfs.build/v2/organizations/${user.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,
      }),
    },
  )

  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'

export function ReportDesigner() {
  return (
    <div style={{ height: '100vh' }}>
      <PdfReportProvider
        fetchSessionToken={async () => {
          const res = await fetch('/api/pdfs-session', { method: 'POST' })
          const { token } = await res.json()
          return token
        }}
        onUnauthorized={() => router.refresh()}
        theme={{ primary: '#6366f1' }}
      >
        <PdfReportEditor />
      </PdfReportProvider>
    </div>
  )
}

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"},
        },
    )
    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.

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": "ses_...",
  "token": "emb_...",
  "templateId": "550e8400-e29b-41d4-a716-446655440000",
  "expiresAt": "2026-07-15T12:15:00.000Z"
}

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

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 gives every end-user their own private chat thread on a template. Two users editing the same template never see each other's conversation history because their externalUserId differs.
• 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.

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()

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. PAYG is opt-in and exists only on the Embedded plan.

When credits run out, the editor renders a credit gate instead of accepting new AI turns. You choose what that looks like:

Session expiry

Tokens last 15 minutes by default and never more than an hour. A long editing session will outlive its token, so handle expiry deliberately rather than hoping users are quick.

<PdfReportProvider
  fetchSessionToken={fetchToken}
  onUnauthorized={() => {
    // Remount the provider with a fresh token.
    setSessionKey((n) => n + 1)
  }}
  key={sessionKey}
>

Raising expiresInSeconds to the 3600 maximum reduces how often this fires, at the cost of a longer-lived credential in the browser. Work saved to the template is persisted server-side as the user goes, so an expired session interrupts editing but does not lose committed changes.

Bundler setup

Troubleshooting

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