{ "openapi": "3.0.3", "info": { "title": "Pulp Engine API", "description": "Template management and document rendering API for Pulp Engine. Authenticate with X-Api-Key (scoped API keys) or X-Editor-Token (short-lived session token). See /docs for the interactive UI.", "version": "0.0.0-extracted" }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "Scoped API key. Accepted scopes: admin, render, preview, editor. Set via API_KEY_ADMIN, API_KEY_RENDER, API_KEY_PREVIEW, or API_KEY_EDITOR environment variables." }, "EditorTokenAuth": { "type": "apiKey", "in": "header", "name": "X-Editor-Token", "description": "Short-lived HMAC-signed session token. Obtain via POST /auth/editor-token. Valid for 8 hours. In shared-key mode, grants editor scope. In named-user mode, grants the scope of the user's configured role (editor or admin)." }, "SandboxTokenAuth": { "type": "apiKey", "in": "header", "name": "X-Sandbox-Token", "description": "Short-lived anonymous token minted by POST /sandbox/session. IP-pinned and quota-counted; only valid for /sandbox/render/* routes. Available exclusively on deployments with SANDBOX_ENABLED=true (the public playground surface at pulpengine.dev/playground)." } }, "schemas": {} }, "paths": { "/assets/upload": { "post": { "operationId": "uploadAsset", "summary": "Upload an image asset (multipart/form-data, max 10 MB)", "tags": [ "Assets" ], "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "filename", "originalName", "mimeType", "sizeBytes", "url", "createdAt", "createdBy" ], "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "originalName": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "number" }, "url": { "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp", "type": "string" }, "createdBy": { "description": "Actor identity (user id) who uploaded this asset, or null if unknown.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referencedBy": { "description": "Active templates referencing this asset via a static image src. Only populated when ?legacySvg=true.", "type": "array", "items": { "type": "object", "required": [ "key", "name", "currentVersion" ], "properties": { "key": { "description": "Template key", "type": "string" }, "name": { "description": "Template display name", "type": "string" }, "currentVersion": { "description": "Current template version", "type": "string" } } } } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "415": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } } }, "/assets/": { "get": { "operationId": "listAssets", "summary": "List uploaded assets, optionally filtered by name (?q=), MIME type (?mimeType=), or legacy SVG signals (?legacySvg=true)", "tags": [ "Assets" ], "parameters": [ { "schema": { "maxLength": 200, "type": "string" }, "in": "query", "name": "q", "required": false, "description": "Case-insensitive substring filter on originalName" }, { "schema": { "maxLength": 100, "type": "string" }, "in": "query", "name": "mimeType", "required": false, "description": "Exact MIME type filter (e.g. image/png). Case-insensitive." }, { "schema": { "type": "boolean" }, "in": "query", "name": "legacySvg", "required": false, "description": "Return assets matching legacy SVG detection signals: declared mimeType of image/svg+xml OR filename ending with .svg. Use this to enumerate assets that may have been uploaded before v0.27.0 SVG rejection was enforced." }, { "schema": { "minimum": 1, "maximum": 1000, "default": 50, "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of items to return (1-1000, default 50)" }, { "schema": { "minimum": 0, "default": 0, "type": "integer" }, "in": "query", "name": "offset", "required": false, "description": "Number of items to skip" } ], "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "200": { "description": "Default Response", "headers": { "type": { "schema": { "0": "o", "1": "b", "2": "j", "3": "e", "4": "c", "5": "t" } }, "required": { "schema": { "0": "X-Request-ID" } }, "properties": { "schema": { "X-Request-ID": { "description": "Server-generated UUID for correlating this response with structured log entries (reqId field).", "type": "string" } } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "total", "limit", "offset" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "filename", "originalName", "mimeType", "sizeBytes", "url", "createdAt", "createdBy" ], "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "originalName": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "number" }, "url": { "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp", "type": "string" }, "createdBy": { "description": "Actor identity (user id) who uploaded this asset, or null if unknown.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referencedBy": { "description": "Active templates referencing this asset via a static image src. Only populated when ?legacySvg=true.", "type": "array", "items": { "type": "object", "required": [ "key", "name", "currentVersion" ], "properties": { "key": { "description": "Template key", "type": "string" }, "name": { "description": "Template display name", "type": "string" }, "currentVersion": { "description": "Current template version", "type": "string" } } } } } } }, "total": { "minimum": 0, "type": "integer" }, "limit": { "minimum": 1, "type": "integer" }, "offset": { "minimum": 0, "type": "integer" } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } } }, "/assets/{id}": { "delete": { "operationId": "deleteAsset", "summary": "Delete an asset by ID", "tags": [ "Assets" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "204": { "description": "Asset deleted", "content": { "application/json": { "schema": { "description": "Asset deleted" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } } }, "/auth/status": { "get": { "operationId": "getAuthStatus", "summary": "Check whether authentication is required and if editor login is available", "tags": [ "Auth" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "authRequired", "editorLoginAvailable", "identityMode" ], "properties": { "authRequired": { "type": "boolean" }, "editorLoginAvailable": { "type": "boolean" }, "identityMode": { "description": "\"named-users\" when EDITOR_USERS_JSON or EDITOR_USERS_FILE is configured (per-user keys, server-derived actor). \"shared-key\" otherwise (legacy shared-key + optional actor).", "anyOf": [ { "type": "string", "enum": [ "named-users" ] }, { "type": "string", "enum": [ "shared-key" ] } ] }, "loginUnavailableReason": { "description": "Present only when editorLoginAvailable is false. \"no_users\" = named-user mode with empty registry; \"no_credentials\" = shared-key mode with no editor-capable keys; \"auth_disabled\" = no credentials configured (dev mode).", "anyOf": [ { "type": "string", "enum": [ "no_credentials" ] }, { "type": "string", "enum": [ "no_users" ] }, { "type": "string", "enum": [ "auth_disabled" ] } ] }, "oidcEnabled": { "description": "True when OIDC SSO is configured. When true, oidcLoginUrl and oidcProviderName are also present.", "type": "boolean" }, "oidcLoginUrl": { "description": "URL to redirect the browser to for OIDC SSO login. Present only when oidcEnabled is true.", "type": "string" }, "oidcProviderName": { "description": "Display name for the OIDC provider (e.g. \"Okta\", \"SSO\"). Used as the login button label.", "type": "string" } } } } } } } } }, "/auth/editor-token": { "post": { "operationId": "createEditorToken", "summary": "Exchange an API key for a short-lived editor session token (8 hours)", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "description": "API key with editor or admin scope", "type": "string" }, "actor": { "description": "Optional operator-supplied actor label for audit attribution. Omit or send a non-empty string (max 200 chars, no control characters). Must not be used for authorization decisions.", "maxLength": 200, "type": "string" } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "token", "expiresAt", "actor", "displayName", "scope", "tenantId" ], "properties": { "token": { "description": "HMAC-signed session token for X-Editor-Token header", "type": "string" }, "expiresAt": { "description": "ISO 8601 expiry timestamp (8 hours from issuance)", "type": "string" }, "actor": { "description": "Actor identifier embedded in the session token. In named-user mode, this is the verified user id. In shared-key mode, this is the operator-supplied label (or null if not provided). Must not be used for authorization decisions.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "displayName": { "description": "Human-readable display name for the authenticated user. Only set in named-user mode. null in shared-key mode.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scope": { "description": "Credential scope this session will present on subsequent requests. `admin` unlocks mutation endpoints like label promotion and version restore; `editor` is read-only for those surfaces. Informational — the server still enforces scope on every request.", "anyOf": [ { "type": "string", "enum": [ "admin" ] }, { "type": "string", "enum": [ "editor" ] } ] }, "tenantId": { "description": "Tenant the session is bound to. For single-tenant deployments this is always \"default\". In multi-tenant mode the value is derived from the credential, named-user, or OIDC default at mint time.", "type": "string" } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: quota_exhausted (sandbox lifetime quota).", "type": "string" } } } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } } }, "/admin/users/": { "get": { "operationId": "listUsers", "summary": "List all named editor users (key redacted)", "tags": [ "Admin" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "users" ], "properties": { "users": { "type": "array", "items": { "type": "object", "required": [ "id", "displayName", "role", "keyHint" ], "properties": { "id": { "type": "string" }, "displayName": { "type": "string" }, "role": { "anyOf": [ { "type": "string", "enum": [ "editor" ] }, { "type": "string", "enum": [ "admin" ] } ] }, "keyHint": { "description": "Last 4 characters of the key, for identification only", "type": "string" }, "tokenIssuedAfter": { "type": "string" }, "tenantId": { "pattern": "^[a-z0-9][a-z0-9-]{0,62}$", "description": "C.0 Stage 2: tenant attribution tag. Absent = default tenant.", "type": "string" } } } } } } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "post": { "operationId": "createUser", "summary": "Add a new named editor user", "tags": [ "Admin" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "displayName", "key", "role" ], "properties": { "id": { "pattern": "^[a-zA-Z0-9_-]+$", "type": "string" }, "displayName": { "minLength": 1, "type": "string" }, "key": { "minLength": 1, "type": "string" }, "role": { "anyOf": [ { "type": "string", "enum": [ "editor" ] }, { "type": "string", "enum": [ "admin" ] } ] }, "tokenIssuedAfter": { "type": "string" }, "tenantId": { "pattern": "^[a-z0-9][a-z0-9-]{0,62}$", "description": "C.0 Stage 2: optional tenant attribution. When minting a token, this user's session is bound to the given tenant. Missing = default tenant.", "type": "string" } } } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "displayName", "role", "keyHint" ], "properties": { "id": { "type": "string" }, "displayName": { "type": "string" }, "role": { "anyOf": [ { "type": "string", "enum": [ "editor" ] }, { "type": "string", "enum": [ "admin" ] } ] }, "keyHint": { "description": "Last 4 characters of the key, for identification only", "type": "string" }, "tokenIssuedAfter": { "type": "string" }, "tenantId": { "pattern": "^[a-z0-9][a-z0-9-]{0,62}$", "description": "C.0 Stage 2: tenant attribution tag. Absent = default tenant.", "type": "string" } } } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/admin/users/{id}": { "put": { "operationId": "updateUser", "summary": "Update an existing named editor user", "tags": [ "Admin" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "minLength": 1, "type": "string" }, "role": { "anyOf": [ { "type": "string", "enum": [ "editor" ] }, { "type": "string", "enum": [ "admin" ] } ] }, "tokenIssuedAfter": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tenantId": { "description": "C.0 Stage 2: patch tenant attribution. null clears the tag (falls back to default).", "anyOf": [ { "pattern": "^[a-z0-9][a-z0-9-]{0,62}$", "type": "string" }, { "type": "null" } ] } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "displayName", "role", "keyHint" ], "properties": { "id": { "type": "string" }, "displayName": { "type": "string" }, "role": { "anyOf": [ { "type": "string", "enum": [ "editor" ] }, { "type": "string", "enum": [ "admin" ] } ] }, "keyHint": { "description": "Last 4 characters of the key, for identification only", "type": "string" }, "tokenIssuedAfter": { "type": "string" }, "tenantId": { "pattern": "^[a-z0-9][a-z0-9-]{0,62}$", "description": "C.0 Stage 2: tenant attribution tag. Absent = default tenant.", "type": "string" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "delete": { "operationId": "deleteUser", "summary": "Remove a named editor user (existing tokens rejected on next request)", "tags": [ "Admin" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted", "registrySize" ], "properties": { "deleted": { "type": "boolean" }, "registrySize": { "type": "number" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/admin/users/reload": { "post": { "operationId": "reloadUsers", "summary": "Re-read EDITOR_USERS_FILE and replace the in-memory registry", "tags": [ "Admin" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "reloaded", "count" ], "properties": { "reloaded": { "type": "boolean" }, "count": { "type": "number" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/audit-events/": { "get": { "operationId": "listAuditEvents", "summary": "List audit events", "tags": [ "Audit" ], "description": "Returns a paginated, filterable list of audit events. Admin scope required.", "parameters": [ { "schema": { "minimum": 1, "maximum": 1000, "default": 50, "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of items to return (1-1000, default 50)" }, { "schema": { "minimum": 0, "default": 0, "type": "integer" }, "in": "query", "name": "offset", "required": false, "description": "Number of items to skip" }, { "schema": { "type": "string" }, "in": "query", "name": "event", "required": false, "description": "Filter by event type" }, { "schema": { "type": "string" }, "in": "query", "name": "operation", "required": false, "description": "Filter by operation" }, { "schema": { "type": "string" }, "in": "query", "name": "actor", "required": false, "description": "Filter by actor" }, { "schema": { "type": "string" }, "in": "query", "name": "resourceType", "required": false, "description": "Filter by resource type" }, { "schema": { "type": "string" }, "in": "query", "name": "resourceId", "required": false, "description": "Filter by resource ID (template key or asset ID)" }, { "schema": { "format": "date-time", "type": "string" }, "in": "query", "name": "since", "required": false, "description": "ISO 8601 lower bound (inclusive)" }, { "schema": { "format": "date-time", "type": "string" }, "in": "query", "name": "until", "required": false, "description": "ISO 8601 upper bound (inclusive)" } ], "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "total", "limit", "offset" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "timestamp", "event", "operation", "resourceType", "resourceId", "actor", "credentialScope", "details" ], "properties": { "id": { "type": "string" }, "timestamp": { "format": "date-time", "type": "string" }, "event": { "description": "Event type: template_mutation, asset_mutation, editor_token_minted, template_generation, batch_job, oidc_provision_conflict", "type": "string" }, "operation": { "description": "Operation: create, update, delete, upload, restore, mint, generate", "type": "string" }, "resourceType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "actor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "credentialScope": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "details": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ] } } } }, "total": { "minimum": 0, "type": "integer" }, "limit": { "minimum": 1, "type": "integer" }, "offset": { "minimum": 0, "type": "integer" } } } } } } } }, "delete": { "operationId": "purgeAuditEvents", "summary": "Purge audit events", "tags": [ "Audit" ], "description": "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.", "parameters": [ { "schema": { "format": "date-time", "type": "string" }, "in": "query", "name": "before", "required": false, "description": "ISO 8601 cutoff — events with timestamp strictly before this value are deleted" }, { "schema": { "type": "string" }, "in": "query", "name": "actor", "required": false, "description": "Actor identifier — deletes events attributed to this actor (GDPR erasure). May be combined with \"before\" for scoped erasure." } ], "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "description": "Number of audit events deleted", "type": "integer" } } } } } } } } }, "/usage": { "get": { "operationId": "getUsageRollup", "summary": "Rollup render usage by time bucket or category", "tags": [ "Usage" ], "description": "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).", "parameters": [ { "schema": { "format": "date-time", "type": "string" }, "in": "query", "name": "from", "required": true, "description": "ISO 8601 lower bound (inclusive)" }, { "schema": { "format": "date-time", "type": "string" }, "in": "query", "name": "to", "required": true, "description": "ISO 8601 upper bound (exclusive — half-open window)" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "day" ] }, { "type": "string", "enum": [ "week" ] }, { "type": "string", "enum": [ "month" ] }, { "type": "string", "enum": [ "template" ] }, { "type": "string", "enum": [ "format" ] }, { "type": "string", "enum": [ "source" ] }, { "type": "string", "enum": [ "mode" ] } ] }, "in": "query", "name": "groupBy", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "production" ] }, { "type": "string", "enum": [ "preview" ] } ] }, "in": "query", "name": "source", "required": false }, { "schema": { "maxLength": 256, "type": "string" }, "in": "query", "name": "templateKey", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "single" ] }, { "type": "string", "enum": [ "batch" ] }, { "type": "string", "enum": [ "async-batch" ] }, { "type": "string", "enum": [ "transform" ] }, { "type": "string", "enum": [ "scheduled" ] } ] }, "in": "query", "name": "mode", "required": false } ], "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "from", "to", "groupBy", "buckets", "total" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "groupBy": { "anyOf": [ { "type": "string", "enum": [ "day" ] }, { "type": "string", "enum": [ "week" ] }, { "type": "string", "enum": [ "month" ] }, { "type": "string", "enum": [ "template" ] }, { "type": "string", "enum": [ "format" ] }, { "type": "string", "enum": [ "source" ] }, { "type": "string", "enum": [ "mode" ] } ] }, "buckets": { "type": "array", "items": { "type": "object", "required": [ "key", "count", "totalDurationMs", "totalOutputBytes", "totalPages" ], "properties": { "key": { "type": "string" }, "count": { "minimum": 0, "type": "integer" }, "totalDurationMs": { "minimum": 0, "type": "integer" }, "totalOutputBytes": { "description": "BigInt serialized as a decimal string", "type": "string" }, "totalPages": { "minimum": 0, "type": "integer" } } } }, "total": { "type": "object", "required": [ "count", "totalDurationMs", "totalOutputBytes", "totalPages" ], "properties": { "count": { "minimum": 0, "type": "integer" }, "totalDurationMs": { "minimum": 0, "type": "integer" }, "totalOutputBytes": { "type": "string" }, "totalPages": { "minimum": 0, "type": "integer" } } } } } } } } } } }, "/usage.csv": { "get": { "operationId": "exportUsageCsv", "summary": "Export render usage rows as CSV for invoicing pipelines", "tags": [ "Usage" ], "description": "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).", "parameters": [ { "schema": { "format": "date-time", "type": "string" }, "in": "query", "name": "from", "required": true }, { "schema": { "format": "date-time", "type": "string" }, "in": "query", "name": "to", "required": true }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "production" ] }, { "type": "string", "enum": [ "preview" ] } ] }, "in": "query", "name": "source", "required": false }, { "schema": { "maxLength": 256, "type": "string" }, "in": "query", "name": "templateKey", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "single" ] }, { "type": "string", "enum": [ "batch" ] }, { "type": "string", "enum": [ "async-batch" ] }, { "type": "string", "enum": [ "transform" ] }, { "type": "string", "enum": [ "scheduled" ] } ] }, "in": "query", "name": "mode", "required": false } ], "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/schedules/": { "post": { "operationId": "createSchedule", "summary": "Create a schedule", "tags": [ "Schedules" ], "description": "Creates a new schedule definition. Computes and stores the next fire time from the cron expression. Admin scope required.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "cronExpression", "templateKey", "dataSource", "deliveryTargets" ], "properties": { "name": { "minLength": 1, "maxLength": 200, "type": "string" }, "enabled": { "type": "boolean" }, "cronExpression": { "minLength": 1, "type": "string" }, "timezone": { "default": "UTC", "type": "string" }, "templateKey": { "minLength": 1, "type": "string" }, "templateVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "templateLabel": { "anyOf": [ { "minLength": 1, "maxLength": 64, "type": "string" }, { "type": "null" } ] }, "format": { "anyOf": [ { "type": "string", "enum": [ "pdf" ] }, { "type": "string", "enum": [ "docx" ] } ] }, "dataSource": { "anyOf": [ { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "enum": [ "static" ] }, "data": { "type": "object", "additionalProperties": {} } } }, { "type": "object", "required": [ "type", "url" ], "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "format": "uri", "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "timeoutMs": { "minimum": 1000, "maximum": 60000, "type": "integer" } } } ] }, "deliveryTargets": { "minItems": 1, "type": "array", "items": { "anyOf": [ { "type": "object", "required": [ "type", "to", "subject" ], "properties": { "type": { "type": "string", "enum": [ "email" ] }, "to": { "minItems": 1, "type": "array", "items": { "format": "email", "type": "string" } }, "cc": { "type": "array", "items": { "format": "email", "type": "string" } }, "subject": { "minLength": 1, "type": "string" }, "body": { "type": "string" }, "attachmentName": { "type": "string" } } }, { "type": "object", "required": [ "type", "key" ], "properties": { "type": { "type": "string", "enum": [ "s3" ] }, "key": { "minLength": 1, "type": "string" }, "bucket": { "type": "string" }, "region": { "type": "string" } } }, { "type": "object", "required": [ "type", "url", "secret" ], "properties": { "type": { "type": "string", "enum": [ "webhook" ] }, "url": { "format": "uri", "type": "string" }, "secret": { "minLength": 8, "type": "string" }, "includeBody": { "type": "boolean" } } } ] } }, "renderOptions": { "type": "object", "additionalProperties": {} } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "enabled", "cronExpression", "timezone", "templateKey", "templateVersion", "templateLabel", "format", "dataSource", "deliveryTargets", "renderOptions", "nextFireAt", "lastFiredAt", "createdAt", "updatedAt", "createdBy" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "cronExpression": { "type": "string" }, "timezone": { "type": "string" }, "templateKey": { "type": "string" }, "templateVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "templateLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "format": { "anyOf": [ { "type": "string", "enum": [ "pdf" ] }, { "type": "string", "enum": [ "docx" ] } ] }, "dataSource": { "description": "Data source (headers masked in response)" }, "deliveryTargets": { "type": "array", "items": { "anyOf": [ { "type": "object", "required": [ "type", "to", "subject" ], "properties": { "type": { "type": "string", "enum": [ "email" ] }, "to": { "type": "array", "items": { "type": "string" } }, "cc": { "type": "array", "items": { "type": "string" } }, "subject": { "type": "string" }, "body": { "type": "string" }, "attachmentName": { "type": "string" } } }, { "type": "object", "required": [ "type", "key" ], "properties": { "type": { "type": "string", "enum": [ "s3" ] }, "key": { "type": "string" }, "bucket": { "type": "string" }, "region": { "type": "string" } } }, { "type": "object", "required": [ "type", "url", "secret" ], "properties": { "type": { "type": "string", "enum": [ "webhook" ] }, "url": { "type": "string" }, "secret": { "type": "string" }, "includeBody": { "type": "boolean" } } } ] } }, "renderOptions": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ] }, "nextFireAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastFiredAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } }, "get": { "operationId": "listSchedules", "summary": "List schedules", "tags": [ "Schedules" ], "description": "Returns a paginated list of schedule definitions. Admin scope required.", "parameters": [ { "schema": { "minimum": 1, "maximum": 1000, "default": 50, "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of items to return (1-1000, default 50)" }, { "schema": { "minimum": 0, "default": 0, "type": "integer" }, "in": "query", "name": "offset", "required": false, "description": "Number of items to skip" }, { "schema": { "type": "string" }, "in": "query", "name": "enabled", "required": false, "description": "Filter by enabled status (true/false)" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "total", "limit", "offset" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "enabled", "cronExpression", "timezone", "templateKey", "templateVersion", "templateLabel", "format", "dataSource", "deliveryTargets", "renderOptions", "nextFireAt", "lastFiredAt", "createdAt", "updatedAt", "createdBy" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "cronExpression": { "type": "string" }, "timezone": { "type": "string" }, "templateKey": { "type": "string" }, "templateVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "templateLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "format": { "anyOf": [ { "type": "string", "enum": [ "pdf" ] }, { "type": "string", "enum": [ "docx" ] } ] }, "dataSource": { "description": "Data source (headers masked in response)" }, "deliveryTargets": { "type": "array", "items": { "anyOf": [ { "type": "object", "required": [ "type", "to", "subject" ], "properties": { "type": { "type": "string", "enum": [ "email" ] }, "to": { "type": "array", "items": { "type": "string" } }, "cc": { "type": "array", "items": { "type": "string" } }, "subject": { "type": "string" }, "body": { "type": "string" }, "attachmentName": { "type": "string" } } }, { "type": "object", "required": [ "type", "key" ], "properties": { "type": { "type": "string", "enum": [ "s3" ] }, "key": { "type": "string" }, "bucket": { "type": "string" }, "region": { "type": "string" } } }, { "type": "object", "required": [ "type", "url", "secret" ], "properties": { "type": { "type": "string", "enum": [ "webhook" ] }, "url": { "type": "string" }, "secret": { "type": "string" }, "includeBody": { "type": "boolean" } } } ] } }, "renderOptions": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ] }, "nextFireAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastFiredAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "total": { "minimum": 0, "type": "integer" }, "limit": { "minimum": 1, "type": "integer" }, "offset": { "minimum": 0, "type": "integer" } } } } } } } } }, "/schedules/{id}": { "get": { "operationId": "getSchedule", "summary": "Get schedule by ID", "tags": [ "Schedules" ], "description": "Returns a single schedule definition with secrets masked. Admin scope required.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "enabled", "cronExpression", "timezone", "templateKey", "templateVersion", "templateLabel", "format", "dataSource", "deliveryTargets", "renderOptions", "nextFireAt", "lastFiredAt", "createdAt", "updatedAt", "createdBy" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "cronExpression": { "type": "string" }, "timezone": { "type": "string" }, "templateKey": { "type": "string" }, "templateVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "templateLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "format": { "anyOf": [ { "type": "string", "enum": [ "pdf" ] }, { "type": "string", "enum": [ "docx" ] } ] }, "dataSource": { "description": "Data source (headers masked in response)" }, "deliveryTargets": { "type": "array", "items": { "anyOf": [ { "type": "object", "required": [ "type", "to", "subject" ], "properties": { "type": { "type": "string", "enum": [ "email" ] }, "to": { "type": "array", "items": { "type": "string" } }, "cc": { "type": "array", "items": { "type": "string" } }, "subject": { "type": "string" }, "body": { "type": "string" }, "attachmentName": { "type": "string" } } }, { "type": "object", "required": [ "type", "key" ], "properties": { "type": { "type": "string", "enum": [ "s3" ] }, "key": { "type": "string" }, "bucket": { "type": "string" }, "region": { "type": "string" } } }, { "type": "object", "required": [ "type", "url", "secret" ], "properties": { "type": { "type": "string", "enum": [ "webhook" ] }, "url": { "type": "string" }, "secret": { "type": "string" }, "includeBody": { "type": "boolean" } } } ] } }, "renderOptions": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ] }, "nextFireAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastFiredAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } }, "put": { "operationId": "replaceSchedule", "summary": "Update schedule (full replace)", "tags": [ "Schedules" ], "description": "Replaces the entire schedule definition. Recomputes next fire time. Admin scope required.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "cronExpression", "templateKey", "dataSource", "deliveryTargets" ], "properties": { "name": { "minLength": 1, "maxLength": 200, "type": "string" }, "enabled": { "type": "boolean" }, "cronExpression": { "minLength": 1, "type": "string" }, "timezone": { "default": "UTC", "type": "string" }, "templateKey": { "minLength": 1, "type": "string" }, "templateVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "templateLabel": { "anyOf": [ { "minLength": 1, "maxLength": 64, "type": "string" }, { "type": "null" } ] }, "format": { "anyOf": [ { "type": "string", "enum": [ "pdf" ] }, { "type": "string", "enum": [ "docx" ] } ] }, "dataSource": { "anyOf": [ { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "enum": [ "static" ] }, "data": { "type": "object", "additionalProperties": {} } } }, { "type": "object", "required": [ "type", "url" ], "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "format": "uri", "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "timeoutMs": { "minimum": 1000, "maximum": 60000, "type": "integer" } } } ] }, "deliveryTargets": { "minItems": 1, "type": "array", "items": { "anyOf": [ { "type": "object", "required": [ "type", "to", "subject" ], "properties": { "type": { "type": "string", "enum": [ "email" ] }, "to": { "minItems": 1, "type": "array", "items": { "format": "email", "type": "string" } }, "cc": { "type": "array", "items": { "format": "email", "type": "string" } }, "subject": { "minLength": 1, "type": "string" }, "body": { "type": "string" }, "attachmentName": { "type": "string" } } }, { "type": "object", "required": [ "type", "key" ], "properties": { "type": { "type": "string", "enum": [ "s3" ] }, "key": { "minLength": 1, "type": "string" }, "bucket": { "type": "string" }, "region": { "type": "string" } } }, { "type": "object", "required": [ "type", "url", "secret" ], "properties": { "type": { "type": "string", "enum": [ "webhook" ] }, "url": { "format": "uri", "type": "string" }, "secret": { "minLength": 8, "type": "string" }, "includeBody": { "type": "boolean" } } } ] } }, "renderOptions": { "type": "object", "additionalProperties": {} } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "enabled", "cronExpression", "timezone", "templateKey", "templateVersion", "templateLabel", "format", "dataSource", "deliveryTargets", "renderOptions", "nextFireAt", "lastFiredAt", "createdAt", "updatedAt", "createdBy" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "cronExpression": { "type": "string" }, "timezone": { "type": "string" }, "templateKey": { "type": "string" }, "templateVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "templateLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "format": { "anyOf": [ { "type": "string", "enum": [ "pdf" ] }, { "type": "string", "enum": [ "docx" ] } ] }, "dataSource": { "description": "Data source (headers masked in response)" }, "deliveryTargets": { "type": "array", "items": { "anyOf": [ { "type": "object", "required": [ "type", "to", "subject" ], "properties": { "type": { "type": "string", "enum": [ "email" ] }, "to": { "type": "array", "items": { "type": "string" } }, "cc": { "type": "array", "items": { "type": "string" } }, "subject": { "type": "string" }, "body": { "type": "string" }, "attachmentName": { "type": "string" } } }, { "type": "object", "required": [ "type", "key" ], "properties": { "type": { "type": "string", "enum": [ "s3" ] }, "key": { "type": "string" }, "bucket": { "type": "string" }, "region": { "type": "string" } } }, { "type": "object", "required": [ "type", "url", "secret" ], "properties": { "type": { "type": "string", "enum": [ "webhook" ] }, "url": { "type": "string" }, "secret": { "type": "string" }, "includeBody": { "type": "boolean" } } } ] } }, "renderOptions": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ] }, "nextFireAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastFiredAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } }, "patch": { "operationId": "updateSchedule", "summary": "Partially update schedule", "tags": [ "Schedules" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "minLength": 1, "maxLength": 200, "type": "string" }, "enabled": { "type": "boolean" }, "cronExpression": { "minLength": 1, "type": "string" }, "timezone": { "default": "UTC", "type": "string" }, "templateKey": { "minLength": 1, "type": "string" }, "templateVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "templateLabel": { "anyOf": [ { "minLength": 1, "maxLength": 64, "type": "string" }, { "type": "null" } ] }, "format": { "anyOf": [ { "type": "string", "enum": [ "pdf" ] }, { "type": "string", "enum": [ "docx" ] } ] }, "dataSource": { "anyOf": [ { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "enum": [ "static" ] }, "data": { "type": "object", "additionalProperties": {} } } }, { "type": "object", "required": [ "type", "url" ], "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "format": "uri", "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "timeoutMs": { "minimum": 1000, "maximum": 60000, "type": "integer" } } } ] }, "deliveryTargets": { "minItems": 1, "type": "array", "items": { "anyOf": [ { "type": "object", "required": [ "type", "to", "subject" ], "properties": { "type": { "type": "string", "enum": [ "email" ] }, "to": { "minItems": 1, "type": "array", "items": { "format": "email", "type": "string" } }, "cc": { "type": "array", "items": { "format": "email", "type": "string" } }, "subject": { "minLength": 1, "type": "string" }, "body": { "type": "string" }, "attachmentName": { "type": "string" } } }, { "type": "object", "required": [ "type", "key" ], "properties": { "type": { "type": "string", "enum": [ "s3" ] }, "key": { "minLength": 1, "type": "string" }, "bucket": { "type": "string" }, "region": { "type": "string" } } }, { "type": "object", "required": [ "type", "url", "secret" ], "properties": { "type": { "type": "string", "enum": [ "webhook" ] }, "url": { "format": "uri", "type": "string" }, "secret": { "minLength": 8, "type": "string" }, "includeBody": { "type": "boolean" } } } ] } }, "renderOptions": { "type": "object", "additionalProperties": {} } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "enabled", "cronExpression", "timezone", "templateKey", "templateVersion", "templateLabel", "format", "dataSource", "deliveryTargets", "renderOptions", "nextFireAt", "lastFiredAt", "createdAt", "updatedAt", "createdBy" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "cronExpression": { "type": "string" }, "timezone": { "type": "string" }, "templateKey": { "type": "string" }, "templateVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "templateLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "format": { "anyOf": [ { "type": "string", "enum": [ "pdf" ] }, { "type": "string", "enum": [ "docx" ] } ] }, "dataSource": { "description": "Data source (headers masked in response)" }, "deliveryTargets": { "type": "array", "items": { "anyOf": [ { "type": "object", "required": [ "type", "to", "subject" ], "properties": { "type": { "type": "string", "enum": [ "email" ] }, "to": { "type": "array", "items": { "type": "string" } }, "cc": { "type": "array", "items": { "type": "string" } }, "subject": { "type": "string" }, "body": { "type": "string" }, "attachmentName": { "type": "string" } } }, { "type": "object", "required": [ "type", "key" ], "properties": { "type": { "type": "string", "enum": [ "s3" ] }, "key": { "type": "string" }, "bucket": { "type": "string" }, "region": { "type": "string" } } }, { "type": "object", "required": [ "type", "url", "secret" ], "properties": { "type": { "type": "string", "enum": [ "webhook" ] }, "url": { "type": "string" }, "secret": { "type": "string" }, "includeBody": { "type": "boolean" } } } ] } }, "renderOptions": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ] }, "nextFireAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastFiredAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } }, "delete": { "operationId": "deleteSchedule", "summary": "Delete schedule", "tags": [ "Schedules" ], "description": "Deletes a schedule and all its execution history. Admin scope required.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "204": { "description": "Default Response" }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } } }, "/schedules/{id}/trigger": { "post": { "operationId": "triggerSchedule", "summary": "Manually trigger schedule", "tags": [ "Schedules" ], "description": "Creates an immediate execution for the schedule. Rate-limited. Admin scope required.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "scheduleId", "fireTime", "status", "claimedBy", "claimedAt", "renderDurationMs", "deliveryResults", "lastError", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "scheduleId": { "type": "string" }, "fireTime": { "type": "string" }, "status": { "type": "string" }, "claimedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "claimedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "renderDurationMs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "deliveryResults": { "anyOf": [ { "type": "array", "items": { "type": "object", "required": [ "targetType", "delivered", "attempts" ], "properties": { "targetType": { "type": "string" }, "delivered": { "type": "boolean" }, "attempts": { "type": "integer" }, "error": { "type": "string" } } } }, { "type": "null" } ] }, "lastError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } } }, "/schedules/{id}/executions": { "get": { "operationId": "listScheduleExecutions", "summary": "List execution history", "tags": [ "Schedules" ], "description": "Returns a paginated list of executions for a schedule. Admin scope required.", "parameters": [ { "schema": { "minimum": 1, "maximum": 1000, "default": 50, "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of items to return (1-1000, default 50)" }, { "schema": { "minimum": 0, "default": 0, "type": "integer" }, "in": "query", "name": "offset", "required": false, "description": "Number of items to skip" }, { "schema": { "type": "string" }, "in": "query", "name": "status", "required": false, "description": "Filter by execution status" }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "total", "limit", "offset" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "scheduleId", "fireTime", "status", "claimedBy", "claimedAt", "renderDurationMs", "deliveryResults", "lastError", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "scheduleId": { "type": "string" }, "fireTime": { "type": "string" }, "status": { "type": "string" }, "claimedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "claimedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "renderDurationMs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "deliveryResults": { "anyOf": [ { "type": "array", "items": { "type": "object", "required": [ "targetType", "delivered", "attempts" ], "properties": { "targetType": { "type": "string" }, "delivered": { "type": "boolean" }, "attempts": { "type": "integer" }, "error": { "type": "string" } } } }, { "type": "null" } ] }, "lastError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } } }, "total": { "minimum": 0, "type": "integer" }, "limit": { "minimum": 1, "type": "integer" }, "offset": { "minimum": 0, "type": "integer" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } } }, "/schedules/{id}/executions/{execId}": { "get": { "operationId": "getScheduleExecution", "summary": "Get execution detail", "tags": [ "Schedules" ], "description": "Returns a single execution record. Admin scope required.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "execId", "required": true } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "scheduleId", "fireTime", "status", "claimedBy", "claimedAt", "renderDurationMs", "deliveryResults", "lastError", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "scheduleId": { "type": "string" }, "fireTime": { "type": "string" }, "status": { "type": "string" }, "claimedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "claimedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "renderDurationMs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "deliveryResults": { "anyOf": [ { "type": "array", "items": { "type": "object", "required": [ "targetType", "delivered", "attempts" ], "properties": { "targetType": { "type": "string" }, "delivered": { "type": "boolean" }, "attempts": { "type": "integer" }, "error": { "type": "string" } } } }, { "type": "null" } ] }, "lastError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } } }, "/admin/schedule-dlq/": { "get": { "operationId": "listScheduleDlq", "summary": "List schedule delivery DLQ entries", "tags": [ "Admin" ], "description": "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).", "parameters": [ { "schema": { "minimum": 1, "maximum": 1000, "default": 50, "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of items to return (1-1000, default 50)" }, { "schema": { "minimum": 0, "default": 0, "type": "integer" }, "in": "query", "name": "offset", "required": false, "description": "Number of items to skip" }, { "schema": { "type": "string" }, "in": "query", "name": "status", "required": false, "description": "Filter by status: pending | replayed | abandoned | orphaned" }, { "schema": { "type": "string" }, "in": "query", "name": "scheduleId", "required": false, "description": "Filter by schedule id" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "total", "limit", "offset" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "scheduleId", "executionId", "targetIndex", "targetType", "targetIdHash", "lastError", "attempts", "firstFailedAt", "lastFailedAt", "replayCount", "status", "createdAt" ], "properties": { "id": { "type": "string" }, "scheduleId": { "type": "string" }, "executionId": { "type": "string" }, "targetIndex": { "type": "integer" }, "targetType": { "type": "string" }, "targetIdHash": { "type": "string" }, "lastError": { "type": "string" }, "attempts": { "type": "integer" }, "firstFailedAt": { "type": "string" }, "lastFailedAt": { "type": "string" }, "replayCount": { "type": "integer" }, "status": { "type": "string" }, "createdAt": { "type": "string" } } } }, "total": { "minimum": 0, "type": "integer" }, "limit": { "minimum": 1, "type": "integer" }, "offset": { "minimum": 0, "type": "integer" } } } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } } }, "/admin/schedule-dlq/{id}": { "get": { "operationId": "getScheduleDlqEntry", "summary": "Get a schedule delivery DLQ entry", "tags": [ "Admin" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "scheduleId", "executionId", "targetIndex", "targetType", "targetIdHash", "lastError", "attempts", "firstFailedAt", "lastFailedAt", "replayCount", "status", "createdAt" ], "properties": { "id": { "type": "string" }, "scheduleId": { "type": "string" }, "executionId": { "type": "string" }, "targetIndex": { "type": "integer" }, "targetType": { "type": "string" }, "targetIdHash": { "type": "string" }, "lastError": { "type": "string" }, "attempts": { "type": "integer" }, "firstFailedAt": { "type": "string" }, "lastFailedAt": { "type": "string" }, "replayCount": { "type": "integer" }, "status": { "type": "string" }, "createdAt": { "type": "string" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } } }, "/admin/schedule-dlq/{id}/replay": { "post": { "operationId": "replayScheduleDlqEntry", "summary": "Replay a dead-lettered delivery", "tags": [ "Admin" ], "description": "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.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "status", "replayCount", "delivered", "attempts" ], "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "replayCount": { "type": "integer" }, "delivered": { "type": "boolean" }, "attempts": { "type": "integer" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } } }, "/admin/schedule-dlq/{id}/abandon": { "post": { "operationId": "abandonScheduleDlqEntry", "summary": "Mark a DLQ entry as abandoned", "tags": [ "Admin" ], "description": "Marks a DLQ entry as terminal (abandoned). Use when an operator has determined the delivery cannot or should not be replayed. Admin scope required.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "204": { "description": "Default Response" }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } } }, "/templates/{key}/labels": { "get": { "operationId": "listTemplateLabels", "summary": "List all labels on a template", "tags": [ "Templates" ], "description": "Returns every named label pointer and the version it resolves to. Dual-scoped: admin or editor.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true } ], "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "label", "version", "trafficSplit", "controlLabel", "updatedAt", "updatedBy" ], "properties": { "label": { "type": "string" }, "version": { "type": "string" }, "trafficSplit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "controlLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "type": "string" }, "updatedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } } }, "/templates/{key}/labels/{label}": { "get": { "operationId": "getTemplateAtLabel", "summary": "Get the template definition at a labeled version", "tags": [ "Templates" ], "description": "Resolves the label to its target version and returns the full template definition. Dual-scoped: admin or editor.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "key", "required": true }, { "schema": { "minLength": 1, "maxLength": 64, "type": "string" }, "in": "path", "name": "label", "required": true } ], "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "key", "name", "currentVersion", "description", "definition" ], "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "currentVersion": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "definition": { "description": "TemplateDefinition object. See validation/template-definition.schema.ts for the full Zod schema." } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } }, "put": { "operationId": "setTemplateLabel", "summary": "Create or re-point a label (admin-only)", "tags": [ "Templates" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "version" ], "properties": { "version": { "minLength": 1, "description": "Target version to point the label at. Must be a saved version.", "type": "string" }, "trafficSplit": { "minimum": 0, "maximum": 100, "description": "Variant traffic-split percentage (0..100). Must be set together with controlLabel.", "type": "integer" }, "controlLabel": { "minLength": 1, "maxLength": 64, "description": "Fallback label name for variant resolution. Must point at an existing label.", "type": "string" } } } } } }, "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "key", "required": true }, { "schema": { "minLength": 1, "maxLength": 64, "type": "string" }, "in": "path", "name": "label", "required": true } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "label", "version", "trafficSplit", "controlLabel", "updatedAt", "updatedBy" ], "properties": { "label": { "type": "string" }, "version": { "type": "string" }, "trafficSplit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "controlLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "type": "string" }, "updatedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "412": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } }, "delete": { "operationId": "deleteTemplateLabel", "summary": "Delete a label (admin-only)", "tags": [ "Templates" ], "description": "Removes the label pointer. Idempotent — succeeds silently on unknown labels as long as the template exists. Admin scope required.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "key", "required": true }, { "schema": { "minLength": 1, "maxLength": 64, "type": "string" }, "in": "path", "name": "label", "required": true } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "204": { "description": "Default Response" }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } } }, "/templates/": { "get": { "operationId": "listTemplates", "summary": "List all templates (paginated)", "tags": [ "Templates" ], "description": "Returns a paginated list of templates. Use ?expand=versions,labels,lastRenders to include nested relations. When expand is present, limit is capped at 100.", "parameters": [ { "schema": { "minimum": 1, "maximum": 1000, "default": 50, "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of items to return (1-1000, default 50)" }, { "schema": { "minimum": 0, "default": 0, "type": "integer" }, "in": "query", "name": "offset", "required": false, "description": "Number of items to skip" }, { "schema": { "type": "string" }, "in": "query", "name": "expand", "required": false, "description": "Comma-separated list of relations to include: versions, labels, lastRenders. When present, list limit is capped at 100." } ], "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "200": { "description": "Default Response", "headers": { "type": { "schema": { "0": "o", "1": "b", "2": "j", "3": "e", "4": "c", "5": "t" } }, "required": { "schema": { "0": "X-Request-ID" } }, "properties": { "schema": { "X-Request-ID": { "description": "Server-generated UUID for correlating this response with structured log entries (reqId field).", "type": "string" } } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "total", "limit", "offset" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "key", "name", "currentVersion", "description" ], "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "currentVersion": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "versions": { "type": "array", "items": { "type": "object", "required": [ "version", "createdAt", "createdBy" ], "properties": { "version": { "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp", "type": "string" }, "createdBy": { "description": "Actor identity (user id) who created this version, or null if unknown.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "labels": { "type": "array", "items": { "type": "object", "required": [ "label", "version", "trafficSplit", "controlLabel", "updatedAt", "updatedBy" ], "properties": { "label": { "type": "string" }, "version": { "type": "string" }, "trafficSplit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "controlLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "type": "string" }, "updatedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "lastRenders": { "type": "object", "required": [ "lastRenderedAt", "renderCount24h" ], "properties": { "lastRenderedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "renderCount24h": { "type": "integer" } } } } } }, "total": { "minimum": 0, "type": "integer" }, "limit": { "minimum": 1, "type": "integer" }, "offset": { "minimum": 0, "type": "integer" } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } }, "post": { "operationId": "createTemplate", "summary": "Create a new template", "tags": [ "Templates" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "properties": { "key": { "description": "Template identifier, e.g. \"invoice-v2\"", "type": "string" }, "version": { "description": "Semantic version, e.g. \"1.0.0\"", "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inputSchema": { "description": "JSON Schema object describing the expected data payload" }, "fieldMappings": { "description": "Optional field-path alias map" }, "renderConfig": { "description": "Paper size, orientation, margin, fonts, etc." }, "document": { "description": "Root document node tree. Full structure validated by TemplateDefinitionSchema (Zod) — see validation/template-definition.schema.ts." } } } } } }, "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "key", "name", "currentVersion", "description" ], "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "currentVersion": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } } }, "/templates/{key}": { "get": { "operationId": "getTemplate", "summary": "Get a template with its current definition", "tags": [ "Templates" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "expand", "required": false, "description": "Comma-separated list of relations to include: versions, labels, lastRenders. When present, list limit is capped at 100." }, { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true } ], "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "key", "name", "currentVersion", "description", "definition" ], "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "currentVersion": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "definition": {}, "versions": { "type": "array", "items": { "type": "object", "required": [ "version", "createdAt", "createdBy" ], "properties": { "version": { "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp", "type": "string" }, "createdBy": { "description": "Actor identity (user id) who created this version, or null if unknown.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "labels": { "type": "array", "items": { "type": "object", "required": [ "label", "version", "trafficSplit", "controlLabel", "updatedAt", "updatedBy" ], "properties": { "label": { "type": "string" }, "version": { "type": "string" }, "trafficSplit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "controlLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "type": "string" }, "updatedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "lastRenders": { "type": "object", "required": [ "lastRenderedAt", "renderCount24h" ], "properties": { "lastRenderedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "renderCount24h": { "type": "integer" } } } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } }, "put": { "operationId": "updateTemplate", "summary": "Update a template definition (requires If-Match header; auto-bumps version)", "tags": [ "Templates" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "properties": { "key": { "description": "Template identifier, e.g. \"invoice-v2\"", "type": "string" }, "version": { "description": "Semantic version, e.g. \"1.0.0\"", "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inputSchema": { "description": "JSON Schema object describing the expected data payload" }, "fieldMappings": { "description": "Optional field-path alias map" }, "renderConfig": { "description": "Paper size, orientation, margin, fonts, etc." }, "document": { "description": "Root document node tree. Full structure validated by TemplateDefinitionSchema (Zod) — see validation/template-definition.schema.ts." } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "if-match", "required": false, "description": "Current version ETag, e.g. \"1.0.3\"" } ], "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "key", "name", "currentVersion", "description" ], "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "currentVersion": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "412": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "428": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } }, "delete": { "operationId": "deleteTemplate", "summary": "Soft-delete a template (admin only; requires If-Match header)", "tags": [ "Templates" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "if-match", "required": false, "description": "Current version ETag, e.g. \"1.0.3\"" } ], "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "204": { "description": "Template deleted", "content": { "application/json": { "schema": { "description": "Template deleted" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "412": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "428": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } } }, "/templates/{key}/schema": { "get": { "operationId": "getTemplateSchema", "summary": "Get the JSON Schema input definition for a template", "tags": [ "Templates" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true } ], "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "200": { "description": "JSON Schema object describing the expected data payload", "content": { "application/json": { "schema": { "description": "JSON Schema object describing the expected data payload", "type": "object", "additionalProperties": {} } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } } }, "/templates/{key}/form-metadata": { "get": { "operationId": "getTemplateFormMetadata", "summary": "Get form-rendering metadata for a template", "tags": [ "Templates" ], "description": "Returns { key, version, title?, description?, inputSchema, hasFieldMappings } for the given template. Used by the 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.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "version", "required": false, "description": "Exact version to pin; mutually exclusive with label" }, { "schema": { "minLength": 1, "maxLength": 64, "type": "string" }, "in": "query", "name": "label", "required": false, "description": "Label name to resolve; mutually exclusive with version" }, { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true } ], "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "key", "version", "inputSchema", "hasFieldMappings" ], "properties": { "key": { "type": "string" }, "version": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "inputSchema": { "type": "object", "additionalProperties": {} }, "hasFieldMappings": { "type": "boolean" } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } } }, "/templates/{key}/sample": { "get": { "operationId": "getTemplateSample", "summary": "Get sample preview data for a template", "tags": [ "Templates" ], "description": "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.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "version", "required": false, "description": "Target template version. Defaults to currentVersion." }, { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true } ], "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "200": { "description": "Sample data object matching the template's inputSchema.", "content": { "application/json": { "schema": { "description": "Sample data object matching the template's inputSchema.", "type": "object", "additionalProperties": {} } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } }, "put": { "operationId": "putTemplateSample", "summary": "Persist sample preview data against the template's current version", "tags": [ "Templates" ], "description": "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`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Preview data payload. Validated against the template's current inputSchema by the server; rejected with 422 on AJV failure.", "type": "object", "additionalProperties": {} } } }, "description": "Preview data payload. Validated against the template's current inputSchema by the server; rejected with 422 on AJV failure." }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true } ], "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "version", "updatedAt" ], "properties": { "version": { "description": "Template version the sample was persisted against (currentVersion at write time).", "type": "string" }, "updatedAt": { "format": "date-time", "description": "Server-assigned last-modified timestamp (ISO 8601).", "type": "string" } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "delete": { "operationId": "deleteTemplateSample", "summary": "Delete stored sample data for a template version", "tags": [ "Templates" ], "description": "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.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "version", "required": false, "description": "Target template version. Defaults to currentVersion." }, { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "204": { "description": "Default Response" }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } } }, "/templates/{key}/validate": { "post": { "operationId": "validateTemplateData", "summary": "Validate a data payload against a template's input schema", "tags": [ "Templates" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": true, "description": "Arbitrary data object to validate against the template's input schema", "type": "object", "properties": {} } } }, "description": "Arbitrary data object to validate against the template's input schema" }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true } ], "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "valid", "issues" ], "properties": { "valid": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "path": { "type": "string" }, "code": { "anyOf": [ { "type": "string", "enum": [ "INVALID_TEMPLATE" ] }, { "type": "string", "enum": [ "asset_blocked" ] }, { "type": "string", "enum": [ "validation_failed" ] }, { "type": "string", "enum": [ "template_expression_error" ] }, { "type": "string", "enum": [ "data_source_error" ] } ] } } } } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } } }, "/templates/generate": { "post": { "operationId": "generateTemplate", "summary": "Generate a draft template from a natural-language prompt (AI)", "tags": [ "Templates" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "minLength": 10, "maxLength": 4000, "description": "Natural-language description of the template to generate. Keep under 4000 chars; the server truncates longer bodies with 400.", "type": "string" }, "model": { "maxLength": 80, "description": "Override the Anthropic model identifier. Defaults to the server-configured ANTHROPIC_MODEL (claude-opus-4-7).", "type": "string" }, "maxAttempts": { "minimum": 1, "maximum": 3, "default": 3, "description": "Total model calls including repair rounds (1 = no repair; 3 = up to 2 repairs). The repair loop feeds validation issues back to the model.", "type": "integer" } } } } } }, "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "template", "meta" ], "properties": { "template": { "additionalProperties": true, "type": "object", "properties": { "key": { "description": "Template identifier, e.g. \"invoice-v2\"", "type": "string" }, "version": { "description": "Semantic version, e.g. \"1.0.0\"", "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inputSchema": { "description": "JSON Schema object describing the expected data payload" }, "fieldMappings": { "description": "Optional field-path alias map" }, "renderConfig": { "description": "Paper size, orientation, margin, fonts, etc." }, "document": { "description": "Root document node tree. Full structure validated by TemplateDefinitionSchema (Zod) — see validation/template-definition.schema.ts." } } }, "meta": { "type": "object", "required": [ "attempts", "model" ], "properties": { "attempts": { "minimum": 1, "maximum": 3, "description": "Number of model calls the generator used.", "type": "integer" }, "model": { "description": "Resolved Anthropic model identifier.", "type": "string" } } }, "sampleData": { "description": "Preview data matching the template's inputSchema. Produced by the model alongside the template when possible; otherwise synthesised server-side by walking the schema. Absent if both paths fail. Clients should handle absence by falling back to an empty preview-data store.", "type": "object", "additionalProperties": {} } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } } }, "/templates/{key}/versions": { "get": { "operationId": "listTemplateVersions", "summary": "List all saved versions for a template (newest first, paginated)", "tags": [ "Templates" ], "parameters": [ { "schema": { "minimum": 1, "maximum": 1000, "default": 50, "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of items to return (1-1000, default 50)" }, { "schema": { "minimum": 0, "default": 0, "type": "integer" }, "in": "query", "name": "offset", "required": false, "description": "Number of items to skip" }, { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true } ], "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "200": { "description": "Default Response", "headers": { "type": { "schema": { "0": "o", "1": "b", "2": "j", "3": "e", "4": "c", "5": "t" } }, "required": { "schema": { "0": "X-Request-ID" } }, "properties": { "schema": { "X-Request-ID": { "description": "Server-generated UUID for correlating this response with structured log entries (reqId field).", "type": "string" } } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "total", "limit", "offset" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "version", "createdAt", "createdBy" ], "properties": { "version": { "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp", "type": "string" }, "createdBy": { "description": "Actor identity (user id) who created this version, or null if unknown.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "total": { "minimum": 0, "type": "integer" }, "limit": { "minimum": 1, "type": "integer" }, "offset": { "minimum": 0, "type": "integer" } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } } }, "/templates/{key}/versions/{version}": { "get": { "operationId": "getTemplateVersion", "summary": "Get a template's definition at a specific version", "tags": [ "Templates" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "version", "required": true } ], "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "key", "name", "currentVersion", "description", "definition" ], "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "currentVersion": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "definition": { "description": "TemplateDefinition object. See validation/template-definition.schema.ts for the full Zod schema." } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } } }, "/templates/{key}/diff": { "post": { "operationId": "diffTemplateVersions", "summary": "Diff two stored versions of a template", "tags": [ "Templates" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "beforeVersion", "afterVersion" ], "properties": { "beforeVersion": { "description": "Stored template version on the left-hand side of the diff.", "type": "string" }, "afterVersion": { "description": "Stored template version on the right-hand side of the diff.", "type": "string" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true } ], "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "templateKey", "metadataChanges", "renderConfigChanges", "inputSchemaChanges", "fieldMappingChanges", "documentRootChanges", "documentChanges", "diagnostics", "summary" ], "properties": { "templateKey": { "type": "string" }, "metadataChanges": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string" }, "before": {}, "after": {} } } }, "renderConfigChanges": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string" }, "before": {}, "after": {} } } }, "inputSchemaChanges": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string" }, "before": {}, "after": {} } } }, "fieldMappingChanges": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string" }, "before": {}, "after": {} } } }, "documentRootChanges": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string" }, "before": {}, "after": {} } } }, "documentChanges": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "nodeId", "nodeType", "kind" ], "properties": { "nodeId": { "type": "string" }, "nodeType": { "type": "string" }, "kind": { "anyOf": [ { "type": "string", "enum": [ "added" ] }, { "type": "string", "enum": [ "removed" ] }, { "type": "string", "enum": [ "modified" ] }, { "type": "string", "enum": [ "moved" ] } ] }, "fromPath": { "type": "string" }, "toPath": { "type": "string" }, "properties": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string" }, "before": {}, "after": {} } } } } } }, "diagnostics": { "type": "array", "items": { "type": "object", "required": [ "level", "message" ], "properties": { "level": { "type": "string", "enum": [ "warn" ] }, "message": { "type": "string" } } } }, "summary": { "type": "object", "required": [ "nodesAdded", "nodesRemoved", "nodesModified", "nodesMoved", "propertiesChanged" ], "properties": { "nodesAdded": { "minimum": 0, "type": "integer" }, "nodesRemoved": { "minimum": 0, "type": "integer" }, "nodesModified": { "minimum": 0, "type": "integer" }, "nodesMoved": { "minimum": 0, "type": "integer" }, "propertiesChanged": { "minimum": 0, "type": "integer" } } } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } } }, "/templates/{key}/versions/{version}/restore": { "post": { "operationId": "restoreTemplateVersion", "summary": "Promote a historical version to current (admin only; requires If-Match header)", "tags": [ "Templates" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "version", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "if-match", "required": false, "description": "Current version ETag, e.g. \"1.0.3\"" } ], "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "key", "name", "currentVersion", "description" ], "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "currentVersion": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "412": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "428": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } } }, "/nodes/rewrite": { "post": { "operationId": "rewriteNode", "summary": "AI-rewrite the content of a single text or heading node (SSE stream)", "tags": [ "Nodes" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "nodeType", "content", "action" ], "properties": { "nodeType": { "description": "Type of the node being rewritten (v1: text or heading).", "anyOf": [ { "type": "string", "enum": [ "text" ] }, { "type": "string", "enum": [ "heading" ] } ] }, "content": { "minLength": 1, "maxLength": 8000, "description": "Current string content of the node.", "type": "string" }, "action": { "description": "Rewrite action preset. Use \"freeform\" with a custom instruction.", "anyOf": [ { "type": "string", "enum": [ "shorten" ] }, { "type": "string", "enum": [ "lengthen" ] }, { "type": "string", "enum": [ "formal" ] }, { "type": "string", "enum": [ "casual" ] }, { "type": "string", "enum": [ "translate" ] }, { "type": "string", "enum": [ "freeform" ] } ] }, "instruction": { "maxLength": 500, "type": "string" }, "locale": { "maxLength": 32, "type": "string" }, "model": { "maxLength": 80, "type": "string" } } } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/nodes/rewrite/outcome": { "post": { "operationId": "recordRewriteOutcome", "summary": "Record the user's apply/dismiss choice for an AI node rewrite", "tags": [ "Nodes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "requestId", "applied" ], "properties": { "requestId": { "minLength": 1, "maxLength": 128, "type": "string" }, "applied": { "type": "boolean" } } } } } }, "responses": { "204": { "description": "Default Response" } } } }, "/batch/": { "post": { "operationId": "submitReadBatch", "summary": "Execute multiple GET requests in a single HTTP call", "tags": [ "Batch" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "minItems": 1, "maxItems": 20, "description": "Array of GET sub-requests (1-20)", "type": "array", "items": { "type": "object", "required": [ "method", "path" ], "properties": { "method": { "type": "string", "enum": [ "GET" ] }, "path": { "minLength": 1, "description": "Absolute API path, e.g. /templates/my-key", "type": "string" } } } } } } } } }, "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "status", "body" ], "properties": { "status": { "type": "integer" }, "body": {} } } } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } } }, "/render/": { "post": { "operationId": "renderPdf", "summary": "Render a template to PDF", "tags": [ "Render" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "template", "data" ], "properties": { "template": { "description": "Template key, e.g. \"loan-approval-letter\"", "type": "string" }, "version": { "description": "Exact saved version string to render, e.g. \"1.0.2\". Omit to render the latest version. Mutually exclusive with `label`.", "type": "string" }, "label": { "minLength": 1, "maxLength": 64, "description": "Label name to resolve (B.1), e.g. \"prod\" or \"staging\". Mutually exclusive with `version`. When both are omitted the current version is used.", "type": "string" }, "bucketKey": { "minLength": 1, "maxLength": 256, "description": "Stable bucket key for B.3 A/B variant resolution. Precedence: body.bucketKey > x-pulp-engine-bucket header > deterministic hash of (template + data). Ignored unless the resolved label is a variant.", "type": "string" }, "data": { "type": "object", "additionalProperties": {} }, "options": { "type": "object", "properties": { "paperSize": { "anyOf": [ { "type": "string", "enum": [ "A4" ] }, { "type": "string", "enum": [ "A3" ] }, { "type": "string", "enum": [ "Letter" ] }, { "type": "string", "enum": [ "Legal" ] }, { "type": "string", "enum": [ "Tabloid" ] } ] }, "orientation": { "anyOf": [ { "type": "string", "enum": [ "portrait" ] }, { "type": "string", "enum": [ "landscape" ] } ] } } }, "dryRun": { "description": "When true, validate input data and exercise all template expressions via a trial HTML render, then return structured JSON results without producing any binary output. Skips Chromium/DOCX/PPTX entirely. Useful for CI/CD pre-flight checks. Response is application/json regardless of the route's normal content type. Default: false.", "default": false, "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "boolean" }, "in": "query", "name": "stream", "required": false, "description": "Streaming control. Unset (default) or true → chunked stream when no post-render hooks are registered. false → force buffered response. true + post-render hooks → 400 STREAM_INCOMPATIBLE_HOOK." } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "PDF document stream — or, when dryRun=true, a JSON DryRunResponse", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "type": "object", "required": [ "dryRun", "valid", "validation", "expressions", "fieldMappingsApplied", "dataSourcesResolved" ], "properties": { "dryRun": { "type": "boolean", "enum": [ true ] }, "valid": { "description": "True when both validation and expression evaluation succeeded.", "type": "boolean" }, "validation": { "type": "object", "required": [ "valid", "errors" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } }, "expressions": { "type": "object", "required": [ "valid", "errors" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "location": { "type": "object", "required": [ "nodeId", "nodeType", "nodePath" ], "properties": { "nodeId": { "description": "ID of the failing node in the template AST.", "type": "string" }, "nodeType": { "description": "Type of the failing node (e.g. \"text\", \"table\").", "type": "string" }, "nodePath": { "description": "Human-readable breadcrumb through the template AST, e.g. \"Page 1 > Section 'Header' > Text block 3\". Stops at templateRef boundaries.", "type": "string" }, "line": { "minimum": 1, "description": "Line number within the expression (1-based), when extractable.", "type": "integer" }, "column": { "minimum": 1, "description": "Column number within the expression (1-based), when extractable.", "type": "integer" } } }, "suggestion": { "type": "object", "required": [ "variable", "suggestions" ], "properties": { "variable": { "description": "Undefined variable name from the error message.", "type": "string" }, "suggestions": { "description": "Up to 3 close matches from the available data context, sorted by Levenshtein distance.", "type": "array", "items": { "type": "string" } } } } } } } } }, "fieldMappingsApplied": { "minimum": 0, "description": "Number of field mappings applied during data adaptation.", "type": "integer" }, "dataSourcesResolved": { "minimum": 0, "description": "Number of templateRef data sources successfully resolved.", "type": "integer" } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "RenderError" ] }, "code": { "anyOf": [ { "type": "string", "enum": [ "template_expression_error" ] }, { "type": "string", "enum": [ "validation_failed" ] }, { "type": "string", "enum": [ "render_timeout" ] }, { "type": "string", "enum": [ "engine_crash" ] }, { "type": "string", "enum": [ "asset_blocked" ] }, { "type": "string", "enum": [ "data_source_error" ] }, { "type": "string", "enum": [ "no_rendered_tables" ] }, { "type": "string", "enum": [ "ambiguous_table" ] }, { "type": "string", "enum": [ "invalid_pdf" ] }, { "type": "string", "enum": [ "pdf_too_large" ] }, { "type": "string", "enum": [ "too_many_pages" ] }, { "type": "string", "enum": [ "invalid_page_range" ] }, { "type": "string", "enum": [ "unsupported_image" ] }, { "type": "string", "enum": [ "PPTX_PIVOT_UNSUPPORTED" ] }, { "type": "string", "enum": [ "PPTX_PAGEBREAK_IN_COLUMNS" ] }, { "type": "string", "enum": [ "stream_incompatible_hook" ] } ] }, "message": { "type": "string" }, "location": { "type": "object", "required": [ "nodeId", "nodeType", "nodePath" ], "properties": { "nodeId": { "description": "ID of the failing node in the template AST.", "type": "string" }, "nodeType": { "description": "Type of the failing node (e.g. \"text\", \"table\").", "type": "string" }, "nodePath": { "description": "Human-readable breadcrumb through the template AST, e.g. \"Page 1 > Section 'Header' > Text block 3\". Stops at templateRef boundaries.", "type": "string" }, "line": { "minimum": 1, "description": "Line number within the expression (1-based), when extractable.", "type": "integer" }, "column": { "minimum": 1, "description": "Column number within the expression (1-based), when extractable.", "type": "integer" } } }, "suggestion": { "type": "object", "required": [ "variable", "suggestions" ], "properties": { "variable": { "description": "Undefined variable name from the error message.", "type": "string" }, "suggestions": { "description": "Up to 3 close matches from the available data context, sorted by Levenshtein distance.", "type": "array", "items": { "type": "string" } } } } } }, { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "RenderError" ] }, "code": { "anyOf": [ { "type": "string", "enum": [ "template_expression_error" ] }, { "type": "string", "enum": [ "validation_failed" ] }, { "type": "string", "enum": [ "render_timeout" ] }, { "type": "string", "enum": [ "engine_crash" ] }, { "type": "string", "enum": [ "asset_blocked" ] }, { "type": "string", "enum": [ "data_source_error" ] }, { "type": "string", "enum": [ "no_rendered_tables" ] }, { "type": "string", "enum": [ "ambiguous_table" ] }, { "type": "string", "enum": [ "invalid_pdf" ] }, { "type": "string", "enum": [ "pdf_too_large" ] }, { "type": "string", "enum": [ "too_many_pages" ] }, { "type": "string", "enum": [ "invalid_page_range" ] }, { "type": "string", "enum": [ "unsupported_image" ] }, { "type": "string", "enum": [ "PPTX_PIVOT_UNSUPPORTED" ] }, { "type": "string", "enum": [ "PPTX_PAGEBREAK_IN_COLUMNS" ] }, { "type": "string", "enum": [ "stream_incompatible_hook" ] } ] }, "message": { "type": "string" }, "location": { "type": "object", "required": [ "nodeId", "nodeType", "nodePath" ], "properties": { "nodeId": { "description": "ID of the failing node in the template AST.", "type": "string" }, "nodeType": { "description": "Type of the failing node (e.g. \"text\", \"table\").", "type": "string" }, "nodePath": { "description": "Human-readable breadcrumb through the template AST, e.g. \"Page 1 > Section 'Header' > Text block 3\". Stops at templateRef boundaries.", "type": "string" }, "line": { "minimum": 1, "description": "Line number within the expression (1-based), when extractable.", "type": "integer" }, "column": { "minimum": 1, "description": "Column number within the expression (1-based), when extractable.", "type": "integer" } } }, "suggestion": { "type": "object", "required": [ "variable", "suggestions" ], "properties": { "variable": { "description": "Undefined variable name from the error message.", "type": "string" }, "suggestions": { "description": "Up to 3 close matches from the available data context, sorted by Levenshtein distance.", "type": "array", "items": { "type": "string" } } } } } }, { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: quota_exhausted (sandbox lifetime quota).", "type": "string" } } } } } } } } }, "/render/html": { "post": { "operationId": "renderHtml", "summary": "Render a template to HTML", "tags": [ "Render" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "template", "data" ], "properties": { "template": { "description": "Template key, e.g. \"loan-approval-letter\"", "type": "string" }, "version": { "description": "Exact saved version string to render, e.g. \"1.0.2\". Omit to render the latest version. Mutually exclusive with `label`.", "type": "string" }, "label": { "minLength": 1, "maxLength": 64, "description": "Label name to resolve (B.1), e.g. \"prod\" or \"staging\". Mutually exclusive with `version`. When both are omitted the current version is used.", "type": "string" }, "bucketKey": { "minLength": 1, "maxLength": 256, "description": "Stable bucket key for B.3 A/B variant resolution. Precedence: body.bucketKey > x-pulp-engine-bucket header > deterministic hash of (template + data). Ignored unless the resolved label is a variant.", "type": "string" }, "data": { "type": "object", "additionalProperties": {} }, "options": { "type": "object", "properties": { "paperSize": { "anyOf": [ { "type": "string", "enum": [ "A4" ] }, { "type": "string", "enum": [ "A3" ] }, { "type": "string", "enum": [ "Letter" ] }, { "type": "string", "enum": [ "Legal" ] }, { "type": "string", "enum": [ "Tabloid" ] } ] }, "orientation": { "anyOf": [ { "type": "string", "enum": [ "portrait" ] }, { "type": "string", "enum": [ "landscape" ] } ] } } }, "dryRun": { "description": "When true, validate input data and exercise all template expressions via a trial HTML render, then return structured JSON results without producing any binary output. Skips Chromium/DOCX/PPTX entirely. Useful for CI/CD pre-flight checks. Response is application/json regardless of the route's normal content type. Default: false.", "default": false, "type": "boolean" } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Rendered HTML document — or, when dryRun=true, a JSON DryRunResponse", "content": { "text/html": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "object", "required": [ "dryRun", "valid", "validation", "expressions", "fieldMappingsApplied", "dataSourcesResolved" ], "properties": { "dryRun": { "type": "boolean", "enum": [ true ] }, "valid": { "description": "True when both validation and expression evaluation succeeded.", "type": "boolean" }, "validation": { "type": "object", "required": [ "valid", "errors" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } }, "expressions": { "type": "object", "required": [ "valid", "errors" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "location": { "type": "object", "required": [ "nodeId", "nodeType", "nodePath" ], "properties": { "nodeId": { "description": "ID of the failing node in the template AST.", "type": "string" }, "nodeType": { "description": "Type of the failing node (e.g. \"text\", \"table\").", "type": "string" }, "nodePath": { "description": "Human-readable breadcrumb through the template AST, e.g. \"Page 1 > Section 'Header' > Text block 3\". Stops at templateRef boundaries.", "type": "string" }, "line": { "minimum": 1, "description": "Line number within the expression (1-based), when extractable.", "type": "integer" }, "column": { "minimum": 1, "description": "Column number within the expression (1-based), when extractable.", "type": "integer" } } }, "suggestion": { "type": "object", "required": [ "variable", "suggestions" ], "properties": { "variable": { "description": "Undefined variable name from the error message.", "type": "string" }, "suggestions": { "description": "Up to 3 close matches from the available data context, sorted by Levenshtein distance.", "type": "array", "items": { "type": "string" } } } } } } } } }, "fieldMappingsApplied": { "minimum": 0, "description": "Number of field mappings applied during data adaptation.", "type": "integer" }, "dataSourcesResolved": { "minimum": 0, "description": "Number of templateRef data sources successfully resolved.", "type": "integer" } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "RenderError" ] }, "code": { "anyOf": [ { "type": "string", "enum": [ "template_expression_error" ] }, { "type": "string", "enum": [ "validation_failed" ] }, { "type": "string", "enum": [ "render_timeout" ] }, { "type": "string", "enum": [ "engine_crash" ] }, { "type": "string", "enum": [ "asset_blocked" ] }, { "type": "string", "enum": [ "data_source_error" ] }, { "type": "string", "enum": [ "no_rendered_tables" ] }, { "type": "string", "enum": [ "ambiguous_table" ] }, { "type": "string", "enum": [ "invalid_pdf" ] }, { "type": "string", "enum": [ "pdf_too_large" ] }, { "type": "string", "enum": [ "too_many_pages" ] }, { "type": "string", "enum": [ "invalid_page_range" ] }, { "type": "string", "enum": [ "unsupported_image" ] }, { "type": "string", "enum": [ "PPTX_PIVOT_UNSUPPORTED" ] }, { "type": "string", "enum": [ "PPTX_PAGEBREAK_IN_COLUMNS" ] }, { "type": "string", "enum": [ "stream_incompatible_hook" ] } ] }, "message": { "type": "string" }, "location": { "type": "object", "required": [ "nodeId", "nodeType", "nodePath" ], "properties": { "nodeId": { "description": "ID of the failing node in the template AST.", "type": "string" }, "nodeType": { "description": "Type of the failing node (e.g. \"text\", \"table\").", "type": "string" }, "nodePath": { "description": "Human-readable breadcrumb through the template AST, e.g. \"Page 1 > Section 'Header' > Text block 3\". Stops at templateRef boundaries.", "type": "string" }, "line": { "minimum": 1, "description": "Line number within the expression (1-based), when extractable.", "type": "integer" }, "column": { "minimum": 1, "description": "Column number within the expression (1-based), when extractable.", "type": "integer" } } }, "suggestion": { "type": "object", "required": [ "variable", "suggestions" ], "properties": { "variable": { "description": "Undefined variable name from the error message.", "type": "string" }, "suggestions": { "description": "Up to 3 close matches from the available data context, sorted by Levenshtein distance.", "type": "array", "items": { "type": "string" } } } } } }, { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: quota_exhausted (sandbox lifetime quota).", "type": "string" } } } } } } } } }, "/render/csv": { "post": { "operationId": "renderCsv", "summary": "Export a table from a template as CSV", "tags": [ "Render" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "template", "data" ], "properties": { "template": { "description": "Template key, e.g. \"loan-approval-letter\"", "type": "string" }, "version": { "description": "Exact saved version string to render, e.g. \"1.0.2\". Omit to render the latest version. Mutually exclusive with `label`.", "type": "string" }, "label": { "minLength": 1, "maxLength": 64, "description": "Label name to resolve (B.1), e.g. \"prod\" or \"staging\". Mutually exclusive with `version`.", "type": "string" }, "bucketKey": { "minLength": 1, "maxLength": 256, "description": "Stable bucket key for B.3 A/B variant resolution.", "type": "string" }, "data": { "type": "object", "additionalProperties": {} }, "tableId": { "description": "Node ID of the table to export. Required when the template contains multiple tables.", "type": "string" }, "dryRun": { "description": "When true, validate and exercise all template expressions, then return structured JSON results without producing CSV output. Default: false.", "default": false, "type": "boolean" } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "CSV data — or, when dryRun=true, a JSON DryRunResponse", "content": { "text/csv": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "object", "required": [ "dryRun", "valid", "validation", "expressions", "fieldMappingsApplied", "dataSourcesResolved" ], "properties": { "dryRun": { "type": "boolean", "enum": [ true ] }, "valid": { "description": "True when both validation and expression evaluation succeeded.", "type": "boolean" }, "validation": { "type": "object", "required": [ "valid", "errors" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } }, "expressions": { "type": "object", "required": [ "valid", "errors" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "location": { "type": "object", "required": [ "nodeId", "nodeType", "nodePath" ], "properties": { "nodeId": { "description": "ID of the failing node in the template AST.", "type": "string" }, "nodeType": { "description": "Type of the failing node (e.g. \"text\", \"table\").", "type": "string" }, "nodePath": { "description": "Human-readable breadcrumb through the template AST, e.g. \"Page 1 > Section 'Header' > Text block 3\". Stops at templateRef boundaries.", "type": "string" }, "line": { "minimum": 1, "description": "Line number within the expression (1-based), when extractable.", "type": "integer" }, "column": { "minimum": 1, "description": "Column number within the expression (1-based), when extractable.", "type": "integer" } } }, "suggestion": { "type": "object", "required": [ "variable", "suggestions" ], "properties": { "variable": { "description": "Undefined variable name from the error message.", "type": "string" }, "suggestions": { "description": "Up to 3 close matches from the available data context, sorted by Levenshtein distance.", "type": "array", "items": { "type": "string" } } } } } } } } }, "fieldMappingsApplied": { "minimum": 0, "description": "Number of field mappings applied during data adaptation.", "type": "integer" }, "dataSourcesResolved": { "minimum": 0, "description": "Number of templateRef data sources successfully resolved.", "type": "integer" } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "RenderError" ] }, "code": { "anyOf": [ { "type": "string", "enum": [ "template_expression_error" ] }, { "type": "string", "enum": [ "validation_failed" ] }, { "type": "string", "enum": [ "render_timeout" ] }, { "type": "string", "enum": [ "engine_crash" ] }, { "type": "string", "enum": [ "asset_blocked" ] }, { "type": "string", "enum": [ "data_source_error" ] }, { "type": "string", "enum": [ "no_rendered_tables" ] }, { "type": "string", "enum": [ "ambiguous_table" ] }, { "type": "string", "enum": [ "invalid_pdf" ] }, { "type": "string", "enum": [ "pdf_too_large" ] }, { "type": "string", "enum": [ "too_many_pages" ] }, { "type": "string", "enum": [ "invalid_page_range" ] }, { "type": "string", "enum": [ "unsupported_image" ] }, { "type": "string", "enum": [ "PPTX_PIVOT_UNSUPPORTED" ] }, { "type": "string", "enum": [ "PPTX_PAGEBREAK_IN_COLUMNS" ] }, { "type": "string", "enum": [ "stream_incompatible_hook" ] } ] }, "message": { "type": "string" }, "location": { "type": "object", "required": [ "nodeId", "nodeType", "nodePath" ], "properties": { "nodeId": { "description": "ID of the failing node in the template AST.", "type": "string" }, "nodeType": { "description": "Type of the failing node (e.g. \"text\", \"table\").", "type": "string" }, "nodePath": { "description": "Human-readable breadcrumb through the template AST, e.g. \"Page 1 > Section 'Header' > Text block 3\". Stops at templateRef boundaries.", "type": "string" }, "line": { "minimum": 1, "description": "Line number within the expression (1-based), when extractable.", "type": "integer" }, "column": { "minimum": 1, "description": "Column number within the expression (1-based), when extractable.", "type": "integer" } } }, "suggestion": { "type": "object", "required": [ "variable", "suggestions" ], "properties": { "variable": { "description": "Undefined variable name from the error message.", "type": "string" }, "suggestions": { "description": "Up to 3 close matches from the available data context, sorted by Levenshtein distance.", "type": "array", "items": { "type": "string" } } } } } }, { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: quota_exhausted (sandbox lifetime quota).", "type": "string" } } } } } } } } }, "/render/xlsx": { "post": { "operationId": "renderXlsx", "summary": "Export table data from a template as XLSX", "tags": [ "Render" ], "description": "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`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "template", "data" ], "properties": { "template": { "description": "Template key, e.g. \"loan-approval-letter\"", "type": "string" }, "version": { "description": "Exact saved version string to render, e.g. \"1.0.2\". Omit to render the latest version. Mutually exclusive with `label`.", "type": "string" }, "label": { "minLength": 1, "maxLength": 64, "description": "Label name to resolve (B.1), e.g. \"prod\" or \"staging\". Mutually exclusive with `version`.", "type": "string" }, "bucketKey": { "minLength": 1, "maxLength": 256, "description": "Stable bucket key for B.3 A/B variant resolution.", "type": "string" }, "data": { "type": "object", "additionalProperties": {} }, "tableId": { "description": "Node ID of the table to export. Required when the template contains multiple tables.", "type": "string" }, "dryRun": { "description": "When true, validate and exercise all template expressions, then return structured JSON results without producing CSV output. Default: false.", "default": false, "type": "boolean" } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "XLSX workbook — or, when dryRun=true, a JSON DryRunResponse", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "type": "object", "required": [ "dryRun", "valid", "validation", "expressions", "fieldMappingsApplied", "dataSourcesResolved" ], "properties": { "dryRun": { "type": "boolean", "enum": [ true ] }, "valid": { "description": "True when both validation and expression evaluation succeeded.", "type": "boolean" }, "validation": { "type": "object", "required": [ "valid", "errors" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } }, "expressions": { "type": "object", "required": [ "valid", "errors" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "location": { "type": "object", "required": [ "nodeId", "nodeType", "nodePath" ], "properties": { "nodeId": { "description": "ID of the failing node in the template AST.", "type": "string" }, "nodeType": { "description": "Type of the failing node (e.g. \"text\", \"table\").", "type": "string" }, "nodePath": { "description": "Human-readable breadcrumb through the template AST, e.g. \"Page 1 > Section 'Header' > Text block 3\". Stops at templateRef boundaries.", "type": "string" }, "line": { "minimum": 1, "description": "Line number within the expression (1-based), when extractable.", "type": "integer" }, "column": { "minimum": 1, "description": "Column number within the expression (1-based), when extractable.", "type": "integer" } } }, "suggestion": { "type": "object", "required": [ "variable", "suggestions" ], "properties": { "variable": { "description": "Undefined variable name from the error message.", "type": "string" }, "suggestions": { "description": "Up to 3 close matches from the available data context, sorted by Levenshtein distance.", "type": "array", "items": { "type": "string" } } } } } } } } }, "fieldMappingsApplied": { "minimum": 0, "description": "Number of field mappings applied during data adaptation.", "type": "integer" }, "dataSourcesResolved": { "minimum": 0, "description": "Number of templateRef data sources successfully resolved.", "type": "integer" } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "RenderError" ] }, "code": { "anyOf": [ { "type": "string", "enum": [ "template_expression_error" ] }, { "type": "string", "enum": [ "validation_failed" ] }, { "type": "string", "enum": [ "render_timeout" ] }, { "type": "string", "enum": [ "engine_crash" ] }, { "type": "string", "enum": [ "asset_blocked" ] }, { "type": "string", "enum": [ "data_source_error" ] }, { "type": "string", "enum": [ "no_rendered_tables" ] }, { "type": "string", "enum": [ "ambiguous_table" ] }, { "type": "string", "enum": [ "invalid_pdf" ] }, { "type": "string", "enum": [ "pdf_too_large" ] }, { "type": "string", "enum": [ "too_many_pages" ] }, { "type": "string", "enum": [ "invalid_page_range" ] }, { "type": "string", "enum": [ "unsupported_image" ] }, { "type": "string", "enum": [ "PPTX_PIVOT_UNSUPPORTED" ] }, { "type": "string", "enum": [ "PPTX_PAGEBREAK_IN_COLUMNS" ] }, { "type": "string", "enum": [ "stream_incompatible_hook" ] } ] }, "message": { "type": "string" }, "location": { "type": "object", "required": [ "nodeId", "nodeType", "nodePath" ], "properties": { "nodeId": { "description": "ID of the failing node in the template AST.", "type": "string" }, "nodeType": { "description": "Type of the failing node (e.g. \"text\", \"table\").", "type": "string" }, "nodePath": { "description": "Human-readable breadcrumb through the template AST, e.g. \"Page 1 > Section 'Header' > Text block 3\". Stops at templateRef boundaries.", "type": "string" }, "line": { "minimum": 1, "description": "Line number within the expression (1-based), when extractable.", "type": "integer" }, "column": { "minimum": 1, "description": "Column number within the expression (1-based), when extractable.", "type": "integer" } } }, "suggestion": { "type": "object", "required": [ "variable", "suggestions" ], "properties": { "variable": { "description": "Undefined variable name from the error message.", "type": "string" }, "suggestions": { "description": "Up to 3 close matches from the available data context, sorted by Levenshtein distance.", "type": "array", "items": { "type": "string" } } } } } }, { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: quota_exhausted (sandbox lifetime quota).", "type": "string" } } } } } } } } }, "/render/docx": { "post": { "operationId": "renderDocx", "summary": "Render a template to DOCX", "tags": [ "Render" ], "description": "Renders a template to a Word document (.docx). The template AST is walked directly — no browser required.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "template", "data" ], "properties": { "template": { "description": "Template key, e.g. \"loan-approval-letter\"", "type": "string" }, "version": { "description": "Exact saved version string to render, e.g. \"1.0.2\". Omit to render the latest version. Mutually exclusive with `label`.", "type": "string" }, "label": { "minLength": 1, "maxLength": 64, "description": "Label name to resolve (B.1), e.g. \"prod\" or \"staging\". Mutually exclusive with `version`. When both are omitted the current version is used.", "type": "string" }, "bucketKey": { "minLength": 1, "maxLength": 256, "description": "Stable bucket key for B.3 A/B variant resolution. Precedence: body.bucketKey > x-pulp-engine-bucket header > deterministic hash of (template + data). Ignored unless the resolved label is a variant.", "type": "string" }, "data": { "type": "object", "additionalProperties": {} }, "options": { "type": "object", "properties": { "paperSize": { "anyOf": [ { "type": "string", "enum": [ "A4" ] }, { "type": "string", "enum": [ "A3" ] }, { "type": "string", "enum": [ "Letter" ] }, { "type": "string", "enum": [ "Legal" ] }, { "type": "string", "enum": [ "Tabloid" ] } ] }, "orientation": { "anyOf": [ { "type": "string", "enum": [ "portrait" ] }, { "type": "string", "enum": [ "landscape" ] } ] } } }, "dryRun": { "description": "When true, validate input data and exercise all template expressions via a trial HTML render, then return structured JSON results without producing any binary output. Skips Chromium/DOCX/PPTX entirely. Useful for CI/CD pre-flight checks. Response is application/json regardless of the route's normal content type. Default: false.", "default": false, "type": "boolean" } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "DOCX document — or, when dryRun=true, a JSON DryRunResponse", "content": { "application/vnd.openxmlformats-officedocument.wordprocessingml.document": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "type": "object", "required": [ "dryRun", "valid", "validation", "expressions", "fieldMappingsApplied", "dataSourcesResolved" ], "properties": { "dryRun": { "type": "boolean", "enum": [ true ] }, "valid": { "description": "True when both validation and expression evaluation succeeded.", "type": "boolean" }, "validation": { "type": "object", "required": [ "valid", "errors" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } }, "expressions": { "type": "object", "required": [ "valid", "errors" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "location": { "type": "object", "required": [ "nodeId", "nodeType", "nodePath" ], "properties": { "nodeId": { "description": "ID of the failing node in the template AST.", "type": "string" }, "nodeType": { "description": "Type of the failing node (e.g. \"text\", \"table\").", "type": "string" }, "nodePath": { "description": "Human-readable breadcrumb through the template AST, e.g. \"Page 1 > Section 'Header' > Text block 3\". Stops at templateRef boundaries.", "type": "string" }, "line": { "minimum": 1, "description": "Line number within the expression (1-based), when extractable.", "type": "integer" }, "column": { "minimum": 1, "description": "Column number within the expression (1-based), when extractable.", "type": "integer" } } }, "suggestion": { "type": "object", "required": [ "variable", "suggestions" ], "properties": { "variable": { "description": "Undefined variable name from the error message.", "type": "string" }, "suggestions": { "description": "Up to 3 close matches from the available data context, sorted by Levenshtein distance.", "type": "array", "items": { "type": "string" } } } } } } } } }, "fieldMappingsApplied": { "minimum": 0, "description": "Number of field mappings applied during data adaptation.", "type": "integer" }, "dataSourcesResolved": { "minimum": 0, "description": "Number of templateRef data sources successfully resolved.", "type": "integer" } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "RenderError" ] }, "code": { "anyOf": [ { "type": "string", "enum": [ "template_expression_error" ] }, { "type": "string", "enum": [ "validation_failed" ] }, { "type": "string", "enum": [ "render_timeout" ] }, { "type": "string", "enum": [ "engine_crash" ] }, { "type": "string", "enum": [ "asset_blocked" ] }, { "type": "string", "enum": [ "data_source_error" ] }, { "type": "string", "enum": [ "no_rendered_tables" ] }, { "type": "string", "enum": [ "ambiguous_table" ] }, { "type": "string", "enum": [ "invalid_pdf" ] }, { "type": "string", "enum": [ "pdf_too_large" ] }, { "type": "string", "enum": [ "too_many_pages" ] }, { "type": "string", "enum": [ "invalid_page_range" ] }, { "type": "string", "enum": [ "unsupported_image" ] }, { "type": "string", "enum": [ "PPTX_PIVOT_UNSUPPORTED" ] }, { "type": "string", "enum": [ "PPTX_PAGEBREAK_IN_COLUMNS" ] }, { "type": "string", "enum": [ "stream_incompatible_hook" ] } ] }, "message": { "type": "string" }, "location": { "type": "object", "required": [ "nodeId", "nodeType", "nodePath" ], "properties": { "nodeId": { "description": "ID of the failing node in the template AST.", "type": "string" }, "nodeType": { "description": "Type of the failing node (e.g. \"text\", \"table\").", "type": "string" }, "nodePath": { "description": "Human-readable breadcrumb through the template AST, e.g. \"Page 1 > Section 'Header' > Text block 3\". Stops at templateRef boundaries.", "type": "string" }, "line": { "minimum": 1, "description": "Line number within the expression (1-based), when extractable.", "type": "integer" }, "column": { "minimum": 1, "description": "Column number within the expression (1-based), when extractable.", "type": "integer" } } }, "suggestion": { "type": "object", "required": [ "variable", "suggestions" ], "properties": { "variable": { "description": "Undefined variable name from the error message.", "type": "string" }, "suggestions": { "description": "Up to 3 close matches from the available data context, sorted by Levenshtein distance.", "type": "array", "items": { "type": "string" } } } } } }, { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: quota_exhausted (sandbox lifetime quota).", "type": "string" } } } } } } } } }, "/render/pptx": { "post": { "operationId": "renderPptx", "summary": "Render a template to PPTX (beta)", "tags": [ "Render" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "template", "data" ], "properties": { "template": { "description": "Template key, e.g. \"loan-approval-letter\"", "type": "string" }, "version": { "description": "Exact saved version string to render, e.g. \"1.0.2\". Omit to render the latest version. Mutually exclusive with `label`.", "type": "string" }, "label": { "minLength": 1, "maxLength": 64, "description": "Label name to resolve (B.1), e.g. \"prod\" or \"staging\". Mutually exclusive with `version`. When both are omitted the current version is used.", "type": "string" }, "bucketKey": { "minLength": 1, "maxLength": 256, "description": "Stable bucket key for B.3 A/B variant resolution. Precedence: body.bucketKey > x-pulp-engine-bucket header > deterministic hash of (template + data). Ignored unless the resolved label is a variant.", "type": "string" }, "data": { "type": "object", "additionalProperties": {} }, "options": { "type": "object", "properties": { "paperSize": { "anyOf": [ { "type": "string", "enum": [ "A4" ] }, { "type": "string", "enum": [ "A3" ] }, { "type": "string", "enum": [ "Letter" ] }, { "type": "string", "enum": [ "Legal" ] }, { "type": "string", "enum": [ "Tabloid" ] } ] }, "orientation": { "anyOf": [ { "type": "string", "enum": [ "portrait" ] }, { "type": "string", "enum": [ "landscape" ] } ] } } }, "dryRun": { "description": "When true, validate input data and exercise all template expressions via a trial HTML render, then return structured JSON results without producing any binary output. Skips Chromium/DOCX/PPTX entirely. Useful for CI/CD pre-flight checks. Response is application/json regardless of the route's normal content type. Default: false.", "default": false, "type": "boolean" } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "PPTX presentation — or, when dryRun=true, a JSON DryRunResponse", "content": { "application/vnd.openxmlformats-officedocument.presentationml.presentation": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "type": "object", "required": [ "dryRun", "valid", "validation", "expressions", "fieldMappingsApplied", "dataSourcesResolved" ], "properties": { "dryRun": { "type": "boolean", "enum": [ true ] }, "valid": { "description": "True when both validation and expression evaluation succeeded.", "type": "boolean" }, "validation": { "type": "object", "required": [ "valid", "errors" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } }, "expressions": { "type": "object", "required": [ "valid", "errors" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "location": { "type": "object", "required": [ "nodeId", "nodeType", "nodePath" ], "properties": { "nodeId": { "description": "ID of the failing node in the template AST.", "type": "string" }, "nodeType": { "description": "Type of the failing node (e.g. \"text\", \"table\").", "type": "string" }, "nodePath": { "description": "Human-readable breadcrumb through the template AST, e.g. \"Page 1 > Section 'Header' > Text block 3\". Stops at templateRef boundaries.", "type": "string" }, "line": { "minimum": 1, "description": "Line number within the expression (1-based), when extractable.", "type": "integer" }, "column": { "minimum": 1, "description": "Column number within the expression (1-based), when extractable.", "type": "integer" } } }, "suggestion": { "type": "object", "required": [ "variable", "suggestions" ], "properties": { "variable": { "description": "Undefined variable name from the error message.", "type": "string" }, "suggestions": { "description": "Up to 3 close matches from the available data context, sorted by Levenshtein distance.", "type": "array", "items": { "type": "string" } } } } } } } } }, "fieldMappingsApplied": { "minimum": 0, "description": "Number of field mappings applied during data adaptation.", "type": "integer" }, "dataSourcesResolved": { "minimum": 0, "description": "Number of templateRef data sources successfully resolved.", "type": "integer" } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "RenderError" ] }, "code": { "anyOf": [ { "type": "string", "enum": [ "template_expression_error" ] }, { "type": "string", "enum": [ "validation_failed" ] }, { "type": "string", "enum": [ "render_timeout" ] }, { "type": "string", "enum": [ "engine_crash" ] }, { "type": "string", "enum": [ "asset_blocked" ] }, { "type": "string", "enum": [ "data_source_error" ] }, { "type": "string", "enum": [ "no_rendered_tables" ] }, { "type": "string", "enum": [ "ambiguous_table" ] }, { "type": "string", "enum": [ "invalid_pdf" ] }, { "type": "string", "enum": [ "pdf_too_large" ] }, { "type": "string", "enum": [ "too_many_pages" ] }, { "type": "string", "enum": [ "invalid_page_range" ] }, { "type": "string", "enum": [ "unsupported_image" ] }, { "type": "string", "enum": [ "PPTX_PIVOT_UNSUPPORTED" ] }, { "type": "string", "enum": [ "PPTX_PAGEBREAK_IN_COLUMNS" ] }, { "type": "string", "enum": [ "stream_incompatible_hook" ] } ] }, "message": { "type": "string" }, "location": { "type": "object", "required": [ "nodeId", "nodeType", "nodePath" ], "properties": { "nodeId": { "description": "ID of the failing node in the template AST.", "type": "string" }, "nodeType": { "description": "Type of the failing node (e.g. \"text\", \"table\").", "type": "string" }, "nodePath": { "description": "Human-readable breadcrumb through the template AST, e.g. \"Page 1 > Section 'Header' > Text block 3\". Stops at templateRef boundaries.", "type": "string" }, "line": { "minimum": 1, "description": "Line number within the expression (1-based), when extractable.", "type": "integer" }, "column": { "minimum": 1, "description": "Column number within the expression (1-based), when extractable.", "type": "integer" } } }, "suggestion": { "type": "object", "required": [ "variable", "suggestions" ], "properties": { "variable": { "description": "Undefined variable name from the error message.", "type": "string" }, "suggestions": { "description": "Up to 3 close matches from the available data context, sorted by Levenshtein distance.", "type": "array", "items": { "type": "string" } } } } } }, { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: quota_exhausted (sandbox lifetime quota).", "type": "string" } } } } } } } } }, "/render/batch/pptx": { "post": { "operationId": "renderBatchPptx", "summary": "Render multiple templates to PPTX in a single request (beta)", "tags": [ "Render" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "minItems": 1, "maxItems": 50, "description": "Array of render items (1–50)", "type": "array", "items": { "type": "object", "required": [ "template", "data" ], "properties": { "template": { "description": "Template key", "type": "string" }, "version": { "description": "Exact saved version string. Mutually exclusive with `label`.", "type": "string" }, "label": { "minLength": 1, "maxLength": 64, "description": "Label name (B.1), mutually exclusive with `version`.", "type": "string" }, "bucketKey": { "minLength": 1, "maxLength": 256, "description": "Per-item stable bucket key for B.3 variant resolution.", "type": "string" }, "data": { "type": "object", "additionalProperties": {} }, "options": { "type": "object", "properties": { "paperSize": { "anyOf": [ { "type": "string", "enum": [ "A4" ] }, { "type": "string", "enum": [ "A3" ] }, { "type": "string", "enum": [ "Letter" ] }, { "type": "string", "enum": [ "Legal" ] }, { "type": "string", "enum": [ "Tabloid" ] } ] }, "orientation": { "anyOf": [ { "type": "string", "enum": [ "portrait" ] }, { "type": "string", "enum": [ "landscape" ] } ] } } } } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "total", "succeeded", "failed", "results" ], "properties": { "total": { "description": "Total items in the request", "type": "integer" }, "succeeded": { "type": "integer" }, "failed": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "required": [ "index", "template", "success" ], "properties": { "index": { "description": "Zero-based index of this item in the request array", "type": "integer" }, "template": { "type": "string" }, "success": { "type": "boolean" }, "pptx": { "description": "Base64-encoded PPTX bytes (present when success=true)", "type": "string" }, "warningCount": { "description": "Number of structured warnings emitted by the renderer", "type": "integer" }, "error": { "description": "Error category (present when success=false)", "type": "string" }, "code": { "anyOf": [ { "type": "string", "enum": [ "template_expression_error" ] }, { "type": "string", "enum": [ "validation_failed" ] }, { "type": "string", "enum": [ "render_timeout" ] }, { "type": "string", "enum": [ "engine_crash" ] }, { "type": "string", "enum": [ "asset_blocked" ] }, { "type": "string", "enum": [ "data_source_error" ] }, { "type": "string", "enum": [ "no_rendered_tables" ] }, { "type": "string", "enum": [ "ambiguous_table" ] }, { "type": "string", "enum": [ "invalid_pdf" ] }, { "type": "string", "enum": [ "pdf_too_large" ] }, { "type": "string", "enum": [ "too_many_pages" ] }, { "type": "string", "enum": [ "invalid_page_range" ] }, { "type": "string", "enum": [ "unsupported_image" ] }, { "type": "string", "enum": [ "PPTX_PIVOT_UNSUPPORTED" ] }, { "type": "string", "enum": [ "PPTX_PAGEBREAK_IN_COLUMNS" ] }, { "type": "string", "enum": [ "stream_incompatible_hook" ] } ] }, "message": { "description": "Human-readable error message (present when success=false)", "type": "string" } } } } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: quota_exhausted (sandbox lifetime quota).", "type": "string" } } } } } } } } }, "/render/batch/docx": { "post": { "operationId": "renderBatchDocx", "summary": "Render multiple templates to DOCX in a single request", "tags": [ "Render" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "minItems": 1, "maxItems": 50, "description": "Array of render items (1–50)", "type": "array", "items": { "type": "object", "required": [ "template", "data" ], "properties": { "template": { "description": "Template key", "type": "string" }, "version": { "description": "Exact saved version string. Mutually exclusive with `label`.", "type": "string" }, "label": { "minLength": 1, "maxLength": 64, "description": "Label name (B.1), mutually exclusive with `version`.", "type": "string" }, "bucketKey": { "minLength": 1, "maxLength": 256, "description": "Per-item stable bucket key for B.3 variant resolution.", "type": "string" }, "data": { "type": "object", "additionalProperties": {} }, "options": { "type": "object", "properties": { "paperSize": { "anyOf": [ { "type": "string", "enum": [ "A4" ] }, { "type": "string", "enum": [ "A3" ] }, { "type": "string", "enum": [ "Letter" ] }, { "type": "string", "enum": [ "Legal" ] }, { "type": "string", "enum": [ "Tabloid" ] } ] }, "orientation": { "anyOf": [ { "type": "string", "enum": [ "portrait" ] }, { "type": "string", "enum": [ "landscape" ] } ] } } } } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "total", "succeeded", "failed", "results" ], "properties": { "total": { "description": "Total items in the request", "type": "integer" }, "succeeded": { "type": "integer" }, "failed": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "required": [ "index", "template", "success" ], "properties": { "index": { "description": "Zero-based index of this item in the request array", "type": "integer" }, "template": { "type": "string" }, "success": { "type": "boolean" }, "docx": { "description": "Base64-encoded DOCX bytes (present when success=true)", "type": "string" }, "error": { "description": "Error category (present when success=false)", "type": "string" }, "code": { "anyOf": [ { "type": "string", "enum": [ "template_expression_error" ] }, { "type": "string", "enum": [ "validation_failed" ] }, { "type": "string", "enum": [ "render_timeout" ] }, { "type": "string", "enum": [ "engine_crash" ] }, { "type": "string", "enum": [ "asset_blocked" ] }, { "type": "string", "enum": [ "data_source_error" ] }, { "type": "string", "enum": [ "no_rendered_tables" ] }, { "type": "string", "enum": [ "ambiguous_table" ] }, { "type": "string", "enum": [ "invalid_pdf" ] }, { "type": "string", "enum": [ "pdf_too_large" ] }, { "type": "string", "enum": [ "too_many_pages" ] }, { "type": "string", "enum": [ "invalid_page_range" ] }, { "type": "string", "enum": [ "unsupported_image" ] }, { "type": "string", "enum": [ "PPTX_PIVOT_UNSUPPORTED" ] }, { "type": "string", "enum": [ "PPTX_PAGEBREAK_IN_COLUMNS" ] }, { "type": "string", "enum": [ "stream_incompatible_hook" ] } ] }, "message": { "description": "Human-readable error message (present when success=false)", "type": "string" } } } } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: quota_exhausted (sandbox lifetime quota).", "type": "string" } } } } } } } } }, "/render/batch": { "post": { "operationId": "renderBatchPdf", "summary": "Render multiple templates to PDF in a single request", "tags": [ "Render" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "minItems": 1, "maxItems": 50, "description": "Array of render items (1–50)", "type": "array", "items": { "type": "object", "required": [ "template", "data" ], "properties": { "template": { "description": "Template key", "type": "string" }, "version": { "description": "Exact saved version string. Mutually exclusive with `label`. Omit both to render the latest version.", "type": "string" }, "label": { "minLength": 1, "maxLength": 64, "description": "Label name (B.1), mutually exclusive with `version`.", "type": "string" }, "bucketKey": { "minLength": 1, "maxLength": 256, "description": "Per-item stable bucket key for B.3 A/B variant resolution. Precedence: item.bucketKey > x-pulp-engine-bucket header > deterministic hash of (template + data).", "type": "string" }, "data": { "type": "object", "additionalProperties": {} }, "options": { "type": "object", "properties": { "paperSize": { "anyOf": [ { "type": "string", "enum": [ "A4" ] }, { "type": "string", "enum": [ "A3" ] }, { "type": "string", "enum": [ "Letter" ] }, { "type": "string", "enum": [ "Legal" ] }, { "type": "string", "enum": [ "Tabloid" ] } ] }, "orientation": { "anyOf": [ { "type": "string", "enum": [ "portrait" ] }, { "type": "string", "enum": [ "landscape" ] } ] } } } } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Batch results. JSON envelope by default; NDJSON stream when Accept: application/x-ndjson is requested.", "content": { "application/json": { "schema": { "type": "object", "required": [ "total", "succeeded", "failed", "results" ], "properties": { "total": { "description": "Total items in the request", "type": "integer" }, "succeeded": { "type": "integer" }, "failed": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "required": [ "index", "template", "success" ], "properties": { "index": { "description": "Zero-based index of this item in the request array", "type": "integer" }, "template": { "type": "string" }, "success": { "type": "boolean" }, "pdf": { "description": "Base64-encoded PDF bytes (present when success=true)", "type": "string" }, "error": { "description": "Error category (present when success=false)", "type": "string" }, "code": { "anyOf": [ { "type": "string", "enum": [ "template_expression_error" ] }, { "type": "string", "enum": [ "validation_failed" ] }, { "type": "string", "enum": [ "render_timeout" ] }, { "type": "string", "enum": [ "engine_crash" ] }, { "type": "string", "enum": [ "asset_blocked" ] }, { "type": "string", "enum": [ "data_source_error" ] }, { "type": "string", "enum": [ "no_rendered_tables" ] }, { "type": "string", "enum": [ "ambiguous_table" ] }, { "type": "string", "enum": [ "invalid_pdf" ] }, { "type": "string", "enum": [ "pdf_too_large" ] }, { "type": "string", "enum": [ "too_many_pages" ] }, { "type": "string", "enum": [ "invalid_page_range" ] }, { "type": "string", "enum": [ "unsupported_image" ] }, { "type": "string", "enum": [ "PPTX_PIVOT_UNSUPPORTED" ] }, { "type": "string", "enum": [ "PPTX_PAGEBREAK_IN_COLUMNS" ] }, { "type": "string", "enum": [ "stream_incompatible_hook" ] } ] }, "message": { "description": "Human-readable error message (present when success=false)", "type": "string" } } } } } } }, "application/x-ndjson": { "schema": { "description": "One line in the NDJSON stream. `result` lines arrive in completion order as each item resolves; a single `summary` line is always emitted last and carries authoritative totals.", "anyOf": [ { "type": "object", "required": [ "type", "index", "template", "success" ], "properties": { "type": { "type": "string", "enum": [ "result" ] }, "index": { "description": "Zero-based index of this item in the request array", "type": "integer" }, "template": { "type": "string" }, "success": { "type": "boolean" }, "pdf": { "description": "Base64-encoded PDF bytes (present when success=true)", "type": "string" }, "error": { "description": "Error category (present when success=false)", "type": "string" }, "code": { "anyOf": [ { "type": "string", "enum": [ "template_expression_error" ] }, { "type": "string", "enum": [ "validation_failed" ] }, { "type": "string", "enum": [ "render_timeout" ] }, { "type": "string", "enum": [ "engine_crash" ] }, { "type": "string", "enum": [ "asset_blocked" ] }, { "type": "string", "enum": [ "data_source_error" ] }, { "type": "string", "enum": [ "no_rendered_tables" ] }, { "type": "string", "enum": [ "ambiguous_table" ] }, { "type": "string", "enum": [ "invalid_pdf" ] }, { "type": "string", "enum": [ "pdf_too_large" ] }, { "type": "string", "enum": [ "too_many_pages" ] }, { "type": "string", "enum": [ "invalid_page_range" ] }, { "type": "string", "enum": [ "unsupported_image" ] }, { "type": "string", "enum": [ "PPTX_PIVOT_UNSUPPORTED" ] }, { "type": "string", "enum": [ "PPTX_PAGEBREAK_IN_COLUMNS" ] }, { "type": "string", "enum": [ "stream_incompatible_hook" ] } ] }, "message": { "description": "Human-readable error message (present when success=false)", "type": "string" } } }, { "type": "object", "required": [ "type", "total", "succeeded", "failed" ], "properties": { "type": { "type": "string", "enum": [ "summary" ] }, "total": { "type": "integer" }, "succeeded": { "type": "integer" }, "failed": { "type": "integer" } } } ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: quota_exhausted (sandbox lifetime quota).", "type": "string" } } } } } } } } }, "/render/validate": { "post": { "operationId": "validateTemplateDefinition", "summary": "Validate a template for publish readiness — always registered, no HTML/PDF output", "tags": [ "Render" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "TemplateDefinition + sample data for publish-readiness validation", "type": "object", "required": [ "template", "data" ], "properties": { "template": {}, "data": { "type": "object", "additionalProperties": {} } } } } }, "description": "TemplateDefinition + sample data for publish-readiness validation" }, "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "valid", "issues" ], "properties": { "valid": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "path": { "type": "string" }, "code": { "anyOf": [ { "type": "string", "enum": [ "INVALID_TEMPLATE" ] }, { "type": "string", "enum": [ "asset_blocked" ] }, { "type": "string", "enum": [ "validation_failed" ] }, { "type": "string", "enum": [ "template_expression_error" ] }, { "type": "string", "enum": [ "data_source_error" ] } ] } } } } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: quota_exhausted (sandbox lifetime quota).", "type": "string" } } } } } } } } }, "/render/pdf/merge": { "post": { "operationId": "mergePdf", "summary": "Merge multiple PDFs into one", "tags": [ "PDF Transform" ], "description": "Concatenate pages from multiple PDF documents into a single PDF, in the order provided.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sources" ], "properties": { "sources": { "minItems": 2, "maxItems": 50, "description": "Array of base64-encoded PDFs to merge in order (2–50)", "type": "array", "items": { "type": "object", "required": [ "data" ], "properties": { "data": { "description": "Base64-encoded PDF", "type": "string" } } } }, "metadata": { "type": "object", "properties": { "title": { "maxLength": 500, "type": "string" }, "author": { "maxLength": 500, "type": "string" }, "subject": { "maxLength": 500, "type": "string" } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Merged PDF", "content": { "application/json": { "schema": { "type": "string", "format": "binary", "description": "Merged PDF" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "RenderError" ] }, "code": { "anyOf": [ { "type": "string", "enum": [ "template_expression_error" ] }, { "type": "string", "enum": [ "validation_failed" ] }, { "type": "string", "enum": [ "render_timeout" ] }, { "type": "string", "enum": [ "engine_crash" ] }, { "type": "string", "enum": [ "asset_blocked" ] }, { "type": "string", "enum": [ "data_source_error" ] }, { "type": "string", "enum": [ "no_rendered_tables" ] }, { "type": "string", "enum": [ "ambiguous_table" ] }, { "type": "string", "enum": [ "invalid_pdf" ] }, { "type": "string", "enum": [ "pdf_too_large" ] }, { "type": "string", "enum": [ "too_many_pages" ] }, { "type": "string", "enum": [ "invalid_page_range" ] }, { "type": "string", "enum": [ "unsupported_image" ] }, { "type": "string", "enum": [ "PPTX_PIVOT_UNSUPPORTED" ] }, { "type": "string", "enum": [ "PPTX_PAGEBREAK_IN_COLUMNS" ] }, { "type": "string", "enum": [ "stream_incompatible_hook" ] } ] }, "message": { "type": "string" }, "location": { "type": "object", "required": [ "nodeId", "nodeType", "nodePath" ], "properties": { "nodeId": { "description": "ID of the failing node in the template AST.", "type": "string" }, "nodeType": { "description": "Type of the failing node (e.g. \"text\", \"table\").", "type": "string" }, "nodePath": { "description": "Human-readable breadcrumb through the template AST, e.g. \"Page 1 > Section 'Header' > Text block 3\". Stops at templateRef boundaries.", "type": "string" }, "line": { "minimum": 1, "description": "Line number within the expression (1-based), when extractable.", "type": "integer" }, "column": { "minimum": 1, "description": "Column number within the expression (1-based), when extractable.", "type": "integer" } } }, "suggestion": { "type": "object", "required": [ "variable", "suggestions" ], "properties": { "variable": { "description": "Undefined variable name from the error message.", "type": "string" }, "suggestions": { "description": "Up to 3 close matches from the available data context, sorted by Levenshtein distance.", "type": "array", "items": { "type": "string" } } } } } } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: quota_exhausted (sandbox lifetime quota).", "type": "string" } } } } } } } } }, "/render/pdf/watermark": { "post": { "operationId": "watermarkPdf", "summary": "Apply a watermark to a PDF", "tags": [ "PDF Transform" ], "description": "Overlay a text or image watermark on every page (or a page range) of a PDF.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pdf", "watermark" ], "properties": { "pdf": { "description": "Base64-encoded source PDF", "type": "string" }, "watermark": { "anyOf": [ { "type": "object", "required": [ "type", "content" ], "properties": { "type": { "type": "string", "enum": [ "text" ] }, "content": { "maxLength": 500, "description": "Watermark text", "type": "string" }, "fontSize": { "minimum": 6, "maximum": 200, "description": "Font size in points (default 48)", "type": "number" }, "color": { "description": "RGB color (0–1 range, default gray 0.6/0.6/0.6)", "type": "object", "required": [ "r", "g", "b" ], "properties": { "r": { "minimum": 0, "maximum": 1, "type": "number" }, "g": { "minimum": 0, "maximum": 1, "type": "number" }, "b": { "minimum": 0, "maximum": 1, "type": "number" } } }, "opacity": { "minimum": 0, "maximum": 1, "description": "Opacity (default 0.3)", "type": "number" }, "rotation": { "minimum": -360, "maximum": 360, "description": "Rotation in degrees (default 0, or -45 for diagonal)", "type": "number" }, "position": { "anyOf": [ { "type": "string", "enum": [ "center" ] }, { "type": "string", "enum": [ "diagonal" ] }, { "type": "string", "enum": [ "header" ] }, { "type": "string", "enum": [ "footer" ] }, { "type": "object", "required": [ "x", "y" ], "properties": { "x": { "description": "X coordinate (points from left)", "type": "number" }, "y": { "description": "Y coordinate (points from bottom)", "type": "number" } } } ] } } }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "enum": [ "image" ] }, "data": { "description": "Base64-encoded PNG or JPEG image", "type": "string" }, "width": { "minimum": 1, "description": "Display width in points", "type": "number" }, "height": { "minimum": 1, "description": "Display height in points", "type": "number" }, "opacity": { "minimum": 0, "maximum": 1, "description": "Opacity (default 0.3)", "type": "number" }, "position": { "anyOf": [ { "type": "string", "enum": [ "center" ] }, { "type": "string", "enum": [ "diagonal" ] }, { "type": "string", "enum": [ "header" ] }, { "type": "string", "enum": [ "footer" ] }, { "type": "object", "required": [ "x", "y" ], "properties": { "x": { "description": "X coordinate (points from left)", "type": "number" }, "y": { "description": "Y coordinate (points from bottom)", "type": "number" } } } ] } } } ] }, "pageRange": { "type": "object", "properties": { "start": { "minimum": 1, "description": "1-indexed start page (default: 1)", "type": "integer" }, "end": { "minimum": 1, "description": "1-indexed end page (default: last page)", "type": "integer" } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Watermarked PDF", "content": { "application/json": { "schema": { "type": "string", "format": "binary", "description": "Watermarked PDF" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "RenderError" ] }, "code": { "anyOf": [ { "type": "string", "enum": [ "template_expression_error" ] }, { "type": "string", "enum": [ "validation_failed" ] }, { "type": "string", "enum": [ "render_timeout" ] }, { "type": "string", "enum": [ "engine_crash" ] }, { "type": "string", "enum": [ "asset_blocked" ] }, { "type": "string", "enum": [ "data_source_error" ] }, { "type": "string", "enum": [ "no_rendered_tables" ] }, { "type": "string", "enum": [ "ambiguous_table" ] }, { "type": "string", "enum": [ "invalid_pdf" ] }, { "type": "string", "enum": [ "pdf_too_large" ] }, { "type": "string", "enum": [ "too_many_pages" ] }, { "type": "string", "enum": [ "invalid_page_range" ] }, { "type": "string", "enum": [ "unsupported_image" ] }, { "type": "string", "enum": [ "PPTX_PIVOT_UNSUPPORTED" ] }, { "type": "string", "enum": [ "PPTX_PAGEBREAK_IN_COLUMNS" ] }, { "type": "string", "enum": [ "stream_incompatible_hook" ] } ] }, "message": { "type": "string" }, "location": { "type": "object", "required": [ "nodeId", "nodeType", "nodePath" ], "properties": { "nodeId": { "description": "ID of the failing node in the template AST.", "type": "string" }, "nodeType": { "description": "Type of the failing node (e.g. \"text\", \"table\").", "type": "string" }, "nodePath": { "description": "Human-readable breadcrumb through the template AST, e.g. \"Page 1 > Section 'Header' > Text block 3\". Stops at templateRef boundaries.", "type": "string" }, "line": { "minimum": 1, "description": "Line number within the expression (1-based), when extractable.", "type": "integer" }, "column": { "minimum": 1, "description": "Column number within the expression (1-based), when extractable.", "type": "integer" } } }, "suggestion": { "type": "object", "required": [ "variable", "suggestions" ], "properties": { "variable": { "description": "Undefined variable name from the error message.", "type": "string" }, "suggestions": { "description": "Up to 3 close matches from the available data context, sorted by Levenshtein distance.", "type": "array", "items": { "type": "string" } } } } } } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: quota_exhausted (sandbox lifetime quota).", "type": "string" } } } } } } } } }, "/render/pdf/insert": { "post": { "operationId": "insertPdfPages", "summary": "Insert pages into a PDF", "tags": [ "PDF Transform" ], "description": "Insert all pages from one PDF into another at a specified position.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target", "insert", "position" ], "properties": { "target": { "description": "Base64-encoded target PDF", "type": "string" }, "insert": { "description": "Base64-encoded PDF pages to insert", "type": "string" }, "position": { "anyOf": [ { "type": "object", "required": [ "at" ], "properties": { "at": { "type": "string", "enum": [ "start" ] } } }, { "type": "object", "required": [ "at" ], "properties": { "at": { "type": "string", "enum": [ "end" ] } } }, { "type": "object", "required": [ "at", "page" ], "properties": { "at": { "type": "string", "enum": [ "before" ] }, "page": { "minimum": 1, "description": "1-indexed page number", "type": "integer" } } }, { "type": "object", "required": [ "at", "page" ], "properties": { "at": { "type": "string", "enum": [ "after" ] }, "page": { "minimum": 1, "description": "1-indexed page number", "type": "integer" } } } ] } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "PDF with inserted pages", "content": { "application/json": { "schema": { "type": "string", "format": "binary", "description": "PDF with inserted pages" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "RenderError" ] }, "code": { "anyOf": [ { "type": "string", "enum": [ "template_expression_error" ] }, { "type": "string", "enum": [ "validation_failed" ] }, { "type": "string", "enum": [ "render_timeout" ] }, { "type": "string", "enum": [ "engine_crash" ] }, { "type": "string", "enum": [ "asset_blocked" ] }, { "type": "string", "enum": [ "data_source_error" ] }, { "type": "string", "enum": [ "no_rendered_tables" ] }, { "type": "string", "enum": [ "ambiguous_table" ] }, { "type": "string", "enum": [ "invalid_pdf" ] }, { "type": "string", "enum": [ "pdf_too_large" ] }, { "type": "string", "enum": [ "too_many_pages" ] }, { "type": "string", "enum": [ "invalid_page_range" ] }, { "type": "string", "enum": [ "unsupported_image" ] }, { "type": "string", "enum": [ "PPTX_PIVOT_UNSUPPORTED" ] }, { "type": "string", "enum": [ "PPTX_PAGEBREAK_IN_COLUMNS" ] }, { "type": "string", "enum": [ "stream_incompatible_hook" ] } ] }, "message": { "type": "string" }, "location": { "type": "object", "required": [ "nodeId", "nodeType", "nodePath" ], "properties": { "nodeId": { "description": "ID of the failing node in the template AST.", "type": "string" }, "nodeType": { "description": "Type of the failing node (e.g. \"text\", \"table\").", "type": "string" }, "nodePath": { "description": "Human-readable breadcrumb through the template AST, e.g. \"Page 1 > Section 'Header' > Text block 3\". Stops at templateRef boundaries.", "type": "string" }, "line": { "minimum": 1, "description": "Line number within the expression (1-based), when extractable.", "type": "integer" }, "column": { "minimum": 1, "description": "Column number within the expression (1-based), when extractable.", "type": "integer" } } }, "suggestion": { "type": "object", "required": [ "variable", "suggestions" ], "properties": { "variable": { "description": "Undefined variable name from the error message.", "type": "string" }, "suggestions": { "description": "Up to 3 close matches from the available data context, sorted by Levenshtein distance.", "type": "array", "items": { "type": "string" } } } } } } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: quota_exhausted (sandbox lifetime quota).", "type": "string" } } } } } } } } }, "/render/batch/async": { "post": { "operationId": "submitAsyncBatchPdf", "summary": "Submit an async PDF batch render with webhook callback", "tags": [ "Render" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "webhookUrl", "webhookSecret" ], "properties": { "items": { "minItems": 1, "maxItems": 50, "description": "Array of render items (1–50)", "type": "array", "items": { "type": "object", "required": [ "template", "data" ], "properties": { "template": { "description": "Template key", "type": "string" }, "version": { "description": "Exact saved version string. Mutually exclusive with `label`. Omit both to render the latest version.", "type": "string" }, "label": { "minLength": 1, "maxLength": 64, "description": "Label name (B.1), mutually exclusive with `version`.", "type": "string" }, "bucketKey": { "minLength": 1, "maxLength": 256, "description": "Per-item stable bucket key for B.3 A/B variant resolution. Precedence: item.bucketKey > x-pulp-engine-bucket header > deterministic hash of (template + data).", "type": "string" }, "data": { "type": "object", "additionalProperties": {} }, "options": { "type": "object", "properties": { "paperSize": { "anyOf": [ { "type": "string", "enum": [ "A4" ] }, { "type": "string", "enum": [ "A3" ] }, { "type": "string", "enum": [ "Letter" ] }, { "type": "string", "enum": [ "Legal" ] }, { "type": "string", "enum": [ "Tabloid" ] } ] }, "orientation": { "anyOf": [ { "type": "string", "enum": [ "portrait" ] }, { "type": "string", "enum": [ "landscape" ] } ] } } } } } }, "webhookUrl": { "format": "uri", "description": "URL to receive completion notification (HTTPS required in production)", "type": "string" }, "webhookSecret": { "minLength": 16, "description": "Shared secret for HMAC-SHA256 webhook signature (min 16 chars)", "type": "string" } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "jobId", "status", "createdAt", "pollUrl" ], "properties": { "jobId": { "format": "uuid", "type": "string" }, "status": { "type": "string", "enum": [ "pending" ] }, "createdAt": { "description": "ISO 8601 timestamp", "type": "string" }, "pollUrl": { "description": "URL to poll for job status", "type": "string" } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: quota_exhausted (sandbox lifetime quota).", "type": "string" } } } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "retryAfter": { "type": "integer" } } } } } } } } }, "/render/batch/async/docx": { "post": { "operationId": "submitAsyncBatchDocx", "summary": "Submit an async DOCX batch render with webhook callback", "tags": [ "Render" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "webhookUrl", "webhookSecret" ], "properties": { "items": { "minItems": 1, "maxItems": 50, "description": "Array of render items (1–50)", "type": "array", "items": { "type": "object", "required": [ "template", "data" ], "properties": { "template": { "description": "Template key", "type": "string" }, "version": { "description": "Exact saved version string. Mutually exclusive with `label`.", "type": "string" }, "label": { "minLength": 1, "maxLength": 64, "description": "Label name (B.1), mutually exclusive with `version`.", "type": "string" }, "bucketKey": { "minLength": 1, "maxLength": 256, "description": "Per-item stable bucket key for B.3 variant resolution.", "type": "string" }, "data": { "type": "object", "additionalProperties": {} }, "options": { "type": "object", "properties": { "paperSize": { "anyOf": [ { "type": "string", "enum": [ "A4" ] }, { "type": "string", "enum": [ "A3" ] }, { "type": "string", "enum": [ "Letter" ] }, { "type": "string", "enum": [ "Legal" ] }, { "type": "string", "enum": [ "Tabloid" ] } ] }, "orientation": { "anyOf": [ { "type": "string", "enum": [ "portrait" ] }, { "type": "string", "enum": [ "landscape" ] } ] } } } } } }, "webhookUrl": { "format": "uri", "description": "URL to receive completion notification (HTTPS required in production)", "type": "string" }, "webhookSecret": { "minLength": 16, "description": "Shared secret for HMAC-SHA256 webhook signature (min 16 chars)", "type": "string" } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "jobId", "status", "createdAt", "pollUrl" ], "properties": { "jobId": { "format": "uuid", "type": "string" }, "status": { "type": "string", "enum": [ "pending" ] }, "createdAt": { "description": "ISO 8601 timestamp", "type": "string" }, "pollUrl": { "description": "URL to poll for job status", "type": "string" } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: quota_exhausted (sandbox lifetime quota).", "type": "string" } } } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "retryAfter": { "type": "integer" } } } } } } } } }, "/render/batch/jobs/{id}": { "get": { "operationId": "getAsyncBatchJob", "summary": "Poll async batch job status", "tags": [ "Render" ], "description": "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.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "jobId", "status", "createdAt", "completedAt", "format", "itemCount", "webhookDelivered" ], "properties": { "jobId": { "format": "uuid", "type": "string" }, "status": { "anyOf": [ { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "processing" ] }, { "type": "string", "enum": [ "completed" ] }, { "type": "string", "enum": [ "failed" ] } ] }, "createdAt": { "type": "string" }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "format": { "anyOf": [ { "type": "string", "enum": [ "pdf" ] }, { "type": "string", "enum": [ "docx" ] } ] }, "itemCount": { "type": "integer" }, "webhookDelivered": { "type": "boolean" }, "results": { "type": "object", "required": [ "total", "succeeded", "failed", "results" ], "properties": { "total": { "description": "Total items in the request", "type": "integer" }, "succeeded": { "type": "integer" }, "failed": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "required": [ "index", "template", "success" ], "properties": { "index": { "description": "Zero-based index of this item in the request array", "type": "integer" }, "template": { "type": "string" }, "success": { "type": "boolean" }, "pdf": { "description": "Base64-encoded PDF bytes (present when success=true)", "type": "string" }, "error": { "description": "Error category (present when success=false)", "type": "string" }, "code": { "anyOf": [ { "type": "string", "enum": [ "template_expression_error" ] }, { "type": "string", "enum": [ "validation_failed" ] }, { "type": "string", "enum": [ "render_timeout" ] }, { "type": "string", "enum": [ "engine_crash" ] }, { "type": "string", "enum": [ "asset_blocked" ] }, { "type": "string", "enum": [ "data_source_error" ] }, { "type": "string", "enum": [ "no_rendered_tables" ] }, { "type": "string", "enum": [ "ambiguous_table" ] }, { "type": "string", "enum": [ "invalid_pdf" ] }, { "type": "string", "enum": [ "pdf_too_large" ] }, { "type": "string", "enum": [ "too_many_pages" ] }, { "type": "string", "enum": [ "invalid_page_range" ] }, { "type": "string", "enum": [ "unsupported_image" ] }, { "type": "string", "enum": [ "PPTX_PIVOT_UNSUPPORTED" ] }, { "type": "string", "enum": [ "PPTX_PAGEBREAK_IN_COLUMNS" ] }, { "type": "string", "enum": [ "stream_incompatible_hook" ] } ] }, "message": { "description": "Human-readable error message (present when success=false)", "type": "string" } } } } } } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } } }, "/admin/batch-dlq/": { "get": { "operationId": "listBatchDlq", "summary": "List batch webhook DLQ entries", "tags": [ "Admin" ], "description": "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).", "parameters": [ { "schema": { "minimum": 1, "maximum": 1000, "default": 50, "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of items to return (1-1000, default 50)" }, { "schema": { "minimum": 0, "default": 0, "type": "integer" }, "in": "query", "name": "offset", "required": false, "description": "Number of items to skip" }, { "schema": { "type": "string" }, "in": "query", "name": "status", "required": false, "description": "Filter by status: pending | replayed | abandoned" }, { "schema": { "type": "string" }, "in": "query", "name": "jobId", "required": false, "description": "Filter by batch job id" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "total", "limit", "offset" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "jobId", "webhookUrlHash", "lastError", "attempts", "firstFailedAt", "lastFailedAt", "replayCount", "status", "createdAt", "replayable" ], "properties": { "id": { "type": "string" }, "jobId": { "type": "string" }, "webhookUrlHash": { "type": "string" }, "lastError": { "type": "string" }, "attempts": { "type": "integer" }, "firstFailedAt": { "type": "string" }, "lastFailedAt": { "type": "string" }, "replayCount": { "type": "integer" }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "replayable": { "type": "boolean" } } } }, "total": { "minimum": 0, "type": "integer" }, "limit": { "minimum": 1, "type": "integer" }, "offset": { "minimum": 0, "type": "integer" } } } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } } }, "/admin/batch-dlq/{id}": { "get": { "operationId": "getBatchDlqEntry", "summary": "Get a batch webhook DLQ entry", "tags": [ "Admin" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "jobId", "webhookUrlHash", "lastError", "attempts", "firstFailedAt", "lastFailedAt", "replayCount", "status", "createdAt", "replayable" ], "properties": { "id": { "type": "string" }, "jobId": { "type": "string" }, "webhookUrlHash": { "type": "string" }, "lastError": { "type": "string" }, "attempts": { "type": "integer" }, "firstFailedAt": { "type": "string" }, "lastFailedAt": { "type": "string" }, "replayCount": { "type": "integer" }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "replayable": { "type": "boolean" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } } }, "/admin/batch-dlq/{id}/replay": { "post": { "operationId": "replayBatchDlqEntry", "summary": "Replay a dead-lettered batch webhook delivery", "tags": [ "Admin" ], "description": "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.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "status", "replayCount", "delivered", "attempts" ], "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "replayCount": { "type": "integer" }, "delivered": { "type": "boolean" }, "attempts": { "type": "integer" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } } }, "/admin/batch-dlq/{id}/abandon": { "post": { "operationId": "abandonBatchDlqEntry", "summary": "Mark a batch webhook DLQ entry as abandoned", "tags": [ "Admin" ], "description": "Marks a DLQ entry as terminal (abandoned). Does not require active tenant (terminal cleanup). Admin scope required.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "204": { "description": "Default Response" }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } } } } }, "/render/preview/html": { "post": { "operationId": "previewHtml", "summary": "Preview template HTML with an inline definition (editor use — no DB save required)", "tags": [ "Preview" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "TemplateDefinition object (no DB lookup — editor preview only)", "type": "object", "required": [ "template", "data" ], "properties": { "template": {}, "data": { "type": "object", "additionalProperties": {} }, "options": {}, "dryRun": { "description": "When true, validate input data and exercise all template expressions via a trial HTML render, then return structured JSON results without producing any binary output. Same semantics as the production routes. Default: false.", "default": false, "type": "boolean" } } } } }, "description": "TemplateDefinition object (no DB lookup — editor preview only)" }, "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "200": { "description": "Rendered HTML document — or, when dryRun=true, a JSON DryRunResponse", "content": { "text/html": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "object", "required": [ "dryRun", "valid", "validation", "expressions", "fieldMappingsApplied", "dataSourcesResolved" ], "properties": { "dryRun": { "type": "boolean", "enum": [ true ] }, "valid": { "description": "True when both validation and expression evaluation succeeded.", "type": "boolean" }, "validation": { "type": "object", "required": [ "valid", "errors" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } }, "expressions": { "type": "object", "required": [ "valid", "errors" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "location": { "type": "object", "required": [ "nodeId", "nodeType", "nodePath" ], "properties": { "nodeId": { "description": "ID of the failing node in the template AST.", "type": "string" }, "nodeType": { "description": "Type of the failing node (e.g. \"text\", \"table\").", "type": "string" }, "nodePath": { "description": "Human-readable breadcrumb through the template AST, e.g. \"Page 1 > Section 'Header' > Text block 3\". Stops at templateRef boundaries.", "type": "string" }, "line": { "minimum": 1, "description": "Line number within the expression (1-based), when extractable.", "type": "integer" }, "column": { "minimum": 1, "description": "Column number within the expression (1-based), when extractable.", "type": "integer" } } }, "suggestion": { "type": "object", "required": [ "variable", "suggestions" ], "properties": { "variable": { "description": "Undefined variable name from the error message.", "type": "string" }, "suggestions": { "description": "Up to 3 close matches from the available data context, sorted by Levenshtein distance.", "type": "array", "items": { "type": "string" } } } } } } } } }, "fieldMappingsApplied": { "minimum": 0, "description": "Number of field mappings applied during data adaptation.", "type": "integer" }, "dataSourcesResolved": { "minimum": 0, "description": "Number of templateRef data sources successfully resolved.", "type": "integer" } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "RenderError" ] }, "code": { "anyOf": [ { "type": "string", "enum": [ "template_expression_error" ] }, { "type": "string", "enum": [ "validation_failed" ] }, { "type": "string", "enum": [ "render_timeout" ] }, { "type": "string", "enum": [ "engine_crash" ] }, { "type": "string", "enum": [ "asset_blocked" ] }, { "type": "string", "enum": [ "data_source_error" ] }, { "type": "string", "enum": [ "no_rendered_tables" ] }, { "type": "string", "enum": [ "ambiguous_table" ] }, { "type": "string", "enum": [ "invalid_pdf" ] }, { "type": "string", "enum": [ "pdf_too_large" ] }, { "type": "string", "enum": [ "too_many_pages" ] }, { "type": "string", "enum": [ "invalid_page_range" ] }, { "type": "string", "enum": [ "unsupported_image" ] }, { "type": "string", "enum": [ "PPTX_PIVOT_UNSUPPORTED" ] }, { "type": "string", "enum": [ "PPTX_PAGEBREAK_IN_COLUMNS" ] }, { "type": "string", "enum": [ "stream_incompatible_hook" ] } ] }, "message": { "type": "string" }, "location": { "type": "object", "required": [ "nodeId", "nodeType", "nodePath" ], "properties": { "nodeId": { "description": "ID of the failing node in the template AST.", "type": "string" }, "nodeType": { "description": "Type of the failing node (e.g. \"text\", \"table\").", "type": "string" }, "nodePath": { "description": "Human-readable breadcrumb through the template AST, e.g. \"Page 1 > Section 'Header' > Text block 3\". Stops at templateRef boundaries.", "type": "string" }, "line": { "minimum": 1, "description": "Line number within the expression (1-based), when extractable.", "type": "integer" }, "column": { "minimum": 1, "description": "Column number within the expression (1-based), when extractable.", "type": "integer" } } }, "suggestion": { "type": "object", "required": [ "variable", "suggestions" ], "properties": { "variable": { "description": "Undefined variable name from the error message.", "type": "string" }, "suggestions": { "description": "Up to 3 close matches from the available data context, sorted by Levenshtein distance.", "type": "array", "items": { "type": "string" } } } } } } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: quota_exhausted (sandbox lifetime quota).", "type": "string" } } } } } } } } }, "/render/preview/docx": { "post": { "operationId": "previewDocx", "summary": "Preview template DOCX with an inline definition (editor use — no DB save required)", "tags": [ "Preview" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "TemplateDefinition object (no DB lookup — editor preview only)", "type": "object", "required": [ "template", "data" ], "properties": { "template": {}, "data": { "type": "object", "additionalProperties": {} }, "options": {}, "dryRun": { "description": "When true, validate input data and exercise all template expressions via a trial HTML render, then return structured JSON results without producing any binary output. Same semantics as the production routes. Default: false.", "default": false, "type": "boolean" } } } } }, "description": "TemplateDefinition object (no DB lookup — editor preview only)" }, "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "200": { "description": "DOCX document — or, when dryRun=true, a JSON DryRunResponse", "content": { "application/vnd.openxmlformats-officedocument.wordprocessingml.document": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "type": "object", "required": [ "dryRun", "valid", "validation", "expressions", "fieldMappingsApplied", "dataSourcesResolved" ], "properties": { "dryRun": { "type": "boolean", "enum": [ true ] }, "valid": { "description": "True when both validation and expression evaluation succeeded.", "type": "boolean" }, "validation": { "type": "object", "required": [ "valid", "errors" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } }, "expressions": { "type": "object", "required": [ "valid", "errors" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "location": { "type": "object", "required": [ "nodeId", "nodeType", "nodePath" ], "properties": { "nodeId": { "description": "ID of the failing node in the template AST.", "type": "string" }, "nodeType": { "description": "Type of the failing node (e.g. \"text\", \"table\").", "type": "string" }, "nodePath": { "description": "Human-readable breadcrumb through the template AST, e.g. \"Page 1 > Section 'Header' > Text block 3\". Stops at templateRef boundaries.", "type": "string" }, "line": { "minimum": 1, "description": "Line number within the expression (1-based), when extractable.", "type": "integer" }, "column": { "minimum": 1, "description": "Column number within the expression (1-based), when extractable.", "type": "integer" } } }, "suggestion": { "type": "object", "required": [ "variable", "suggestions" ], "properties": { "variable": { "description": "Undefined variable name from the error message.", "type": "string" }, "suggestions": { "description": "Up to 3 close matches from the available data context, sorted by Levenshtein distance.", "type": "array", "items": { "type": "string" } } } } } } } } }, "fieldMappingsApplied": { "minimum": 0, "description": "Number of field mappings applied during data adaptation.", "type": "integer" }, "dataSourcesResolved": { "minimum": 0, "description": "Number of templateRef data sources successfully resolved.", "type": "integer" } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "RenderError" ] }, "code": { "anyOf": [ { "type": "string", "enum": [ "template_expression_error" ] }, { "type": "string", "enum": [ "validation_failed" ] }, { "type": "string", "enum": [ "render_timeout" ] }, { "type": "string", "enum": [ "engine_crash" ] }, { "type": "string", "enum": [ "asset_blocked" ] }, { "type": "string", "enum": [ "data_source_error" ] }, { "type": "string", "enum": [ "no_rendered_tables" ] }, { "type": "string", "enum": [ "ambiguous_table" ] }, { "type": "string", "enum": [ "invalid_pdf" ] }, { "type": "string", "enum": [ "pdf_too_large" ] }, { "type": "string", "enum": [ "too_many_pages" ] }, { "type": "string", "enum": [ "invalid_page_range" ] }, { "type": "string", "enum": [ "unsupported_image" ] }, { "type": "string", "enum": [ "PPTX_PIVOT_UNSUPPORTED" ] }, { "type": "string", "enum": [ "PPTX_PAGEBREAK_IN_COLUMNS" ] }, { "type": "string", "enum": [ "stream_incompatible_hook" ] } ] }, "message": { "type": "string" }, "location": { "type": "object", "required": [ "nodeId", "nodeType", "nodePath" ], "properties": { "nodeId": { "description": "ID of the failing node in the template AST.", "type": "string" }, "nodeType": { "description": "Type of the failing node (e.g. \"text\", \"table\").", "type": "string" }, "nodePath": { "description": "Human-readable breadcrumb through the template AST, e.g. \"Page 1 > Section 'Header' > Text block 3\". Stops at templateRef boundaries.", "type": "string" }, "line": { "minimum": 1, "description": "Line number within the expression (1-based), when extractable.", "type": "integer" }, "column": { "minimum": 1, "description": "Column number within the expression (1-based), when extractable.", "type": "integer" } } }, "suggestion": { "type": "object", "required": [ "variable", "suggestions" ], "properties": { "variable": { "description": "Undefined variable name from the error message.", "type": "string" }, "suggestions": { "description": "Up to 3 close matches from the available data context, sorted by Levenshtein distance.", "type": "array", "items": { "type": "string" } } } } } } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: quota_exhausted (sandbox lifetime quota).", "type": "string" } } } } } } } } }, "/render/preview/pptx": { "post": { "operationId": "previewPptx", "summary": "Preview template PPTX with an inline definition (editor use — no DB save required)", "tags": [ "Preview" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "TemplateDefinition object (no DB lookup — editor preview only)", "type": "object", "required": [ "template", "data" ], "properties": { "template": {}, "data": { "type": "object", "additionalProperties": {} }, "options": {}, "dryRun": { "description": "When true, validate input data and exercise all template expressions via a trial HTML render, then return structured JSON results without producing any binary output. Same semantics as the production routes. Default: false.", "default": false, "type": "boolean" } } } } }, "description": "TemplateDefinition object (no DB lookup — editor preview only)" }, "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "200": { "description": "PPTX presentation — or, when dryRun=true, a JSON DryRunResponse", "content": { "application/vnd.openxmlformats-officedocument.presentationml.presentation": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "type": "object", "required": [ "dryRun", "valid", "validation", "expressions", "fieldMappingsApplied", "dataSourcesResolved" ], "properties": { "dryRun": { "type": "boolean", "enum": [ true ] }, "valid": { "description": "True when both validation and expression evaluation succeeded.", "type": "boolean" }, "validation": { "type": "object", "required": [ "valid", "errors" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } }, "expressions": { "type": "object", "required": [ "valid", "errors" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "location": { "type": "object", "required": [ "nodeId", "nodeType", "nodePath" ], "properties": { "nodeId": { "description": "ID of the failing node in the template AST.", "type": "string" }, "nodeType": { "description": "Type of the failing node (e.g. \"text\", \"table\").", "type": "string" }, "nodePath": { "description": "Human-readable breadcrumb through the template AST, e.g. \"Page 1 > Section 'Header' > Text block 3\". Stops at templateRef boundaries.", "type": "string" }, "line": { "minimum": 1, "description": "Line number within the expression (1-based), when extractable.", "type": "integer" }, "column": { "minimum": 1, "description": "Column number within the expression (1-based), when extractable.", "type": "integer" } } }, "suggestion": { "type": "object", "required": [ "variable", "suggestions" ], "properties": { "variable": { "description": "Undefined variable name from the error message.", "type": "string" }, "suggestions": { "description": "Up to 3 close matches from the available data context, sorted by Levenshtein distance.", "type": "array", "items": { "type": "string" } } } } } } } } }, "fieldMappingsApplied": { "minimum": 0, "description": "Number of field mappings applied during data adaptation.", "type": "integer" }, "dataSourcesResolved": { "minimum": 0, "description": "Number of templateRef data sources successfully resolved.", "type": "integer" } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "RenderError" ] }, "code": { "anyOf": [ { "type": "string", "enum": [ "template_expression_error" ] }, { "type": "string", "enum": [ "validation_failed" ] }, { "type": "string", "enum": [ "render_timeout" ] }, { "type": "string", "enum": [ "engine_crash" ] }, { "type": "string", "enum": [ "asset_blocked" ] }, { "type": "string", "enum": [ "data_source_error" ] }, { "type": "string", "enum": [ "no_rendered_tables" ] }, { "type": "string", "enum": [ "ambiguous_table" ] }, { "type": "string", "enum": [ "invalid_pdf" ] }, { "type": "string", "enum": [ "pdf_too_large" ] }, { "type": "string", "enum": [ "too_many_pages" ] }, { "type": "string", "enum": [ "invalid_page_range" ] }, { "type": "string", "enum": [ "unsupported_image" ] }, { "type": "string", "enum": [ "PPTX_PIVOT_UNSUPPORTED" ] }, { "type": "string", "enum": [ "PPTX_PAGEBREAK_IN_COLUMNS" ] }, { "type": "string", "enum": [ "stream_incompatible_hook" ] } ] }, "message": { "type": "string" }, "location": { "type": "object", "required": [ "nodeId", "nodeType", "nodePath" ], "properties": { "nodeId": { "description": "ID of the failing node in the template AST.", "type": "string" }, "nodeType": { "description": "Type of the failing node (e.g. \"text\", \"table\").", "type": "string" }, "nodePath": { "description": "Human-readable breadcrumb through the template AST, e.g. \"Page 1 > Section 'Header' > Text block 3\". Stops at templateRef boundaries.", "type": "string" }, "line": { "minimum": 1, "description": "Line number within the expression (1-based), when extractable.", "type": "integer" }, "column": { "minimum": 1, "description": "Column number within the expression (1-based), when extractable.", "type": "integer" } } }, "suggestion": { "type": "object", "required": [ "variable", "suggestions" ], "properties": { "variable": { "description": "Undefined variable name from the error message.", "type": "string" }, "suggestions": { "description": "Up to 3 close matches from the available data context, sorted by Levenshtein distance.", "type": "array", "items": { "type": "string" } } } } } } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: quota_exhausted (sandbox lifetime quota).", "type": "string" } } } } } } } } }, "/render/preview/pdf": { "post": { "operationId": "previewPdf", "summary": "Preview template PDF with an inline definition (editor use — no DB save required)", "tags": [ "Preview" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "TemplateDefinition object (no DB lookup — editor preview only)", "type": "object", "required": [ "template", "data" ], "properties": { "template": {}, "data": { "type": "object", "additionalProperties": {} }, "options": {}, "dryRun": { "description": "When true, validate input data and exercise all template expressions via a trial HTML render, then return structured JSON results without producing any binary output. Same semantics as the production routes. Default: false.", "default": false, "type": "boolean" } } } } }, "description": "TemplateDefinition object (no DB lookup — editor preview only)" }, "parameters": [ { "schema": { "type": "boolean" }, "in": "query", "name": "stream", "required": false, "description": "Streaming control. Unset (default) or true → chunked stream. false → force buffered response. Preview has no post-render hooks, so stream=true never errors." } ], "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "200": { "description": "PDF document stream — or, when dryRun=true, a JSON DryRunResponse", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "type": "object", "required": [ "dryRun", "valid", "validation", "expressions", "fieldMappingsApplied", "dataSourcesResolved" ], "properties": { "dryRun": { "type": "boolean", "enum": [ true ] }, "valid": { "description": "True when both validation and expression evaluation succeeded.", "type": "boolean" }, "validation": { "type": "object", "required": [ "valid", "errors" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } }, "expressions": { "type": "object", "required": [ "valid", "errors" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "location": { "type": "object", "required": [ "nodeId", "nodeType", "nodePath" ], "properties": { "nodeId": { "description": "ID of the failing node in the template AST.", "type": "string" }, "nodeType": { "description": "Type of the failing node (e.g. \"text\", \"table\").", "type": "string" }, "nodePath": { "description": "Human-readable breadcrumb through the template AST, e.g. \"Page 1 > Section 'Header' > Text block 3\". Stops at templateRef boundaries.", "type": "string" }, "line": { "minimum": 1, "description": "Line number within the expression (1-based), when extractable.", "type": "integer" }, "column": { "minimum": 1, "description": "Column number within the expression (1-based), when extractable.", "type": "integer" } } }, "suggestion": { "type": "object", "required": [ "variable", "suggestions" ], "properties": { "variable": { "description": "Undefined variable name from the error message.", "type": "string" }, "suggestions": { "description": "Up to 3 close matches from the available data context, sorted by Levenshtein distance.", "type": "array", "items": { "type": "string" } } } } } } } } }, "fieldMappingsApplied": { "minimum": 0, "description": "Number of field mappings applied during data adaptation.", "type": "integer" }, "dataSourcesResolved": { "minimum": 0, "description": "Number of templateRef data sources successfully resolved.", "type": "integer" } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "RenderError" ] }, "code": { "anyOf": [ { "type": "string", "enum": [ "template_expression_error" ] }, { "type": "string", "enum": [ "validation_failed" ] }, { "type": "string", "enum": [ "render_timeout" ] }, { "type": "string", "enum": [ "engine_crash" ] }, { "type": "string", "enum": [ "asset_blocked" ] }, { "type": "string", "enum": [ "data_source_error" ] }, { "type": "string", "enum": [ "no_rendered_tables" ] }, { "type": "string", "enum": [ "ambiguous_table" ] }, { "type": "string", "enum": [ "invalid_pdf" ] }, { "type": "string", "enum": [ "pdf_too_large" ] }, { "type": "string", "enum": [ "too_many_pages" ] }, { "type": "string", "enum": [ "invalid_page_range" ] }, { "type": "string", "enum": [ "unsupported_image" ] }, { "type": "string", "enum": [ "PPTX_PIVOT_UNSUPPORTED" ] }, { "type": "string", "enum": [ "PPTX_PAGEBREAK_IN_COLUMNS" ] }, { "type": "string", "enum": [ "stream_incompatible_hook" ] } ] }, "message": { "type": "string" }, "location": { "type": "object", "required": [ "nodeId", "nodeType", "nodePath" ], "properties": { "nodeId": { "description": "ID of the failing node in the template AST.", "type": "string" }, "nodeType": { "description": "Type of the failing node (e.g. \"text\", \"table\").", "type": "string" }, "nodePath": { "description": "Human-readable breadcrumb through the template AST, e.g. \"Page 1 > Section 'Header' > Text block 3\". Stops at templateRef boundaries.", "type": "string" }, "line": { "minimum": 1, "description": "Line number within the expression (1-based), when extractable.", "type": "integer" }, "column": { "minimum": 1, "description": "Column number within the expression (1-based), when extractable.", "type": "integer" } } }, "suggestion": { "type": "object", "required": [ "variable", "suggestions" ], "properties": { "variable": { "description": "Undefined variable name from the error message.", "type": "string" }, "suggestions": { "description": "Up to 3 close matches from the available data context, sorted by Levenshtein distance.", "type": "array", "items": { "type": "string" } } } } } } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: quota_exhausted (sandbox lifetime quota).", "type": "string" } } } } } } } } }, "/render/preview/csv": { "post": { "operationId": "previewCsv", "summary": "Preview template CSV with an inline definition (editor use — no DB save required)", "tags": [ "Preview" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "TemplateDefinition object (no DB lookup — editor preview only)", "type": "object", "required": [ "template", "data" ], "properties": { "template": {}, "data": { "type": "object", "additionalProperties": {} }, "options": {}, "dryRun": { "description": "When true, validate input data and exercise all template expressions via a trial HTML render, then return structured JSON results without producing any binary output. Same semantics as the production routes. Default: false.", "default": false, "type": "boolean" } } } } }, "description": "TemplateDefinition object (no DB lookup — editor preview only)" }, "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "200": { "description": "CSV table data — or, when dryRun=true, a JSON DryRunResponse", "content": { "text/csv": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "object", "required": [ "dryRun", "valid", "validation", "expressions", "fieldMappingsApplied", "dataSourcesResolved" ], "properties": { "dryRun": { "type": "boolean", "enum": [ true ] }, "valid": { "description": "True when both validation and expression evaluation succeeded.", "type": "boolean" }, "validation": { "type": "object", "required": [ "valid", "errors" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } }, "expressions": { "type": "object", "required": [ "valid", "errors" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "location": { "type": "object", "required": [ "nodeId", "nodeType", "nodePath" ], "properties": { "nodeId": { "description": "ID of the failing node in the template AST.", "type": "string" }, "nodeType": { "description": "Type of the failing node (e.g. \"text\", \"table\").", "type": "string" }, "nodePath": { "description": "Human-readable breadcrumb through the template AST, e.g. \"Page 1 > Section 'Header' > Text block 3\". Stops at templateRef boundaries.", "type": "string" }, "line": { "minimum": 1, "description": "Line number within the expression (1-based), when extractable.", "type": "integer" }, "column": { "minimum": 1, "description": "Column number within the expression (1-based), when extractable.", "type": "integer" } } }, "suggestion": { "type": "object", "required": [ "variable", "suggestions" ], "properties": { "variable": { "description": "Undefined variable name from the error message.", "type": "string" }, "suggestions": { "description": "Up to 3 close matches from the available data context, sorted by Levenshtein distance.", "type": "array", "items": { "type": "string" } } } } } } } } }, "fieldMappingsApplied": { "minimum": 0, "description": "Number of field mappings applied during data adaptation.", "type": "integer" }, "dataSourcesResolved": { "minimum": 0, "description": "Number of templateRef data sources successfully resolved.", "type": "integer" } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "RenderError" ] }, "code": { "anyOf": [ { "type": "string", "enum": [ "template_expression_error" ] }, { "type": "string", "enum": [ "validation_failed" ] }, { "type": "string", "enum": [ "render_timeout" ] }, { "type": "string", "enum": [ "engine_crash" ] }, { "type": "string", "enum": [ "asset_blocked" ] }, { "type": "string", "enum": [ "data_source_error" ] }, { "type": "string", "enum": [ "no_rendered_tables" ] }, { "type": "string", "enum": [ "ambiguous_table" ] }, { "type": "string", "enum": [ "invalid_pdf" ] }, { "type": "string", "enum": [ "pdf_too_large" ] }, { "type": "string", "enum": [ "too_many_pages" ] }, { "type": "string", "enum": [ "invalid_page_range" ] }, { "type": "string", "enum": [ "unsupported_image" ] }, { "type": "string", "enum": [ "PPTX_PIVOT_UNSUPPORTED" ] }, { "type": "string", "enum": [ "PPTX_PAGEBREAK_IN_COLUMNS" ] }, { "type": "string", "enum": [ "stream_incompatible_hook" ] } ] }, "message": { "type": "string" }, "location": { "type": "object", "required": [ "nodeId", "nodeType", "nodePath" ], "properties": { "nodeId": { "description": "ID of the failing node in the template AST.", "type": "string" }, "nodeType": { "description": "Type of the failing node (e.g. \"text\", \"table\").", "type": "string" }, "nodePath": { "description": "Human-readable breadcrumb through the template AST, e.g. \"Page 1 > Section 'Header' > Text block 3\". Stops at templateRef boundaries.", "type": "string" }, "line": { "minimum": 1, "description": "Line number within the expression (1-based), when extractable.", "type": "integer" }, "column": { "minimum": 1, "description": "Column number within the expression (1-based), when extractable.", "type": "integer" } } }, "suggestion": { "type": "object", "required": [ "variable", "suggestions" ], "properties": { "variable": { "description": "Undefined variable name from the error message.", "type": "string" }, "suggestions": { "description": "Up to 3 close matches from the available data context, sorted by Levenshtein distance.", "type": "array", "items": { "type": "string" } } } } } } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: quota_exhausted (sandbox lifetime quota).", "type": "string" } } } } } } } } }, "/render/preview/xlsx": { "post": { "operationId": "previewXlsx", "summary": "Preview template XLSX with an inline definition (editor use — no DB save required)", "tags": [ "Preview" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "TemplateDefinition object (no DB lookup — editor preview only)", "type": "object", "required": [ "template", "data" ], "properties": { "template": {}, "data": { "type": "object", "additionalProperties": {} }, "options": {}, "dryRun": { "description": "When true, validate input data and exercise all template expressions via a trial HTML render, then return structured JSON results without producing any binary output. Same semantics as the production routes. Default: false.", "default": false, "type": "boolean" } } } } }, "description": "TemplateDefinition object (no DB lookup — editor preview only)" }, "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "200": { "description": "XLSX workbook — or, when dryRun=true, a JSON DryRunResponse", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "type": "object", "required": [ "dryRun", "valid", "validation", "expressions", "fieldMappingsApplied", "dataSourcesResolved" ], "properties": { "dryRun": { "type": "boolean", "enum": [ true ] }, "valid": { "description": "True when both validation and expression evaluation succeeded.", "type": "boolean" }, "validation": { "type": "object", "required": [ "valid", "errors" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } }, "expressions": { "type": "object", "required": [ "valid", "errors" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "location": { "type": "object", "required": [ "nodeId", "nodeType", "nodePath" ], "properties": { "nodeId": { "description": "ID of the failing node in the template AST.", "type": "string" }, "nodeType": { "description": "Type of the failing node (e.g. \"text\", \"table\").", "type": "string" }, "nodePath": { "description": "Human-readable breadcrumb through the template AST, e.g. \"Page 1 > Section 'Header' > Text block 3\". Stops at templateRef boundaries.", "type": "string" }, "line": { "minimum": 1, "description": "Line number within the expression (1-based), when extractable.", "type": "integer" }, "column": { "minimum": 1, "description": "Column number within the expression (1-based), when extractable.", "type": "integer" } } }, "suggestion": { "type": "object", "required": [ "variable", "suggestions" ], "properties": { "variable": { "description": "Undefined variable name from the error message.", "type": "string" }, "suggestions": { "description": "Up to 3 close matches from the available data context, sorted by Levenshtein distance.", "type": "array", "items": { "type": "string" } } } } } } } } }, "fieldMappingsApplied": { "minimum": 0, "description": "Number of field mappings applied during data adaptation.", "type": "integer" }, "dataSourcesResolved": { "minimum": 0, "description": "Number of templateRef data sources successfully resolved.", "type": "integer" } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: tenant_unknown, tenant_archived.", "type": "string" } } } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "RenderError" ] }, "code": { "anyOf": [ { "type": "string", "enum": [ "template_expression_error" ] }, { "type": "string", "enum": [ "validation_failed" ] }, { "type": "string", "enum": [ "render_timeout" ] }, { "type": "string", "enum": [ "engine_crash" ] }, { "type": "string", "enum": [ "asset_blocked" ] }, { "type": "string", "enum": [ "data_source_error" ] }, { "type": "string", "enum": [ "no_rendered_tables" ] }, { "type": "string", "enum": [ "ambiguous_table" ] }, { "type": "string", "enum": [ "invalid_pdf" ] }, { "type": "string", "enum": [ "pdf_too_large" ] }, { "type": "string", "enum": [ "too_many_pages" ] }, { "type": "string", "enum": [ "invalid_page_range" ] }, { "type": "string", "enum": [ "unsupported_image" ] }, { "type": "string", "enum": [ "PPTX_PIVOT_UNSUPPORTED" ] }, { "type": "string", "enum": [ "PPTX_PAGEBREAK_IN_COLUMNS" ] }, { "type": "string", "enum": [ "stream_incompatible_hook" ] } ] }, "message": { "type": "string" }, "location": { "type": "object", "required": [ "nodeId", "nodeType", "nodePath" ], "properties": { "nodeId": { "description": "ID of the failing node in the template AST.", "type": "string" }, "nodeType": { "description": "Type of the failing node (e.g. \"text\", \"table\").", "type": "string" }, "nodePath": { "description": "Human-readable breadcrumb through the template AST, e.g. \"Page 1 > Section 'Header' > Text block 3\". Stops at templateRef boundaries.", "type": "string" }, "line": { "minimum": 1, "description": "Line number within the expression (1-based), when extractable.", "type": "integer" }, "column": { "minimum": 1, "description": "Column number within the expression (1-based), when extractable.", "type": "integer" } } }, "suggestion": { "type": "object", "required": [ "variable", "suggestions" ], "properties": { "variable": { "description": "Undefined variable name from the error message.", "type": "string" }, "suggestions": { "description": "Up to 3 close matches from the available data context, sorted by Levenshtein distance.", "type": "array", "items": { "type": "string" } } } } } } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "description": "Optional stable error classifier. Known values: quota_exhausted (sandbox lifetime quota).", "type": "string" } } } } } } } } }, "/render/preview/status": { "get": { "operationId": "getPreviewStatus", "summary": "Preview capability status — cached startup snapshot; always returns 200", "tags": [ "Preview" ], "description": "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.", "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "required": [ "available" ], "properties": { "available": { "type": "boolean", "enum": [ true ] } } }, { "type": "object", "required": [ "available", "reason" ], "properties": { "available": { "type": "boolean", "enum": [ false ] }, "reason": { "anyOf": [ { "type": "string", "enum": [ "routes_disabled" ] }, { "type": "string", "enum": [ "browser_unavailable" ] } ] } } } ] } } } } } } }, "/capabilities": { "get": { "operationId": "getCapabilities", "summary": "Server feature capabilities — per-format render toggles + future flags", "tags": [ "Health" ], "description": "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.", "security": [ { "ApiKeyAuth": [] }, { "EditorTokenAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "formats", "ai", "streaming" ], "properties": { "formats": { "type": "object", "required": [ "pdf", "html", "docx", "csv", "xlsx", "pptx" ], "properties": { "pdf": { "description": "POST /render/pdf is available", "type": "boolean" }, "html": { "description": "POST /render/html is available", "type": "boolean" }, "docx": { "description": "POST /render/docx is available", "type": "boolean" }, "csv": { "description": "POST /render/csv is available", "type": "boolean" }, "xlsx": { "description": "POST /render/xlsx is available", "type": "boolean" }, "pptx": { "description": "POST /render/pptx is available (gated by PPTX_ENABLED env var; beta in v0.60.0)", "type": "boolean" } } }, "ai": { "type": "object", "required": [ "templateGeneration", "nodeRewrite" ], "properties": { "templateGeneration": { "description": "POST /templates/generate is available — AI-assisted draft template generation via Anthropic tool-use. Enabled when ANTHROPIC_API_KEY is set.", "type": "boolean" }, "nodeRewrite": { "description": "POST /nodes/rewrite is available — AI-assisted selection rewrite for text/heading nodes (Stage 2 Feature 1). Same gating as templateGeneration.", "type": "boolean" } } }, "streaming": { "type": "object", "required": [ "singleDoc", "mode" ], "properties": { "singleDoc": { "description": "True if POST /render and /render/preview/pdf stream PDF bytes as they are produced (no full-PDF buffering). Stream-capable in all dispatch modes: in-process, child-process, container, and socket. Clients still receive chunked transfer-encoding from Fastify — the flag documents that the dispatcher layer does not buffer the full PDF.", "type": "boolean" }, "mode": { "description": "Active RENDER_MODE on this server", "anyOf": [ { "type": "string", "enum": [ "in-process" ] }, { "type": "string", "enum": [ "child-process" ] }, { "type": "string", "enum": [ "container" ] }, { "type": "string", "enum": [ "socket" ] } ] } } } } } } } } } } }, "/health": { "get": { "operationId": "getHealth", "summary": "Liveness probe — always 200 if the process is up", "tags": [ "Health" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "version", "timestamp" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "version": { "description": "Application version (SemVer)", "type": "string" }, "timestamp": { "description": "ISO 8601 timestamp", "type": "string" } } } } } } } } }, "/health/ready": { "get": { "operationId": "getHealthReady", "summary": "Readiness probe — 503 if storage is unreachable", "tags": [ "Health" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "version", "timestamp", "checks" ], "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "ok" ] }, { "type": "string", "enum": [ "degraded" ] } ] }, "version": { "description": "Application version (SemVer)", "type": "string" }, "timestamp": { "description": "ISO 8601 timestamp", "type": "string" }, "checks": { "type": "object", "required": [ "storage", "assetBinaryStore", "renderer" ], "properties": { "storage": { "anyOf": [ { "type": "string", "enum": [ "ok" ] }, { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "timeout" ] } ] }, "assetBinaryStore": { "anyOf": [ { "type": "string", "enum": [ "ok" ] }, { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "timeout" ] } ] }, "renderer": { "anyOf": [ { "type": "string", "enum": [ "ok" ] }, { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "timeout" ] } ] }, "rateLimitRedis": { "anyOf": [ { "type": "string", "enum": [ "ok" ] }, { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "timeout" ] } ] } } } } } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "version", "timestamp", "checks" ], "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "ok" ] }, { "type": "string", "enum": [ "degraded" ] } ] }, "version": { "description": "Application version (SemVer)", "type": "string" }, "timestamp": { "description": "ISO 8601 timestamp", "type": "string" }, "checks": { "type": "object", "required": [ "storage", "assetBinaryStore", "renderer" ], "properties": { "storage": { "anyOf": [ { "type": "string", "enum": [ "ok" ] }, { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "timeout" ] } ] }, "assetBinaryStore": { "anyOf": [ { "type": "string", "enum": [ "ok" ] }, { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "timeout" ] } ] }, "renderer": { "anyOf": [ { "type": "string", "enum": [ "ok" ] }, { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "timeout" ] } ] }, "rateLimitRedis": { "anyOf": [ { "type": "string", "enum": [ "ok" ] }, { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "timeout" ] } ] } } } } } } } } } } } }, "tags": [ { "name": "Render", "description": "Production rendering: template key + data → PDF or HTML" }, { "name": "Preview", "description": "Editor preview rendering: inline TemplateDefinition, no DB save required" }, { "name": "Templates", "description": "Template CRUD, version history, and input validation" }, { "name": "Assets", "description": "Image asset upload and management" }, { "name": "Auth", "description": "Editor session token issuance and auth status check" }, { "name": "Admin", "description": "User management and administrative operations" }, { "name": "PDF Transform", "description": "Post-render PDF manipulation: merge, watermark, page insert" }, { "name": "Health", "description": "Liveness and readiness probes" } ] }