Pulp Engine API

Preview template CSV with an inline definition (editor use — no DB save required)

Preview template DOCX with an inline definition (editor use — no DB save required)

Preview template HTML with an inline definition (editor use — no DB save required)

Preview template PDF with an inline definition (editor use — no DB save required)

Preview template PPTX with an inline definition (editor use — no DB save required)

Preview capability status — cached startup snapshot; always returns 200

Returns whether the preview renderer was available when this process started. This is a startup snapshot, not a perpetual guarantee: if preview is available at startup but a later individual render fails, that travels the normal 422/500 path. Raw browser failure details are kept in server logs only.

Preview template XLSX with an inline definition (editor use — no DB save required)

Execute multiple GET requests in a single HTTP call

Accepts an array of GET sub-requests targeting template read surfaces (/templates, /templates/:key, /templates/:key/versions, /templates/:key/labels). Returns an array of {status, body} responses. Max 20 items. Auth scope: admin or editor.

Insert pages into a PDF

Insert all pages from one PDF into another at a specified position.

Merge multiple PDFs into one

Concatenate pages from multiple PDF documents into a single PDF, in the order provided.

Apply a watermark to a PDF

Overlay a text or image watermark on every page (or a page range) of a PDF.

List all templates (paginated)

Returns a paginated list of templates. Use ?expand=versions,labels,lastRenders to include nested relations. When expand is present, limit is capped at 100.

Create a new template

Soft-delete a template (admin only; requires If-Match header)

Get a template with its current definition

Update a template definition (requires If-Match header; auto-bumps version)

Diff two stored versions of a template

Computes a structural diff between two stored versions of the same template key. Returns the raw TemplateDiff JSON from @pulp-engine/template-diff — metadata, renderConfig, inputSchema, fieldMapping, document-root, and document-tree changes plus aggregate counts. v1 scope: both versions must exist in the resolved tenant.

Get form-rendering metadata for a template

Returns { key, version, title?, description?, inputSchema, hasFieldMappings } for the given template. Used by the <pulp-engine-form> embed to auto-generate a fillable form. hasFieldMappings=true signals that the template transforms raw input via fieldMappings; the v1 form refuses to render such templates because inputSchema describes the POST-MAPPING shape, not the submission shape.

List all labels on a template

Returns every named label pointer and the version it resolves to. Dual-scoped: admin or editor.

Delete a label (admin-only)

Removes the label pointer. Idempotent — succeeds silently on unknown labels as long as the template exists. Admin scope required.

Get the template definition at a labeled version

Resolves the label to its target version and returns the full template definition. Dual-scoped: admin or editor.

Create or re-point a label (admin-only)

Creates the label if it does not exist, or re-points it if it does. The target version must be a saved version. Supports optimistic concurrency via the If-Match header: when present, the label's current version must match the supplied string or the request fails with 412 Precondition Failed. When absent, the label is upserted unconditionally (for automated promotion flows that trust their own serialization). Admin scope required.

Delete stored sample data for a template version

Admin-only. Idempotent — returns 204 whether or not a row existed. Use ?version= to target a specific version; defaults to the current version. Subsequent GET falls through to SampleService.

Get sample preview data for a template

Returns stored sample data when present and still valid against the template's inputSchema; otherwise synthesises a payload via SampleService. Use ?version= to target a specific historical version; defaults to the current version. The source is reported in the X-Sample-Source response header.

Persist sample preview data against the template's current version

Last-write-wins: no If-Match, no ETag response header. The payload is AJV-validated against the current inputSchema before persist; invalid payloads are rejected with 422 and no row is written. Audit: emits a `template_mutation` event with operation `set_sample`.

Get the JSON Schema input definition for a template

Validate a data payload against a template's input schema

Validates arbitrary input data against the stored template's JSON Schema. Applies field mappings (data adapter) before validation. Use this to pre-check data payloads before calling the render endpoint. This does NOT validate the template structure itself — use POST /render/validate for that.

List all saved versions for a template (newest first, paginated)

Get a template's definition at a specific version

Promote a historical version to current (admin only; requires If-Match header)

Generate a draft template from a natural-language prompt (AI)

