# Welcome > **Documents, crafted.** Build a template once, expose it as a typed REST API, a signed inbound webhook, or an embeddable form, and render PDFs in milliseconds. Craftkit is a developer toolkit for generating documents. You design a template visually with merge fields, then ship it through whichever surface fits the integration: a typed REST endpoint at `/v1/templates//render`, an HMAC-signed inbound webhook URL, an embeddable builder for your customers, or a drop-in form for end-users to fill. Send the data, get a PDF back, with delivery webhooks, storage, version pinning, and dashboards out of the box. ## Quick Start The fastest path to a rendered PDF is the REST API. Three steps: create a template in the dashboard, mint an API key, render against it. **curl** ```bash curl -X POST https://api.craftkit.dev/v1/templates/invoice/render \ -H "Authorization: Bearer $CRAFTKIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{"data": {"customer": {"name": "Acme Corp"}}}' ``` **Node.js** ```javascript const res = await fetch('https://api.craftkit.dev/v1/templates/invoice/render', { method: 'POST', headers: { Authorization: `Bearer ${process.env.CRAFTKIT_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ data: { customer: { name: 'Acme Corp' } } }), }); const { id, pollUrl } = await res.json(); ``` **Python** ```python import os, requests res = requests.post( "https://api.craftkit.dev/v1/templates/invoice/render", headers={"Authorization": f"Bearer {os.environ['CRAFTKIT_API_KEY']}"}, json={"data": {"customer": {"name": "Acme Corp"}}}, ) job = res.json() ``` The full walkthrough lives in [Quickstart](/documentation/quickstart). ## What's in the docs | Section | Covers | |---|---| | Get started | Quickstart and the mental model behind templates, versions, variables, and renders. | | REST API | Authentication, the render endpoint, polling, the inbound webhook, and the error envelope. | | Embed | Drop the Craftkit builder or form into your own SaaS — theming, JWT, postMessage, the host SDK, the variable catalog. | | Architecture | How the pieces fit together: data model, render pipeline, tenancy. | ## Pick a path - **Backend integrator** — start with the [Quickstart](/documentation/quickstart), then read [Authentication](/documentation/api/authentication) and the [Render API](/documentation/api/render-template). - **Embedding the builder in a SaaS** — open the [Embed overview](/documentation/embed), then the [Embed quickstart](/documentation/embed/quickstart) and [Styling & themes](/documentation/embed/styling). - **Adding a fill-in form for end-users** — see the [Embed quickstart](/documentation/embed/quickstart) (the form section) and the [Form-fill embeddable](/documentation/embed/form-route) reference. - **Curious how it works** — read the [Architecture overview](/documentation/architecture/overview). ## Related - [Quickstart](/documentation/quickstart) - [Concepts](/documentation/concepts) - [Authentication](/documentation/api/authentication) - [Embed quickstart](/documentation/embed/quickstart) --- # Quickstart This walkthrough takes you from zero to a rendered PDF in five minutes. You'll create a project, design a template visually, mint an API key, hit the render endpoint, and download the result. ## Quick Start End-to-end, in three calls: render, poll, download. The same operation in three languages: **curl** ```bash # 1. Enqueue a render curl -X POST https://api.craftkit.dev/v1/templates/invoice/render \ -H "Authorization: Bearer $CRAFTKIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{"data": {"customer": {"name": "Acme Corp"}}}' # 2. Poll until succeeded (returns downloadUrl when done) curl https://api.craftkit.dev/v1/renders/ \ -H "Authorization: Bearer $CRAFTKIT_API_KEY" # 3. Download the PDF curl -L "" -o invoice.pdf ``` **Node.js** ```javascript const headers = { Authorization: `Bearer ${process.env.CRAFTKIT_API_KEY}`, 'Content-Type': 'application/json', }; const enqueue = await fetch('https://api.craftkit.dev/v1/templates/invoice/render', { method: 'POST', headers, body: JSON.stringify({ data: { customer: { name: 'Acme Corp' } } }), }); const { id, pollUrl } = await enqueue.json(); let job; do { await new Promise((r) => setTimeout(r, 250)); job = await (await fetch(pollUrl, { headers })).json(); } while (job.status === 'queued' || job.status === 'rendering'); console.log('PDF ready at:', job.downloadUrl); ``` **Python** ```python import os, time, requests headers = {"Authorization": f"Bearer {os.environ['CRAFTKIT_API_KEY']}"} enqueue = requests.post( "https://api.craftkit.dev/v1/templates/invoice/render", headers=headers, json={"data": {"customer": {"name": "Acme Corp"}}}, ).json() job = enqueue while job["status"] in ("queued", "rendering"): time.sleep(0.25) job = requests.get(enqueue["pollUrl"], headers=headers).json() print("PDF ready at:", job["downloadUrl"]) ``` ## Step 1 — Create a project Sign in at [app.craftkit.dev](/dashboard) and create a project. A project is the unit that owns templates, API keys, webhooks, and rendered assets. ## Step 2 — Design a template Inside the project, click **+ New template** and pick a builder mode: | Mode | When to use it | |---|---| | Document canvas | Paginated A4/Letter with headers, footers, and signatures. Use for contracts, certificates, invoices. | | Simple flow | A continuous document. Use for receipts, transactional emails, short one-pagers. | Use the toolbar to insert a **Variable** block. Give it a key path like `customer.name` and mark it required. Click **Publish version** when you're happy. ## Step 3 — Mint an API key Open the project's **API keys** tab and create one. The cleartext key is shown **once** — copy it immediately and store it as a server-side secret. ## Step 4 — Render The Quick Start above shows the full enqueue → poll → download cycle. Most renders complete in **under 200ms**. If you'd rather hold the connection open instead of polling, set `options.sync: true` on the request. ## Tips - Pin renders to a specific version with `options.versionNumber` for deterministic output across template edits. - Use the dashboard's **Renders** tab to inspect every call: input data, duration, output asset, and which API key triggered it. - For high volume, configure an outgoing webhook (project settings) so Craftkit posts to you on completion — no polling needed. ## Related - [Authentication](/documentation/api/authentication) — how API keys work in practice - [Concepts](/documentation/concepts) — templates, versions, manifests - [POST /v1/templates/:slug/render](/documentation/api/render-template) — full request shape - [Inbound webhook](/documentation/api/inbound-webhook) — let Stripe, Zapier, or Make trigger a render directly --- # Concepts This page is the mental model behind Craftkit. Five primitives compose every workflow: templates, versions, variables, loops, and renders. ## Quick Start If you only remember one thing, remember this hierarchy: ``` Project └── Template (slug: "invoice") └── Template version (immutable snapshot, "v3") ├── Variables (manifest) └── Loops (repeating blocks) └── Render (one execution against input data) ``` A `POST /v1/templates/invoice/render` walks the chain: latest published version of `invoice` → manifest → validate input → enqueue render row. ## Templates A **template** is a visual blueprint with merge fields. It belongs to a project, has a slug (`invoice`, `contract`, ...), and accumulates versions over time. You design templates in either the **Document canvas** (paginated, for contracts) or the **Simple flow** editor (continuous, for receipts). ## Versions Every time you click **Publish version**, Craftkit snapshots the template's content, compiles it, and stores it as a new immutable `templateVersion`. The active version is what `/render` uses by default. Old versions stay on disk forever — past API calls keep working. Pin a render to a specific version: ```json { "data": { "...": "..." }, "options": { "versionNumber": 3 } } ``` ## Variables A **variable** is a single merge field with a key, a label, a data type, and a `required` flag. Keys can be dot-pathed (`customer.name`, `order.shipping.country`). | Data type | Description | |---|---| | `text` | Single-line string | | `longtext` | Multi-line string | | `number` | Finite numeric, optional integer flag | | `currency` | Numeric with currency formatting (`format: "money:EUR"`) | | `date` | ISO date | | `datetime` | ISO datetime | | `boolean` | True/false checkbox | | `image` | Image asset (URL or upload) | | `url` | Hyperlink | | `email` | Email address | | `select` | Fixed choice from a declared `options` list | A `select` variable carries an **`options`** array of `{ value, label }` choices — `value` is stored and validated, `label` is display text. A `select` requires a non-empty `options` list at publish time (a `select` with no options is rejected); option `value`s must be unique, and a `defaultValue`, if set, must be a string matching one of them. At render time only a declared `value` is accepted (anything else fails with `invalid_input_data`), and the auto-generated JSON Schema emits the field as a string `enum` of the option values. `options` is optional and only meaningful for `select`, so clients that ignore it are unaffected. ```json { "key": "bunker_cost_party", "dataType": "select", "required": false, "label": "Bunker cost party", "options": [ { "value": "SHIPOWNER", "label": "Shipowner" }, { "value": "CHARTERER", "label": "Charterer" } ] } ``` When a version is published, Craftkit walks the template, collects every variable and loop, and stores a **variable manifest** on the version. That manifest is the contract behind: - The Zod validator that gates incoming render requests. - The auto-generated JSON Schema shown in the dashboard. - The cURL snippet on the template detail page. - The form fields rendered by the embeddable form route. ## Loops A **loop** is a repeating block (Handlebars-style `{{#each items}}...{{/each}}`) keyed on an array variable. Each loop has an item shape — its own list of variables. Loops are how you express invoice line items, package contents, attendee lists. ## Renders A **render** is one execution of one template version against one set of input data. Each render lives as a row in Postgres with: | Field | Description | |---|---| | `status` | `queued` → `rendering` → `succeeded` \| `failed` \| `cancelled` | | `data` | The input payload that was validated against the manifest | | `downloadUrl` | The output asset URL once the render reaches a terminal state | | `durationMs` | Wall-clock time from enqueue to completion | | `source` | What triggered the render: `api`, `form`, `partner_supplied`, or `dashboard` | | `apiKeyId` | The API key (or embed session) that initiated the call | The dashboard's **Renders** tab is just a window onto this table. ## Glossary | Term | Meaning | |---|---| | Template | A visual blueprint with merge fields, scoped to a project | | Template version | An immutable snapshot of a template's content + manifest | | Variable | A single merge field (key + type + required) | | Loop | A repeating block keyed on an array variable | | Manifest | The list of variables + loops extracted from a version | | Render | One execution of one template version against input data | | API key | A bearer token authenticating one project's API calls | | Inbound webhook | A signed URL that triggers a render from any external system | | Embed session | A short-lived JWT that scopes an iframe mount to one tenant + actor | ## Related - [Quickstart](/documentation/quickstart) — see the primitives in action - [POST /v1/templates/:slug/render](/documentation/api/render-template) — the request that uses the manifest - [Architecture: data model](/documentation/architecture/data-model) — the Postgres schema for these primitives --- # Integration guide A step-by-step implementation guide that takes you from a new Craftkit account to a fully working production integration — covering the REST API, the builder embed, and the form-fill embed. > **Pick your path:** If you only need programmatic PDF rendering (no embedded editor), complete Phase 1 and Phase 2 then stop. Add Phase 3 when your customers need to design their own templates. Add Phase 4 when end-users need to fill and generate documents themselves. --- ## What you'll build | Phase | What it unlocks | |---|---| | Phase 1 — Setup | Account, project, API key, local dev environment | | Phase 2 — API rendering | Your backend calls Craftkit, gets a PDF | | Phase 3 — Builder embed | Your customers design templates inside your app | | Phase 4 — Form embed | Your end-users fill templates and produce documents | | Phase 5 — Production | Hardening, key rotation, monitoring, error handling | --- ## Phase 1 — Setup ### 1.1 Create your project Sign in → Dashboard → **New project** → give it a name. One project = one namespace for templates, API keys, and embed settings. ### 1.2 Design a template Dashboard → your project → **Templates** → **New template**. Design it in the visual editor: - Add text, images, and layout blocks - Insert variables with `{{ }}` — e.g. `{{customer.name}}`, `{{invoice.total}}` - Publish the template when ready Note the **template slug** from the URL (`/templates//edit`) — you'll use it in API calls. ### 1.3 Create an API key Dashboard → Project → **API keys** → **Create key** → copy it immediately (shown once). > **Environment rule:** API keys are stored as SHA-256 hashes in the database they were created in. A key minted on localhost only works against `http://localhost:3000`. A production key only works against `https://api.craftkit.dev`. Always create keys in the target environment's dashboard. ### 1.4 Configure your local environment ```bash # .env.local CRAFTKIT_API_KEY=ck_live_... # never commit this CRAFTKIT_API_URL=https://api.craftkit.dev ``` Verify connectivity: ```bash curl https://api.craftkit.dev/health # → { "status": "ok" } ``` --- ## Phase 2 — API rendering This is the simplest integration: your backend feeds data → Craftkit returns a PDF. No iframe, no embed, no browser involved. ### 2.1 Enqueue a render ```bash curl -X POST https://api.craftkit.dev/v1/templates/charter-contract/render \ -H "Authorization: Bearer $CRAFTKIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "data": { "customer.name": "Ada Lovelace", "booking.date": "2026-06-15", "booking.vessel": "SV Horizon" }, "jobId": "booking-12345" }' ``` Response: ```json { "id": "render_01...", "status": "queued", "pollUrl": "https://api.craftkit.dev/v1/renders/render_01..." } ``` `jobId` is optional but recommended — it makes the render idempotent (retrying with the same `jobId` returns the existing render instead of creating a new one). ### 2.2 Poll until complete ```javascript async function waitForRender(renderId, timeoutMs = 30_000) { const deadline = Date.now() + timeoutMs; let delay = 250; while (Date.now() < deadline) { const r = await fetch(`https://api.craftkit.dev/v1/renders/${renderId}`, { headers: { Authorization: `Bearer ${process.env.CRAFTKIT_API_KEY}` }, }); const render = await r.json(); if (render.status === 'succeeded') return render.downloadUrl; if (render.status === 'failed') { throw new Error(`Render failed: ${render.errorMessage}`); } await new Promise(res => setTimeout(res, delay)); delay = Math.min(delay * 2, 5_000); } throw new Error('Render timed out'); } const pdfUrl = await waitForRender(renderId); ``` ### 2.3 Receive via webhook (alternative to polling) Instead of polling, configure a webhook on the template so Craftkit pushes the result to your server when done. Dashboard → Template → **Webhooks** → **Add webhook URL** → enter your endpoint. ```javascript // POST https://yourapp.com/api/craftkit/webhook app.post('/api/craftkit/webhook', express.raw({ type: 'application/json' }), (req, res) => { const sig = req.headers['x-craftkit-signature']; const hmac = createHmac('sha256', process.env.CK_WEBHOOK_SECRET) .update(req.body).digest('hex'); if (hmac !== sig) return res.status(401).end(); // x-craftkit-signature is raw hex, no prefix const event = JSON.parse(req.body); if (event.event === 'render.succeeded') { storeDownloadUrl(event.renderId, event.downloadUrl); } res.json({ received: true }); }); ``` ### 2.4 Handle errors ```javascript const res = await fetch(url, options); if (!res.ok) { const { error } = await res.json(); switch (error.code) { case 'template_not_found': throw new Error('Wrong slug or wrong project API key'); case 'no_published_version': throw new Error('Publish a template version in the dashboard first'); case 'invalid_input_data': console.error('Field errors:', error.issues?.fieldErrors); throw new Error('Data does not match the template manifest'); case 'rate_limited': await backoff(); return retry(); default: throw new Error(`${error.code}: ${error.message}`); } } ``` See [Errors](/documentation/api/errors) for the full code list and retry semantics. --- ## Phase 3 — Builder embed Let your customers design their own templates directly inside your app — without leaving to a separate tool. ### 3.1 Enable embed mode Dashboard → Project → **Embed → Overview** → **Enable embed mode**. Craftkit generates a publishable key (`ck_pk_live_...`) and an Ed25519 signing key. Add your production domain to the allowed origins list: | Pattern | Example | |---|---| | Exact match | `https://app.acme.com` | | Wildcard subdomain | `https://*.acme.com` | ### 3.2 Publish a variable catalog (optional but recommended) A catalog injects your data model into the builder's variable picker. Ship it from your CI/CD pipeline so it stays in sync with your database schema. ```bash curl -X POST https://api.craftkit.dev/v1/embed/catalogs \ -H "Authorization: Bearer $CRAFTKIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "acme-v1", "catalog": { "allowCustom": false, "namespaces": [ { "key": "customer", "label": "Customer", "fields": [ { "key": "customer.name", "label": "Name", "dataType": "text" }, { "key": "customer.email", "label": "Email", "dataType": "email" }, { "key": "customer.company", "label": "Company", "dataType": "text" } ] }, { "key": "booking", "label": "Booking", "fields": [ { "key": "booking.date", "label": "Date", "dataType": "date" }, { "key": "booking.vessel", "label": "Vessel", "dataType": "text" }, { "key": "booking.total", "label": "Total", "dataType": "currency" } ] } ], "loops": [] } }' # → { "id": "cat_01...", "name": "acme-v1", "version": 1 } ``` Store the catalog `id`. Use it in every session mint. ### 3.3 Add a session-mint endpoint to your backend ```javascript // POST /api/craftkit/builder-session app.post('/api/craftkit/builder-session', requireAuth, async (req, res) => { const { templateExternalId } = req.body; // null for new templates const r = await fetch('https://api.craftkit.dev/v1/embed/sessions', { method: 'POST', headers: { Authorization: `Bearer ${process.env.CK_SECRET}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ tenant: { externalId: req.user.orgId, displayName: req.user.orgName, }, actor: { externalId: req.user.id, email: req.user.email, displayName: req.user.name, }, scope: { mode: templateExternalId ? 'edit' : 'create', templateExternalId, }, permissions: { publish: true, saveDraft: true, createCustomVariables: false, // lock to catalog viewVersionHistory: true, }, catalogId: process.env.CK_CATALOG_ID, callbacks: { onPublished: `${process.env.APP_URL}/api/craftkit/events`, }, }), }); if (!r.ok) { const { error } = await r.json(); return res.status(502).json({ error }); } const { session_token, renew_token, expires_at } = await r.json(); // Store renew_token server-side for later refresh await storeRenewToken(req.user.id, renew_token); res.json({ sessionToken: session_token, expiresAt: expires_at }); }); ``` ### 3.4 Add a session-refresh endpoint ```javascript // POST /api/craftkit/refresh app.post('/api/craftkit/refresh', requireAuth, async (req, res) => { const renewToken = await getRenewToken(req.user.id); const r = await fetch('https://api.craftkit.dev/v1/embed/sessions/refresh', { method: 'POST', headers: { Authorization: `Bearer ${process.env.CK_SECRET}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ renewToken }), }); const { session_token, renew_token } = await r.json(); await storeRenewToken(req.user.id, renew_token); // rotate — it's single-use res.json({ session_token }); }); ``` ### 3.5 Mount the builder in your frontend ```javascript import { Craftkit } from '@craftkit/embed'; const ck = Craftkit.init({ publishableKey: 'ck_pk_live_...' }); async function openTemplateEditor(templateExternalId = null) { // 1. Get a session token from your backend const { sessionToken } = await fetch('/api/craftkit/builder-session', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ templateExternalId }), }).then(r => r.json()); // 2. Mount the builder const builder = ck.mountBuilder({ container: '#editor-container', sessionToken, autoResize: true, refresh: async () => { const r = await fetch('/api/craftkit/refresh', { method: 'POST' }); return (await r.json()).session_token; }, }); // 3. Handle the result builder.on('template.published', async ({ templateId, version, manifest }) => { // Save the mapping to your database await saveTemplate({ templateExternalId, craftkitId: templateId, version }); builder.destroy(); showToast(`Template published (v${version})`); }); builder.on('close.requested', () => builder.destroy()); builder.on('error', (err) => { if (!err.recoverable) { builder.destroy(); showError(err.message); } }); } ``` ### 3.6 Handle the webhook ```javascript // POST /api/craftkit/events app.post('/api/craftkit/events', express.raw({ type: 'application/json' }), async (req, res) => { const sig = req.headers['x-craftkit-signature']; const hmac = createHmac('sha256', process.env.CK_WEBHOOK_SECRET) .update(req.body).digest('hex'); if (hmac !== sig) return res.status(401).end(); // x-craftkit-signature is raw hex, no prefix const event = JSON.parse(req.body); if (event.type === 'template.published') { await db.upsert('templates', { tenantId: event.tenantExternalId, externalId: event.templateExternalId, craftkitId: event.templateId, version: event.version, variables: event.manifest.fields, }); } res.json({ received: true }); }); ``` > **Tip:** Always write to your database from the webhook, not just the postMessage event. The postMessage fires faster (great for UI), but the webhook is durable — it fires even if the tab was closed before the editor finished. --- ## Phase 4 — Form embed Let end-users fill a published template's variables and produce a document, directly inside your app — no coding required on their part. ### 4.1 Prerequisites - You need a **published template** (from Phase 3 or created in the dashboard). - The template's variables must match your data model (use the catalog from Phase 3). - The session must use `scope.mode: 'fill'` and include `scope.templateId`. ### 4.2 Add a form-session endpoint to your backend ```javascript // POST /api/craftkit/form-session app.post('/api/craftkit/form-session', requireAuth, async (req, res) => { const { craftkitTemplateId } = req.body; // from your DB (stored in Phase 3) const r = await fetch('https://api.craftkit.dev/v1/embed/sessions', { method: 'POST', headers: { Authorization: `Bearer ${process.env.CK_SECRET}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ tenant: { externalId: req.user.orgId, displayName: req.user.orgName }, actor: { externalId: req.user.id, email: req.user.email }, scope: { mode: 'fill', template_id: craftkitTemplateId, }, permissions: { submit_form: true }, }), }); const { session_token, renew_token } = await r.json(); await storeRenewToken(req.user.id, renew_token); res.json({ session_token }); }); ``` ### 4.3 Mount the form in your frontend ```javascript import { Craftkit } from '@craftkit/embed'; const ck = Craftkit.init({ publishableKey: 'ck_pk_live_...' }); async function openDocumentForm(craftkitTemplateId) { const { session_token } = await fetch('/api/craftkit/form-session', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ craftkitTemplateId }), }).then(r => r.json()); const form = ck.mountForm({ container: '#form-container', sessionToken: session_token, autoResize: true, refresh: async () => { const r = await fetch('/api/craftkit/refresh', { method: 'POST' }); return (await r.json()).session_token; }, }); // Optional: pre-fill form fields from your app's data form.on('ready', () => { form.setValues({ 'customer.name': currentUser.name, 'customer.email': currentUser.email, }); }); // Document produced form.on('form.completed', ({ renderId, downloadUrl }) => { storeDocument(renderId, downloadUrl); showDownloadLink(downloadUrl); }); form.on('close.requested', () => form.destroy()); } ``` ### 4.4 Optional: dataset prefill Let users pick a record from your app's data (e.g. "pick a booking") and have it auto-fill the form fields. ```javascript form.on('ready', () => { form.setDatasets({ bookings: { label: 'Pick a booking', items: myBookings.map(b => ({ id: b.id, label: `${b.vessel} — ${b.date}`, values: { 'booking.date': b.date, 'booking.vessel': b.vessel, 'booking.total': b.total, }, })), }, }); }); ``` Dataset content stays client-side — Craftkit only logs the selected item's `id` for audit. ### 4.5 Optional: intercept submit for custom logic Intercept the submit to add signing, custom rendering, or post-processing before the PDF is displayed. ```javascript form.on('submit', async (e) => { if (!needsSigning(e.data)) return; // skip — let default render proceed e.preventDefault(); // claim the submit (must be within 500ms) try { const signed = await mySigningService(e.data); const pdf = await myRenderPipeline(signed); await e.complete({ pdfUrl: pdf.url }); // iframe displays the PDF; emits form.completed { source: 'partner_supplied' } } catch (err) { await e.fail({ message: err.message }); } }); ``` See [Form-fill embeddable](/documentation/embed/form-route) for the full form reference. --- ## Phase 5 — Production hardening ### Checklist **API keys** - [ ] One key per integration (rendering, embed, inbound webhooks — each separate) - [ ] Keys stored in environment variables, never in code or logs - [ ] Test keys (`ck_test_...`) for staging, live keys (`ck_live_...`) for production — never mix - [ ] Rotate keys quarterly: mint new → deploy → revoke old **Embed setup** - [ ] Only production origins in the allowed-origins list - [ ] Catalog deployed from CI/CD and `catalogId` stored in your env vars - [ ] `renew_token` stored server-side and rotated on every refresh - [ ] `refresh` callback wired up in the SDK so sessions don't expire mid-edit **Error handling** - [ ] All API calls wrapped with error handling that switches on `error.code` - [ ] Retry logic for `rate_limited` and `5xx` (exponential backoff, max 5 attempts) - [ ] `error` event handled in the builder and form with fallback UI for `recoverable: false` **Webhooks** - [ ] HMAC signature verified on every webhook before processing - [ ] Webhook endpoint responds within 10s (enqueue heavy work, don't block) - [ ] Idempotency: use `jobId` for renders, check for duplicate `templateId + version` in your DB **Monitoring** - [ ] Alert on sustained `5xx` rate from Craftkit endpoints - [ ] Track `session.expired` events — indicates `refresh` is failing - [ ] Log `error.code` from the embed error event to a monitoring system ### Key rotation procedure ```bash # 1. Mint a new key in the dashboard # 2. Update your environment variable export CRAFTKIT_API_KEY=ck_live_ # 3. Deploy (traffic shifts to new key) vercel deploy --prod # 4. Verify traffic on new key (check your metrics / Craftkit dashboard) # 5. Revoke the old key in the dashboard # Revocation is immediate — no grace period. ``` ### Error code quick reference | Code | Phase | Fix | |---|---|---| | `missing_authorization` | Any | Add `Authorization: Bearer ...` header | | `invalid_credentials` | Any | Key from wrong environment or embed not enabled — see [Authentication](/documentation/api/authentication#troubleshooting-invalid_credentials) | | `template_not_found` | Phase 2 | Wrong slug or wrong project's key | | `no_published_version` | Phase 2, 4 | Publish a template version first | | `invalid_input_data` | Phase 2 | Check `error.issues.fieldErrors` against the template manifest | | `rate_limited` | Any | Back off and retry | | `session_invalid` | Phase 3, 4 | Stale session — mint a new one | | `origin_not_allowed` | Phase 3, 4 | Add the origin in Dashboard → Embed → Origins | | `internal_error` | Any | Retry with backoff; check status page | --- ## Related - [Quickstart](/documentation/quickstart) — render your first PDF in five minutes - [Builder embed](/documentation/embed/builder) — full builder reference - [Form-fill embeddable](/documentation/embed/form-route) — full form reference - [Embed quickstart](/documentation/embed/quickstart) — minimal embed setup - [Variable catalog](/documentation/embed/variable-catalog) — field schema reference - [POST /v1/embed/catalogs](/documentation/api/embed-catalogs) — catalog API - [Authentication](/documentation/api/authentication) — key management and troubleshooting - [Errors](/documentation/api/errors) — full error envelope and retry semantics --- # AI project setup — one-prompt Craftkit integration Copy the prompt below and paste it directly into Claude, ChatGPT, Cursor, or any AI coding assistant. The AI will ask you a few questions and then generate a complete, production-ready Craftkit integration tailored to your project. --- ## The prompt > You are setting up a complete Craftkit document-generation integration. > Craftkit (https://www.craftkit.dev) lets SaaS apps embed a template builder and/or a > document form-fill widget. It also exposes a REST API for programmatic PDF rendering. > > Ask me the following questions ONE AT A TIME before writing any code: > > 1. **Stack**: What framework and language is your backend? (Next.js App Router, Express, FastAPI, Rails, Laravel, etc.) > 2. **Frontend**: What framework is your frontend? (React, Vue, Svelte, vanilla JS, etc.) > 3. **Auth**: What auth system do you use? (Clerk, NextAuth, custom JWT, session cookies, etc.) — I need to know how to protect the Craftkit proxy routes. > 4. **Tenancy**: Is this single-tenant (one org) or multi-tenant (many orgs, each needing isolated templates)? > 5. **Use case**: Which embed surfaces do you need? > - (A) **Builder only** — your customers design their own templates > - (B) **Form-fill only** — your users fill and generate documents from pre-built templates > - (C) **Both** — customers design templates; users fill them > - (D) **API-only** — your backend triggers renders programmatically (no embed) > 6. **Variables**: Describe your data model briefly — what fields will populate the documents? > (e.g. "customer name/email, booking date/vessel, invoice total") > > Once I answer all six questions, generate the following **complete, working code** with no placeholders: > > ### A. Environment variables > List every env var needed with a comment explaining each one. > > ### B. Backend proxy routes > For Next.js App Router: generate the full `app/api/craftkit/` directory tree with all > route files. For other frameworks: generate equivalent middleware/controllers. > Always use the **admin provision** pattern for multi-tenant: > - `lib/credentials.ts` — `getOrgApiKey(orgId)` caches per-org keys via `POST /v1/admin/provision` > - `session/route.ts` — mint sessions; resolve org key; support modes: create/edit/fill/view > - `refresh/route.ts` — refresh sessions; **must pass `orgId` and use `getOrgApiKey(orgId)`**, > NOT a single fixed `CRAFTKIT_API_KEY` (that breaks multi-tenant refresh) > - `templates/route.ts` — list published templates for an org > - `renders/route.ts` — list renders for an org > - `renders/[id]/download/route.ts` — proxy PDF download > > ### C. Frontend embed component > A complete, reusable React/Vue/vanilla component that: > - Mints a session on mount (calls the backend session route) > - Renders the Craftkit iframe using the returned `iframe_url` > - Handles `session.expiring` by calling the refresh route with `orgId` > - Handles `session.expired` by re-minting > - Emits `onPublished` when a template is published (saves `craftkitTemplateId` to your DB) > - Emits `onCompleted` when a form-fill document is ready > - Shows a loading state while minting and an error state on failure > > ### D. Variable catalog > Generate a `POST /v1/embed/catalogs` call (curl + equivalent code) with my data model > mapped to Craftkit field types (`text`, `number`, `currency`, `date`, `email`, `url`, > `image`, `boolean`, `longtext`). Mark fields that should be required in the form. > > ### E. Example page > One example page/route that uses the embed component — create mode for a new template > or fill mode for a document. > > ### F. Checklist > A copy-paste checklist of everything I need to do in the Craftkit dashboard before this > code will work: > - [ ] Create account and project > - [ ] Enable embed mode (Dashboard → Project → Embed → Overview) > - [ ] Add allowed origins for the embed iframe > - [ ] Note the CRAFTKIT_ADMIN_KEY from project settings > - [ ] (if catalog) Publish the variable catalog and note its name > > **Key rules the AI must follow when generating code:** > - Never hardcode API keys or secrets — always use env vars > - The refresh route MUST use `getOrgApiKey(orgId)`, not a fixed `CRAFTKIT_API_KEY` > - The `templateExternalId` passed to session minting must be the Craftkit UUID > (from the `template.published` event), NOT an internal MongoDB ObjectId or integer ID > - The `iframe_url` from the session response must be used verbatim — never construct > the iframe URL manually (path differs between fill and builder modes) > - Validate `e.origin` before acting on postMessage events > - Always mint a fresh session for each iframe mount — never cache `iframe_url` --- ## What the AI will generate Depending on your answers, the AI generates a complete, drop-in integration: | Answer | Generated output | |---|---| | Next.js + Clerk + multi-tenant + builder + form | Full `app/api/craftkit/` directory, `CraftkitEmbed` component, Clerk `auth()` guard, Zustand/React Query hooks | | Express + JWT + single-tenant + API-only | Middleware, render controller, webhook handler, polling utility | | Next.js + NextAuth + single-tenant + form-fill | Slim proxy (no provision), form-fill component, catalog | --- ## Quick reference — key decisions ### Multi-tenant vs single-tenant | | Single-tenant | Multi-tenant | |---|---|---| | Env vars | `CRAFTKIT_API_KEY` (one fixed key) | `CRAFTKIT_ADMIN_KEY` (provision key) | | Session mint | Use `CRAFTKIT_API_KEY` directly | Call `getOrgApiKey(orgId)` | | Session refresh | Use `CRAFTKIT_API_KEY` directly | Call `getOrgApiKey(orgId)` — **MUST match session's org** | | Org isolation | Shared project | One Craftkit project per org, auto-provisioned | ### Mode cheat sheet | Mode | iframe path | Permissions required | |---|---|---| | `create` | `/embed/builder` | `publish: true, saveDraft: true` (defaults) | | `edit` | `/embed/builder` | `publish: true, saveDraft: true` (defaults) | | `view` | `/embed/builder` | `publish: false, saveDraft: false` | | `fill` | `/embed/form` | `submitForm: true` ← **must set explicitly** | ### Critical pitfalls 1. **Never use a MongoDB ObjectId as `templateExternalId`** — Craftkit requires UUID format. Store the UUID from the `template.published` event and use that. 2. **Never cache `iframe_url` across page navigations** — each mount needs a fresh mint. 3. **Never use a fixed `CRAFTKIT_API_KEY` for refresh in multi-tenant** — the session's `partnerId` must match the key used for refresh. Use `getOrgApiKey(orgId)`. 4. **`submitForm` defaults to `false`** — fill sessions must explicitly set it to `true`. 5. **API keys are environment-specific** — a key created in local dev does not exist in production. Always create keys in the target environment's Craftkit dashboard. --- ## Related - [Integration guide](/documentation/integration-guide) — full phase-by-phase walkthrough - [Multi-tenant embed](/documentation/embed/multi-tenant) — admin provision deep dive - [Embed quickstart](/documentation/embed/quickstart) — minimal setup - [Variable catalog](/documentation/embed/variable-catalog) — field schema reference - [Client integration guide](../embed/13-client-integration-guide.md) — pitfall checklist --- # Authentication All requests to `/v1/*` carry a project API key in the `Authorization` header. Keys are scoped to one project and can be created or revoked from the dashboard. This page covers the format, how to create and rotate keys, scope, and the errors you'll see when something is off. ## Quick Start Three languages, the same authenticated request. **curl** ```bash curl https://api.craftkit.dev/v1/renders/0193c2c3 \ -H "Authorization: Bearer $CRAFTKIT_API_KEY" ``` **Node.js** ```javascript const res = await fetch('https://api.craftkit.dev/v1/renders/0193c2c3', { headers: { Authorization: `Bearer ${process.env.CRAFTKIT_API_KEY}`, }, }); ``` **Python** ```python import os, requests res = requests.get( "https://api.craftkit.dev/v1/renders/0193c2c3", headers={"Authorization": f"Bearer {os.environ['CRAFTKIT_API_KEY']}"}, ) ``` ## Header format ```http Authorization: Bearer ck_live_ ``` | Prefix | Environment | |---|---| | `ck_live_` | Production renders, billable, hits the live worker pool | | `ck_test_` | Test renders, free, watermarked output | ## Creating a key Dashboard → Project → **API keys** → enter a name → **Create key**. The cleartext key is returned **once** — copy it immediately. We only store the SHA-256 hash, so a lost key cannot be recovered. Each project can have many keys, each independently revocable. Use one key per integration so you can rotate without coordinating an outage across services. ## Revoking a key Same screen → **Revoke**. Subsequent calls return `401 invalid_credentials` immediately (no grace window). Issue a replacement first, deploy it, then revoke. ## Scope API keys are scoped to one project. They **can**: - POST a render against any template in that project. - Read renders for that project. - Trigger inbound webhooks for templates in that project (the inbound token authenticates instead, but the key still owns the resulting render row). They **cannot**: - Modify templates, projects, or webhook configs (use the dashboard). - Read other projects' data. - Mint embed sessions for partner integrations (use the embed publishable + signing key pair instead). ## Errors | HTTP | Code | When | Fix | |---|---|---|---| | 401 | `missing_authorization` | No `Authorization: Bearer ...` header | Add the header | | 401 | `invalid_credentials` | Key is unknown or revoked | Mint a new key | | 403 | `partner_suspended` | Project's embed partnership is suspended | Contact support | ## Best practices - **Never embed keys in client code.** Browser bundles, mobile apps, and public repositories all leak. Keep keys on a server. - **Use environment-specific keys.** Separate `ck_test_` for staging and `ck_live_` for production. Never share a key across environments. - **Rotate quarterly.** Mint a new key, deploy it, revoke the old one once metrics confirm zero traffic on the previous key. - **One key per workload.** Background jobs, the synchronous API path, and the inbound webhook handler each get their own key. Revoking one doesn't disrupt the others. ## Troubleshooting `invalid_credentials` **The most common cause: the key was created in a different environment.** API keys are stored as SHA-256 hashes in the database for the environment where they were created. A key you minted in your local dev environment does not exist in production, and vice versa. If you see `invalid_credentials` after deploying, the fix is to mint a new key inside the target environment's dashboard. ``` Local dev key → only works against http://localhost:3000 Production key → only works against https://api.craftkit.dev ``` **Second most common cause (embed sessions): embed is not enabled for the project.** `POST /v1/embed/sessions` and `POST /v1/embed/catalogs` require the API key's project to have embed enabled. An otherwise valid key returns `invalid_credentials` on these endpoints if the project has no embed partner record. Fix: Dashboard → Project → **Embed → Overview** → **Enable embed mode**. **Checklist** | Symptom | Check | |---|---| | Valid key works locally, fails in production | Re-mint the key in the production dashboard | | Key works on `/v1/renders/*` but not `/v1/embed/*` | Enable embed mode for the project | | Key was working, now suddenly fails | Check if it was revoked (Revoke column in API keys tab) | | `missing_authorization` instead of `invalid_credentials` | The `Authorization: Bearer ...` header is missing entirely | ## Related - [POST /v1/templates/:slug/render](/documentation/api/render-template) — the most common authenticated call - [Errors](/documentation/api/errors) — the full envelope shape - [Inbound webhook](/documentation/api/inbound-webhook) — alternative auth via per-template token --- # POST /v1/templates/:slug/render Enqueue a render against a template. Returns `202 Accepted` with a poll URL. The variable data must match the template version's manifest, validated server-side with Zod. ```http POST /v1/templates/:slug/render ``` `:slug` is the template's slug within the authenticated project. ## Quick Start **curl** ```bash curl -X POST https://api.craftkit.dev/v1/templates/invoice/render \ -H "Authorization: Bearer $CRAFTKIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "data": { "customer": { "name": "Acme Corp" }, "items": [{ "name": "Widget", "qty": 5, "price": 9.99 }], "total": 49.95 } }' ``` **Node.js** ```javascript const res = await fetch('https://api.craftkit.dev/v1/templates/invoice/render', { method: 'POST', headers: { Authorization: `Bearer ${process.env.CRAFTKIT_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ data: { customer: { name: 'Acme Corp' }, items: [{ name: 'Widget', qty: 5, price: 9.99 }], total: 49.95, }, }), }); const { id, pollUrl } = await res.json(); ``` **Python** ```python import os, requests res = requests.post( "https://api.craftkit.dev/v1/templates/invoice/render", headers={"Authorization": f"Bearer {os.environ['CRAFTKIT_API_KEY']}"}, json={ "data": { "customer": {"name": "Acme Corp"}, "items": [{"name": "Widget", "qty": 5, "price": 9.99}], "total": 49.95, } }, ) job = res.json() ``` ## Request body ```json { "data": { "customer": { "name": "Acme Corp" }, "items": [{ "name": "Widget", "qty": 5, "price": 9.99 }], "total": 49.95 }, "options": { "versionNumber": 3, "sync": false, "filename": "invoice-2026-005.pdf" } } ``` | Field | Type | Description | Default | |---|---|---|---| | `data` | object | Variable values keyed by manifest key paths. Required. Scalars nest by dot-path; loops are keyed by their dot-free top-level key. Keys absent from the manifest are stripped. | — | | `jobId` | string | Optional idempotency key. Retrying with the same value returns the original render instead of creating a duplicate. The `Idempotency-Key` request header takes precedence. | — | | `options.versionNumber` | integer | Pin to a specific published version. | Current published version | | `options.sync` | boolean | Accepted by the schema but **not honored** — every render is async. Poll the result or use a webhook. | `false` | | `options.filename` | string | Override the asset filename. | Template default | > **Idempotency.** Send an `Idempotency-Key` header (preferred) or a body `jobId` so a retried submit dedupes to the original render. The header wins when both are present; the response is `200` on an idempotent replay vs `202` for a newly-queued render. ## Response — `202 Accepted` ```json { "id": "0193c2c3-...", "status": "queued", "pollUrl": "https://api.craftkit.dev/v1/renders/0193c2c3-...", "downloadUrl": null, "errorMessage": null, "createdAt": "2026-05-03T10:14:00.000Z" } ``` | Field | Type | Description | |---|---|---| | `id` | string | Render id (UUIDv7). | | `status` | string | `queued` initially. Progresses to `rendering` then `succeeded` \| `failed`. | | `pollUrl` | string | Hit this with the same bearer token to poll status. | | `downloadUrl` | string \| null | Populated on success. A permanent public URL (no presigning, no TTL); `null` until the render succeeds. | | `errorMessage` | string \| null | Populated on failure. | | `createdAt` | string | ISO-8601 timestamp. | Poll `pollUrl` until `status` is `succeeded` or `failed`. See [GET /v1/renders/:id](/documentation/api/render-status) for polling cadence and the outgoing webhook alternative. ## Errors | HTTP | Code | Meaning | Fix | |---|---|---|---| | 400 | `invalid_json` | Body wasn't valid JSON | Check `Content-Type` and JSON.stringify | | 400 | `invalid_request` | Top-level shape didn't match `{ data, options? }` | See request body table above | | 400 | `invalid_input_data` | Data didn't match the version's manifest | Inspect `issues.fieldErrors` for offending keys | | 404 | `template_not_found` | No template with that slug in this project | Check the slug and the API key's project scope | | 404 | `version_not_found` | `options.versionNumber` doesn't exist | Omit it or pick a real version | | 409 | `no_published_version` | Template has no published version yet | Publish a version in the dashboard | | 429 | `rate_limited` | Project quota exceeded | Back off with jitter | See [Errors](/documentation/api/errors) for the envelope shape and full code list. ## Tips - **Idempotency:** safe to retry on 5xx and network errors — send the same `Idempotency-Key` header (or body `jobId`) so the retry returns the original render instead of creating a duplicate. Use a stable business key (e.g. `invoice-{orderId}`), not a per-attempt random value. A retry after a failure returns the failed render; use a new key to force a fresh attempt. - **No sync mode:** `options.sync` is not honored — always poll `pollUrl` or configure an outgoing webhook. There is no long-poll. - **Validation introspection:** the dashboard's template detail page exposes the auto-generated JSON Schema and a working cURL snippet that matches the live manifest. ## Related - [GET /v1/renders/:id](/documentation/api/render-status) — poll the render to completion - [Inbound webhook](/documentation/api/inbound-webhook) — same pipeline, signed-URL trigger - [Errors](/documentation/api/errors) — error envelope and retry semantics - [Authentication](/documentation/api/authentication) — bearer token format --- # GET /v1/renders/:id Get the current status of a render. Most renders complete in under 200ms — this endpoint is what you poll between enqueue and download. For high volume, prefer the outgoing webhook. ```http GET /v1/renders/:id ``` ## Quick Start **curl** ```bash curl https://api.craftkit.dev/v1/renders/0193c2c3 \ -H "Authorization: Bearer $CRAFTKIT_API_KEY" ``` **Node.js** ```javascript async function pollUntilDone(pollUrl) { const headers = { Authorization: `Bearer ${process.env.CRAFTKIT_API_KEY}` }; let delay = 200; for (let i = 0; i < 20; i++) { const job = await (await fetch(pollUrl, { headers })).json(); if (job.status === 'succeeded' || job.status === 'failed') return job; await new Promise((r) => setTimeout(r, delay)); delay = Math.min(delay * 1.5, 1000); } throw new Error('render timed out'); } ``` **Python** ```python import os, time, requests def poll_until_done(poll_url): headers = {"Authorization": f"Bearer {os.environ['CRAFTKIT_API_KEY']}"} delay = 0.2 for _ in range(20): job = requests.get(poll_url, headers=headers).json() if job["status"] in ("succeeded", "failed"): return job time.sleep(delay) delay = min(delay * 1.5, 1.0) raise TimeoutError("render timed out") ``` ## Response ```json { "id": "0193c2c3-...", "status": "succeeded", "pollUrl": "https://api.craftkit.dev/v1/renders/0193c2c3-...", "downloadUrl": "https://cdn.craftkit.dev/.../0193c2c3.pdf", "errorMessage": null, "createdAt": "2026-05-03T10:14:00.000Z", "completedAt": "2026-05-03T10:14:00.150Z", "durationMs": 150 } ``` | Field | Type | Description | |---|---|---| | `id` | string | Render id (UUIDv7). | | `status` | string | See status progression below. | | `pollUrl` | string | Self-referential; same as the request URL. | | `downloadUrl` | string \| null | Populated when `status === 'succeeded'`. A permanent public URL (no presigning, no TTL); `null` if no public bucket is configured. For private or revokable delivery, use the partner-key download stream or a share link. | | `errorMessage` | string \| null | Populated when `status === 'failed'`. | | `createdAt` | string | ISO-8601 enqueue timestamp. | | `completedAt` | string \| null | ISO-8601 terminal-state timestamp. | | `durationMs` | integer \| null | Wall-clock render duration. | ## Status progression ``` queued → rendering → succeeded → failed → cancelled ``` `succeeded` and `failed` are the terminal states you will observe — once reached, the row never changes. `cancelled` exists in the enum but is not produced today (there is no cancellation path), so branch on `succeeded`/`failed`. ## Polling cadence A reasonable poll loop: | Step | Delay | |---|---| | First poll | 200ms after the 202 | | Backoff | 200ms, 300ms, 500ms, 1s, 1s, 1s ... capped at 1s | | Timeout | 30s — return an error to your caller after that | There is no synchronous render mode — `options.sync` is accepted by the schema but not honored, and the render endpoint always returns `202` with `status: "queued"`. Either poll (above) or use the outgoing webhook (below). If you'd rather not poll, prefer the webhook. ## Outgoing webhook (preferred for high volume) Configure an outgoing webhook in your project settings. Craftkit POSTs to your URL when a render reaches a terminal state, signed with HMAC. Saves the polling round-trip and your worker count. ```json { "event": "render.succeeded", "renderId": "0193c2c3-...", "templateId": "1f2e3d4c-...", "status": "succeeded", "downloadUrl": "https://cdn.craftkit.dev/.../0193c2c3.pdf", "errorMessage": null, "createdAt": "2026-05-03T10:14:00.000Z", "completedAt": "2026-05-03T10:14:00.150Z" } ``` Headers include `x-craftkit-event`, `x-craftkit-signature` (HMAC-SHA256 hex of the raw body), `x-craftkit-timestamp`, and `x-craftkit-delivery-id`. Subscribed events are `render.succeeded` and `render.failed`. Verify the signature with your webhook secret: **Node.js** ```javascript import crypto from 'node:crypto'; const expected = crypto .createHmac('sha256', process.env.WEBHOOK_SECRET) .update(rawBody) .digest('hex'); if (expected !== req.headers['x-craftkit-signature']) { throw new Error('bad signature'); } ``` **Python** ```python import hmac, hashlib, os expected = hmac.new( os.environ["WEBHOOK_SECRET"].encode(), raw_body, hashlib.sha256, ).hexdigest() if not hmac.compare_digest(expected, request.headers["x-craftkit-signature"]): raise ValueError("bad signature") ``` ## Best practices - **Always cap your poll loop.** A runaway poll loop on a stuck render burns API budget. 20 attempts × 1s max = 20s is plenty. - **Use the outgoing webhook above ~10 renders/min.** Polling at scale wastes round-trips. - **`downloadUrl` is a permanent public URL** (no presigning, no TTL). If you need expiry or private delivery, mint a share link or use the partner-key download stream rather than handing out the raw URL. - **Check `durationMs` for capacity planning.** Sustained durations > 1s mean your templates are doing heavy work — consider splitting them. ## Related - [POST /v1/templates/:slug/render](/documentation/api/render-template) — produces the id you poll - [Errors](/documentation/api/errors) — what `status: 'failed'` looks like - [Inbound webhook](/documentation/api/inbound-webhook) — third-party trigger, same status flow --- # POST /v1/hooks/:token Trigger a render from any external system that can POST JSON. The webhook URL and HMAC secret are auto-generated when a template is created. Inbound webhooks share the rendering pipeline with the regular render endpoint, so the same validation, versioning, dashboard view, and outgoing webhooks apply. ```http POST /v1/hooks/:token ``` `:token` is the per-template inbound token from the **Use this template → Inbound webhook** panel. ## Quick Start The body is **the variable data, flat** — no `{ data: ... }` wrapper. This shape is intentionally compatible with what most third-party integrations (Stripe, Zapier, Make, n8n) emit out of the box. **curl** ```bash SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $2}') curl -X POST "https://api.craftkit.dev/v1/hooks/$TOKEN" \ -H "x-craftkit-signature: $SIG" \ -H "Content-Type: application/json" \ -d "$BODY" ``` **Node.js** ```javascript import crypto from 'node:crypto'; const body = JSON.stringify({ customer: { name: 'Acme Corp' }, items: [{ name: 'Widget', qty: 5, price: 9.99 }], total: 49.95, }); const signature = crypto .createHmac('sha256', process.env.CRAFTKIT_INBOUND_SECRET) .update(body) .digest('hex'); await fetch(`https://api.craftkit.dev/v1/hooks/${process.env.CRAFTKIT_INBOUND_TOKEN}`, { method: 'POST', headers: { 'x-craftkit-signature': signature, 'Content-Type': 'application/json', }, body, }); ``` **Python** ```python import hashlib, hmac, json, os, requests body = json.dumps({ "customer": {"name": "Acme Corp"}, "items": [{"name": "Widget", "qty": 5, "price": 9.99}], "total": 49.95, }) signature = hmac.new( os.environ["CRAFTKIT_INBOUND_SECRET"].encode(), body.encode(), hashlib.sha256, ).hexdigest() requests.post( f"https://api.craftkit.dev/v1/hooks/{os.environ['CRAFTKIT_INBOUND_TOKEN']}", headers={"x-craftkit-signature": signature, "Content-Type": "application/json"}, data=body, ) ``` ## Request body ```json { "customer": { "name": "Acme Corp" }, "items": [ { "name": "Widget", "qty": 5, "price": 9.99 } ], "total": 49.95 } ``` The keys are the variable manifest keys for the target template (no envelope, no `data` wrapper). The same validation that gates the REST render endpoint applies — invalid payloads return `400 invalid_input_data` with the offending fields in `issues.fieldErrors`. ## Path parameters | Field | Type | Description | Default | |---|---|---|---| | `token` | string | The per-template inbound token. Identifies the template and authenticates the request. | — | ## HMAC signature If the sender supports HMAC, include the SHA-256 hex digest of the **raw body** under `x-craftkit-signature`, computed against the template's inbound secret. | Header | Value | |---|---| | `x-craftkit-signature` | Hex-encoded HMAC-SHA256 of the raw body, keyed by the template's inbound secret | | Condition | Result | |---|---| | Signature present and valid | `202 Accepted` (render enqueued) | | Signature present and invalid | `401 invalid_signature` | | Signature absent | Accepted by default (no enforcement) | > **Note** — Pin signature enforcement on per template via the dashboard for production traffic. The unsigned mode is convenient for prototyping with services that can't sign (e.g., a Google Form via Zapier), but always sign in production. ## Response — `202 Accepted` ```json { "id": "0193c2c3-...", "status": "queued", "pollUrl": "https://api.craftkit.dev/v1/renders/0193c2c3-..." } ``` | Field | Type | Description | |---|---|---| | `id` | string | Render id (UUIDv7). | | `status` | string | Always `queued` on accept. Progresses to `rendering` then `succeeded` \| `failed`. | | `pollUrl` | string | Poll this with your project bearer token to track the render to completion. | ## Errors | HTTP | Code | Meaning | Fix | |---|---|---|---| | 400 | `invalid_json` | Body wasn't valid JSON | Check `Content-Type` and serialization | | 400 | `invalid_input_data` | Body didn't match the template manifest | Inspect `issues.fieldErrors` for offending keys | | 401 | `invalid_signature` | `x-craftkit-signature` was present but didn't match | Recompute the HMAC over the exact raw bytes with the template's inbound secret | | 404 | `invalid_token` | No template matches this inbound token | Check the token; regenerate it in the dashboard if rotated | | 409 | `no_published_version` | Template has no published version yet | Publish a version in the dashboard | | 503 | `queue_unavailable` | Render queue is temporarily unreachable | Retry with backoff | See [Errors](/documentation/api/errors) for the envelope shape and full code list. ## Use cases | System | Trigger | Body shape needed | |---|---|---| | Stripe | `payment_intent.succeeded` webhook | Map invoice fields from `data.object` in your Stripe handler | | Zapier / Make | Form submission, Sheets row, etc. | Map fields with the visual mapper to the template's variable keys | | n8n | Workflow node | `Set` node maps CRM fields to manifest keys | | Your own backend | Any business event | One fewer round-trip than the API key path | ## Same pipeline Inbound webhook renders go through the exact same pipeline as `POST /v1/templates/:slug/render`: - Same Zod validation against the manifest. - Same versioning (uses the latest published version unless pinned). - Same render worker. - Same outgoing webhooks fire on completion. - Same `render` row in the dashboard. The only differences are the auth (per-template HMAC vs project bearer token) and the body shape (flat vs enveloped). ## Tips - **One token per template.** Tokens are scoped to a single template, which means revoking one doesn't affect others. - **Sign in production.** Toggle "Require signature" in the dashboard for any template that processes real money or PII. - **Test with Zapier first.** It's the fastest way to verify the manifest mapping is right without writing a server. - **Match the source's body shape.** If Stripe sends `data.object.amount`, configure your Stripe handler (or Zap) to flatten it to `amount` before posting. ## Related - [POST /v1/templates/:slug/render](/documentation/api/render-template) — the API-key path - [GET /v1/renders/:id](/documentation/api/render-status) — same status surface for both triggers - [Errors](/documentation/api/errors) — `invalid_signature` and validation errors --- # Webhooks Craftkit pushes **outgoing webhooks** to your server as renders, documents, and signature requests change state, so you don't have to poll. Collect-only embed fill forms also deliver their submissions this way (`form.submitted`). Every delivery is signed with HMAC-SHA256 — always verify the signature before trusting a payload. > Looking to *trigger* a render from an external system instead? That's the [inbound render webhook](/documentation/api/inbound-webhook) (`POST /v1/hooks/:token`), a different endpoint. ## Subscriptions Create a webhook subscription in the dashboard under **Project → Webhooks**. A subscription has: | Field | Description | |---|---| | `url` | Your HTTPS endpoint. Craftkit `POST`s each subscribed event here. | | `secret` | The HMAC-SHA256 signing secret. Used to compute the `x-craftkit-signature` header. | | `events` | The list of event names this subscription receives. New subscriptions default to `render.succeeded` + `render.failed`. | | `active` | A subscription can be paused; inactive subscriptions receive nothing. | A subscription only receives the events it is explicitly subscribed to. You can run several subscriptions per project — e.g. separate endpoints (and secrets) for render, document-engagement, and signature events. ## Event triggers There are four event families. Every event name is a dot-separated `family.action`. ### `render.*` — rendering lifecycle | Event | Fired when | |---|---| | `render.succeeded` | A render job finished and the PDF is available. | | `render.failed` | A render job failed (`errorMessage` explains why). | ### `document.*` — engagement on a delivered document Fired as recipients interact with a render you've shared or emailed (see [Shares & delivery](/documentation/api/shares) and [Engagement](/documentation/api/engagement)). | Event | Fired when | |---|---| | `document.share_created` | A share link was created for a render. | | `document.share_revoked` | A share link was revoked. | | `document.email_sent` | The render was emailed to a recipient. | | `document.email_opened` | A recipient opened the delivery email (tracking pixel). | | `document.viewed` | A recipient opened the shared document. | | `document.downloaded` | A recipient downloaded the PDF. | | `document.printed` | A recipient printed the document. | > Recipient-facing engagement events (`viewed`/`downloaded`/`printed`/`email_opened`) are de-duplicated within a 5-minute window per `(share, event, source IP)`, so a refresh-happy recipient won't spam your endpoint. ### `signature.*` — e-signature lifecycle Fired as a [signature request](/documentation/api/signatures) progresses. Provider-neutral: payloads carry Craftkit's own status vocabulary, never a third-party event type or identifier. | Event | Fired when | |---|---| | `signature.sent` | A signature request was created and its recipients were emailed. | | `signature.viewed` | A recipient opened the signing UI. | | `signature.signed` | A single recipient signed (per-recipient; does **not** move the top-level status). | | `signature.completed` | All recipients signed and the document is finalized. | | `signature.declined` | A recipient declined to sign. | | `signature.expired` | The request passed its expiration window. | | `signature.cancelled` | The request was cancelled. | ### `form.*` — collect-only fill submissions Emitted by embed **fill** sessions minted with `form.captureMode: "collect"` (see [Embed sessions](/documentation/embed/sessions-api)). In collect-only mode the fill form is pure data-collection infrastructure: on submit, Craftkit validates the field data and delivers it here **without creating a render or storing the field data**. You persist it in your own system of record, then request the render as a separate follow-up [`POST /v1/templates/:slug/render`](/documentation/api/render-template) call. | Event | Fired when | |---|---| | `form.submitted` | A collect-only fill form was submitted and validated. | > **Ephemeral / purge-on-ack.** Because collect-only mode retains nothing, the delivery payload (which carries the submitted field data) is held only until your endpoint returns `2xx`, then it is **purged** — the audit row (status/attempts/timestamps) remains without the payload. There is **no pull fallback**: the webhook is the only delivery path, so alert on any `form.submitted` delivery that exhausts its retries (`abandoned`). > **At-least-once, and no replay.** The collect submit returns `202` only after the `form.submitted` delivery is durably enqueued — but a `503`/`500` from the submit endpoint may *still* have enqueued (and delivered) it, so treat `form.submitted` as **at-least-once**. A submit retry mints a **new** delivery, so `x-craftkit-delivery-id` won't match across a resubmit — **dedupe on the payload's `sessionId`** (stable per fill) rather than on the delivery id alone. And because an `abandoned` delivery is purged, it **cannot be replayed**: keep your endpoint reachable and lean on your own retry if you miss one. ## Delivery format Each delivery is a `POST` to your subscription `url` with `Content-Type: application/json` and these headers: | Header | Description | |---|---| | `x-craftkit-event` | The event name (e.g. `render.succeeded`). Mirrors the body's `event` field. | | `x-craftkit-signature` | HMAC-SHA256 of the **raw request body**, keyed with the subscription `secret`, hex-encoded (no prefix). | | `x-craftkit-timestamp` | Unix epoch seconds when the delivery was sent. Use with the signature to reject stale replays. | | `x-craftkit-delivery-id` | Stable id for this delivery. The **same id is reused across retries** — use it to dedupe. | | `user-agent` | `Craftkit-Webhook/1.0`. | Every body is a JSON object whose first field is `event` (the event name). The remaining fields depend on the family. ## Payload data structures ### `render.*` | Field | Type | Description | |---|---|---| | `event` | string | `render.succeeded` or `render.failed`. | | `renderId` | string (UUID) | The render this event is about. | | `templateId` | string (UUID) | The template the render was produced from. | | `status` | string | Terminal render status (`succeeded` / `failed`). | | `downloadUrl` | string \| null | Public CDN URL of the PDF on success; `null` when public delivery isn't configured (fetch via the [authenticated download route](/documentation/api/render-download) instead) or on failure. | | `errorMessage` | string \| null | Populated on `render.failed`; `null` otherwise. | | `createdAt` | string (ISO-8601) | When the render was created. | | `completedAt` | string (ISO-8601) \| null | When the render reached its terminal state. | ```json { "event": "render.succeeded", "renderId": "0193c2c3-1111-7aaa-8bbb-000000000001", "templateId": "0193c2c3-0000-7aaa-8bbb-000000000000", "status": "succeeded", "downloadUrl": "https://cdn.craftkit.dev/craftkit-renders/…​.pdf", "errorMessage": null, "createdAt": "2026-06-05T10:00:00.000Z", "completedAt": "2026-06-05T10:00:00.420Z" } ``` ### `document.*` | Field | Type | Description | |---|---|---| | `event` | string | The `document.*` event name. | | `renderId` | string (UUID) | The render (document) that was engaged with. | | `templateId` | string (UUID) | The template behind the render. | | `shareId` | string (UUID) \| null | The share link involved, when the event originated from one. | | `eventId` | string (UUID) | Unique id of the recorded engagement event. | | `eventType` | string | The bare engagement type (`viewed`, `downloaded`, `printed`, `email_opened`, `email_sent`, `share_created`, `share_revoked`). | | `actorKind` | string | Who caused it: `recipient`, `partner`, or `system`. | | `sourceIp` | string \| null | Source IP for recipient-facing events. | | `userAgent` | string \| null | User-agent for recipient-facing events. | | `metadata` | object \| null | Any custom metadata attached when the event was recorded. | | `createdAt` | string (ISO-8601) | When the engagement occurred. | ```json { "event": "document.viewed", "renderId": "0193c2c3-1111-7aaa-8bbb-000000000001", "templateId": "0193c2c3-0000-7aaa-8bbb-000000000000", "shareId": "0193c2c3-3333-7aaa-8bbb-000000000003", "eventId": "0193c2c3-4444-7aaa-8bbb-000000000004", "eventType": "viewed", "actorKind": "recipient", "sourceIp": "203.0.113.7", "userAgent": "Mozilla/5.0 …", "metadata": null, "createdAt": "2026-06-05T11:03:00.000Z" } ``` ### `signature.*` | Field | Type | Description | |---|---|---| | `event` | string | The `signature.*` event name. | | `signatureRequestId` | string (UUID) | The signature request. Use it with [GET /v1/signatures/:id](/documentation/api/signatures). | | `renderId` | string (UUID) | The render that was sent for signature. | | `status` | string | Provider-neutral request status (e.g. `sent`, `viewed`, `completed`). Present on lifecycle events. | | `name` | string | The request name. Present on `signature.sent`. | | `recipients` | array | Recipient snapshot (name/email/designation/order). Present on `signature.sent`. | | `reason` | string \| null | Decline/cancel reason, when provided. | Only `event`, `signatureRequestId`, and `renderId` are guaranteed on every signature event; the rest depend on the event (e.g. `name`/`recipients` on `sent`, `status` on lifecycle events, `reason` on `declined`/`cancelled`). ```json { "event": "signature.completed", "signatureRequestId": "0193c2c3-2222-7aaa-8bbb-000000000002", "renderId": "0193c2c3-1111-7aaa-8bbb-000000000001", "status": "completed" } ``` ### `form.*` | Field | Type | Description | |---|---|---| | `event` | string | `form.submitted`. | | `sessionId` | string (UUID) | The embed fill session that produced the submission. | | `templateSlug` | string | Slug of the template the form was scoped to. | | `templateVersion` | number | Published version number the data was validated against. | | `renderId` | string (UUID) \| null | `null` in collect-only mode (no render was created); set only if a render was also enqueued. | | `data` | object | The complete merged, manifest-keyed, coerced field set (prefill + user entries, user wins). Byte-symmetric with what the render API accepts, so you can store-then-render with it verbatim. | | `submittedAt` | string (ISO-8601) | When the form was submitted. | The payload is retained only until your endpoint `2xx`s it, then purged (see the ephemeral note above). ```json { "event": "form.submitted", "sessionId": "0193c2c3-5555-7aaa-8bbb-000000000005", "templateSlug": "e-charterparty", "templateVersion": 6, "renderId": null, "data": { "customer": { "name": "Acme Corp" }, "amount": 42 }, "submittedAt": "2026-06-05T11:00:00.000Z" } ``` ## Verifying the signature Recompute the HMAC over the **exact raw body bytes** you received (do not re-serialize the parsed JSON — key ordering and whitespace must match) and compare it to `x-craftkit-signature` in constant time. Optionally reject deliveries whose `x-craftkit-timestamp` is outside a tolerance window to blunt replays. **Node.js** ```javascript import { createHmac, timingSafeEqual } from 'node:crypto'; function verify(rawBody, headerSig, secret) { const expected = createHmac('sha256', secret).update(rawBody).digest('hex'); const a = Buffer.from(expected); const b = Buffer.from(headerSig ?? ''); return a.length === b.length && timingSafeEqual(a, b); } // Express: capture the raw body, e.g. app.use(express.raw({ type: 'application/json' })) app.post('/craftkit-webhook', (req, res) => { if (!verify(req.body, req.header('x-craftkit-signature'), process.env.CRAFTKIT_WEBHOOK_SECRET)) { return res.sendStatus(401); } const evt = JSON.parse(req.body.toString('utf8')); switch (evt.event) { case 'render.succeeded': // evt.downloadUrl, evt.renderId … break; case 'document.viewed': // evt.shareId, evt.actorKind … break; case 'signature.completed': // evt.signatureRequestId … break; } res.sendStatus(200); }); ``` **Python** ```python import hashlib, hmac def verify(raw_body: bytes, header_sig: str, secret: str) -> bool: expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, header_sig or "") ``` ## Retries & idempotency - Craftkit treats any `2xx` response as success. Anything else — or a timeout; the budget is **15s per attempt** — is a failure. - Failed deliveries are retried up to **6 attempts** with backoff. After the final attempt the delivery is marked `abandoned` and not retried again. - Retries reuse the **same `x-craftkit-delivery-id`**. Make your handler idempotent by keying on it, since the same event may arrive more than once. - Respond `2xx` quickly and do heavy work asynchronously, so a slow handler doesn't trip the 15s budget and trigger needless retries. - Subscribe each endpoint to only the events it needs; unmatched events are never delivered. ## Related - [Digital signatures](/documentation/api/signatures) — send documents for signature and emit `signature.*` events - [Shares & delivery](/documentation/api/shares) and [Engagement](/documentation/api/engagement) — the source of `document.*` events - [GET /v1/renders/:id](/documentation/api/render-status) — the poll-based alternative to `render.*` webhooks - [Inbound render webhook](/documentation/api/inbound-webhook) — trigger a render from an external system - [Errors](/documentation/api/errors) — error envelope and codes --- # POST /v1/embed/catalogs Publish a new version of a named variable catalog. Each call creates the next version number and marks it as current — the previous version is archived but never deleted. ```http POST /v1/embed/catalogs ``` ## Quick Start **curl** ```bash curl -X POST https://api.craftkit.dev/v1/embed/catalogs \ -H "Authorization: Bearer $CRAFTKIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "my-catalog", "catalog": { "allowCustom": false, "namespaces": [ { "key": "customer", "label": "Customer", "fields": [ { "key": "customer.name", "label": "Customer name", "dataType": "text", "previewData": "Acme Corp" }, { "key": "customer.email", "label": "Customer email", "dataType": "email", "previewData": "hello@acme.com" } ] } ], "loops": [] } }' ``` **Node.js** ```typescript const res = await fetch('https://api.craftkit.dev/v1/embed/catalogs', { method: 'POST', headers: { Authorization: `Bearer ${process.env.CRAFTKIT_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ name: 'my-catalog', catalog: { allowCustom: false, namespaces: [ { key: 'customer', label: 'Customer', fields: [ { key: 'customer.name', label: 'Customer name', dataType: 'text', previewData: 'Acme Corp' }, { key: 'customer.email', label: 'Customer email', dataType: 'email', previewData: 'hello@acme.com' }, ], }, ], loops: [], }, }), }); const { id, name, version } = await res.json(); // { id: "0193c2c3-1a2b-7c3d-8e4f-aabbccddeeff", name: "my-catalog", version: 1 } ``` **Python** ```python import os, requests res = requests.post( "https://api.craftkit.dev/v1/embed/catalogs", headers={"Authorization": f"Bearer {os.environ['CRAFTKIT_API_KEY']}"}, json={ "name": "my-catalog", "catalog": { "allowCustom": False, "namespaces": [ { "key": "customer", "label": "Customer", "fields": [ {"key": "customer.name", "label": "Customer name", "dataType": "text", "previewData": "Acme Corp"}, {"key": "customer.email", "label": "Customer email", "dataType": "email", "previewData": "hello@acme.com"}, ], } ], "loops": [], }, }, ) result = res.json() # {"id": "0193c2c3-1a2b-7c3d-8e4f-aabbccddeeff", "name": "my-catalog", "version": 1} ``` ## Request body ```json { "name": "my-catalog", "catalog": { "allowCustom": false, "namespaces": [ ... ], "loops": [ ... ] } } ``` | Field | Type | Required | Description | |---|---|---|---| | `name` | string | Yes | Catalog name. Lowercase letters, numbers, and hyphens. Reusing an existing name creates the next version. | | `catalog` | object | Yes | The full catalog payload — see schema below. | ## Catalog schema ```json { "allowCustom": false, "namespaces": [ { "key": "customer", "label": "Customer", "icon": "user", "fields": [ { "key": "customer.name", "label": "Customer name", "dataType": "text", "previewData": "Acme Corp", "description": "The company or individual name", "format": "optional format string" } ] } ], "loops": [ { "key": "order.items", "label": "Order items", "itemFields": [ { "key": "name", "label": "Product", "dataType": "text", "previewData": "Widget A" }, { "key": "qty", "label": "Quantity", "dataType": "number", "previewData": 2 }, { "key": "price", "label": "Unit price", "dataType": "currency", "previewData": 49.99 } ], "previewData": [ { "name": "Widget A", "qty": 2, "price": 49.99 }, { "name": "Widget B", "qty": 1, "price": 99.00 } ] } ] } ``` ### `namespaces[].fields` object | Field | Type | Required | Description | |---|---|---|---| | `key` | string | Yes | Dot-path key used in templates: `customer.name`. Pattern: `^[a-zA-Z_][a-zA-Z0-9_.]*$`. | | `label` | string | Yes | Display name in the variable picker. | | `dataType` | string | Yes | One of `text`, `longtext`, `number`, `currency`, `date`, `datetime`, `boolean`, `image`, `url`, `email`, `select`. | | `options` | `{ value, label }[]` | — | Fixed choices for a `select` field — `value` is stored/validated, `label` is display text. Required (non-empty, unique `value`s) when `dataType` is `select`; ignored otherwise. A value outside the options is rejected with `invalid_input_data` when the resolved template renders. | | `previewData` | scalar | — | Dummy value shown in the live preview. Doubles as input placeholder in form-fill embeds. | | `format` | string | — | Formatting hint: `currency:EUR`, `date:DD/MM/YYYY`. | | `description` | string | — | Helper text shown beneath the field in the variable picker. | ### `loops` object | Field | Type | Required | Description | |---|---|---|---| | `key` | string | Yes | Loop key: `order.items`. Compiles to `{{#each order.items}}...{{/each}}`. | | `label` | string | Yes | Display name in the picker. | | `itemFields` | array | Yes | Fields available inside the loop body. Same shape as namespace fields. | | `previewData` | array | — | Dummy rows for the live preview (max 10). | ## Response **201 Created** ```json { "id": "0193c2c3-1a2b-7c3d-8e4f-aabbccddeeff", "name": "my-catalog", "version": 1 } ``` | Field | Type | Description | |---|---|---| | `id` | string | Catalog row UUID. To pin a session to a specific version, pass `catalogRef: { name, version }` (catalogs are referenced by name + version, not by id). | | `name` | string | The catalog name you passed. | | `version` | number | Monotonically increasing version number within this name. | ## Versioning Calling `POST /v1/embed/catalogs` with the same `name` creates the next version: ``` v1 → archived v2 → archived v3 → current ← sessions referencing this name get v3 ``` Sessions minted with `catalogRef: { name: "my-catalog" }` always resolve to the current version. To pin a session to a specific version, pass `catalogRef: { name: "my-catalog", version: 2 }`. ## Referencing the catalog in a session After publishing, reference the catalog by name when minting a session: ```json { "tenant": { "externalId": "org_123", "displayName": "Acme Corp" }, "actor": { "externalId": "usr_456", "displayName": "Jane Smith" }, "catalogRef": { "name": "my-catalog" } } ``` Or inline a one-off catalog without publishing it first: ```json { "tenant": { ... }, "actor": { ... }, "variableCatalog": { "allowCustom": false, "namespaces": [...], "loops": [] } } ``` See [Session API (mint & refresh)](/documentation/embed/sessions-api) for the full session mint reference. ## Errors | Status | Code | Meaning | |---|---|---| | 401 | `missing_authorization` | No `Authorization` header. | | 401 | `invalid_credentials` | API key not found, revoked, or embed not enabled. | | 400 | `invalid_json` | Request body is not valid JSON. | | 422 | `invalid_request` | Body or `catalog` failed validation — check `issues` array for field-level details. | | 500 | `internal_error` | Auth check or catalog persistence threw server-side. Retry; contact support if it persists. | --- _Last revised: 2026-05-12_ --- # Errors Every Craftkit error response uses one envelope. Switch on `error.code` (stable, machine-readable) in your code; surface `error.message` to developers; inspect `error.issues` for validation problems. ## Quick Start The envelope: ```json { "error": { "code": "invalid_input_data", "message": "Variable data did not match the template manifest.", "issues": { "formErrors": [], "fieldErrors": { "customer": ["Required"] } } } } ``` Handling it: **Node.js** ```javascript const res = await fetch(url, options); if (!res.ok) { const { error } = await res.json(); if (error.code === 'invalid_input_data') { console.error('Field issues:', error.issues.fieldErrors); } else if (error.code === 'rate_limited') { await backoff(); } throw new Error(`${error.code}: ${error.message}`); } ``` **Python** ```python res = requests.post(url, json=body, headers=headers) if not res.ok: error = res.json()["error"] if error["code"] == "invalid_input_data": print("Field issues:", error["issues"]["fieldErrors"]) elif error["code"] == "rate_limited": backoff() raise RuntimeError(f"{error['code']}: {error['message']}") ``` ## Envelope shape | Field | Type | Description | |---|---|---| | `code` | string | Stable, machine-readable identifier. Switch on this. | | `message` | string | Human-readable. Safe for developers; safe-ish for end users. | | `issues` | object \| undefined | Present for validation errors only. Mirrors Zod's `flatten()` output: `{ formErrors: string[], fieldErrors: Record }`. | ## Common codes | Code | HTTP | When | Action | |---|---|---|---| | `missing_authorization` | 401 | No bearer header | Send the API key in `Authorization: Bearer ...` | | `invalid_credentials` | 401 | Key revoked, unknown, or (on `/v1/embed/*`) embed not enabled for the project | Mint a new key **in the target environment**; for embed endpoints, also enable embed mode in the dashboard | | `partner_suspended` | 403 | Embed partnership suspended | Contact support | | `template_not_found` | 404 | Slug doesn't exist in this project | Check the slug + the API key's project scope | | `version_not_found` | 404 | Pinned version doesn't exist | Omit `options.versionNumber` or pick a real one | | `no_published_version` | 409 | Template has no published version | Publish a version in the dashboard | | `invalid_json` | 400 | Body wasn't JSON | Set `Content-Type: application/json` and stringify | | `invalid_request` | 400 | Top-level shape wrong | See the API reference for the surface you called | | `invalid_input_data` | 400 | Data didn't match manifest | Inspect `issues.fieldErrors` | | `invalid_signature` | 401 | HMAC mismatch on inbound webhook | Recompute signature from the raw body | | `rate_limited` | 429 | Too many requests | Back off with exponential jitter | | `internal_error` | 500 | Something is wrong on our side | Retry with backoff; check status page | ## Retry semantics | HTTP | Retry? | Notes | |---|---|---| | 4xx (except 429) | No | Fix the request first | | 429 | Yes | Exponential backoff with jitter | | 5xx | Yes | POST `/render` is safe to retry — the worker dedupes by `jobId` | | Network error | Yes | Same backoff strategy | Recommended backoff: **1s, 2s, 4s, 8s, 16s, capped at 30s, max 5 attempts.** ```javascript async function withRetry(fn, max = 5) { for (let i = 0; i < max; i++) { try { const res = await fn(); if (res.status < 500 && res.status !== 429) return res; } catch (err) { if (i === max - 1) throw err; } const delay = Math.min(1000 * 2 ** i, 30000) + Math.random() * 250; await new Promise((r) => setTimeout(r, delay)); } } ``` ## Tips - **Always switch on `code`, not `message`.** Messages are human-readable and may change for clarity. Codes are part of the API contract. - **Surface `fieldErrors` to your form UI.** Each key in `fieldErrors` is a manifest path; map them straight onto the corresponding input. - **Don't retry 4xx (except 429).** They mean the request itself is wrong. Retrying just burns quota. - **Idempotency for 5xx retries.** The render worker dedupes by job hash, so retrying a `POST /render` after a 502 won't enqueue twice. ## Related - [Authentication](/documentation/api/authentication) — `missing_authorization` and `invalid_credentials` - [POST /v1/templates/:slug/render](/documentation/api/render-template) — `invalid_input_data` and friends - [Inbound webhook](/documentation/api/inbound-webhook) — `invalid_signature` ## Changelog - **Validation library upgraded to Zod v4.** The default validator text inside `error.message` and `error.issues` (`fieldErrors`/`formErrors`) was reworded upstream — `error.code` and the `issues` shape are unchanged, so integrations that switch on `code` (per the Tips above) are unaffected. --- # Template management Create, read, list, update, and delete templates from a variable manifest — no dashboard or hand-written layout required. Craftkit synthesizes a renderable layout from the manifest and publishes it as a version; render against it with [POST /v1/templates/:slug/render](/documentation/api/render-template). ```http POST /v1/templates GET /v1/templates GET /v1/templates/:slug PUT /v1/templates/:slug DELETE /v1/templates/:slug ``` `:slug` is the template's slug within the authenticated key's project. All five endpoints are scoped to the project that owns the API key. ## Quick Start Create a template from a manifest, then list it back. **curl** ```bash curl -X POST https://api.craftkit.dev/v1/templates \ -H "Authorization: Bearer $CRAFTKIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Charter Handover", "slug": "charter-handover", "manifest": { "variables": [ { "key": "booking.code", "label": "Booking code", "dataType": "text", "required": true }, { "key": "handover.signedBy", "label": "Signed by", "dataType": "text", "required": true }, { "key": "handover.signatureImageUrl", "label": "Signature", "dataType": "image" } ], "loops": [ { "key": "areas", "label": "Inspection areas", "itemFields": [ { "key": "areaKey", "label": "Area", "dataType": "text" }, { "key": "condition", "label": "Condition", "dataType": "text" } ] } ] } }' curl https://api.craftkit.dev/v1/templates \ -H "Authorization: Bearer $CRAFTKIT_API_KEY" ``` **Node.js** ```javascript const base = 'https://api.craftkit.dev'; const headers = { Authorization: `Bearer ${process.env.CRAFTKIT_API_KEY}`, 'Content-Type': 'application/json', }; // Idempotent provisioning: create-or-republish at a known slug. const put = await fetch(`${base}/v1/templates/charter-handover`, { method: 'PUT', headers, body: JSON.stringify({ name: 'Charter Handover', manifest: { variables: [ { key: 'booking.code', label: 'Booking code', dataType: 'text', required: true }, { key: 'handover.signatureImageUrl', label: 'Signature', dataType: 'image' }, ], loops: [ { key: 'areas', label: 'Inspection areas', itemFields: [ { key: 'areaKey', label: 'Area', dataType: 'text' }, { key: 'condition', label: 'Condition', dataType: 'text' }, ], }, ], }, }), }); const { slug, currentVersionNumber } = await put.json(); ``` **Python** ```python import os, requests base = 'https://api.craftkit.dev' headers = {'Authorization': f"Bearer {os.environ['CRAFTKIT_API_KEY']}"} # Fetch the manifest + generated JSON Schema before rendering. res = requests.get(f'{base}/v1/templates/charter-handover', headers=headers) template = res.json() manifest = template['manifest'] json_schema = template['jsonSchema'] ``` ## POST /v1/templates — create Creates a template from a manifest, synthesizes a layout, and publishes version 1. ### Request body ```json { "name": "Charter Handover", "slug": "charter-handover", "description": "Pre/post charter inspection sign-off", "manifest": { "variables": [ { "key": "booking.code", "label": "Booking code", "dataType": "text", "required": true }, { "key": "handover.signatureImageUrl", "label": "Signature", "dataType": "image" } ], "loops": [ { "key": "areas", "label": "Inspection areas", "itemFields": [ { "key": "areaKey", "label": "Area", "dataType": "text" }, { "key": "condition", "label": "Condition", "dataType": "text" } ] } ] }, "pageConfig": { "format": "A4", "orientation": "portrait", "margin": "20mm", "printBackground": true } } ``` | Field | Type | Description | Default | |---|---|---|---| | `name` | string | Display name, 1–120 chars. Required. | — | | `slug` | string | Kebab-case identifier (`^[a-z0-9]+(?:-[a-z0-9]+)*$`), 1–120 chars, unique in the project. Omit to derive one from `name`. A provided slug that already exists returns `409`. | Derived from `name` | | `description` | string | Optional, up to 280 chars. | `null` | | `manifest` | object | Variable manifest the render payload binds to: `{ variables: VariableDefinition[], loops: LoopDefinition[] }`. Required. Both arrays must be present. | — | | `manifest.variables[]` | object | Scalar variables. Each: `key` (dot-path), `label`, `dataType`, optional `required`/`defaultValue`/`format`/`description`/`options`. An `image` variable renders as a data-bound ``; a `select` variable carries an `options` array (see below). | — | | `manifest.loops[]` | object | Array loops, each rendered as a repeating table. Each: `key` (**dot-free, top-level**), `label`, `itemFields[]` (≥1). A loop `key` containing a dot is rejected with `invalid_loop_key`. | — | | `layout` | object | Optional CanvasDocument `contentJson` override. When omitted, a layout is synthesized from the manifest. | Synthesized | | `pageConfig` | object | Optional page format: `format` (`A4` \| `A5` \| `Letter` \| `Legal`), `orientation` (`portrait` \| `landscape`), `margin` (e.g. `20mm`), `printBackground`. | A4 portrait, `20mm`, backgrounds on | `dataType` is one of: `text`, `longtext`, `number`, `currency`, `date`, `datetime`, `boolean`, `image`, `url`, `email`, `select`. > **`select` variables.** A variable with `dataType: "select"` must include a non-empty `options` array of `{ value, label }` choices — `value` is stored/validated, `label` is display text. Publishing a `select` with no options is rejected with `invalid_request`; option `value`s must be unique, and a `defaultValue`, if set, must be a string matching one of them. `GET /v1/templates/:slug` returns `options` on the variable and emits it in the generated JSON Schema as a string `enum` (e.g. `{ "type": "string", "enum": ["SHIPOWNER", "CHARTERER"] }`). At render time a value outside the options is rejected with `invalid_input_data`. `options` is optional and only meaningful for `select`, so clients that ignore it are unaffected. > > ```json > { > "key": "bunker_cost_party", > "label": "Bunker cost party", > "dataType": "select", > "required": false, > "options": [ > { "value": "SHIPOWNER", "label": "Shipowner" }, > { "value": "CHARTERER", "label": "Charterer" } > ] > } > ``` > **Slug collision.** A *derived* slug that collides gets a short random hex suffix appended (e.g. `charter-handover-9f3a1c`) — the response carries the final slug. An *explicit* slug that collides is a hard `409 slug_conflict`. ### Response — `201 Created` ```json { "id": "0193c2c3-...", "slug": "charter-handover", "currentVersionNumber": 1, "manifest": { "variables": ["..."], "loops": ["..."] } } ``` | Field | Type | Description | |---|---|---| | `id` | string | New template id (UUID). | | `slug` | string | Final slug — may differ from a derived input if it collided. | | `currentVersionNumber` | number | Always `1` for a freshly created template. | | `manifest` | object | The stored manifest, echoed back. | ## GET /v1/templates — list Returns every non-deleted template in the project, newest-`updatedAt` first. Lightweight — no manifest or JSON Schema (use [GET /v1/templates/:slug](/documentation/api/templates) for those). ### Response — `200 OK` ```json { "templates": [ { "id": "0193c2c3-...", "name": "Charter Handover", "slug": "charter-handover", "description": null, "templateType": "document", "currentVersionNumber": 2, "published": true, "createdAt": "2026-05-01T09:00:00.000Z", "updatedAt": "2026-06-01T12:00:00.000Z" } ] } ``` | Field | Type | Description | |---|---|---| | `templates` | array | Templates in the project, ordered by `updatedAt` descending. | | `templates[].id` | string | Template id. | | `templates[].name` | string | Display name. | | `templates[].slug` | string | Slug used in render and read calls. | | `templates[].description` | string \| null | Optional description. | | `templates[].templateType` | string | `document` (manifest-driven default) or `pdf-overlay`. | | `templates[].currentVersionNumber` | number \| null | Published version number, or `null` if nothing is published yet. | | `templates[].published` | boolean | `true` when a current version exists. | | `templates[].createdAt` | string | ISO-8601 timestamp. | | `templates[].updatedAt` | string | ISO-8601 timestamp. | ## GET /v1/templates/:slug — read one Fetches one template plus its published **manifest** (the contract your render `data` must satisfy) and an auto-generated **JSON Schema** for client-side validation. ### Path parameters | Field | Type | Description | Default | |---|---|---|---| | `slug` | string | Template slug, unique within the project. | — | ### Response — `200 OK` ```json { "id": "0193c2c3-...", "name": "Charter Handover", "slug": "charter-handover", "description": null, "templateType": "document", "currentVersionNumber": 2, "published": true, "manifest": { "variables": [ { "key": "booking.code", "label": "Booking code", "dataType": "text", "required": true } ], "loops": [ { "key": "areas", "label": "Inspection areas", "itemFields": [ { "key": "areaKey", "label": "Area", "dataType": "text" } ] } ] }, "jsonSchema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": {} }, "createdAt": "2026-05-01T09:00:00.000Z", "updatedAt": "2026-06-01T12:00:00.000Z" } ``` | Field | Type | Description | |---|---|---| | `id` | string | Template id. | | `name` | string | Display name. | | `slug` | string | Template slug. | | `description` | string \| null | Optional description. | | `templateType` | string | `document` or `pdf-overlay`. | | `currentVersionNumber` | number \| null | Published version number, falling back to the highest version. `null` when unpublished. | | `published` | boolean | `false` when the template exists but has no published version yet (distinct from a `404`). | | `manifest` | object \| null | The published manifest (`{ variables, loops }`), or `null` when unpublished. | | `jsonSchema` | object \| null | Draft-07 JSON Schema derived from the manifest, or `null` when unpublished. | | `createdAt` | string | ISO-8601 timestamp. | | `updatedAt` | string | ISO-8601 timestamp. | ## PUT /v1/templates/:slug — create-or-republish The idempotent companion to create. The URL slug is canonical — any `slug` in the body is ignored. The body is otherwise identical to [create](#post-v1templates--create) (`name`, `manifest`, optional `description`/`layout`/`pageConfig`). - **Template does not exist** → it is created and published as version 1 → `201`. - **Template exists** → a new version (n+1) is published and becomes current; `name`, `description`, and the synthesized draft are updated too → `200`. Existing renders are never affected: each render pins its own `templateVersionId`, so republishing only changes what *new* renders use. Each PUT creates a new version even when the manifest is unchanged — calling PUT N times leaves N versions in history. ### Path parameters | Field | Type | Description | Default | |---|---|---|---| | `slug` | string | Canonical kebab-case slug. The URL slug wins; a `slug` field in the body is ignored. | — | ### Response — `201 Created` (created) or `200 OK` (republished) ```json { "id": "0193c2c3-...", "slug": "charter-handover", "currentVersionNumber": 2, "manifest": { "variables": ["..."], "loops": ["..."] } } ``` | Field | Type | Description | |---|---|---| | `id` | string | Template id (stable across republishes). | | `slug` | string | The canonical slug (the one in the URL). | | `currentVersionNumber` | number | The newly published version. `1` on create; incremented by one on every republish. | | `manifest` | object | The stored manifest, echoed back. | > **Idempotent provisioning.** Drive PUT from a setup script: the first run creates, every subsequent run republishes in place. Prefer it over `DELETE` + `POST` when you only need the latest layout — it keeps the same `id` and slug and leaves prior renders intact. ## DELETE /v1/templates/:slug — soft-delete Soft-deletes the template (sets `deletedAt`) and **tombstones the slug** so the canonical slug can be recreated. Because `(project_id, slug)` is a non-partial unique index, the row's slug is moved aside (`{slug}__deleted__{hex}`) to free the original. The original slug is echoed back. Existing renders are untouched — they pin their own `templateVersionId` and remain fetchable by render id. A second DELETE of the same slug returns `404` — idempotent in effect. ### Path parameters | Field | Type | Description | Default | |---|---|---|---| | `slug` | string | Slug of the template to delete. | — | ### Response — `200 OK` ```json { "id": "0193c2c3-...", "slug": "charter-handover", "deletedAt": "2026-06-06T00:00:00.000Z" } ``` | Field | Type | Description | |---|---|---| | `id` | string | The deleted template's id. | | `slug` | string | The original (now-freed) slug, echoed back. | | `deletedAt` | string | ISO-8601 timestamp of the soft-delete. | ## Errors | HTTP | Code | Meaning | Fix | |---|---|---|---| | 400 | `invalid_json` | Body wasn't valid JSON (POST/PUT) | Check `Content-Type` and JSON.stringify | | 400 | `invalid_request` | Envelope, `manifest`, or `pageConfig` failed validation | Inspect `issues` for the offending fields | | 400 | `invalid_loop_key` | A loop `key` contains a dot | Use a dot-free top-level key (e.g. `areas`, not `handover.areas`) | | 401 | `unauthorized` | Missing, invalid, or revoked API key | Send `Authorization: Bearer $CRAFTKIT_API_KEY` | | 404 | `template_not_found` | No live template with that slug in this project (GET one / PUT-republish path / DELETE) | Check the slug and the key's project scope | | 409 | `slug_conflict` | An explicit `slug` (POST) or a tombstoned slug (PUT create) is already occupied | Pick a new slug or DELETE the existing template first | | 409 | `version_conflict` | Concurrent republishes raced for the next version number (PUT) | Retry the request | See [Errors](/documentation/api/errors) for the envelope shape and full code list. ## Tips - **Manifest is the contract.** `manifest.variables` are scalars keyed by dot-path; `manifest.loops` are arrays keyed by a dot-free top-level key. The same manifest drives the synthesized layout, the auto-generated JSON Schema, and render-time validation. - **Validate before rendering.** GET the template, read `jsonSchema`, and validate your render `data` client-side to catch shape errors before enqueuing a job. - **Layout override.** Pass `layout` (a CanvasDocument `contentJson`) only when you need full control; otherwise let Craftkit synthesize one from the manifest. ## Related - [POST /v1/templates/:slug/render](/documentation/api/render-template) — enqueue a render against a published template - [GET /v1/renders/:id](/documentation/api/render-status) — poll a render to completion - [Errors](/documentation/api/errors) — error envelope and retry semantics - [Authentication](/documentation/api/authentication) — bearer token format --- # Shares & delivery Share a succeeded render with recipients — mint durable revokable share links, list and revoke them, or send the document straight to an inbox via Resend. Shares are scoped to the render's project; the render must have status `succeeded` before any share or email can be created. ```http POST /v1/renders/:id/shares GET /v1/renders/:id/shares DELETE /v1/renders/:id/shares/:shareId POST /v1/renders/:id/email ``` `:id` is a render id (UUIDv7) within the authenticated project. `:shareId` is a share id returned by create or list. ## Create a share ```http POST /v1/renders/:id/shares ``` Mints a guest-facing share link. The render must have **succeeded** (`409 not_ready` otherwise). For `channel: "email"` the API only records the share row — it does **not** send mail; use `POST /v1/renders/:id/email` to actually deliver. ### Quick Start **curl** ```bash curl -X POST https://api.craftkit.dev/v1/renders/$RENDER_ID/shares \ -H "Authorization: Bearer $CRAFTKIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "channel": "link", "message": "Here is your signed agreement.", "expiresAt": "2026-12-31T23:59:59Z" }' ``` **Node.js** ```javascript const res = await fetch(`https://api.craftkit.dev/v1/renders/${renderId}/shares`, { method: 'POST', headers: { Authorization: `Bearer ${process.env.CRAFTKIT_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ channel: 'link', message: 'Here is your signed agreement.', expiresAt: '2026-12-31T23:59:59Z', }), }); const { shareUrl, shareToken } = await res.json(); ``` **Python** ```python import os, requests res = requests.post( f"https://api.craftkit.dev/v1/renders/{render_id}/shares", headers={"Authorization": f"Bearer {os.environ['CRAFTKIT_API_KEY']}"}, json={ "channel": "link", "message": "Here is your signed agreement.", "expiresAt": "2026-12-31T23:59:59Z", }, ) share = res.json() ``` ### Path parameters | Field | Type | Description | Default | |---|---|---|---| | `id` | string | Render id (UUIDv7) within the authenticated project. Required. | — | ### Request body ```json { "channel": "link", "recipientEmail": "client@acme.com", "message": "Here is your signed agreement.", "expiresAt": "2026-12-31T23:59:59Z" } ``` | Field | Type | Description | Default | |---|---|---|---| | `channel` | string | `link` or `email`. `link` is a plain copy-and-paste URL; `email` tags the share as email-destined but does **not** send — it requires `recipientEmail` and you must call `POST /v1/renders/:id/email` to deliver. | `link` | | `recipientEmail` | string | Recipient email (must be a valid address). Required when `channel` is `email`, otherwise optional metadata. | — | | `message` | string | Optional note shown to the recipient. Max 2000 chars. | — | | `expiresAt` | string | ISO-8601 timestamp. After this instant the share resolves to not-found on the public side. Omit for no auto-expiry. | No expiry | ### Response — `201 Created` ```json { "id": "0193c2c3-...", "shareToken": "cks_8sd9...", "shareUrl": "https://www.craftkit.dev/share/cks_8sd9...", "channel": "link", "recipientEmail": null, "message": "Here is your signed agreement.", "expiresAt": "2026-12-31T23:59:59.000Z", "revokedAt": null, "createdAt": "2026-06-05T10:05:00.000Z" } ``` | Field | Type | Description | |---|---|---| | `id` | string | Share id. Pass to `DELETE` to revoke. | | `shareToken` | string | Opaque token (prefixed `cks_`) embedded in `shareUrl`. Stored hashed server-side. | | `shareUrl` | string | Public link: `{shareBase}/share/{shareToken}`. The base resolves to the partner's custom domain, then `SHARE_BASE_URL`, then `APP_URL`, then the request origin. | | `channel` | string | `link` or `email`. | | `recipientEmail` | string \| null | Echoed recipient, or `null` for a plain link. | | `message` | string \| null | Echoed message. | | `expiresAt` | string \| null | ISO-8601 expiry, or `null`. | | `revokedAt` | string \| null | Always `null` on create. | | `createdAt` | string | ISO-8601 creation timestamp. | ### Errors | HTTP | Code | Meaning | Fix | |---|---|---|---| | 400 | `invalid_json` | Body wasn't valid JSON | Check `Content-Type` and JSON.stringify | | 400 | `invalid_request` | Body failed schema validation, or `channel="email"` without `recipientEmail` | Inspect `issues`; supply `recipientEmail` for the email channel | | 401 | `unauthorized` | Missing/invalid/revoked key | Send a valid `Authorization: Bearer` key | | 404 | `not_found` | No render with that id in this key's project | Check the id and the key's project scope | | 409 | `not_ready` | Render has not succeeded yet | Poll the render until `status` is `succeeded` | ## List shares ```http GET /v1/renders/:id/shares ``` Returns every share for the render, newest first, **including revoked ones**. Each row carries a click count (recipient `viewed` events attributed to the share). ### Quick Start **curl** ```bash curl https://api.craftkit.dev/v1/renders/$RENDER_ID/shares \ -H "Authorization: Bearer $CRAFTKIT_API_KEY" ``` **Node.js** ```javascript const res = await fetch(`https://api.craftkit.dev/v1/renders/${renderId}/shares`, { headers: { Authorization: `Bearer ${process.env.CRAFTKIT_API_KEY}` }, }); const { shares } = await res.json(); ``` **Python** ```python import os, requests res = requests.get( f"https://api.craftkit.dev/v1/renders/{render_id}/shares", headers={"Authorization": f"Bearer {os.environ['CRAFTKIT_API_KEY']}"}, ) shares = res.json()["shares"] ``` ### Path parameters | Field | Type | Description | Default | |---|---|---|---| | `id` | string | Render id (UUIDv7) within the authenticated project. Required. | — | ### Response — `200 OK` ```json { "shares": [ { "id": "0193c2c3-...", "channel": "link", "recipientEmail": null, "message": "Here is your signed agreement.", "revokedAt": null, "revokedReason": null, "expiresAt": "2026-12-31T23:59:59.000Z", "createdAt": "2026-06-05T10:05:00.000Z", "shareToken": "cks_8sd9...", "clickCount": 3, "shareUrl": "https://www.craftkit.dev/share/cks_8sd9..." } ] } ``` | Field | Type | Description | |---|---|---| | `shares` | array | Shares for the render, newest first. Revoked shares are included. | | `shares[].id` | string | Share id. | | `shares[].channel` | string | `link` or `email`. | | `shares[].recipientEmail` | string \| null | Recipient, or `null`. | | `shares[].message` | string \| null | Message shown to the recipient. | | `shares[].revokedAt` | string \| null | ISO-8601 revocation timestamp, or `null` if active. | | `shares[].revokedReason` | string \| null | Reason recorded at revoke time (e.g. `revoked_by_partner`), or `null`. | | `shares[].expiresAt` | string \| null | ISO-8601 expiry, or `null`. | | `shares[].createdAt` | string | ISO-8601 creation timestamp. | | `shares[].shareToken` | string | Plain token, re-exposed so a dashboard can re-display copy-link rows. | | `shares[].clickCount` | integer | Count of recipient `viewed` events attributed to this share. | | `shares[].shareUrl` | string | `{shareBase}/share/{shareToken}`. | ### Errors | HTTP | Code | Meaning | Fix | |---|---|---|---| | 401 | `unauthorized` | Missing/invalid/revoked key | Send a valid `Authorization: Bearer` key | | 404 | `not_found` | No render with that id in this key's project | Check the id and the key's project scope | ## Revoke a share ```http DELETE /v1/renders/:id/shares/:shareId ``` Soft-deletes the share by stamping `revokedAt` (reason `revoked_by_partner`). The public `/share/:token` URL stops resolving immediately. Revoking is idempotent only in the sense that an already-revoked or unknown share returns `404` — a share can be revoked once. ### Quick Start **curl** ```bash curl -X DELETE https://api.craftkit.dev/v1/renders/$RENDER_ID/shares/$SHARE_ID \ -H "Authorization: Bearer $CRAFTKIT_API_KEY" ``` **Node.js** ```javascript const res = await fetch( `https://api.craftkit.dev/v1/renders/${renderId}/shares/${shareId}`, { method: 'DELETE', headers: { Authorization: `Bearer ${process.env.CRAFTKIT_API_KEY}` }, }, ); const { revokedAt } = await res.json(); ``` **Python** ```python import os, requests res = requests.delete( f"https://api.craftkit.dev/v1/renders/{render_id}/shares/{share_id}", headers={"Authorization": f"Bearer {os.environ['CRAFTKIT_API_KEY']}"}, ) result = res.json() ``` ### Path parameters | Field | Type | Description | Default | |---|---|---|---| | `id` | string | Render id (UUIDv7) within the authenticated project. Required. | — | | `shareId` | string | Share id to revoke. Required. | — | ### Response — `200 OK` ```json { "id": "0193c2c3-...", "revokedAt": "2026-06-06T09:00:00.000Z" } ``` | Field | Type | Description | |---|---|---| | `id` | string | The revoked share id. | | `revokedAt` | string | ISO-8601 revocation timestamp. | ### Errors | HTTP | Code | Meaning | Fix | |---|---|---|---| | 401 | `unauthorized` | Missing/invalid/revoked key | Send a valid `Authorization: Bearer` key | | 404 | `not_found` | Render not found, or share not found / already revoked | Confirm both ids; a share can only be revoked once | ## Email a render ```http POST /v1/renders/:id/email ``` Creates an `email`-channel share **and** sends the document via Resend in one call. The render must have **succeeded**. Returns the Resend message id. This endpoint requires email to be configured: `RESEND_API_KEY` plus a sender address (`EMAIL_FROM`, or a per-partner `emailFrom`) — otherwise it returns `503 email_not_configured`. ### Quick Start **curl** ```bash curl -X POST https://api.craftkit.dev/v1/renders/$RENDER_ID/email \ -H "Authorization: Bearer $CRAFTKIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": "client@acme.com", "recipientName": "Jane Doe", "message": "Here is your signed agreement.", "expiresAt": "2026-12-31T23:59:59Z" }' ``` **Node.js** ```javascript const res = await fetch(`https://api.craftkit.dev/v1/renders/${renderId}/email`, { method: 'POST', headers: { Authorization: `Bearer ${process.env.CRAFTKIT_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ to: 'client@acme.com', recipientName: 'Jane Doe', message: 'Here is your signed agreement.', expiresAt: '2026-12-31T23:59:59Z', }), }); const { emailMessageId, sentAt } = await res.json(); ``` **Python** ```python import os, requests res = requests.post( f"https://api.craftkit.dev/v1/renders/{render_id}/email", headers={"Authorization": f"Bearer {os.environ['CRAFTKIT_API_KEY']}"}, json={ "to": "client@acme.com", "recipientName": "Jane Doe", "message": "Here is your signed agreement.", "expiresAt": "2026-12-31T23:59:59Z", }, ) result = res.json() ``` ### Path parameters | Field | Type | Description | Default | |---|---|---|---| | `id` | string | Render id (UUIDv7) within the authenticated project. Required. | — | ### Request body ```json { "to": "client@acme.com", "recipientName": "Jane Doe", "message": "Here is your signed agreement.", "expiresAt": "2026-12-31T23:59:59Z" } ``` | Field | Type | Description | Default | |---|---|---|---| | `to` | string | Recipient email (must be a valid address). Required. | — | | `recipientName` | string | Recipient display name used in the email greeting. Max 200 chars. | — | | `message` | string | Optional note included in the email body. Max 2000 chars. | — | | `expiresAt` | string | ISO-8601 timestamp. Sets an expiry on the underlying share link. Omit for no auto-expiry. | No expiry | ### Response — `201 Created` ```json { "id": "0193c2c3-...", "shareToken": "cks_8sd9...", "shareUrl": "https://www.craftkit.dev/share/cks_8sd9...", "emailMessageId": "re_abc123", "sentAt": "2026-06-06T09:05:00.000Z" } ``` | Field | Type | Description | |---|---|---| | `id` | string | The created share id (channel `email`). | | `shareToken` | string | Opaque token embedded in `shareUrl`. | | `shareUrl` | string | The link delivered in the email: `{shareBase}/share/{shareToken}`. | | `emailMessageId` | string | Resend provider message id for the sent email. | | `sentAt` | string | ISO-8601 timestamp the email was dispatched. | ### Errors | HTTP | Code | Meaning | Fix | |---|---|---|---| | 400 | `invalid_json` | Body wasn't valid JSON | Check `Content-Type` and JSON.stringify | | 400 | `invalid_request` | Body failed schema validation (missing/invalid `to`, etc.) | Inspect `issues`; provide a valid `to` address | | 401 | `unauthorized` | Missing/invalid/revoked key | Send a valid `Authorization: Bearer` key | | 404 | `not_found` | No render with that id in this key's project | Check the id and the key's project scope | | 409 | `not_ready` | Render has not succeeded yet | Poll the render until `status` is `succeeded` | | 502 | `email_send_failed` | Resend rejected the send | Inspect the error message; verify sender domain and recipient | | 503 | `email_not_configured` | Resend isn't wired on this deployment | Set `RESEND_API_KEY` + `EMAIL_FROM` (or a per-partner sender) | ## Related - [POST /v1/templates/:slug/render](/documentation/api/render-template) — enqueue the render to share - [GET /v1/renders/:id](/documentation/api/render-status) — poll the render to `succeeded` before sharing - [Errors](/documentation/api/errors) — error envelope and retry semantics - [Authentication](/documentation/api/authentication) — bearer token format --- # Engagement & analytics Read aggregate engagement counts and recent activity for a render, and record partner-side events from your own viewer UI. Engagement tracks who viewed, downloaded, printed, or was emailed a rendered document. ```http GET /v1/renders/:id/engagement POST /v1/renders/:id/events ``` `:id` is the render id (UUIDv7) within the authenticated project. ## Quick Start **curl** ```bash # Read the engagement summary curl https://api.craftkit.dev/v1/renders/0193c2c3/engagement \ -H "Authorization: Bearer $CRAFTKIT_API_KEY" # Record a partner-side event curl -X POST https://api.craftkit.dev/v1/renders/0193c2c3/events \ -H "Authorization: Bearer $CRAFTKIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "eventType": "downloaded", "metadata": { "source": "dashboard" } }' ``` **Node.js** ```javascript const headers = { Authorization: `Bearer ${process.env.CRAFTKIT_API_KEY}` }; const summary = await ( await fetch('https://api.craftkit.dev/v1/renders/0193c2c3/engagement', { headers }) ).json(); console.log(summary.counts.viewed, summary.linkOpens, summary.total); const res = await fetch('https://api.craftkit.dev/v1/renders/0193c2c3/events', { method: 'POST', headers: { ...headers, 'Content-Type': 'application/json' }, body: JSON.stringify({ eventType: 'printed', metadata: { source: 'dashboard' } }), }); const { recorded } = await res.json(); ``` **Python** ```python import os, requests headers = {"Authorization": f"Bearer {os.environ['CRAFTKIT_API_KEY']}"} summary = requests.get( "https://api.craftkit.dev/v1/renders/0193c2c3/engagement", headers=headers, ).json() res = requests.post( "https://api.craftkit.dev/v1/renders/0193c2c3/events", headers=headers, json={"eventType": "viewed", "metadata": {"source": "dashboard"}}, ) recorded = res.json()["recorded"] ``` ## Path parameters | Field | Type | Description | Default | |---|---|---|---| | `id` | string | Render id (UUIDv7). Must belong to the API key's project. | — | ## GET `/v1/renders/:id/engagement` Returns aggregate counts across all event types, a `linkOpens` tally, the grand total, and the most recent events (newest first, capped at 25). ### Response ```json { "counts": { "viewed": 12, "downloaded": 3, "printed": 1, "email_opened": 4, "email_sent": 2, "share_created": 1, "share_revoked": 0 }, "linkOpens": 8, "total": 23, "recent": [ { "id": "0193c2d0-...", "eventType": "viewed", "actorKind": "recipient", "shareId": "0193c2cf-...", "sourceIp": "203.0.113.7", "userAgent": "Mozilla/5.0 ...", "metadata": null, "createdAt": "2026-05-03T10:20:00.000Z" } ] } ``` | Field | Type | Description | |---|---|---| | `counts` | object | Per-type event counts. Always includes all seven keys, zero-filled. | | `counts.viewed` | integer | Document opens. | | `counts.downloaded` | integer | PDF downloads. | | `counts.printed` | integer | Print actions. | | `counts.email_opened` | integer | Tracking-pixel opens on a sent email. | | `counts.email_sent` | integer | Emails dispatched (partner audit). | | `counts.share_created` | integer | Share links minted (partner audit). | | `counts.share_revoked` | integer | Share links revoked (partner audit). | | `linkOpens` | integer | Subset of `viewed` events that originated from a shared link (`shareId` is non-null). Distinguishes link traffic from in-dashboard views. | | `total` | integer | Sum of all `counts`. | | `recent` | array | Up to 25 most recent events, newest first. | | `recent[].id` | string | Event id. | | `recent[].eventType` | string | One of `viewed`, `downloaded`, `printed`, `email_opened`, `email_sent`, `share_created`, `share_revoked`. | | `recent[].actorKind` | string | Who triggered it: `recipient` (the share recipient), `partner` (you, via the events endpoint or dashboard), or `system` (server-side automation). | | `recent[].shareId` | string \| null | The originating share link, when the event came through one. | | `recent[].sourceIp` | string \| null | Best-effort client IP (`x-forwarded-for` first hop, else `x-real-ip`). | | `recent[].userAgent` | string \| null | Client user-agent string. | | `recent[].metadata` | object \| null | Arbitrary key/value bag attached when the event was recorded. | | `recent[].createdAt` | string | ISO-8601 timestamp. | ## POST `/v1/renders/:id/events` Records a partner-side engagement event from your own viewer UI. Every event written here is stamped `actorKind: "partner"` — you cannot record recipient-side events through this route. Recipient-side `viewed`/`downloaded`/`printed` events are written server-side by the public share page. ### Request body ```json { "eventType": "downloaded", "metadata": { "source": "dashboard", "userId": "u_123" } } ``` | Field | Type | Description | Default | |---|---|---|---| | `eventType` | string | Required. One of `viewed`, `downloaded`, `printed`. Other engagement types (`email_*`, `share_*`) are recorded by the system, not this route. | — | | `metadata` | object | Optional free-form key/value bag (string keys, any JSON values) stored verbatim with the event. | — | > **Dedupe.** `viewed`, `downloaded`, and `printed` are deduped within a 5-minute window keyed on `(shareId, eventType, sourceIp)`. A duplicate inside that window returns `{ "recorded": false }` and is not written. ### Response ```json { "recorded": true } ``` | Field | Type | Description | |---|---|---| | `recorded` | boolean | `true` if the event was inserted, `false` if it was deduped within the 5-minute window. | ## Errors | HTTP | Code | Meaning | Fix | |---|---|---|---| | 400 | `invalid_json` | POST body wasn't valid JSON | Check `Content-Type` and JSON.stringify | | 400 | `invalid_request` | POST body didn't match `{ eventType, metadata? }` | Inspect `issues.fieldErrors`; `eventType` must be `viewed`/`downloaded`/`printed` | | 401 | `unauthorized` | Missing, invalid, or revoked API key | Send a valid `Authorization: Bearer` key | | 403 | `forbidden` | Key's project no longer exists | Use a key from an active project | | 404 | `not_found` | No render with that id in this key's project | Check the id and the API key's project scope | See [Errors](/documentation/api/errors) for the envelope shape and full code list. ## Related - [GET /v1/renders/:id](/documentation/api/render-status) — poll the render and read its `downloadUrl` - [Download a render](/documentation/api/render-download) — authenticated PDF stream - [Errors](/documentation/api/errors) — error envelope and retry semantics - [Authentication](/documentation/api/authentication) — bearer token format --- # Download a render Stream a succeeded render's PDF straight from storage, authenticated with your project API key. Use this when you don't want to hand out a public bucket URL — the bytes are served behind your bearer token. ```http GET /v1/renders/:id/download ``` `:id` is the render id (UUIDv7) within the authenticated project. ## Quick Start **curl** ```bash curl https://api.craftkit.dev/v1/renders/0193c2c3/download \ -H "Authorization: Bearer $CRAFTKIT_API_KEY" \ --output render.pdf ``` **Node.js** ```javascript import { writeFile } from 'node:fs/promises'; const res = await fetch('https://api.craftkit.dev/v1/renders/0193c2c3/download', { headers: { Authorization: `Bearer ${process.env.CRAFTKIT_API_KEY}` }, }); if (!res.ok) throw new Error(`download failed: ${res.status}`); const bytes = Buffer.from(await res.arrayBuffer()); await writeFile('render.pdf', bytes); ``` **Python** ```python import os, requests res = requests.get( "https://api.craftkit.dev/v1/renders/0193c2c3/download", headers={"Authorization": f"Bearer {os.environ['CRAFTKIT_API_KEY']}"}, ) res.raise_for_status() with open("render.pdf", "wb") as f: f.write(res.content) ``` ## Path parameters | Field | Type | Description | Default | |---|---|---|---| | `id` | string | Render id (UUIDv7). Must belong to the API key's project and have `status: "succeeded"`. | — | ## Response — `200 OK` The response body is the raw PDF. There is no JSON envelope on success. | Header | Value | |---|---| | `Content-Type` | `application/pdf` | | `Content-Length` | Byte length of the PDF (lets you detect truncation) | | `Content-Disposition` | `attachment; filename=".pdf"` | The asset is buffered server-side before the response is sent, so a storage read error surfaces as a clean `500` rather than a truncated `200`. Always check `res.ok` (or `raise_for_status()`) before writing the bytes to disk. ## When to use this vs `downloadUrl` [`GET /v1/renders/:id`](/documentation/api/render-status) returns a `downloadUrl`. Its value depends on deployment config: | Config | `downloadUrl` returned by `GET /v1/renders/:id` | This route | |---|---|---| | `S3_PUBLIC_URL` **set** (e.g. a public R2/MinIO bucket) | A permanent direct public CDN URL to the object — no auth, no TTL | Still works; the equivalent authenticated fetch if you prefer not to expose the public URL | | `S3_PUBLIC_URL` **not set** | This authenticated route's URL (`…/v1/renders/:id/download`) | The only way to fetch the PDF — there is no public object URL | In short: when no public bucket is configured, `downloadUrl` points back at this route, and a bearer token is required to fetch the bytes. ## Errors | HTTP | Code | Meaning | Fix | |---|---|---|---| | 401 | `unauthorized` | Missing, invalid, or revoked API key | Send a valid `Authorization: Bearer` key | | 403 | `forbidden` | Key's project no longer exists | Use a key from an active project | | 404 | `not_found` | No render with that id in this key's project | Check the id and the API key's project scope | | 409 | `conflict` | Render hasn't succeeded yet, or has no stored asset (message includes the current status) | Poll [GET /v1/renders/:id](/documentation/api/render-status) until `status` is `succeeded`, then retry | | 500 | `internal` | The PDF could not be read from storage | Transient — retry; if it persists, contact support | See [Errors](/documentation/api/errors) for the envelope shape and full code list. ## Related - [GET /v1/renders/:id](/documentation/api/render-status) — poll the render and read its `downloadUrl` - [POST /v1/templates/:slug/render](/documentation/api/render-template) — enqueue the render that produces the PDF - [Engagement & analytics](/documentation/api/engagement) — record a `downloaded` event after fetching - [Authentication](/documentation/api/authentication) — bearer token format --- # Digital signatures Send a rendered PDF out for digital signature, track its lifecycle, and download the archived signed document and completion certificate. Craftkit sends the rendered PDF for digital signature, emails the recipients, hosts the signing UI, and reports status back — the signature service is handled entirely behind the Craftkit API surface. ```http POST /v1/signatures GET /v1/signatures GET /v1/signatures/:id POST /v1/signatures/:id/cancel GET /v1/signatures/:id/download GET /v1/signatures/:id/certificate ``` All endpoints authenticate with the project API key (`Authorization: Bearer $CRAFTKIT_API_KEY`) and are scoped to that key's project. ## Create a signature request ```http POST /v1/signatures ``` Takes a **succeeded** render, submits its PDF to the signature service as an atomic create-and-send signing request, and returns the persisted request at `201`. The render must belong to the API key's project and have a stored PDF asset. ### Quick Start **curl** ```bash curl -X POST https://api.craftkit.dev/v1/signatures \ -H "Authorization: Bearer $CRAFTKIT_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: sign-order-12345" \ -d '{ "renderId": "0193c2c3-1111-7aaa-8bbb-000000000001", "name": "Charter handover — BK-12345", "recipients": [ { "firstName": "Jane", "lastName": "Doe", "email": "jane@example.com", "designation": "Signer", "order": 1 } ], "anchorTags": [ { "anchorString": "{{sign_here}}", "type": "signature", "recipientIndex": 0, "required": true } ], "expirationHours": 168 }' ``` **Node.js** ```javascript const res = await fetch('https://api.craftkit.dev/v1/signatures', { method: 'POST', headers: { Authorization: `Bearer ${process.env.CRAFTKIT_API_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': 'sign-order-12345', }, body: JSON.stringify({ renderId: '0193c2c3-1111-7aaa-8bbb-000000000001', name: 'Charter handover — BK-12345', recipients: [ { firstName: 'Jane', lastName: 'Doe', email: 'jane@example.com', designation: 'Signer', order: 1 }, ], anchorTags: [ { anchorString: '{{sign_here}}', type: 'signature', recipientIndex: 0, required: true }, ], expirationHours: 168, }), }); const signature = await res.json(); ``` **Python** ```python import os, requests res = requests.post( "https://api.craftkit.dev/v1/signatures", headers={ "Authorization": f"Bearer {os.environ['CRAFTKIT_API_KEY']}", "Idempotency-Key": "sign-order-12345", }, json={ "renderId": "0193c2c3-1111-7aaa-8bbb-000000000001", "name": "Charter handover — BK-12345", "recipients": [ {"firstName": "Jane", "lastName": "Doe", "email": "jane@example.com", "designation": "Signer", "order": 1}, ], "anchorTags": [ {"anchorString": "{{sign_here}}", "type": "signature", "recipientIndex": 0, "required": True}, ], "expirationHours": 168, }, ) signature = res.json() ``` ### Request body | Field | Type | Description | Default | |---|---|---|---| | `renderId` | string (UUID) | The render to sign. Must be in this project and have `status: "succeeded"` with a stored PDF. Required. | — | | `name` | string | Human-readable name for the request (1–255 chars). | `Signature request ` | | `recipients` | array | 1–20 recipients (see below). Required. | — | | `fields` | array | Up to 200 explicit field placements by page + coordinates (see below). | — | | `anchorTags` | array | Up to 200 text-anchor placements (see below). Recommended for Craftkit templates. | — | | `expirationHours` | integer | Hours until the request expires (1–8760). | Provider default (168) | At least one `fields` entry **or** `anchorTags` entry is required whenever any recipient is a `Signer`. #### `recipients[]` | Field | Type | Description | Default | |---|---|---|---| | `firstName` | string | Recipient first name (1–100 chars). Required. | — | | `lastName` | string | Recipient last name (≤100 chars). | — | | `email` | string | Recipient email (≤255 chars). Required. | — | | `designation` | enum | `Signer`, `Approver`, or `CC`. | `Signer` | | `order` | integer | Signing order, ≥1. When supplied on any recipient, the supplied values must be unique and within `[1, recipientCount]`. | Array position (1-based) | #### `fields[]` Explicit placement by page and coordinates. Coordinates are **percentages of page width/height (0–100), origin top-left** — the signature service's coordinate system. | Field | Type | Description | Default | |---|---|---|---| | `recipientIndex` | integer | 0-based index into `recipients`. Must reference an existing recipient. Required. | — | | `type` | enum | `signature`, `initial`, `text`, `date`, `checkbox`, `dropdown`, `radio_buttons`, or `text_area`. Required. | — | | `page` | integer | 1-based page number. Required. | — | | `x` | number | Horizontal position, 0–100 (% of page width). Required. | — | | `y` | number | Vertical position, 0–100 (% of page height). Required. | — | | `width` | number | Field width, >0 and ≤100 (% of page width). | Provider default | | `height` | number | Field height, >0 and ≤100 (% of page height). | Provider default | | `required` | boolean | Whether the field must be completed. | Provider default | #### `anchorTags[]` Placement relative to a text anchor baked into the template (e.g. add `{{sign_here}}` to the template body and reference it here). Unlike `fields`, anchor `width`/`height` are **points relative to the matched text**, not page percentages. | Field | Type | Description | Default | |---|---|---|---| | `anchorString` | string | The literal text to anchor on (1–200 chars). Required. | — | | `type` | enum | `signature`, `initials`, `text`, `date`, or `checkbox`. Note `initials` (plural) here vs. `initial` in `fields` — this mirrors the signature service's wire vocabulary. Required. | — | | `recipientIndex` | integer | 0-based index into `recipients`. Must reference an existing recipient. Required. | — | | `width` | number | Offset width in points, >0 and ≤1000. | Provider default | | `height` | number | Offset height in points, >0 and ≤1000. | Provider default | | `required` | boolean | Whether the field must be completed. | Provider default | | `ignoreIfNotPresent` | boolean | Skip silently if the anchor text isn't found in the document. | Provider default | > **Idempotency.** Send an `Idempotency-Key` header so a retried POST returns the original request instead of minting (and billing) a second signing envelope. Keys are scoped per project; a replay returns `200` with the original body instead of `201`. ### Response — `201 Created` ```json { "id": "0193c2c3-2222-7aaa-8bbb-000000000002", "renderId": "0193c2c3-1111-7aaa-8bbb-000000000001", "name": "Charter handover — BK-12345", "status": "sent", "recipients": [ { "id": "rcp_8e10-12ab34cd56ef", "firstName": "Jane", "lastName": "Doe", "email": "jane@example.com", "designation": "Signer", "order": 1 } ], "expirationHours": 168, "signedDownloadUrl": null, "certificateUrl": null, "errorMessage": null, "createdAt": "2026-06-05T10:00:00.000Z", "completedAt": null } ``` | Field | Type | Description | |---|---|---| | `id` | string | Craftkit signature request id (UUID). Use this for status, cancel, download, and certificate. | | `renderId` | string | The render that was sent for signature. | | `name` | string | The request name. | | `status` | string | Lifecycle status — `sent` on creation. See [status lifecycle](#status-lifecycle). | | `recipients` | array | Recipient snapshot, now carrying provider-assigned `id`s. May also include `signedAt` / `declinedAt` once those events arrive. | | `expirationHours` | integer \| null | Hours until expiry, as resolved by the signature service. | | `signedDownloadUrl` | string \| null | Authenticated Craftkit URL to download the signed PDF (`GET /v1/signatures/:id/download`); `null` until the document is archived. | | `certificateUrl` | string \| null | Authenticated Craftkit URL to download the completion certificate (`GET /v1/signatures/:id/certificate`); `null` until the certificate is available. Always a Craftkit-owned URL — never a provider domain. | | `errorMessage` | string \| null | Human-readable error or decline/cancel reason. | | `createdAt` | string | ISO-8601 timestamp. | | `completedAt` | string \| null | ISO-8601 timestamp set when the request completes. | ### Errors | HTTP | Code | Meaning | Fix | |---|---|---|---| | 400 | `invalid_json` | Body wasn't valid JSON | Check `Content-Type` and JSON.stringify | | 400 | `invalid_request` | Body didn't match the schema | Inspect `issues` for offending fields | | 402 | `signature_credits_exhausted` | The signature service account is out of credits | Top up the signature service account | | 404 | `not_found` | No render with that id in this project | Check `renderId` and the key's project scope | | 409 | `conflict` | Render isn't ready for signing (not `succeeded`, or no PDF) | Wait for the render to succeed, then retry | | 413 | `document_too_large` | Rendered PDF exceeds the 20MB signing limit | Reduce the document size | | 500 | `internal` | Failed to load the PDF or persist the request | Retry; if persistent, contact support | | 502 | `signature_provider_error` | The signature service rejected the create-and-send request | Inspect `message`; verify recipients/fields | | 503 | `signatures_unavailable` | Digital signatures are not configured on this server | Enable digital signatures, or contact support | ## List signature requests ```http GET /v1/signatures ``` Returns the project's signature requests, newest first, cursor-paginated. ### Quick Start **curl** ```bash curl "https://api.craftkit.dev/v1/signatures?limit=20" \ -H "Authorization: Bearer $CRAFTKIT_API_KEY" ``` **Node.js** ```javascript const res = await fetch('https://api.craftkit.dev/v1/signatures?limit=20', { headers: { Authorization: `Bearer ${process.env.CRAFTKIT_API_KEY}` }, }); const { signatures, nextCursor, hasMore } = await res.json(); ``` **Python** ```python import os, requests res = requests.get( "https://api.craftkit.dev/v1/signatures", headers={"Authorization": f"Bearer {os.environ['CRAFTKIT_API_KEY']}"}, params={"limit": 20}, ) page = res.json() ``` ### Query parameters | Field | Type | Description | Default | |---|---|---|---| | `limit` | integer | Page size, 1–100. | `50` | | `renderId` | string (UUID) | Filter to signature requests for a single render. | — | | `cursor` | string (ISO-8601) | Keyset cursor — return rows created strictly before this timestamp. Pass the previous page's `nextCursor`. | — | ### Response — `200 OK` ```json { "signatures": [ { "id": "0193c2c3-2222-7aaa-8bbb-000000000002", "renderId": "0193c2c3-1111-7aaa-8bbb-000000000001", "name": "Charter handover — BK-12345", "status": "completed", "recipients": [], "expirationHours": 168, "signedDownloadUrl": "https://api.craftkit.dev/v1/signatures/0193c2c3-2222-7aaa-8bbb-000000000002/download", "certificateUrl": "https://api.craftkit.dev/v1/signatures/0193c2c3-2222-7aaa-8bbb-000000000002/certificate", "errorMessage": null, "createdAt": "2026-06-05T10:00:00.000Z", "completedAt": "2026-06-05T11:42:08.000Z" } ], "nextCursor": "2026-06-05T10:00:00.000Z", "hasMore": false } ``` | Field | Type | Description | |---|---|---| | `signatures` | array | Signature requests (same shape as the create response). | | `nextCursor` | string \| null | Pass as `cursor` to fetch the next page; `null` when there are no more rows. | | `hasMore` | boolean | `true` when a full page was returned and more rows may exist. | ### Errors | HTTP | Code | Meaning | Fix | |---|---|---|---| | 400 | `invalid_request` | Invalid query parameters | Check `limit`, `renderId`, `cursor` formats | | 401 | `unauthorized` | Missing/invalid/revoked key | Check the bearer token | ## Get a signature request ```http GET /v1/signatures/:id ``` Poll a single signature request for its current status and (once available) the signed-document URL and certificate. ### Quick Start **curl** ```bash curl https://api.craftkit.dev/v1/signatures/$SIGNATURE_ID \ -H "Authorization: Bearer $CRAFTKIT_API_KEY" ``` **Node.js** ```javascript const res = await fetch(`https://api.craftkit.dev/v1/signatures/${id}`, { headers: { Authorization: `Bearer ${process.env.CRAFTKIT_API_KEY}` }, }); const signature = await res.json(); ``` **Python** ```python import os, requests res = requests.get( f"https://api.craftkit.dev/v1/signatures/{signature_id}", headers={"Authorization": f"Bearer {os.environ['CRAFTKIT_API_KEY']}"}, ) signature = res.json() ``` ### Path parameters | Field | Type | Description | Default | |---|---|---|---| | `id` | string (UUID) | The signature request id. | — | ### Response — `200 OK` Same shape as the [create response](#response--201-created). Watch `status`, `signedDownloadUrl`, `certificateUrl`, and `completedAt` change as the request progresses. ### Status lifecycle `status` moves through these values as the signature service delivers lifecycle events: | Status | Meaning | |---|---| | `sent` | Request created; the recipients have been emailed. | | `viewed` | A recipient opened the signing UI. | | `declined` | A recipient declined to sign (terminal). | | `expired` | The request passed its expiration window (terminal). | | `cancelled` | The request was cancelled (terminal). | | `completed` | All recipients signed and the document is finalized (terminal). | | `failed` | Processing failed (terminal). | Recipient-level signing arrives as a `signature.signed` webhook (and per-recipient `signedAt` timestamps) without moving the top-level `status`. Once the request is `completed`, Craftkit archives the signed PDF to its own storage and populates `signedDownloadUrl` and `certificateUrl`. ### Errors | HTTP | Code | Meaning | Fix | |---|---|---|---| | 401 | `unauthorized` | Missing/invalid/revoked key | Check the bearer token | | 404 | `not_found` | No signature request with that id in this project | Check the id and key's project scope | ## Cancel a signature request ```http POST /v1/signatures/:id/cancel ``` Cancels an in-flight request with the signature service and marks it `cancelled`. Rejected with `409` when the request is already in a terminal state (`completed`, `declined`, `expired`, `cancelled`, or `failed`). ### Quick Start **curl** ```bash curl -X POST https://api.craftkit.dev/v1/signatures/$SIGNATURE_ID/cancel \ -H "Authorization: Bearer $CRAFTKIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "reason": "Customer changed the terms" }' ``` **Node.js** ```javascript const res = await fetch(`https://api.craftkit.dev/v1/signatures/${id}/cancel`, { method: 'POST', headers: { Authorization: `Bearer ${process.env.CRAFTKIT_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ reason: 'Customer changed the terms' }), }); const signature = await res.json(); ``` **Python** ```python import os, requests res = requests.post( f"https://api.craftkit.dev/v1/signatures/{signature_id}/cancel", headers={"Authorization": f"Bearer {os.environ['CRAFTKIT_API_KEY']}"}, json={"reason": "Customer changed the terms"}, ) signature = res.json() ``` ### Path parameters | Field | Type | Description | Default | |---|---|---|---| | `id` | string (UUID) | The signature request id. | — | ### Request body The body is optional (an empty body is accepted). | Field | Type | Description | Default | |---|---|---|---| | `reason` | string | Cancellation reason (≤500 chars). Stored on the request as `errorMessage`. | — | ### Response — `200 OK` The updated signature request (same shape as the create response), now with `status: "cancelled"`. ### Errors | HTTP | Code | Meaning | Fix | |---|---|---|---| | 400 | `invalid_json` | Body wasn't valid JSON | Send an empty body or valid JSON | | 400 | `invalid_request` | Body didn't match the schema | `reason` must be a string ≤500 chars | | 401 | `unauthorized` | Missing/invalid/revoked key | Check the bearer token | | 404 | `not_found` | No signature request with that id in this project | Check the id and key's project scope | | 409 | `conflict` | Request is already terminal and can't be cancelled | Don't cancel completed/declined/expired/cancelled requests | | 502 | `signature_provider_error` | The signature service failed to cancel the request | Retry; reconcile via the status endpoint | ## Download the signed PDF ```http GET /v1/signatures/:id/download ``` Streams the archived signed PDF. The signed document is a sensitive legal artifact, so it is served **only** through the authenticated API (streamed from storage) — it is never reachable from a public bucket URL. Returns `409` until the document has been archived (i.e. until `signedDownloadUrl` is non-null). ### Quick Start **curl** ```bash curl https://api.craftkit.dev/v1/signatures/$SIGNATURE_ID/download \ -H "Authorization: Bearer $CRAFTKIT_API_KEY" \ -o signed.pdf ``` **Node.js** ```javascript const res = await fetch(`https://api.craftkit.dev/v1/signatures/${id}/download`, { headers: { Authorization: `Bearer ${process.env.CRAFTKIT_API_KEY}` }, }); const pdf = Buffer.from(await res.arrayBuffer()); ``` **Python** ```python import os, requests res = requests.get( f"https://api.craftkit.dev/v1/signatures/{signature_id}/download", headers={"Authorization": f"Bearer {os.environ['CRAFTKIT_API_KEY']}"}, ) with open("signed.pdf", "wb") as f: f.write(res.content) ``` ### Path parameters | Field | Type | Description | Default | |---|---|---|---| | `id` | string (UUID) | The signature request id. | — | ### Response — `200 OK` The signed PDF bytes (`Content-Type: application/pdf`), served as an attachment named `-signed.pdf`. ### Errors | HTTP | Code | Meaning | Fix | |---|---|---|---| | 401 | `unauthorized` | Missing/invalid/revoked key | Check the bearer token | | 404 | `not_found` | No signature request with that id in this project | Check the id and key's project scope | | 409 | `conflict` | Signed document isn't archived yet | Poll status until `signedDownloadUrl` is set | ## Download the completion certificate ```http GET /v1/signatures/:id/certificate ``` Streams the completion certificate (the audit trail PDF) for a finished signature request. Like the signed document, the certificate is served **only** through the authenticated API — Craftkit fetches it server-side and streams the bytes back, so the underlying provider URL never appears on the wire. Returns `409` until the certificate is available (i.e. until `certificateUrl` is non-null), and `502` if the document can't be retrieved upstream. ### Quick Start **curl** ```bash curl https://api.craftkit.dev/v1/signatures/$SIGNATURE_ID/certificate \ -H "Authorization: Bearer $CRAFTKIT_API_KEY" \ -o certificate.pdf ``` **Node.js** ```javascript const res = await fetch(`https://api.craftkit.dev/v1/signatures/${id}/certificate`, { headers: { Authorization: `Bearer ${process.env.CRAFTKIT_API_KEY}` }, }); const pdf = Buffer.from(await res.arrayBuffer()); ``` **Python** ```python import os, requests res = requests.get( f"https://api.craftkit.dev/v1/signatures/{signature_id}/certificate", headers={"Authorization": f"Bearer {os.environ['CRAFTKIT_API_KEY']}"}, ) with open("certificate.pdf", "wb") as f: f.write(res.content) ``` ### Path parameters | Field | Type | Description | Default | |---|---|---|---| | `id` | string (UUID) | The signature request id. | — | ### Response — `200 OK` The completion certificate bytes (`Content-Type: application/pdf`), served as an attachment named `-certificate.pdf`. ### Errors | HTTP | Code | Meaning | Fix | |---|---|---|---| | 401 | `unauthorized` | Missing/invalid/revoked key | Check the bearer token | | 404 | `not_found` | No signature request with that id in this project | Check the id and key's project scope | | 409 | `conflict` | Completion certificate isn't available yet | Poll status until `certificateUrl` is set | | 502 | `upstream_error` | The certificate couldn't be retrieved from the signature service | Retry; if persistent, contact support | ## Signature webhook events If your project has a webhook subscription (configured in the dashboard, see [Webhooks](/documentation/api/webhooks)), Craftkit emits signed outgoing webhooks to your server as the signature request changes state. These ride the same delivery contract as render webhooks: a `POST` of a JSON body with an `event` field, signed with HMAC-SHA256 of the raw body (hex, no prefix) in the `x-craftkit-signature` header, plus `x-craftkit-event`, `x-craftkit-timestamp`, and `x-craftkit-delivery-id`. Verify the signature against the subscription secret before trusting the payload, and respond `2xx` promptly. | Event | Fired when | |---|---| | `signature.sent` | The request was created and recipients were emailed. | | `signature.viewed` | A recipient opened the signing UI. | | `signature.signed` | A single recipient signed (per-recipient; does not move the top-level status). | | `signature.completed` | All recipients signed and the document is finalized. | | `signature.declined` | A recipient declined to sign. | | `signature.expired` | The request passed its expiration window. | | `signature.cancelled` | The request was cancelled. | A subscription only receives the events it is subscribed to. Each payload carries the Craftkit `event` name plus `signatureRequestId`, `renderId`, and a provider-neutral `status`; subscribe and verify on your side just as you would for `render.*` events. The payload never includes any provider-specific event type or identifier. ```json { "event": "signature.completed", "signatureRequestId": "0193c2c3-2222-7aaa-8bbb-000000000002", "renderId": "0193c2c3-1111-7aaa-8bbb-000000000001", "status": "completed" } ``` | Field | Type | Description | |---|---|---| | `event` | string | The Craftkit event name (e.g. `signature.completed`). | | `signatureRequestId` | string | The signature request id. | | `renderId` | string | The render that was sent for signature. | | `status` | string | Provider-neutral lifecycle status — one of `sent`, `viewed`, `completed`, `declined`, `expired`, `cancelled`. | ## Related - [Render a template](/documentation/api/render-template) — produce the PDF you send for signature - [GET /v1/renders/:id](/documentation/api/render-status) — confirm the render succeeded first - [Webhooks](/documentation/api/webhooks) — subscribe to `signature.*` lifecycle events - [Errors](/documentation/api/errors) — error envelope and retry semantics - [Authentication](/documentation/api/authentication) — bearer token format --- # Health check Public liveness and readiness probe for the Craftkit API. Returns `200` when all dependency checks pass and `503` when any are failing. No authentication is required. ```http GET /v1/health ``` ## Quick Start **curl** ```bash curl -i https://api.craftkit.dev/v1/health ``` **Node.js** ```javascript const res = await fetch('https://api.craftkit.dev/v1/health'); const health = await res.json(); const healthy = res.status === 200 && health.status === 'ok'; ``` **Python** ```python import requests res = requests.get("https://api.craftkit.dev/v1/health") healthy = res.status_code == 200 and res.json()["status"] == "ok" ``` No `Authorization` header is needed — this endpoint is public. ## Response — `200 OK` ```json { "status": "ok", "version": "a1b2c3d", "checks": { "database": "ok" } } ``` | Field | Type | Description | |---|---|---| | `status` | string | `ok` when every check passed, `degraded` when at least one failed. `degraded` is returned with HTTP `503`. | | `version` | string | Short git commit SHA of the running deployment (first 7 chars), or `local` when not deployed on Vercel. | | `checks` | object | Per-dependency status map. Each value is `ok` or `error`. | | `checks.database` | string | `ok` if a `SELECT 1` against Postgres succeeded, `error` otherwise. | When a dependency is failing, the same shape is returned with `status: "degraded"` and HTTP `503`: ```json { "status": "degraded", "version": "a1b2c3d", "checks": { "database": "error" } } ``` ## Errors | HTTP | Code | Meaning | Fix | |---|---|---|---| | 503 | `degraded` | One or more dependency checks failed (see `checks`) | Inspect the failing check; this signals an outage, not a client error | This endpoint never returns `4xx` — it takes no input and requires no auth. Treat `200` as healthy and `503` as degraded; the JSON body is the same shape in both cases. ## Related - [Authentication](/documentation/api/authentication) — bearer token format for the rest of the API - [Provisioning (multi-tenant)](/documentation/admin/provision) — admin endpoint for tenant setup - [Errors](/documentation/api/errors) — error envelope for the authenticated API --- # 01 — Embed Architecture > **Mental model**: the partner SaaS owns the data; Craftkit owns the editing > experience. They never share schemas. Instead, the partner *injects* its > variable catalog into the embedded builder for the duration of one editing > session. > Two iframe surfaces share this architecture: the **builder embed** > (`/embed/builder`) where partner end-users design templates, and the > **form-fill embed** (`/embed/form`) where they *fill* a published template > and produce documents. Same JWT mint flow, same origin pinning, same > appearance pipeline — only the UI inside the iframe differs. See > [12-form-route.md](./12-form-route.md) for the form embed's full design. ## The big picture ``` ┌─────────────────────────────────┐ │ Partner SaaS │ │ ┌───────────────────────────┐ │ ┌──────────────────────────┐ │ │ "Edit document template" │──┼────▶│ Craftkit Server │ │ │ (button in their UI) │ │ │ POST /v1/embed/sessions │ │ └───────────────────────────┘ │◀────│ → JWT (5 min TTL) │ │ │ │ └──────────────────────────┘ │ ▼ │ │ ┌───────────────────────────┐ │ │ │ ``` **React** ```tsx ``` ```js // JSON object → URL-safe base64 const appearance = { baseTheme: 'dark', variables: { colorPrimary: '#0EA5E9' } }; const b64 = btoa(JSON.stringify(appearance)) .replace(/\+/g, '-').replace(/\//g, '_'); iframe.src = `${baseUrl}?session_token=${token}&appearance=${b64}`; ``` URL params override mint-time appearance. Useful for live light/dark toggles where you don't want to re-mint a session. ### 3. Runtime (postMessage) For live updates after mount: switching themes when the user toggles dark mode, updating brand color from a settings page, swapping density. Same call from any framework: ```js iframe.contentWindow.postMessage( { type: 'craftkit.appearance.set', version: 1, payload: { appearance: { baseTheme: 'dark', variables: { colorPrimary: '#7C3AED' } } } }, 'https://embed.craftkit.dev' // targetOrigin — required for security ); ``` The iframe validates the sender origin against your registered `embed_origin` rows, then merges the partial appearance on top of the mint-time baseline and re-applies CSS without re-rendering. It acks back with: ```js window.addEventListener('message', (e) => { if (e.data?.type === 'craftkit.appearance.applied') { console.log('iframe accepted:', e.data.payload.acceptedKeys); } }); ``` ### 4. Partner stylesheet (CSS escape hatch) For partners that already maintain a brand stylesheet they don't want to translate to JSON. Set `appearance.stylesheetUrl` (mint-time, URL, or runtime) — the embed loads it as a `` inside the iframe, after our defaults so partner CSS wins. ```jsonc { "stylesheetUrl": "https://app.acme.com/embed-brand.css" } ``` ```css /* https://app.acme.com/embed-brand.css */ .ck-embed-root { --primary: #0EA5E9; --radius: 12px; } .ck-publish-button { font-weight: 600; } ``` **Origin gate.** The stylesheet URL must be HTTPS and on a host you've registered as an embed origin. Anything else is silently dropped — no error, just no custom CSS — so a typo never breaks the embed. --- ## Precedence ``` defaults ← embed.css ships these ↓ baseTheme ← appearance.baseTheme: 'light' | 'dark' | … ↓ branding (legacy) ← back-compat: primaryColor, fontUrl, logoUrl ↓ project default appearance ← embed_partner.default_appearance (Dashboard → Embed → Themes) ↓ mint-time appearance ← JWT.ck.appearance (per-session override) ↓ URL appearance ← ?theme= / ?appearance= ↓ runtime appearance ← postMessage('craftkit.appearance.set', …) ↓ partner stylesheet ← appearance.stylesheetUrl (cascades last) ``` Each step is **optional**. A partner that sets none gets the neutral default theme — system fonts, slate primary, a Stripe-y look that's intentionally generic so it blends into any host. --- ## Variables (`appearance.variables`) JSON keys map 1:1 to CSS custom properties on `.ck-embed-root`. Every key is optional. Values are plain CSS strings — hex, rgb(), hsl(), system keywords, anything CSS understands. | JSON key | CSS variable | Default | Purpose | |---|---|---|---| | `colorPrimary` | `--primary` | slate-900 | Buttons, focus rings, link accents | | `colorPrimaryForeground` | `--primary-foreground` | white | Text on primary backgrounds | | `colorBackground` | `--background` | white | Page surface | | `colorForeground` | `--foreground` | slate-900 | Body text | | `colorMuted` | `--muted` | slate-100 | Subdued surfaces (banner bg) | | `colorMutedForeground` | `--muted-foreground` | slate-500 | Subdued text | | `colorAccent` | `--accent` | slate-100 | Hover state surface | | `colorAccentForeground` | `--accent-foreground` | slate-900 | Text on accent surface | | `colorBorder` | `--border` | slate-200 | Outlines | | `colorInput` | `--input` | slate-200 | Form-field outlines | | `colorRing` | `--ring` | slate-900 | Focus ring color | | `colorDanger` | `--destructive` | red-500 | Error states | | `colorSuccess` | `--success` | emerald-500 | Success states | | `colorWarning` | `--warning` | amber-500 | Warning states | | `fontFamily` | `--font-sans` | system | Body font stack | | `fontFamilyMono` | `--font-mono` | system mono | Code/key font | | `fontSizeBase` | `--font-size-base` | 14px | Root font size | | `fontWeightNormal` | `--font-weight-normal` | 400 | Body weight | | `fontWeightMedium` | `--font-weight-medium` | 500 | Button/heading weight | | `fontWeightBold` | `--font-weight-bold` | 600 | Strong text | | `borderRadius` | `--radius` | 0.5rem | Corner radius | | `spacingUnit` | `--spacing-unit` | 0.25rem | Spacing scale base | --- ## Rules (`appearance.rules`) For surgical overrides where a variable change isn't enough. CSS-like selector → camelCase property map. ```json { "rules": { ".ck-publish-button": { "boxShadow": "0 1px 2px rgba(0,0,0,0.06)" }, ".ck-publish-button:hover": { "boxShadow": "0 4px 12px rgba(14,165,233,0.25)" }, ".ck-input": { "fontWeight": "500" }, ".ck-input:focus": { "borderColor": "#0EA5E9" } } } ``` **Selector allowlist.** Only published `.ck-*` classes are valid (see [07-admin-ui.md](./07-admin-ui.md)). Optional state suffixes: `:hover`, `:focus`, `:focus-visible`, `:active`, `:disabled`, `::placeholder`, `--selected`, `--invalid`. Anything else is silently dropped. **Property allowlist.** Color, typography, padding/margin, border, border-radius, box-shadow, opacity, cursor, transition. Anything else (position, z-index, display, content, pointer-events, …) is silently dropped — those properties could break the iframe layout or escape the widget surface. **Value sanitization.** Values that contain `<`, `expression(`, `javascript:`, `@import`, or unbalanced parens are silently dropped. --- ## Layout (`appearance.layout`) Structural toggles, independent of color/type. | Key | Type | Purpose | |---|---|---| | `showTopBar` | `boolean` | Show/hide the top bar | | `showCloseButton` | `boolean` | Show/hide the embed close button | | `showPublishButton` | `boolean` | Show/hide the publish action | | `showSaveDraftButton`| `boolean` | Show/hide the save-draft action | | `showTemplateList` | `boolean` | Show/hide the template-list rail | | `showRenderHistory` | `boolean` | Show/hide the render-history rail | | `density` | `'comfortable' \| 'compact'` | Spacing scale | | `locale` | `string` | UI locale, e.g. `en`, `es`, `de-DE` | --- ## Per-framework recipes The same JSON, four ways. None require shadcn or Tailwind. ### Vanilla HTML / plain JS ```html ``` ### React / Next.js ```tsx function CraftkitEmbed({ sessionToken, appearance }) { const ref = useRef(null); useEffect(() => { if (!appearance) return; ref.current?.contentWindow?.postMessage( { type: 'craftkit.appearance.set', version: 1, payload: { appearance } }, 'https://embed.craftkit.dev', ); }, [appearance]); return ( `, }) export class CraftkitEmbed implements OnChanges { @Input() sessionToken!: string; @Input() appearance?: Appearance; @ViewChild('ifr') ifr!: ElementRef; get src() { return `https://embed.craftkit.dev/embed/builder?session_token=${this.sessionToken}`; } ngOnChanges(c: SimpleChanges) { if (c.appearance && this.ifr) { this.ifr.nativeElement.contentWindow?.postMessage( { type: 'craftkit.appearance.set', version: 1, payload: { appearance: this.appearance } }, 'https://embed.craftkit.dev' ); } } } ``` ### Astro / static site ```astro --- const { sessionToken } = Astro.props; --- ``` The `?theme=auto` URL param has the iframe follow the user's OS `prefers-color-scheme` — works without any client JS. ### Rails / Laravel / Django (server-rendered) Server-renders the iframe with mint-time appearance baked in: ```erb <%# Rails: assume @session was minted with appearance already %> ``` The mint API call: ```ruby # Rails — same call from any backend language Faraday.post( "#{ENV['CRAFTKIT_API']}/v1/embed/sessions", { tenant: { externalId: account.id, displayName: account.name }, actor: { externalId: current_user.id, email: current_user.email }, appearance: { baseTheme: 'light', variables: { colorPrimary: account.brand_color, fontFamily: "'Inter', system-ui, sans-serif", borderRadius: '10px', }, }, }.to_json, { 'Authorization' => "Bearer #{ENV['CK_API_KEY']}", 'Content-Type' => 'application/json' }, ) ``` --- ## shadcn / Tailwind hosts (opt-in) If your host is built on shadcn/ui, you already define `--primary`, `--background`, `--ring`, `--radius`, etc. on ``. Cross-origin iframes can't read those, so a 12-line snippet on your host mirrors them into the embed via postMessage: ```js function pushShadcnAppearance(iframe) { const cs = getComputedStyle(document.documentElement); const v = (k) => cs.getPropertyValue(k).trim(); iframe.contentWindow.postMessage({ type: 'craftkit.appearance.set', version: 1, payload: { appearance: { baseTheme: 'shadcn', variables: { colorPrimary: v('--primary'), colorPrimaryForeground: v('--primary-foreground'), colorBackground: v('--background'), colorForeground: v('--foreground'), colorMuted: v('--muted'), colorMutedForeground: v('--muted-foreground'), colorAccent: v('--accent'), colorAccentForeground: v('--accent-foreground'), colorBorder: v('--border'), colorInput: v('--input'), colorRing: v('--ring'), colorDanger: v('--destructive'), borderRadius: v('--radius'), } } } }, 'https://embed.craftkit.dev'); } document.querySelector('#ck').addEventListener('load', (e) => pushShadcnAppearance(e.target)); ``` This is the shadcn equivalent of [Clerk's `baseTheme: shadcn` preset](https://clerk.com/changelog/2025-07-23-shadcn-theme), adapted for cross-origin iframes (which can't share CSS variables natively). --- ## Security model - **Origin-gated postMessage.** The iframe rejects every postMessage from an origin not registered in your partner's `embed_origin` table. - **Selector + property allowlists.** Rules can only target our published `.ck-*` classes with whitelisted properties. Layout-killing properties (`position`, `z-index`, `display`, `pointer-events`, `content`) are silently dropped. - **Value sanitizer.** Values containing `<`, `javascript:`, `expression(`, `@import`, or unbalanced parens are dropped. - **CSP-gated stylesheetUrl.** `` only loads if the URL is HTTPS and on a registered embed origin. Drive-by injection attempts fail closed. - **No JS injection.** `appearance.rules` cannot define `behavior:` or `expression()` (IE-era CSS exec); modern browsers don't execute these anyway, but the sanitizer drops them defensively. --- ## See also - [05 — postMessage Protocol](./05-postmessage-protocol.md) — full event catalogue including `craftkit.appearance.set` / `applied`. - [07 — Admin UI](./07-admin-ui.md) — full `.ck-*` class catalogue with DOM context, the stable contract you can target via `rules`. --- # 02 — JWT & Session Specification This document is the authoritative reference for the embed session token format. ## Signing | | | |---|---| | **Algorithm** | `EdDSA` (Ed25519) — small, fast, modern. Asymmetric so partners can verify tokens publicly without secret round-trips | | **Key rotation** | `kid` header points to current key; previous keys honored for 24h overlap | | **TTL** | 5 minutes for the session token; 24h for the optional context token | | **Transport** | URL query param on initial load only (`?session_token=…`); subsequent renewals via `postMessage` *only* — never re-write the URL | | **Storage in iframe** | In-memory only. Never localStorage / sessionStorage / cookies | ## Claims schema ```jsonc { // Standard JWT claims "iss": "ck_pk_live_aB3xQ7…", // partner's publishable key (issuer) "aud": "embed.craftkit.dev", // expected iframe host "sub": "session_01HVRX...", // session id (audit trail key) "iat": 1714657200, "exp": 1714657500, // iat + 300s "nbf": 1714657200, "jti": "ck_sess_…", // single-use enforcement on renewals // Craftkit-specific claims (under "ck" namespace) "ck": { "v": 1, // schema version "partner": { "id": "ck_partner_01HVR…", // resolved from publishable key "project_id": "ck_proj_01HVR…" // which project hosts the templates }, "tenant": { "external_id": "partner-org-12345", "display_name": "Acme Charters Ltd" }, "actor": { "external_id": "partner-user-67890", "display_name": "Jane Doe", "email": "jane@acme.com", // optional; audit only "avatar_url": "https://…" // optional }, "scope": { "mode": "edit", // "edit" | "create" | "view" | "fill" "template_id": "ck_tpl_01HVR…", // null when mode=create; required when mode=fill "template_external_id": "partner-template-9999" }, "permissions": { "publish": true, "save_draft": true, "delete": false, "create_custom_variables": false, // false = catalog-locked "change_page_settings": true, "rename": false, "view_version_history": true, "rollback_version": false, "submit_form": true, // mode=fill: required to POST /v1/embed/form-submit "save_form_draft": false // mode=fill: placeholder, phase 3 }, "form": { // optional; only consulted when mode=fill "prefill": { "customer.name": "Ada Lovelace" }, "show_preview": true, // side-by-side live preview pane "show_document_after_submit": true,// false = blank/close iframe after submit "redirect_url": null // optional partner "back" URL }, "catalog_ref": "cat_01HVR…", // pointer to a stored catalog "branding": { "logo_url": "https://acme.com/logo.svg", "primary_color": "#2563EB", "font_url": null, "locale": "en-GB", "ui": { "show_top_bar": false, "show_template_list": false, "show_render_history": false, "show_api_keys_link": false, "show_publish_button": true, "show_save_draft_button": true, "show_close_button": true } }, "callbacks": { "on_published": "https://saas.com/api/craftkit/events", "on_close_url": "https://saas.com/back-to-template-list" }, "limits": { "max_publishes": 5, "max_save_drafts": 50, "max_uploads_bytes": 5242880 }, "renew_token": "rt_01HVR…" // opaque; for /v1/embed/sessions/refresh } } ``` ## Why split `catalog_ref` from inline catalog Variable catalogs can be **large** (typical partner has 100–500 fields). Encoding that in a JWT URL would explode past most browser URL limits. So the partner POSTs the catalog *once* when minting the session; Craftkit stores it server-side; the JWT carries only the reference. The embed page fetches it with `Authorization: Bearer ` on load. ## Validation rules (server-side) Every embed page render must pass ALL of these: 1. JWT signature valid against current/previous Ed25519 keys 2. `exp > now`, `nbf ≤ now`, `iat ≤ now` 3. `aud` matches the request's `Host` header 4. `iss` resolves to a partner whose status is `active` 5. The request's `Origin` (or `Referer`) is in the partner's allowed-origins list 6. `ck.partner.project_id` belongs to the partner 7. `ck.scope.template_id` (if present) belongs to the partner's project AND the template is not deleted 8. `ck.catalog_ref` is owned by this session 9. `jti` not yet seen → mark seen for `exp` window If any fail → render `/embed/error?code=session_invalid` with NO leak of which check failed. ## Form-mode requirements (`scope.mode === 'fill'`) Form-fill sessions have a few extra invariants on top of the generic validation list above: 1. `scope.template_id` **or** `scope.template_external_id` must be set — the form needs a template to render. Sessions without one resolve the form route to `template_not_resolved` (404). 2. The resolved template must have a **published** version. Drafts are not fillable. A template with no published version surfaces as `unpublished_template` (404) on the API and `template_unpublished` on the embed error page. 3. `permissions.submit_form` is required to call `POST /v1/embed/form-submit/:sessionId`. Sessions with `submit_form: false` still load the form UI (useful as a preview affordance) but submission returns `permission_denied` (403). 4. `ck.form.prefill` keys are validated against the resolved variable schema at submit time (`invalid_input_data` if a key isn't in the manifest). Unknown keys in `prefill` are silently dropped at session mint, not at submit, so a stale partner integration can't accidentally inject data the template doesn't accept. 5. The other modes (`'edit' | 'create' | 'view'`) cannot call the form-submit endpoint — they receive `wrong_mode` (403). The `ck.form` block is optional; absent claims behave as if `prefill={}`, `showPreview=false`, `showDocumentAfterSubmit=true`, `redirectUrl=null`. ## Renewal flow ``` T-30s before expiry: iframe → parent : { type: 'craftkit.session.expiring', seconds: 30 } parent → its backend : POST /api/craftkit/refresh-session { renew_token } backend → Craftkit : POST /v1/embed/sessions/refresh { renew_token, ck_live_* } ← { session_token: "eyJ…", expires_at: ... } parent → iframe : { type: 'craftkit.token.refresh', token: 'eyJ…' } iframe acknowledges and replaces in-memory token If renewal fails (revoked / partner deleted / actor disabled): parent receives 401 → calls iframe `craftkit.session.terminate` iframe shows "Session expired — please reopen this template" ``` `renew_token` is single-use (rotates each refresh). Limits replay attacks. --- _Last revised: 2026-05-02_ --- # 05 — postMessage Protocol The bidirectional event bus between the partner's parent page and Craftkit's embedded iframe. The same protocol serves both the **builder** embed and the **form-fill** embed; form-only message types are tagged in the tables below. **Wire format:** every message is a JSON object: `{ type, version: 1, payload, requestId? }`. **Origin pinning:** - Iframe accepts only messages from validated parent origins - Parent (via SDK) accepts only messages from `https://embed.craftkit.dev` (or partner-configured `iframeOrigin`) - All other messages silently dropped ## Parent → iframe (commands) | Type | Payload | Purpose | |---|---|---| | `craftkit.token.refresh` | `{ token }` | Hand a new JWT just before expiry | | `craftkit.template.load` | `{ externalId }` | Switch to editing a different template | | `craftkit.theme.update` | `{ primaryColor?, logoUrl? }` | **Legacy** — superseded by `craftkit.appearance.set` | | `craftkit.appearance.set` | `{ appearance: Partial }` | Live appearance update — variables, rules, theme, density, layout, fonts. See [embed-styling guide](./11-styling.md). | | `craftkit.preview.data` | `{ data }` | Inject custom sample data for live preview | | `craftkit.session.terminate` | `{}` | Force-end the session (after revoke) | | `craftkit.command.save` | `{ requestId }` | Trigger save (response: `craftkit.response.save`) | | `craftkit.command.publish` | `{ requestId }` | Trigger publish (response: `craftkit.response.publish`) | | `craftkit.focus` | `{}` | Focus the editor | | `craftkit.form.submit` *(form)* | `{ requestId }` | Programmatically trigger a submit (mirror of clicking the form's submit button). Same `ParentCommandPayload` arm as `{ command: 'form.submit' }`. | | `craftkit.form.complete` *(form)* | `{ requestId, pdfUrl, metadata? }` | Reply to an intercepted `craftkit.form.submit` event — tells the iframe to display the partner-rendered PDF inline | | `craftkit.form.fail` *(form)* | `{ requestId, message, cause? }` | Reply to an intercepted submit — tells the iframe to show an error state | | `craftkit.form.set_value` *(form)* | `{ key, value }` | Set one form field | | `craftkit.form.set_values` *(form)* | `{ values }` | Bulk-set form fields (shallow merge) | | `craftkit.form.reset` *(form)* | `{}` | Clear all form values back to defaults/prefill | | `craftkit.form.set_read_only` *(form)* | `{ readOnly: boolean }` | Toggle read-only mode on the form | | `craftkit.dataset.set` *(form)* | `{ datasets: Record }` | Push complete eager datasets to the form | | `craftkit.dataset.declare` *(form)* | `{ datasets: Record }` | Declare lazy datasets — iframe will emit `dataset.search` as user types | | `craftkit.dataset.items` *(form)* | `{ key, items: [{ id, label }] }` | Reply to a `craftkit.dataset.search` request | | `craftkit.dataset.apply_item` *(form)* | `{ key, values }` | Reply to a `craftkit.dataset.item.requested` — supplies the full record to merge into form state | ## Iframe → parent (events) | Type | Payload | When | |---|---|---| | `craftkit.ready` | `{ sessionId, templateId }` | Iframe finished hydrating | | `craftkit.template.saved` | `{ templateId, version, manifest }` | User clicked Save | | `craftkit.template.published` | `{ templateId, version, manifest }` | User clicked Publish | | `craftkit.variable.inserted` | `{ key, type, source }` | After a variable is added | | `craftkit.variable.removed` | `{ key }` | After a variable is removed | | `craftkit.session.expiring` | `{ secondsRemaining }` | ~30s before JWT exp | | `craftkit.session.refreshed` | `{ newExpiresAt }` | After token replacement | | `craftkit.session.expired` | `{}` | JWT exp passed without refresh | | `craftkit.height.changed` | `{ heightPx }` | For autosizing iframe (optional) | | `craftkit.close.requested` | `{}` | User clicked the close button | | `craftkit.appearance.applied` | `{ acceptedKeys, droppedKeys }` | Ack for `craftkit.appearance.set` — lists fields the iframe accepted vs dropped (e.g. unknown selectors) | | `craftkit.error` | `CraftkitError` | Any failure surface | | `craftkit.response.save` | `{ requestId, version? }` | Response to save command | | `craftkit.response.publish` | `{ requestId, version? }` | Response to publish command | | `craftkit.form.submit` *(form)* | `{ data, datasetSelection, requestId }` | **Pre-submit** event. Interceptable: parent has 500ms to reply with `craftkit.form.complete` or `craftkit.form.fail` to claim the submit. No reply within 500ms → iframe POSTs to `/v1/embed/form-submit/:sessionId` itself. | | `craftkit.form.completed` *(form)* | `{ renderId, downloadUrl, data, datasetSelection, source: 'default' \| 'partner_supplied' }` | Render finished and is displayed inline | | `craftkit.form.failed` *(form)* | `{ message, cause?, renderId?, source }` | Submit or render failed; iframe shows error state | | `craftkit.form.invalid` *(form)* | `{ issues: ZodIssue[] }` | Client-side validation rejected the submit; no submit fired | | `craftkit.field.changed` *(form)* | `{ key, value }` | Debounced 300ms; useful for parent-side draft sync | | `craftkit.dataset.search` *(form)* | `{ key, query, requestId }` | User typed into a lazy dataset combobox; reply with `craftkit.dataset.items` | | `craftkit.dataset.item.requested` *(form)* | `{ key, itemId, requestId }` | User picked an item from a lazy dataset; reply with `craftkit.dataset.apply_item` carrying its full `values` | ## Request/response pattern For commands that need a result, use `requestId`: ```js // Parent → iframe postMessage({ type: 'craftkit.command.publish', version: 1, requestId: 'req_xyz', }); // Iframe → parent (matches by requestId) postMessage({ type: 'craftkit.response.publish', version: 1, requestId: 'req_xyz', payload: { version: 5 }, }); ``` The SDK exposes this via `builder.triggerPublish()` returning a Promise. ### Form-submit interception `craftkit.form.submit` (iframe → parent) is the only event in the protocol that is **interceptable** — replying with `craftkit.form.complete` or `craftkit.form.fail` matching the same `requestId` within 500ms causes the iframe to skip its default `POST /v1/embed/form-submit` call and display the partner-supplied PDF instead. The SDK exposes this as `e.preventDefault()` + `e.complete({ pdfUrl })` / `e.fail({ message })` on the `submit` event handler. After 500ms with no reply, the iframe proceeds with the default render. After 60s with no reply on a claimed submit, the iframe surfaces `craftkit.form.failed` with `cause: 'partner_timeout'`. ## Validation rules (both sides) Every message is validated: 1. `event.source === iframe.contentWindow` (parent side) OR `event.source === window.parent` (iframe side) 2. `event.origin === expectedOrigin` (strict equality) 3. `payload` is an object with `type: string` 4. `type` starts with `craftkit.` 5. `version` matches expected (currently always 1) Anything failing → silently dropped, NOT logged to user (avoids information leak to malicious origins). ## Versioning The `version` field allows protocol evolution. When v2 ships: - v1 SDKs continue working (server tolerates v1) - v2 SDKs prefer v2 but fall back to v1 - The iframe negotiates by inspecting first message's version ## Why postMessage AND webhooks | | postMessage | Webhook | |---|---|---| | Latency | Sub-ms | 100ms–10s | | Reliability | Lost on tab close, navigation | Durable, retried | | Security | Origin-pinned | HMAC-signed | | Use for | UX (close modal, show toast) | Source of truth (DB writes) | **The rule:** webhook is the source of truth. postMessage is for snappy UX. Never trust postMessage alone for state changes that matter. --- _Last revised: 2026-05-02_ --- # 03 — `@craftkit/embed` SDK The drop-in JavaScript SDK that partners use to mount Craftkit's two embed surfaces: the **builder** (`mountBuilder`) for designing templates and the **form-fill embed** (`mountForm`) for end-users to fill a published template and produce a document. Both share the same `Craftkit.init(...)` client, the same origin gating, and the same refresh/teardown plumbing. **Goals:** - Tiny, dependency-free - ESM + CJS + UMD builds - Loadable as ` ``` ## Form-fill quickstart Mounting the form embed is the same shape — different mount method, different events. The session token must have `scope.mode === 'fill'` and resolve to a published template (see [02-jwt-spec.md](./02-jwt-spec.md)). ```html