Schema-constrained Claude tool-use call. Returns an unsaved draft TemplateDefinition validated by the same Zod schema as hand-authored saves. The caller must POST /templates to persist. Per-actor rate limited (default 5/min). Returns 503 when ANTHROPIC_API_KEY is unset. 502 is returned for any upstream failure (network, malformed tool use, or validation exhausted after repair attempts) — query the audit log (event=template_generation) for specifics.

List uploaded assets, optionally filtered by name (?q=), MIME type (?mimeType=), or legacy SVG signals (?legacySvg=true)

Delete an asset by ID

Upload an image asset (multipart/form-data, max 10 MB)

List schedules

Returns a paginated list of schedule definitions. Admin scope required.

Create a schedule

Creates a new schedule definition. Computes and stores the next fire time from the cron expression. Admin scope required.

Delete schedule

Deletes a schedule and all its execution history. Admin scope required.

Get schedule by ID

Returns a single schedule definition with secrets masked. Admin scope required.

Partially update schedule

Updates specified fields only. JSON fields (dataSource, deliveryTargets) are full-replaced, not deep-merged. Recomputes next fire time if cron or enabled changes. Admin scope required.

Update schedule (full replace)

Replaces the entire schedule definition. Recomputes next fire time. Admin scope required.

List execution history

Returns a paginated list of executions for a schedule. Admin scope required.

Get execution detail

Returns a single execution record. Admin scope required.

Manually trigger schedule

Creates an immediate execution for the schedule. Rate-limited. Admin scope required.

Exchange an API key for a short-lived editor session token (8 hours)

Check whether authentication is required and if editor login is available

List batch webhook DLQ entries

Returns a paginated list of dead-lettered batch webhook delivery attempts. Each entry includes a `replayable` flag: on postgres deployments this is a three-part check (the durable batch-job row exists + the result blob is present + the DLQ entry is still `pending`). On file/sqlserver deployments it falls back to the pre-T3 in-memory check. Admin scope required. Returns 503 in file mode (requires STORAGE_MODE=postgres or sqlserver for the DLQ store).

Get a batch webhook DLQ entry

Mark a batch webhook DLQ entry as abandoned

Marks a DLQ entry as terminal (abandoned). Does not require active tenant (terminal cleanup). Admin scope required.

Replay a dead-lettered batch webhook delivery

Re-delivers the batch job webhook. On postgres deployments reads the webhook URL, secret, and result payload from the durable batch-job + blob stores, so replay survives API restart. On file/sqlserver deployments falls back to the in-memory job store. Returns 409 `job_expired` if the job has been purged, 409 `job_not_completed` if the job is still running, 409 `already_terminal` if already replayed/abandoned.

List schedule delivery DLQ entries

Returns a paginated list of dead-lettered delivery attempts. Response includes references only — the raw target config is never echoed back. Admin scope required. Returns 503 when the DLQ store is not available (file mode — requires STORAGE_MODE=postgres or sqlserver).

Get a schedule delivery DLQ entry

Mark a DLQ entry as abandoned

Marks a DLQ entry as terminal (abandoned). Use when an operator has determined the delivery cannot or should not be replayed. Admin scope required.

Replay a dead-lettered delivery

Re-dispatches a single failed delivery target. Rehydrates the current target config from the live schedule — an operator fix to the schedule (e.g. correcting a webhook URL) is picked up automatically. Returns 409 with a specific `code` when the replay cannot proceed: schedule_gone, schedule_mutated, render_artifact_expired, dispatcher_unavailable, already_terminal.

List all named editor users (key redacted)

Add a new named editor user

Remove a named editor user (existing tokens rejected on next request)

Update an existing named editor user

Re-read EDITOR_USERS_FILE and replace the in-memory registry

Purge audit events

Deletes audit events. Supply "before" for time-based retention purges, "actor" for GDPR erasure of a specific identity, or both to scope an erasure to events older than a cutoff. At least one of "before" or "actor" is required. Admin scope required.

List audit events

Returns a paginated, filterable list of audit events. Admin scope required.

Rollup render usage by time bucket or category

Aggregates render volume for the caller's tenant over a half-open [from, to) window. Temporal buckets (day/week/month) use UTC date_trunc; categorical buckets use direct group-by. Window capped at 92 days. Admin scope required. Returns 503 usage_not_available in file mode (no DB-backed store).

Export render usage rows as CSV for invoicing pipelines

Returns up to USAGE_EXPORT_MAX_ROWS rows as text/csv, ordered by timestamp. Hard cap 500000: if count exceeds cap, returns 413 usage_export_too_large with the count. Narrow the window to fit. Admin scope required. Returns 503 in file mode (no DB-backed store).

Server feature capabilities — per-format render toggles + future flags

Returns which features are currently enabled at this server. v0.60.0 only carries per-format render route booleans (pdf/html/docx/csv/xlsx/pptx). PPTX is gated by the PPTX_ENABLED env var (default true; beta in v0.60.0). Always returns 200.

Liveness probe — always 200 if the process is up

Readiness probe — 503 if storage is unreachable

AI-rewrite the content of a single text or heading node (SSE stream)

Streams `delta` (append) or `replace` (reset-buffer) events, optional `restart` on repair, then a terminal `done` or `error`. Response Content-Type is text/event-stream. See plan for wire contract. Returns 503 when AI generation is disabled and 409 when block-form Handlebars (`{{#each}}`, `{{#if}}`, `{{else}}`) is present in content.

Record the user's apply/dismiss choice for an AI node rewrite

Render a template to PDF

Render multiple templates to PDF in a single request

Renders up to 50 templates concurrently. Each item is rendered independently; one failure does not abort others. Default response is a single JSON envelope. When the caller sends `Accept: application/x-ndjson`, the route streams one `result` line per item in completion order as each resolves, followed by a single `summary` line with authoritative totals.

Submit an async PDF batch render with webhook callback

Accepts up to 50 templates. Returns 202 immediately with a job ID. Results are rendered in the background and the webhook URL receives a metadata-only notification on completion. Poll GET /render/batch/jobs/:id for full results including rendered PDFs.

Submit an async DOCX batch render with webhook callback

Accepts up to 50 templates. Returns 202 immediately with a job ID. Results are rendered in the background and the webhook URL receives a metadata-only notification on completion. Poll GET /render/batch/jobs/:id for full results including rendered DOCX bytes.

Render multiple templates to DOCX in a single request

Renders up to 50 templates concurrently. Each item is rendered independently; one failure does not abort others. Results are returned as base64-encoded DOCX bytes in a JSON envelope.

Poll async batch job status

Returns the current status and results (when complete) of an async batch render job. Results include base64-encoded rendered output. Jobs are retained after completion for at least WEBHOOK_JOB_RETENTION_SECONDS; on postgres deployments completed jobs survive API restart and remain pollable until that retention window elapses. Pending/processing jobs that survive a restart without their worker are failed at the next start via the orphan-reconciliation step.

Render multiple templates to PPTX in a single request (beta)

Renders up to 50 templates concurrently as PowerPoint presentations. Each item is rendered independently; one failure does not abort others. Each successful result includes a warningCount field counting structured warnings emitted by the renderer. Beta in v0.60.0 — gated by PPTX_ENABLED.

Export a table from a template as CSV

Extracts a single table node from a template and renders it as RFC 4180 CSV. If the template contains exactly one table, it is selected automatically. If multiple tables exist, specify `tableId` to select which one.

Render a template to DOCX

Renders a template to a Word document (.docx). The template AST is walked directly — no browser required.

Render a template to HTML

Render a template to PPTX (beta)

Renders a template to a PowerPoint presentation (.pptx). Beta in v0.60.0 — gated by the PPTX_ENABLED env var (default true). The renderer walks the template AST directly and produces a .pptx binary via pptxgenjs. Structured warnings are surfaced via the x-render-warnings response header.

Validate a template for publish readiness — always registered, no HTML/PDF output

Validates a template DEFINITION for structural correctness and renderability. Performs three checks: (1) Zod structural parse, (2) blocked-asset detection, (3) trial HTML render. Use this before publishing a template. This does NOT validate input data — use POST /templates/:key/validate for that.

Export table data from a template as XLSX

Extracts table nodes from a template and renders them into an Excel workbook. Single-table templates auto-select; multi-table templates produce one sheet per table (or filter to a single table via `tableId`).