``` ### `FormInstance` — the API surface you'll use ```ts interface FormInstance { // Lifecycle on(event: FormEventType, handler): () => void; off(event: FormEventType, handler): void; destroy(): void; // Imperative commands setValue(key: string, value: unknown): void; setValues(values: Record): void; submit(): Promise; // programmatic submit reset(): void; setReadOnly(readOnly: boolean): void; // Datasets (see below) setDatasets(datasets: Record): void; declareDatasets(datasets: Record): void; setDatasetItems(key: string, items: Array<{ id: string; label: string }>): void; applyDatasetItem(key: string, values: Record): void; } type FormEventType = | 'ready' // iframe hydrated | 'submit' // pre-submit; interceptable (Stripe-style) | 'form.completed' // post-submit success (default OR partner_supplied) | 'form.failed' // post-submit failure | 'form.invalid' // client-side validation failure (no submit fired) | 'field.changed' // debounced 300ms | 'dataset.search' // lazy dataset queried by user | 'dataset.item.requested' | 'session.expiring' | 'session.refreshed' | 'session.expired' | 'close.requested' | 'error'; ``` The full TypeScript shape (event payloads, `EagerDataset`, etc.) lives in `packages/embed/src/index.ts`. ### Stripe-style submit interception By default, the iframe enqueues the render and displays the PDF inline. A parent handler can claim the submit and supply its own PDF instead. Identical UX from the user's perspective — they always see the document in the same iframe, only the PDF source changes. ```js form.on('submit', async (e) => { // e = { data, datasetSelection, requestId, preventDefault, complete, fail } if (!needsCustomSigning(e.data)) return; // let default render proceed e.preventDefault(); // claim the submit (within 500ms) try { const signed = await mySigningService(e.data); const pdf = await myRenderPipeline(signed); await e.complete({ pdfUrl: pdf.url, metadata: { signedBy: 'acme' } }); // iframe now shows pdf.url; emits form.completed { source: 'partner_supplied' } } catch (err) { await e.fail({ message: err.message, cause: err }); } }); ``` The interception window is **500ms** after `craftkit.form.submit` fires. A synchronous `e.preventDefault()` always wins. Once claimed, the partner has up to 60s to call `e.complete()` or `e.fail()` before the iframe surfaces a `partner_timeout` error. ### Eager dataset prefill Datasets are partner-supplied lookups (bookings, contacts, etc.) that let the user pick an item and auto-fill the form. **All dataset content stays client-side** — Craftkit only sees the `id` of the item the user picked (stored on `render.dataset_selection` for audit). ```js form.on('ready', () => { form.setDatasets({ bookings: { label: 'Pick a booking', items: myBookings.map(b => ({ id: b.id, // internal correlation label: `${b.customer} — ${b.month}`, // shown in dropdown values: { // shallow-merged into form state 'customer.name': b.customer, 'booking.startDate': b.startDate, }, })), }, }); }); ``` For huge or per-user-authorized datasets, declare a lazy dataset and respond to `dataset.search` / `dataset.item.requested` events. Single- select per dataset; multi-select for loop fields is a phase-3 follow-up. Full design in [12-form-route.md](./12-form-route.md) §7c. ## Public API surface ```ts namespace Craftkit { function init(config: { publishableKey: string; debug?: boolean; iframeOrigin?: string; // default https://embed.craftkit.dev onError?: (err: CraftkitError) => void; }): CraftkitClient; } interface CraftkitClient { mountBuilder(opts: MountBuilderOptions): BuilderInstance; mountForm(opts: MountFormOptions): FormInstance; // (future: mountTemplatePicker, mountRenderHistory, mountUsageDashboard…) } interface MountBuilderOptions { container: string | HTMLElement; sessionToken: string; height?: 'auto' | string | number; autoResize?: boolean; loadingComponent?: HTMLElement | string; refresh: () => Promise; sandboxFlags?: string; allowFullscreen?: boolean; } interface BuilderInstance { readonly sessionId: string; readonly templateId: string | null; readonly renewToken: string; readonly iframeElement: HTMLIFrameElement; on( event: E, handler: (payload: BuilderEvents[E]) => void ): () => void; off(event: E, handler: Function): void; setTheme(theme: Partial<{ primaryColor: string; logoUrl: string }>): void; loadTemplate(externalId: string): Promise; setPreviewData(data: Record): void; triggerSave(): Promise<{ version: number }>; triggerPublish(): Promise<{ version: number }>; focus(): void; destroy(): void; isDestroyed(): boolean; } interface BuilderEvents { 'ready': { sessionId: string; templateId: string | null }; 'template.saved': { templateId: string; version: number; manifest: VariableManifest }; 'template.published': { templateId: string; version: number; manifest: VariableManifest }; 'variable.inserted': { key: string; type: string; source: 'catalog' | 'custom' }; 'variable.removed': { key: string }; 'session.expiring': { secondsRemaining: number }; 'session.refreshed': { newExpiresAt: string }; 'session.expired': {}; 'height.changed': { heightPx: number }; 'close.requested': {}; 'error': CraftkitError; } interface CraftkitError { code: | 'session_invalid' | 'session_expired' | 'origin_not_allowed' | 'permission_denied' | 'iframe_load_failed' | 'refresh_failed' | 'rate_limited' | 'unknown'; message: string; recoverable: boolean; } ``` ## Internal architecture ``` ┌─────────────────── Partner page ────────────────────┐ │ │ │ CraftkitClient │ │ ├─ origin allowlist check │ │ ├─ event bus (Map>) │ │ └─ BuilderInstance │ │ ├─ creates ``` ```tsx // React