{ "components": { "schemas": { "Account": { "properties": { "cycle": { "properties": { "end": { "format": "date-time", "type": "string" }, "start": { "format": "date-time", "type": "string" } }, "type": "object" }, "limits": { "description": "Effective plan limits (docs/05 §10).", "properties": { "bulk_concurrency": { "type": "integer" }, "max_pages": { "type": "integer" }, "max_payload_mb": { "type": "integer" }, "rate_limit_rps": { "type": "integer" }, "sync_concurrency": { "type": "integer" }, "sync_timeout_s": { "type": "integer" } }, "type": "object" }, "plan": { "properties": { "code": { "example": "growth", "type": "string" }, "interval": { "enum": [ "month", "year" ], "type": "string" } }, "type": "object" }, "regions": { "description": "Regions this workspace may render in.", "items": { "example": "eu", "type": "string" }, "type": "array" }, "renders": { "description": "Billed renders in the current cycle (whole numbers).", "properties": { "included": { "description": "Plan allowance.", "type": "integer" }, "prepaid_remaining": { "description": "Left in render packs and auto top-ups.", "type": "integer" }, "remaining_included": { "type": "integer" }, "spend_cap_cents": { "description": "Monthly top-up limit: total cycle spend (plan price + auto top-ups) in euro cents, excluding VAT. 0 = auto top-ups off.", "type": "integer" }, "used": { "description": "Of the allowance.", "type": "integer" } }, "type": "object" }, "workspace": { "properties": { "id": { "example": "ws_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "type": "string" }, "name": { "type": "string" } }, "type": "object" } }, "required": [ "workspace", "plan", "cycle", "renders", "limits", "regions" ], "type": "object" }, "BasicAuth": { "additionalProperties": false, "properties": { "password": { "maxLength": 1024, "title": "Password", "type": "string" }, "username": { "maxLength": 256, "title": "Username", "type": "string" } }, "required": [ "username", "password" ], "title": "BasicAuth", "type": "object" }, "Batch": { "properties": { "canceled": { "type": "integer" }, "combine": { "properties": { "merged_pdf": { "type": "boolean" }, "zip": { "type": "boolean" }, "zip_filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "type": "object" }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "emails": { "$ref": "#/components/schemas/BatchEmailCounts" }, "error": { "anyOf": [ { "description": "Set when a requested combined file failed, which fails the batch: that file's error (the ZIP's first). `null` otherwise. `item_files_expired`: the files of succeeded items expired or were deleted before they could be combined; the combined files hold every succeeded item or none.", "properties": { "code": { "example": "item_files_expired", "type": "string" }, "items": { "description": "`item_files_expired`: indexes of the items whose files are gone, ascending, at most 100.", "items": { "type": "integer" }, "type": "array" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "type": "null" } ] }, "failed": { "type": "integer" }, "files": { "items": { "$ref": "#/components/schemas/BatchFile" }, "type": "array" }, "id": { "example": "bat_01J9ZN4T6V8X0Z2B4D6F8H0K2M", "type": "string" }, "metadata": { "additionalProperties": true, "type": "object" }, "object": { "enum": [ "batch" ], "type": "string" }, "paused": { "anyOf": [ { "description": "Set while the batch waits for renders: no item is released until a render pack, a plan change or the next cycle makes renders available again, then the batch resumes on its own (checked about once a minute). Items in flight finish normally; canceling works as usual. `null` otherwise.", "properties": { "reason": { "enum": [ "render_limit_reached" ], "type": "string" }, "since": { "format": "date-time", "type": "string" } }, "required": [ "reason", "since" ], "type": "object" }, { "type": "null" } ] }, "pending": { "description": "Items without a final status yet.", "type": "integer" }, "progress": { "description": "Finished items ÷ total.", "maximum": 1, "minimum": 0, "type": "number" }, "reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "queued", "processing", "completed", "failed", "canceled" ], "type": "string" }, "succeeded": { "type": "integer" }, "template_id": { "example": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "type": "string" }, "template_version": { "anyOf": [ { "description": "Version number rendered.", "type": "integer" }, { "type": "null" } ] }, "test": { "type": "boolean" }, "total": { "type": "integer" } }, "required": [ "id", "object", "status", "test", "total", "files", "created_at" ], "type": "object" }, "BatchEmailCounts": { "description": "The newest email of each item and rule, by status (a resend replaces the email it repeats): `pending` includes `sending` and `retrying`, `sent` includes `sandboxed`.", "properties": { "canceled": { "minimum": 0, "type": "integer" }, "failed": { "minimum": 0, "type": "integer" }, "pending": { "minimum": 0, "type": "integer" }, "sent": { "minimum": 0, "type": "integer" }, "skipped": { "minimum": 0, "type": "integer" }, "unknown": { "minimum": 0, "type": "integer" } }, "required": [ "sent", "failed", "unknown", "pending", "skipped", "canceled" ], "type": "object" }, "BatchFile": { "description": "A combined output of the batch.", "properties": { "bytes": { "example": 1843200, "type": "integer" }, "content_type": { "example": "application/zip", "type": "string" }, "expires_at": { "anyOf": [ { "description": "When the hosted file is deleted.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "file_id": { "example": "file_01J9ZM1X3F7R8K2C4V6B8N0P2R", "type": "string" }, "filename": { "example": "certificates.zip", "type": "string" }, "kind": { "enum": [ "zip", "merged_pdf" ], "type": "string" }, "pages": { "anyOf": [ { "description": "Merged PDF only.", "type": "integer" }, { "type": "null" } ] }, "url": { "description": "Signed URL (omitted when not hosted).", "format": "uri", "type": "string" }, "url_expires_at": { "format": "date-time", "type": "string" } }, "required": [ "kind", "file_id", "filename", "content_type", "bytes" ], "type": "object" }, "BatchItem": { "properties": { "error": { "anyOf": [ { "additionalProperties": true, "description": "The render error; after a retry `previous_render_id` names the old one.", "type": "object" }, { "type": "null" } ] }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "index": { "description": "0-based position in `items` (or CSV data row).", "type": "integer" }, "reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "render_id": { "anyOf": [ { "description": "Set once the item is released.", "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "pending", "queued", "succeeded", "failed", "canceled" ], "type": "string" } }, "required": [ "index", "status" ], "type": "object" }, "BatchItemList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/BatchItem" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "object": { "enum": [ "list" ], "type": "string" } }, "required": [ "object", "data", "has_more" ], "type": "object" }, "BatchItemSpec": { "additionalProperties": false, "properties": { "data": { "additionalProperties": true, "title": "Data", "type": "object" }, "filename": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Filename" }, "metadata": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "propertyNames": { "maxLength": 40, "minLength": 1 }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Metadata" }, "reference": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Reference" } }, "title": "BatchItemSpec", "type": "object" }, "BatchList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Batch" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "object": { "enum": [ "list" ], "type": "string" } }, "required": [ "object", "data", "has_more" ], "type": "object" }, "BatchRequest": { "additionalProperties": false, "properties": { "combine": { "anyOf": [ { "$ref": "#/components/schemas/CombineSpec" }, { "type": "null" } ], "default": null }, "csv_mapping": { "anyOf": [ { "additionalProperties": { "maxLength": 200, "minLength": 1, "type": "string" }, "maxProperties": 500, "propertyNames": { "maxLength": 200, "minLength": 1 }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Csv Mapping" }, "csv_upload_id": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "title": "Csv Upload Id" }, "delivery": { "anyOf": [ { "$ref": "#/components/schemas/DeliverySpec" }, { "type": "null" } ], "default": null }, "engine": { "anyOf": [ { "pattern": "^\\d{4}\\.\\d{1,6}$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Engine" }, "items": { "anyOf": [ { "items": { "$ref": "#/components/schemas/BatchItemSpec" }, "maxItems": 100000, "type": "array" }, { "type": "null" } ], "default": null, "title": "Items" }, "metadata": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "propertyNames": { "maxLength": 40, "minLength": 1 }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Metadata" }, "output": { "anyOf": [ { "$ref": "#/components/schemas/OutputSpec" }, { "type": "null" } ], "default": null }, "reference": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Reference" }, "template_id": { "maxLength": 64, "minLength": 1, "title": "Template Id", "type": "string" }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Test" }, "version": { "anyOf": [ { "const": "live", "type": "string" }, { "minimum": 1, "type": "integer" } ], "default": "live", "title": "Version" }, "webhook": { "anyOf": [ { "$ref": "#/components/schemas/BatchWebhookSpec" }, { "type": "null" } ], "default": null } }, "required": [ "template_id" ], "title": "BatchRequest", "type": "object" }, "BatchResendEmailsRequest": { "additionalProperties": false, "description": "`POST /v1/batches/{id}/resend-emails` (proto/README.md §24.8).", "properties": { "statuses": { "description": "Resend the newest email of each render and rule when its status is listed.", "items": { "enum": [ "failed", "unknown" ], "type": "string" }, "maxItems": 2, "minItems": 1, "title": "Statuses", "type": "array" } }, "title": "BatchResendEmailsRequest", "type": "object" }, "BatchResendEmailsResult": { "properties": { "resent": { "type": "integer" }, "skipped": { "description": "Emails that could not be resent (at most 100 listed).", "items": { "properties": { "code": { "enum": [ "email_not_resendable", "email_file_expired" ], "type": "string" }, "send_id": { "type": "string" } }, "type": "object" }, "maxItems": 100, "type": "array" } }, "required": [ "resent", "skipped" ], "type": "object" }, "BatchWebhookSpec": { "additionalProperties": false, "properties": { "events": { "items": { "enum": [ "batch.progress", "batch.completed" ], "type": "string" }, "maxItems": 2, "minItems": 1, "title": "Events", "type": "array" }, "format": { "const": "standard", "default": "standard", "title": "Format", "type": "string" }, "url": { "maxLength": 2048, "minLength": 8, "title": "Url", "type": "string" } }, "required": [ "url" ], "title": "BatchWebhookSpec", "type": "object" }, "CombineSpec": { "additionalProperties": false, "properties": { "merged_pdf": { "default": false, "title": "Merged Pdf", "type": "boolean" }, "zip": { "default": false, "title": "Zip", "type": "boolean" }, "zip_filename": { "anyOf": [ { "maxLength": 200, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "title": "Zip Filename" } }, "title": "CombineSpec", "type": "object" }, "ConformanceFinding": { "description": "One validator finding; identical rule + location are merged (`count`).", "properties": { "count": { "minimum": 1, "type": "integer" }, "location": { "description": "JSON path into the invoice for model issues found before the XML was written, else the validator's XPath or veraPDF context; empty when the finding concerns the whole document (e.g. a PDF/A `conversion` error).", "example": "invoice.seller.contact.email", "type": "string" }, "message": { "type": "string" }, "rule": { "description": "Business rule (EN 16931 `BR-…`, XRechnung `BR-DE-…`), schema rule, or PDF/A or PDF/UA clause and test number (`6.2.4.3-2`, `7.3-1`).", "example": "BR-DE-15", "type": "string" } }, "required": [ "rule", "message", "location", "count" ], "type": "object" }, "ConformanceReport": { "description": "Validation of the delivered file against the standards it claims.", "properties": { "einvoice": { "$ref": "#/components/schemas/EInvoiceConformance" }, "pdfa": { "$ref": "#/components/schemas/PdfaConformance" }, "pdfua": { "$ref": "#/components/schemas/PdfuaConformance" } }, "type": "object" }, "Cookie": { "additionalProperties": false, "properties": { "domain": { "anyOf": [ { "maxLength": 253, "type": "string" }, { "type": "null" } ], "default": null, "title": "Domain" }, "http_only": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Http Only" }, "name": { "maxLength": 256, "minLength": 1, "title": "Name", "type": "string" }, "path": { "anyOf": [ { "maxLength": 1024, "type": "string" }, { "type": "null" } ], "default": null, "title": "Path" }, "secure": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Secure" }, "value": { "maxLength": 4096, "title": "Value", "type": "string" } }, "required": [ "name", "value" ], "title": "Cookie", "type": "object" }, "DeliverySpec": { "additionalProperties": false, "properties": { "email": { "anyOf": [ { "oneOf": [ { "const": false, "type": "boolean" }, { "items": { "$ref": "#/components/schemas/EmailTargetSpec" }, "maxItems": 5, "minItems": 1, "type": "array" } ] }, { "type": "null" } ], "default": null, "description": "Email rules (Growth plan and up; proto/README.md §24.3). Absent or `null`: the template's enabled rules; `false`: none; a list: only those rules, optionally with literal `to`/`cc`/`bcc`. Template renders only (not previews, signed links, PDF tools or zero-retention renders).", "title": "Email" }, "expires_in": { "default": 3600, "maximum": 604800, "minimum": 60, "title": "Expires In", "type": "integer" }, "hosted": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Keep the hosted copy; `false` deletes it once the storage uploads and email sends have succeeded. Absent or `null`: `false` when every storage destination of the render has `keep_hosted_copy: false`, else `true`. Zero-retention renders never keep one.", "title": "Hosted" }, "retention": { "anyOf": [ { "enum": [ "none", "default" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Retention" }, "retention_days": { "anyOf": [ { "maximum": 36500, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null, "title": "Retention Days" }, "storage": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StorageTargetSpec" }, "maxItems": 10, "type": "array" }, { "type": "null" } ], "default": null, "title": "Storage" }, "type": { "anyOf": [ { "enum": [ "url", "binary", "base64", "none" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "`url`: signed file URLs in the response; `binary` / `base64`: the file itself (sync only); `none`: no file in the response (storage destinations, email). Absent or `null`: `url` when the render keeps a hosted copy, else `none`.", "title": "Type" } }, "title": "DeliverySpec", "type": "object" }, "EInvoiceConformance": { "properties": { "errors": { "items": { "$ref": "#/components/schemas/ConformanceFinding" }, "maxItems": 100, "type": "array" }, "profile": { "enum": [ "MINIMUM", "BASIC_WL", "BASIC", "EN16931", "EXTENDED", "XRECHNUNG" ], "type": "string" }, "scenario": { "anyOf": [ { "description": "The validator scenario that matched; `null` when it did not run.", "example": "EN16931 XRechnung (CII)", "type": "string" }, { "type": "null" } ] }, "status": { "description": "`unavailable`: the validator was not configured or did not answer in time; the file was delivered unvalidated (warning `einvoice_validation_unavailable`).", "enum": [ "passed", "failed", "unavailable" ], "type": "string" }, "syntax": { "enum": [ "cii", "ubl" ], "type": "string" }, "validator": { "anyOf": [ { "description": "`null` when the validator did not run (`einvoice_invalid`: the model broke a rule before any XML was written, or unavailable).", "example": "KoSIT Validator 1.6.3", "type": "string" }, { "type": "null" } ] }, "warnings": { "items": { "$ref": "#/components/schemas/ConformanceFinding" }, "maxItems": 100, "type": "array" } }, "required": [ "profile", "syntax", "status", "validator", "scenario", "errors", "warnings" ], "type": "object" }, "EInvoiceRequest": { "additionalProperties": false, "description": "The e-invoice XML itself as the output file; the envelope fields behave as on `POST /v1/renders`.", "properties": { "delivery": { "anyOf": [ { "$ref": "#/components/schemas/DeliverySpec" }, { "type": "null" } ], "default": null }, "filename": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "description": "Output filename (`.xml` is enforced). Default: the invoice number, sanitised, + `.xml`.", "title": "Filename" }, "invoice": { "allOf": [ { "$ref": "#/components/schemas/Invoice" } ], "description": "The invoice model (EN 16931 business terms).", "title": "Invoice" }, "metadata": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "propertyNames": { "maxLength": 40, "minLength": 1 }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Metadata" }, "mode": { "default": "sync", "enum": [ "sync", "async" ], "title": "Mode", "type": "string" }, "priority": { "default": "normal", "enum": [ "normal", "low" ], "title": "Priority", "type": "string" }, "profile": { "description": "EN 16931 profile of the XML: `XRECHNUNG` (German public sector), `EN16931`, or a Factur-X / ZUGFeRD profile (`MINIMUM`, `BASIC_WL`, `BASIC`, `EXTENDED`; CII only).", "enum": [ "MINIMUM", "BASIC_WL", "BASIC", "EN16931", "EXTENDED", "XRECHNUNG" ], "title": "Profile", "type": "string" }, "reference": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Reference" }, "syntax": { "default": "cii", "description": "`cii` (UN/CEFACT Cross Industry Invoice D16B) or `ubl` (UBL 2.1 Invoice / CreditNote; `EN16931` and `XRECHNUNG` only).", "enum": [ "cii", "ubl" ], "title": "Syntax", "type": "string" }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Test" }, "timeout_behavior": { "default": "continue", "enum": [ "continue", "cancel" ], "title": "Timeout Behavior", "type": "string" }, "webhook": { "anyOf": [ { "$ref": "#/components/schemas/WebhookSpec" }, { "type": "null" } ], "default": null } }, "required": [ "profile", "invoice" ], "title": "EInvoiceRequest", "type": "object" }, "EInvoiceSpec": { "additionalProperties": false, "description": "`output.einvoice`: embed a Factur-X / ZUGFeRD / XRechnung invoice in a PDF/A-3b (hybrid PDF).", "properties": { "invoice": { "allOf": [ { "$ref": "#/components/schemas/Invoice" } ], "default": null, "description": "The invoice model (EN 16931 business terms); exactly one of `invoice`, `invoice_path`.", "title": "Invoice" }, "invoice_path": { "anyOf": [ { "maxLength": 200, "minLength": 1, "pattern": "^[^.\\s][^.]*(\\.[^.\\s][^.]*)*$", "type": "string" }, { "type": "null" } ], "default": null, "description": "Dotted path of object keys into `data` that holds the invoice model, e.g. `invoice` or `order.invoice` (each batch item resolves it in its own data).", "examples": [ "invoice" ], "title": "Invoice Path" }, "profile": { "description": "Factur-X / ZUGFeRD profile, or `XRECHNUNG` (German CIUS, embedded as `xrechnung.xml`).", "enum": [ "MINIMUM", "BASIC_WL", "BASIC", "EN16931", "EXTENDED", "XRECHNUNG" ], "title": "Profile", "type": "string" }, "syntax": { "anyOf": [ { "enum": [ "cii", "ubl" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "Hybrid PDFs embed UN/CEFACT CII: omit or `\"cii\"` (UBL XML: `POST /v1/einvoices`).", "title": "Syntax" } }, "required": [ "profile" ], "title": "EInvoiceSpec", "type": "object" }, "EmailConnection": { "properties": { "config": { "additionalProperties": {}, "description": "The provider's settings (see the write `config`), always with `attachment_budget_bytes` and `max_per_second`: the provider's defaults unless set.", "type": "object" }, "created_at": { "format": "date-time", "type": "string" }, "credentials": { "$ref": "#/components/schemas/EmailCredentialsState" }, "credentials_delete_at": { "description": "Set after a downgrade: the credentials are deleted then.", "format": "date-time", "type": [ "string", "null" ] }, "default_from": { "$ref": "#/components/schemas/EmailDefaultFrom" }, "egress_ips": { "description": "The addresses our email traffic leaves from: authorize them at providers that restrict calling IPs (Brevo: Security → Authorized IPs).", "items": { "type": "string" }, "type": "array" }, "events": { "additionalProperties": { "description": "* `registered` - registered\n* `failed` - failed", "enum": [ "registered", "failed" ], "type": "string", "x-spec-enum-id": "f519474cfe52e720" }, "description": "Brevo connections only: the delivery-events webhook in the Brevo account, per region; empty for other providers.", "type": "object" }, "id": { "description": "`emc_…`", "type": "string" }, "last_error": { "oneOf": [ { "$ref": "#/components/schemas/EmailConnectionError" }, { "type": "null" } ] }, "last_test_at": { "format": "date-time", "type": [ "string", "null" ] }, "last_test_status": { "description": "* `succeeded` - succeeded\n* `failed` - failed", "enum": [ "succeeded", "failed", null ], "type": [ "string", "null" ], "x-spec-enum-id": "c784105c2922494d" }, "name": { "type": "string" }, "object": { "default": "email_connection", "type": "string" }, "provider": { "description": "* `brevo` - Brevo\n* `smtp` - SMTP\n* `postmark` - Postmark\n* `resend` - Resend\n* `ses` - Amazon SES\n* `graph` - Microsoft 365 (Graph)", "enum": [ "brevo", "smtp", "postmark", "resend", "ses", "graph" ], "type": "string", "x-spec-enum-id": "e7a31054cb3443ae" }, "reply_to": { "type": [ "string", "null" ] }, "senders": { "description": "Verified senders and domains found by the last test.", "items": { "$ref": "#/components/schemas/EmailSender" }, "type": "array" }, "status": { "description": "* `active` - active\n* `failing` - failing", "enum": [ "active", "failing" ], "type": "string", "x-spec-enum-id": "998d9403dd142d1d" }, "test_mode": { "description": "* `sandbox` - Sandbox\n* `redirect` - Redirect\n* `skip` - Skip", "enum": [ "sandbox", "redirect", "skip" ], "type": "string", "x-spec-enum-id": "edd83b93494872a4" }, "test_recipient": { "type": [ "string", "null" ] }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "config", "created_at", "credentials", "credentials_delete_at", "default_from", "egress_ips", "events", "id", "last_error", "last_test_at", "last_test_status", "name", "provider", "reply_to", "senders", "status", "test_mode", "test_recipient", "updated_at" ], "type": "object" }, "EmailConnectionError": { "properties": { "at": { "format": "date-time", "type": "string" }, "code": { "description": "`email_provider_auth_failed`, `email_ip_not_authorized` or `email_credentials_removed`.", "type": "string" }, "message": { "type": "string" } }, "required": [ "at", "code", "message" ], "type": "object" }, "EmailConnectionList": { "description": "Cursor-pagination envelope (docs/05 §1). Management lists are single-page today.", "properties": { "data": { "items": { "$ref": "#/components/schemas/EmailConnection" }, "type": "array" }, "egress_ips": { "description": "The addresses our email traffic leaves from: authorize them at providers that restrict calling IPs (Brevo: Security → Authorized IPs).", "items": { "type": "string" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "object": { "default": "list", "type": "string" } }, "required": [ "data", "egress_ips", "has_more", "next_cursor" ], "type": "object" }, "EmailConnectionTest": { "properties": { "connection": { "$ref": "#/components/schemas/EmailConnection" }, "object": { "default": "email_connection_test", "type": "string" }, "ok": { "type": "boolean" }, "senders": { "items": { "$ref": "#/components/schemas/EmailSender" }, "type": "array" }, "steps": { "items": { "$ref": "#/components/schemas/EmailTestStep" }, "type": "array" } }, "required": [ "connection", "ok", "senders", "steps" ], "type": "object" }, "EmailConnectionTestRequest": { "properties": { "send_to": { "description": "Also send a real test email to this address: the verified address of a workspace member.", "maxLength": 254, "type": [ "string", "null" ] } }, "type": "object" }, "EmailConnectionWrite": { "properties": { "config": { "additionalProperties": {}, "description": "Per provider: SMTP `{host, port, username}` (port 587 or 2525); Postmark `{message_stream}` (default `outbound`, also when empty or null); Amazon SES `{region, configuration_set?}`; Microsoft 365 `{tenant_id, client_id, sender}` (`sender`: the mailbox that sends); Brevo and Resend none. Every provider: `attachment_budget_bytes`, the bytes of files attached per email (default / maximum: Brevo 10 / 13 MiB, SMTP 6 / 25 MiB, Postmark 6 / 6 MiB, Resend 10 / 25 MiB, Amazon SES 10 / 25 MiB, Microsoft 365 2 / 2 MiB), and `max_per_second` (1 to 100, default 10).", "type": "object" }, "credentials": { "additionalProperties": {}, "description": "Write-only: Brevo `{api_key}` (an API key, not its SMTP key), SMTP `{password}`, Postmark `{server_token}`, Resend `{api_key}`, Amazon SES `{access_key_id, secret_access_key}`, Microsoft 365 `{client_secret}`. A PATCH without them keeps them.", "type": "object" }, "default_from": { "$ref": "#/components/schemas/EmailDefaultFromWrite" }, "name": { "maxLength": 100, "type": "string" }, "provider": { "description": "`brevo`, `smtp`, `postmark`, `resend`, `ses` (Amazon SES) or `graph` (Microsoft 365); it can't change after creation.\n\n* `brevo` - Brevo\n* `smtp` - SMTP\n* `postmark` - Postmark\n* `resend` - Resend\n* `ses` - Amazon SES\n* `graph` - Microsoft 365 (Graph)", "enum": [ "brevo", "smtp", "postmark", "resend", "ses", "graph" ], "type": "string", "x-spec-enum-id": "e7a31054cb3443ae" }, "reply_to": { "maxLength": 254, "type": [ "string", "null" ] }, "test_mode": { "description": "Test renders: `sandbox` (Brevo only, and its default: Brevo checks the email without delivering it), `redirect` (to `test_recipient`, subject prefixed `[Test] `), `skip` (no provider call; the default for every other provider).\n\n* `sandbox` - Sandbox\n* `redirect` - Redirect\n* `skip` - Skip", "enum": [ "sandbox", "redirect", "skip" ], "type": "string", "x-spec-enum-id": "edd83b93494872a4" }, "test_recipient": { "description": "The verified address of a workspace member; required with `test_mode: redirect`.", "maxLength": 254, "type": [ "string", "null" ] } }, "required": [ "default_from", "name", "provider" ], "type": "object" }, "EmailCredentialsState": { "properties": { "configured": { "description": "Credentials are write-only; `false` once they were deleted after a downgrade.", "type": "boolean" } }, "required": [ "configured" ], "type": "object" }, "EmailDefaultFrom": { "properties": { "email": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "email", "name" ], "type": "object" }, "EmailDefaultFromWrite": { "properties": { "email": { "description": "One address: the sender of rules without their own.", "maxLength": 254, "type": "string" }, "name": { "maxLength": 255, "type": [ "string", "null" ] } }, "required": [ "email" ], "type": "object" }, "EmailDeliveryCounts": { "description": "The recipients' delivery events, by kind: only Brevo reports them, so other providers' sends show zeros. `bounced` counts soft and hard bounces.", "properties": { "blocked": { "minimum": 0, "type": "integer" }, "bounced": { "minimum": 0, "type": "integer" }, "complained": { "minimum": 0, "type": "integer" }, "deferred": { "minimum": 0, "type": "integer" }, "delivered": { "minimum": 0, "type": "integer" }, "invalid": { "minimum": 0, "type": "integer" } }, "required": [ "delivered", "deferred", "bounced", "blocked", "complained", "invalid" ], "type": "object" }, "EmailMailbox": { "properties": { "email": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "email" ], "type": "object" }, "EmailPreview": { "description": "What the rule would send for the previewed render; nothing is sent. `send` is false with `skip_reason` (the condition is false) or `error` (a template error, the recipients or the attachments). `html` and `text` keep the download-links marker the deliverer fills; an empty `text` is derived from `html` when sending.", "properties": { "attachments": { "items": { "$ref": "#/components/schemas/EmailSendAttachment" }, "type": "array" }, "bcc": { "items": { "$ref": "#/components/schemas/EmailMailbox" }, "type": "array" }, "cc": { "items": { "$ref": "#/components/schemas/EmailMailbox" }, "type": "array" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/RenderError" }, { "type": "null" } ] }, "from_email": { "type": "string" }, "from_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "html": { "type": "string" }, "provider_template": { "anyOf": [ { "properties": { "id": { "type": "integer" }, "params": { "additionalProperties": true, "type": "object" } }, "type": "object" }, { "type": "null" } ] }, "recipient_errors": { "description": "Every recipient entry that is not an address.", "items": { "type": "string" }, "type": "array" }, "reply_to": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "send": { "type": "boolean" }, "skip_reason": { "anyOf": [ { "enum": [ "condition_false" ], "type": "string" }, { "type": "null" } ] }, "subject": { "type": "string" }, "text": { "type": "string" }, "to": { "items": { "$ref": "#/components/schemas/EmailMailbox" }, "type": "array" } }, "required": [ "send", "skip_reason", "error", "from_email", "from_name", "reply_to", "to", "cc", "bcc", "subject", "html", "text", "attachments" ], "type": "object" }, "EmailProviderTemplate": { "properties": { "id": { "description": "The template's id in the Brevo account.", "minimum": 1, "type": "integer" }, "params": { "description": "Template source that must render to a JSON object (≤ 64 KiB).", "type": "string" } }, "required": [ "id", "params" ], "type": "object" }, "EmailProviderTemplateSpec": { "additionalProperties": false, "description": "A Brevo template the rule sends instead of its own body; Brevo connections only (§24.15).", "properties": { "id": { "description": "The template id in the Brevo account.", "minimum": 1, "title": "Id", "type": "integer" }, "params": { "default": "", "description": "Template source that must render to a JSON object (Brevo's `params`).", "maxLength": 65536, "title": "Params", "type": "string" } }, "required": [ "id" ], "title": "EmailProviderTemplateSpec", "type": "object" }, "EmailRule": { "properties": { "attach_formats": { "items": { "type": "string" }, "type": "array" }, "attachments": { "description": "* `attach_or_link` - Attach Or Link\n* `attach` - Attach\n* `link` - Link\n* `none` - None", "enum": [ "attach_or_link", "attach", "link", "none" ], "type": "string", "x-spec-enum-id": "31eaadd397405cc6" }, "bcc": { "type": "string" }, "cc": { "type": "string" }, "condition": { "type": "string" }, "connection_id": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "enabled": { "type": "boolean" }, "from_email": { "description": "null = the connection's default sender.", "type": [ "string", "null" ] }, "from_name": { "type": "string" }, "html": { "type": "string" }, "id": { "description": "`emr_…`", "type": "string" }, "name": { "type": "string" }, "object": { "default": "email_rule", "type": "string" }, "position": { "description": "0 to 4: the order the template's rules send in.", "type": "integer" }, "provider_template": { "oneOf": [ { "$ref": "#/components/schemas/EmailProviderTemplate" }, { "type": "null" } ] }, "reply_to": { "type": "string" }, "subject": { "type": "string" }, "template_id": { "type": "string" }, "text": { "type": "string" }, "to": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "warnings": { "description": "On create and update responses.", "items": { "$ref": "#/components/schemas/EmailRuleWarning" }, "type": "array" } }, "required": [ "attach_formats", "attachments", "bcc", "cc", "condition", "connection_id", "created_at", "enabled", "from_email", "from_name", "html", "id", "name", "position", "provider_template", "reply_to", "subject", "template_id", "text", "to", "updated_at" ], "type": "object" }, "EmailRuleDraftPreviewRequest": { "additionalProperties": false, "description": "`POST /v1/email-rules/preview`: a rule that has not been saved yet.", "properties": { "data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Data" }, "dataset_id": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "title": "Dataset Id" }, "rule": { "$ref": "#/components/schemas/EmailRuleSpec", "description": "The rule's fields; `connection_id` is required." }, "template_id": { "maxLength": 64, "minLength": 1, "title": "Template Id", "type": "string" } }, "required": [ "template_id", "rule" ], "title": "EmailRuleDraftPreviewRequest", "type": "object" }, "EmailRuleList": { "description": "Cursor-pagination envelope (docs/05 §1). Management lists are single-page today.", "properties": { "data": { "items": { "$ref": "#/components/schemas/EmailRule" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "object": { "default": "list", "type": "string" } }, "required": [ "data", "has_more", "next_cursor" ], "type": "object" }, "EmailRulePreviewRequest": { "additionalProperties": false, "description": "`POST /v1/email-rules/{id}/preview`. Data: `data`, else `dataset_id`, else the default dataset.", "properties": { "data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Data" }, "dataset_id": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "A dataset (`ds_…`) of the template.", "title": "Dataset Id" }, "rule": { "anyOf": [ { "$ref": "#/components/schemas/EmailRuleSpec" }, { "type": "null" } ], "default": null, "description": "Unsaved fields instead of the saved rule." } }, "title": "EmailRulePreviewRequest", "type": "object" }, "EmailRuleSpec": { "description": "The editable fields of an email rule, as the rule editor holds them (unsaved state, §24.17).\n\nUsed instead of the saved rule; fields the editor does not know (`name`, `enabled`, …) are ignored. `null`\ncounts as empty. Syntax errors come back as the preview's `email_preview.error`.", "properties": { "attach_formats": { "anyOf": [ { "items": { "enum": [ "pdf", "png", "jpeg", "webp", "html", "xml", "zip" ], "type": "string" }, "maxItems": 7, "type": "array" }, { "type": "null" } ], "default": null, "title": "Attach Formats" }, "attachments": { "anyOf": [ { "enum": [ "attach_or_link", "attach", "link", "none" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Attachments" }, "bcc": { "anyOf": [ { "maxLength": 16384, "type": "string" }, { "type": "null" } ], "default": null, "title": "Bcc" }, "cc": { "anyOf": [ { "maxLength": 16384, "type": "string" }, { "type": "null" } ], "default": null, "title": "Cc" }, "condition": { "anyOf": [ { "maxLength": 16384, "type": "string" }, { "type": "null" } ], "default": null, "title": "Condition" }, "connection_id": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "`emc_…`; defaults to the saved rule's connection.", "title": "Connection Id" }, "from_email": { "anyOf": [ { "maxLength": 254, "type": "string" }, { "type": "null" } ], "default": null, "title": "From Email" }, "from_name": { "anyOf": [ { "maxLength": 16384, "type": "string" }, { "type": "null" } ], "default": null, "title": "From Name" }, "html": { "anyOf": [ { "maxLength": 262144, "type": "string" }, { "type": "null" } ], "default": null, "title": "Html" }, "provider_template": { "anyOf": [ { "$ref": "#/components/schemas/EmailProviderTemplateSpec" }, { "type": "null" } ], "default": null }, "reply_to": { "anyOf": [ { "maxLength": 16384, "type": "string" }, { "type": "null" } ], "default": null, "title": "Reply To" }, "subject": { "anyOf": [ { "maxLength": 16384, "type": "string" }, { "type": "null" } ], "default": null, "title": "Subject" }, "text": { "anyOf": [ { "maxLength": 16384, "type": "string" }, { "type": "null" } ], "default": null, "title": "Text" }, "to": { "anyOf": [ { "maxLength": 16384, "type": "string" }, { "type": "null" } ], "default": null, "title": "To" } }, "title": "EmailRuleSpec", "type": "object" }, "EmailRuleTestRequest": { "additionalProperties": false, "description": "`POST /v1/email-rules/{id}/test`: a test render whose one email goes to `to`.", "properties": { "data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Data" }, "dataset_id": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "title": "Dataset Id" }, "rule": { "anyOf": [ { "$ref": "#/components/schemas/EmailRuleSpec" }, { "type": "null" } ], "default": null, "description": "Unsaved fields instead of the saved rule." }, "to": { "description": "The verified email address of an active member of the workspace.", "maxLength": 254, "minLength": 3, "title": "To", "type": "string" } }, "required": [ "to" ], "title": "EmailRuleTestRequest", "type": "object" }, "EmailRuleWarning": { "properties": { "code": { "description": "`email_sender_unverified`", "type": "string" }, "message": { "type": "string" }, "path": { "type": "string" } }, "required": [ "code", "message", "path" ], "type": "object" }, "EmailRuleWrite": { "properties": { "attach_formats": { "description": "Only files of these formats; empty = every file.", "items": { "description": "* `pdf` - pdf\n* `png` - png\n* `jpeg` - jpeg\n* `webp` - webp\n* `html` - html\n* `xml` - xml\n* `zip` - zip", "enum": [ "pdf", "png", "jpeg", "webp", "html", "xml", "zip" ], "type": "string", "x-spec-enum-id": "22bc71b676b2a590" }, "maxItems": 7, "type": "array" }, "attachments": { "default": "attach_or_link", "description": "* `attach_or_link` - Attach Or Link\n* `attach` - Attach\n* `link` - Link\n* `none` - None", "enum": [ "attach_or_link", "attach", "link", "none" ], "type": "string", "x-spec-enum-id": "31eaadd397405cc6" }, "bcc": { "type": [ "string", "null" ] }, "cc": { "type": [ "string", "null" ] }, "condition": { "description": "An expression; the rule sends when it is true. Empty = always.", "type": [ "string", "null" ] }, "connection_id": { "description": "`emc_…` of this workspace.", "type": "string" }, "enabled": { "default": true, "type": "boolean" }, "from_email": { "description": "Literal; empty = the connection's default sender. One the provider hasn't verified is saved with the warning `email_sender_unverified`.", "maxLength": 254, "type": [ "string", "null" ] }, "from_name": { "description": "Template source; one line after rendering.", "type": [ "string", "null" ] }, "html": { "description": "Template source, values HTML-escaped (≤ 256 KiB).", "type": [ "string", "null" ] }, "name": { "maxLength": 100, "type": "string" }, "position": { "description": "0 to 4; the others move. Default: the end.", "maximum": 4, "minimum": 0, "type": "integer" }, "provider_template": { "oneOf": [ { "$ref": "#/components/schemas/EmailProviderTemplate" }, { "type": "null" } ] }, "reply_to": { "description": "Template source; one line after rendering.", "type": [ "string", "null" ] }, "subject": { "description": "Template source; required unless a provider template gives it.", "type": [ "string", "null" ] }, "text": { "description": "Template source; empty = derived from `html`.", "type": [ "string", "null" ] }, "to": { "description": "Template source rendering to addresses separated by `,` `;` or line breaks.", "type": [ "string", "null" ] } }, "required": [ "connection_id", "name" ], "type": "object" }, "EmailSend": { "description": "One email of a render and rule. Only `to` shows addresses; cc and bcc are counts.", "properties": { "attachments": { "items": { "$ref": "#/components/schemas/EmailSendAttachment" }, "type": "array" }, "attempts": { "type": "integer" }, "batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bcc_count": { "type": "integer" }, "cc_count": { "type": "integer" }, "connection_id": { "example": "emc_01J9ZK3M7Q8V5W2X4Y6Z8A0B1F", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "delivery": { "$ref": "#/components/schemas/EmailDeliveryCounts" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/EmailSendError" }, { "type": "null" } ] }, "id": { "example": "ems_01J9ZM1X3F7R8K2C4V6B8N0P2T", "type": "string" }, "mode": { "description": "`live`; for test renders the connection's `test_mode` (`sandbox`, `redirect`, `skip`); `redirect` for a rule test.", "enum": [ "live", "sandbox", "redirect", "skip" ], "type": "string" }, "object": { "enum": [ "email_send" ], "type": "string" }, "provider": { "enum": [ "brevo", "smtp", "postmark", "resend", "ses", "graph" ], "type": "string" }, "provider_message_id": { "anyOf": [ { "description": "The provider's id of the message; for SMTP the `Message-ID` we set. Microsoft 365 (`graph`) returns none.", "type": "string" }, { "type": "null" } ] }, "render_id": { "example": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "type": "string" }, "resend_of": { "anyOf": [ { "description": "The send this one repeats (`ems_…`).", "type": "string" }, { "type": "null" } ] }, "rule_id": { "example": "emr_01J9ZK3M7Q8V5W2X4Y6Z8A0B1E", "type": "string" }, "sandbox": { "description": "Sent with Brevo's sandbox header: nothing is delivered.", "type": "boolean" }, "sent_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "skip_reason": { "anyOf": [ { "enum": [ "condition_false", "test_mode" ], "type": "string" }, { "type": "null" } ] }, "status": { "description": "`unknown`: the provider may have delivered it (e.g. a timeout after sending); it is never retried automatically: check the provider's logs (the message carries `X-Dda-Send-Id`) before resending.", "enum": [ "pending", "sending", "retrying", "sent", "sandboxed", "skipped", "failed", "unknown", "canceled" ], "type": "string" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "template_id": { "anyOf": [ { "example": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "type": "string" }, { "type": "null" } ] }, "test": { "type": "boolean" }, "to": { "items": { "type": "string" }, "type": "array" } }, "required": [ "id", "object", "render_id", "batch_id", "template_id", "rule_id", "connection_id", "status", "skip_reason", "mode", "test", "sandbox", "to", "cc_count", "bcc_count", "subject", "attachments", "provider", "provider_message_id", "attempts", "error", "delivery", "resend_of", "created_at", "sent_at" ], "type": "object" }, "EmailSendAttachment": { "properties": { "bytes": { "example": 48213, "type": "integer" }, "file_id": { "example": "file_01J9ZM1X3F7R8K2C4V6B8N0P2R", "type": "string" }, "filename": { "example": "R-2026-0042.pdf", "type": "string" }, "mode": { "description": "`linked`: a download link valid until the file's retention ends, at most 7 days.", "enum": [ "attached", "linked" ], "type": "string" } }, "required": [ "file_id", "filename", "bytes", "mode" ], "type": "object" }, "EmailSendError": { "additionalProperties": true, "description": "Why a send failed or waits: never message bodies or addresses.", "properties": { "code": { "description": "`email_template_error`, `email_too_large`, `email_recipient_missing`, `email_address_invalid`, `email_too_many_recipients`, `email_attachment_too_large`, `email_attachment_type_not_allowed`, `email_needs_hosted_file`, `email_provider_rejected`, `email_provider_auth_failed`, `email_provider_unavailable`, `email_ip_not_authorized`, `email_rate_limited`, `email_outcome_unknown`, `email_daily_cap_reached`, `email_disabled`, `email_credentials_removed`, `email_send_expired`, `internal_error`", "example": "email_daily_cap_reached", "type": "string" }, "column": { "type": "integer" }, "field": { "description": "`email_template_error`, `email_too_large`: the rule field, e.g. `subject`.", "type": "string" }, "line": { "description": "`email_template_error`: where in the field.", "type": "integer" }, "message": { "type": "string" }, "provider_code": { "anyOf": [ { "description": "The provider's own error code.", "type": "string" }, { "type": "null" } ] }, "provider_status": { "anyOf": [ { "description": "The provider's HTTP or SMTP status.", "type": "integer" }, { "type": "null" } ] } }, "required": [ "code", "message" ], "type": "object" }, "EmailSendEvent": { "properties": { "event": { "enum": [ "delivered", "deferred", "soft_bounce", "hard_bounce", "blocked", "spam", "invalid" ], "type": "string" }, "occurred_at": { "format": "date-time", "type": "string" }, "reason": { "description": "The provider's reason (bounces, blocks); may be empty.", "type": "string" }, "recipient": { "type": "string" } }, "required": [ "event", "recipient", "reason", "occurred_at" ], "type": "object" }, "EmailSendEventList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/EmailSendEvent" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "object": { "enum": [ "list" ], "type": "string" } }, "required": [ "object", "data", "has_more" ], "type": "object" }, "EmailSendList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/EmailSend" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "object": { "enum": [ "list" ], "type": "string" } }, "required": [ "object", "data", "has_more" ], "type": "object" }, "EmailSender": { "properties": { "email": { "description": "An address, or the domain for `kind: domain`.", "type": "string" }, "kind": { "description": "* `sender` - sender\n* `domain` - domain", "enum": [ "sender", "domain" ], "type": "string", "x-spec-enum-id": "782a6daad730dd03" }, "name": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "required": [ "email", "kind", "name", "verified" ], "type": "object" }, "EmailStats": { "properties": { "last_30_days": { "description": "Sends created in the last 30 days, by status.", "properties": { "canceled": { "type": "integer" }, "failed": { "type": "integer" }, "sandboxed": { "type": "integer" }, "sent": { "type": "integer" }, "skipped": { "type": "integer" }, "unknown": { "type": "integer" } }, "type": "object" }, "object": { "enum": [ "email_stats" ], "type": "string" }, "today": { "description": "Recipients of live emails today (UTC) in this region, against the daily cap.", "properties": { "limit": { "type": "integer" }, "recipients": { "type": "integer" }, "resets_at": { "format": "date-time", "type": "string" } }, "required": [ "recipients", "limit", "resets_at" ], "type": "object" } }, "required": [ "object", "today", "last_30_days" ], "type": "object" }, "EmailTargetSpec": { "additionalProperties": false, "description": "One entry of `delivery.email` (proto/README.md §24.3).", "properties": { "bcc": { "anyOf": [ { "items": { "maxLength": 512, "minLength": 1, "type": "string" }, "maxItems": 50, "type": "array" }, { "type": "null" } ], "default": null, "description": "Replaces the rule's `bcc` (`[]`: none).", "title": "Bcc" }, "cc": { "anyOf": [ { "items": { "maxLength": 512, "minLength": 1, "type": "string" }, "maxItems": 50, "type": "array" }, { "type": "null" } ], "default": null, "description": "Replaces the rule's `cc` (`[]`: none).", "title": "Cc" }, "rule_id": { "description": "An enabled email rule (`emr_…`) of the render's template.", "maxLength": 64, "minLength": 1, "title": "Rule Id", "type": "string" }, "to": { "anyOf": [ { "items": { "maxLength": 512, "minLength": 1, "type": "string" }, "maxItems": 50, "minItems": 1, "type": "array" }, { "type": "null" } ], "default": null, "description": "Literal recipients instead of the rule's `to`: each entry one address or `Name
`.", "title": "To" } }, "required": [ "rule_id" ], "title": "EmailTargetSpec", "type": "object" }, "EmailTestStep": { "properties": { "detail": { "type": [ "string", "null" ] }, "name": { "description": "Brevo: `credentials`, `senders`, `sandbox_send`; SMTP: `connect`, `starttls`, `smtp_auth`; Postmark: `credentials`; Resend: `credentials` (also lists the verified domains); Amazon SES: `credentials`, `senders`; Microsoft 365: `credentials` (a token). Then `send` with `send_to`.", "type": "string" }, "ok": { "type": "boolean" } }, "required": [ "detail", "name", "ok" ], "type": "object" }, "FormatOptions": { "additionalProperties": false, "properties": { "lossless": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Lossless" }, "progressive": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Progressive" }, "quality": { "anyOf": [ { "maximum": 100, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null, "title": "Quality" } }, "title": "FormatOptions", "type": "object" }, "HeaderFooter": { "additionalProperties": false, "properties": { "center": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "default": null, "title": "Center" }, "enabled": { "default": false, "title": "Enabled", "type": "boolean" }, "font_size": { "anyOf": [ { "maxLength": 16, "pattern": "^(0|\\d+(\\.\\d+)?(mm|cm|in|px|pt|pc))$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Font Size" }, "height": { "anyOf": [ { "maxLength": 16, "pattern": "^(0|\\d+(\\.\\d+)?(mm|cm|in|px|pt|pc))$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Height" }, "html": { "anyOf": [ { "maxLength": 200000, "type": "string" }, { "type": "null" } ], "default": null, "title": "Html" }, "left": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "default": null, "title": "Left" }, "right": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "default": null, "title": "Right" } }, "title": "HeaderFooter", "type": "object" }, "HtmlInputSpec": { "additionalProperties": false, "properties": { "head": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Head" }, "html": { "title": "Html", "type": "string" }, "templating": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Templating" }, "type": { "const": "html", "title": "Type", "type": "string" } }, "required": [ "type", "html" ], "title": "HtmlInputSpec", "type": "object" }, "HtmlPreview": { "properties": { "duration_ms": { "type": "integer" }, "html": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "markdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "object": { "enum": [ "preview" ], "type": "string" }, "template_type": { "type": "string" } }, "type": "object" }, "HtmlPreviewRequest": { "additionalProperties": false, "properties": { "content": { "anyOf": [ { "$ref": "#/components/schemas/PreviewContent" }, { "type": "null" } ], "default": null }, "data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Data" }, "head": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Head" }, "html": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Html" }, "markdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Markdown" }, "partials": { "anyOf": [ { "additionalProperties": { "type": "string" }, "maxProperties": 200, "propertyNames": { "maxLength": 120 }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Partials" }, "strict_undefined": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Strict Undefined" }, "template_id": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "default": null, "title": "Template Id" }, "template_type": { "default": "pdf_code", "enum": [ "pdf_code", "pdf_markdown" ], "title": "Template Type", "type": "string" } }, "title": "HtmlPreviewRequest", "type": "object" }, "HttpOptions": { "additionalProperties": false, "properties": { "basic_auth": { "anyOf": [ { "$ref": "#/components/schemas/BasicAuth" }, { "type": "null" } ], "default": null }, "cookies": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Cookie" }, "maxItems": 50, "type": "array" }, { "type": "null" } ], "default": null, "title": "Cookies" }, "headers": { "anyOf": [ { "additionalProperties": { "maxLength": 8192, "type": "string" }, "maxProperties": 50, "propertyNames": { "maxLength": 256, "minLength": 1 }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Headers" }, "user_agent": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "default": null, "title": "User Agent" } }, "title": "HttpOptions", "type": "object" }, "ImageCanvasDraftWrite": { "properties": { "content": { "additionalProperties": true, "description": "The whole content in one object, instead of the separate fields.", "type": "object" }, "options": { "additionalProperties": true, "description": "Default output options (`RenderOptions`: `output_format`, `filename`, `pdf` — PdfOptions §2.4 —, `image`, `strict_undefined`, and for PDF templates `einvoice: {profile, invoice_path}`, a default hybrid e-invoice that every render embeds unless the request sends `output.einvoice`).", "type": "object" }, "scene": { "additionalProperties": true, "description": "The canvas scene as defined by `@dynamic-document-api/scene-schema`.", "type": "object" }, "schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ] } }, "title": "ImageCanvas draft", "type": "object" }, "ImageCanvasTemplateCreate": { "properties": { "content": { "additionalProperties": true, "description": "The whole content in one object, instead of the separate fields.", "type": "object" }, "datasets": { "description": "Sample data sets `{name, data, is_default}` (rendered when publishing).", "items": { "additionalProperties": true, "type": "object" }, "maxItems": 50, "type": "array" }, "description": { "maxLength": 5000, "type": "string" }, "name": { "maxLength": 120, "type": "string" }, "options": { "additionalProperties": true, "description": "Default output options (`RenderOptions`: `output_format`, `filename`, `pdf` — PdfOptions §2.4 —, `image`, `strict_undefined`, and for PDF templates `einvoice: {profile, invoice_path}`, a default hybrid e-invoice that every render embeds unless the request sends `output.einvoice`).", "type": "object" }, "scene": { "additionalProperties": true, "description": "The canvas scene as defined by `@dynamic-document-api/scene-schema`.", "type": "object" }, "schema": { "anyOf": [ { "additionalProperties": true, "description": "JSON Schema.", "type": "object" }, { "type": "null" } ] }, "type": { "enum": [ "image_canvas" ], "type": "string" } }, "required": [ "name", "type" ], "title": "ImageCanvas template", "type": "object" }, "ImageOptions": { "additionalProperties": false, "properties": { "clip_selector": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "default": null, "title": "Clip Selector" }, "fit": { "anyOf": [ { "enum": [ "contain", "cover", "fill" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Fit" }, "format_options": { "anyOf": [ { "$ref": "#/components/schemas/FormatOptions" }, { "type": "null" } ], "default": null }, "full_page": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Full Page" }, "height": { "anyOf": [ { "maximum": 10000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null, "title": "Height" }, "omit_background": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Omit Background" }, "scale": { "anyOf": [ { "maximum": 3, "minimum": 1, "type": "number" }, { "type": "null" } ], "default": null, "title": "Scale" }, "transparent": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Transparent" }, "viewport": { "anyOf": [ { "$ref": "#/components/schemas/Viewport" }, { "type": "null" } ], "default": null }, "wait": { "anyOf": [ { "$ref": "#/components/schemas/Wait" }, { "type": "null" } ], "default": null }, "width": { "anyOf": [ { "maximum": 10000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null, "title": "Width" } }, "title": "ImageOptions", "type": "object" }, "Invoice": { "additionalProperties": false, "description": "Invoice data for `output.einvoice.invoice` and `POST /v1/einvoices` (proto/README.md §20). Semantic model of EN 16931-1:2017 with snake_case names; every field names its business term (BT-n) or group (BG-n). Amounts are decimal strings (numbers are accepted) in the invoice currency with at most 2 decimals; quantities and prices allow up to 6 decimals. Derived values (line net amounts BT-131, the VAT breakdown BG-23 and the document totals BG-22) are computed by the engine and must not be sent, except `net_amount` on a line, which is checked when present.", "properties": { "allowances": { "description": "BG-20 Document level allowances (BT-92…BT-98).", "items": { "$ref": "#/components/schemas/InvoiceDocumentAllowanceCharge" }, "maxItems": 100, "type": "array" }, "buyer": { "$ref": "#/components/schemas/InvoiceBuyer" }, "buyer_accounting_reference": { "description": "BT-19 Buyer accounting reference.", "maxLength": 200, "type": "string" }, "buyer_reference": { "description": "BT-10 Buyer reference (the Leitweg-ID for German public buyers; mandatory for XRECHNUNG).", "maxLength": 200, "type": "string" }, "charges": { "description": "BG-21 Document level charges (BT-99…BT-105).", "items": { "$ref": "#/components/schemas/InvoiceDocumentAllowanceCharge" }, "maxItems": 100, "type": "array" }, "contract_reference": { "description": "BT-12 Contract reference.", "maxLength": 200, "type": "string" }, "currency": { "description": "BT-5 Invoice currency code (ISO 4217).", "pattern": "^[A-Z]{3}$", "type": "string" }, "delivery": { "additionalProperties": false, "description": "BG-13 Delivery information.", "properties": { "address": { "$ref": "#/components/schemas/InvoiceAddress", "description": "BG-15 Deliver to address." }, "date": { "$ref": "#/components/schemas/InvoiceDate", "description": "BT-72 Actual delivery date." }, "location": { "$ref": "#/components/schemas/InvoiceIdentifier", "description": "BT-71 Deliver to location identifier (+ scheme)." }, "party_name": { "description": "BT-70 Deliver to party name.", "maxLength": 200, "type": "string" } }, "type": "object" }, "despatch_advice_reference": { "description": "BT-16 Despatch advice reference.", "maxLength": 200, "type": "string" }, "due_date": { "$ref": "#/components/schemas/InvoiceDate", "description": "BT-9 Payment due date." }, "invoice_period": { "$ref": "#/components/schemas/InvoicePeriod", "description": "BG-14 Invoicing period (BT-73 start, BT-74 end)." }, "invoiced_object": { "$ref": "#/components/schemas/InvoiceIdentifier", "description": "BT-18 Invoiced object identifier (+ scheme, UNTDID 1153)." }, "issue_date": { "$ref": "#/components/schemas/InvoiceDate", "description": "BT-2 Invoice issue date." }, "lines": { "description": "BG-25 Invoice lines. Always required: MINIMUM and BASIC_WL do not transmit lines, but the totals are computed from them.", "items": { "$ref": "#/components/schemas/InvoiceLine" }, "maxItems": 10000, "minItems": 1, "type": "array" }, "notes": { "description": "BG-1 Invoice notes.", "items": { "additionalProperties": false, "properties": { "subject_code": { "description": "BT-21 Invoice note subject code (UNTDID 4451, e.g. AAI, REG, ABL, TXD).", "pattern": "^[A-Z0-9]{3}$", "type": "string" }, "text": { "description": "BT-22 Invoice note.", "maxLength": 5000, "minLength": 1, "type": "string" } }, "required": [ "text" ], "type": "object" }, "maxItems": 100, "type": "array" }, "number": { "description": "BT-1 Invoice number.", "maxLength": 200, "minLength": 1, "type": "string" }, "order_reference": { "description": "BT-13 Purchase order reference.", "maxLength": 200, "type": "string" }, "payee": { "additionalProperties": false, "description": "BG-10 Payee, when different from the seller.", "properties": { "identifier": { "$ref": "#/components/schemas/InvoiceIdentifier", "description": "BT-60 Payee identifier (+ scheme, ISO 6523 ICD)." }, "legal_registration": { "$ref": "#/components/schemas/InvoiceIdentifier", "description": "BT-61 Payee legal registration identifier (+ scheme)." }, "name": { "description": "BT-59 Payee name.", "maxLength": 200, "minLength": 1, "type": "string" } }, "required": [ "name" ], "type": "object" }, "payment": { "$ref": "#/components/schemas/InvoicePayment" }, "payment_terms": { "description": "BT-20 Payment terms (free text; XRECHNUNG accepts the `#SKONTO#` syntax here).", "maxLength": 2000, "type": "string" }, "preceding_invoices": { "description": "BG-3 Preceding invoice references (required for corrected invoices 384).", "items": { "additionalProperties": false, "properties": { "issue_date": { "$ref": "#/components/schemas/InvoiceDate", "description": "BT-26 Preceding invoice issue date." }, "number": { "description": "BT-25 Preceding invoice reference.", "maxLength": 200, "minLength": 1, "type": "string" } }, "required": [ "number" ], "type": "object" }, "maxItems": 100, "type": "array" }, "prepaid_amount": { "$ref": "#/components/schemas/InvoiceDecimal", "description": "BT-113 Paid amount." }, "process_id": { "description": "BT-23 Business process type. Defaults for XRECHNUNG to `urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`.", "maxLength": 200, "type": "string" }, "project_reference": { "description": "BT-11 Project reference.", "maxLength": 200, "type": "string" }, "receiving_advice_reference": { "description": "BT-15 Receiving advice reference.", "maxLength": 200, "type": "string" }, "rounding_amount": { "$ref": "#/components/schemas/InvoiceDecimal", "description": "BT-114 Rounding amount." }, "sales_order_reference": { "description": "BT-14 Sales order reference.", "maxLength": 200, "type": "string" }, "seller": { "$ref": "#/components/schemas/InvoiceSeller" }, "supporting_documents": { "description": "BG-24 Additional supporting documents (references only).", "items": { "additionalProperties": false, "properties": { "description": { "description": "BT-123 Supporting document description.", "maxLength": 1000, "type": "string" }, "id": { "description": "BT-122 Supporting document reference.", "maxLength": 200, "minLength": 1, "type": "string" }, "url": { "description": "BT-124 External document location.", "maxLength": 2000, "type": "string" } }, "required": [ "id" ], "type": "object" }, "maxItems": 100, "type": "array" }, "tax_currency": { "description": "BT-6 VAT accounting currency code (ISO 4217), when it differs from the invoice currency. Requires `tax_total_in_tax_currency`.", "pattern": "^[A-Z]{3}$", "type": "string" }, "tax_point_date": { "$ref": "#/components/schemas/InvoiceDate", "description": "BT-7 Value added tax point date." }, "tax_point_date_code": { "description": "BT-8 Value added tax point date code (UNTDID 2005): 3 invoice document issue date, 35 actual delivery date, 432 paid to date.", "enum": [ "3", "35", "432" ], "type": "string" }, "tax_representative": { "additionalProperties": false, "description": "BG-11 Seller tax representative party.", "properties": { "address": { "$ref": "#/components/schemas/InvoiceAddress", "description": "BG-12 Seller tax representative postal address." }, "name": { "description": "BT-62 Seller tax representative name.", "maxLength": 200, "minLength": 1, "type": "string" }, "vat_id": { "description": "BT-63 Seller tax representative VAT identifier (with ISO 3166-1 country prefix).", "maxLength": 50, "minLength": 3, "type": "string" } }, "required": [ "name", "vat_id", "address" ], "type": "object" }, "tax_total_in_tax_currency": { "$ref": "#/components/schemas/InvoiceDecimal", "description": "BT-111 Invoice total VAT amount in the accounting currency (only with `tax_currency`)." }, "tender_reference": { "description": "BT-17 Tender or lot reference.", "maxLength": 200, "type": "string" }, "type_code": { "description": "BT-3 Invoice type code (UNTDID 1001): 380 commercial invoice (default), 381 credit note, 384 corrected invoice, 389 self-billed invoice, 326 partial invoice, 386 prepayment invoice, 751 invoice information for accounting purposes, 875/876/877 partial/partial final/final construction invoice.", "pattern": "^[0-9]{3}$", "type": "string" }, "vat_exemptions": { "additionalProperties": { "additionalProperties": false, "properties": { "reason": { "description": "BT-120 VAT exemption reason text.", "maxLength": 1000, "type": "string" }, "reason_code": { "description": "BT-121 VAT exemption reason code (VATEX code list, e.g. vatex-eu-ae).", "maxLength": 50, "type": "string" } }, "type": "object" }, "description": "BT-120/BT-121 VAT exemption reason per VAT category code (BG-23), e.g. {\"AE\": {\"reason\": \"Reverse charge\", \"reason_code\": \"vatex-eu-ae\"}}. Required for categories E, AE, K, G, O (EN 16931 BR-E-10, BR-AE-10, BR-IC-10, BR-G-10, BR-O-10).", "propertyNames": { "$ref": "#/components/schemas/InvoiceVatCategory" }, "type": "object" } }, "required": [ "number", "issue_date", "currency", "seller", "buyer", "lines" ], "title": "Dynamic Document API e-invoice model", "type": "object" }, "InvoiceAddress": { "additionalProperties": false, "properties": { "city": { "description": "BT-37/BT-52/BT-66/BT-77 City.", "maxLength": 200, "type": "string" }, "country": { "$ref": "#/components/schemas/InvoiceCountry", "description": "BT-40/BT-55/BT-69/BT-80 Country code." }, "line1": { "description": "BT-35/BT-50/BT-64/BT-75 Address line 1.", "maxLength": 200, "type": "string" }, "line2": { "description": "BT-36/BT-51/BT-65/BT-76 Address line 2.", "maxLength": 200, "type": "string" }, "line3": { "description": "BT-162/BT-163/BT-164/BT-165 Address line 3.", "maxLength": 200, "type": "string" }, "postcode": { "description": "BT-38/BT-53/BT-67/BT-78 Post code.", "maxLength": 50, "type": "string" }, "subdivision": { "description": "BT-39/BT-54/BT-68/BT-79 Country subdivision.", "maxLength": 200, "type": "string" } }, "required": [ "country" ], "type": "object" }, "InvoiceBuyer": { "additionalProperties": false, "description": "BG-7 Buyer.", "properties": { "address": { "$ref": "#/components/schemas/InvoiceAddress", "description": "BG-5/BG-8 Postal address." }, "contact": { "$ref": "#/components/schemas/InvoiceContact", "description": "BG-6/BG-9 Contact (seller contact name, phone and e-mail are mandatory for XRECHNUNG)." }, "electronic_address": { "$ref": "#/components/schemas/InvoiceIdentifier", "description": "BT-34/BT-49 Electronic address; `scheme` (EAS code) is required, e.g. {\"id\": \"invoices@example.com\", \"scheme\": \"EM\"}. Mandatory for XRECHNUNG." }, "identifiers": { "description": "BT-29 Seller identifier(s) / BT-46 Buyer identifier (one) with ISO 6523 ICD scheme.", "items": { "$ref": "#/components/schemas/InvoiceIdentifier" }, "maxItems": 1, "type": "array" }, "legal_registration": { "$ref": "#/components/schemas/InvoiceIdentifier", "description": "BT-30/BT-47 Legal registration identifier (+ scheme), e.g. HRB 12345." }, "name": { "description": "BT-27/BT-44 Name.", "maxLength": 200, "minLength": 1, "type": "string" }, "trading_name": { "description": "BT-28/BT-45 Trading name.", "maxLength": 200, "type": "string" }, "vat_id": { "description": "BT-31/BT-48 VAT identifier with ISO 3166-1 country prefix, e.g. DE123456789.", "maxLength": 50, "minLength": 3, "type": "string" } }, "required": [ "name", "address" ], "type": "object" }, "InvoiceContact": { "additionalProperties": false, "properties": { "email": { "description": "BT-43/BT-58 Contact e-mail address.", "maxLength": 200, "type": "string" }, "name": { "description": "BT-41/BT-56 Contact point (person or department).", "maxLength": 200, "type": "string" }, "phone": { "description": "BT-42/BT-57 Contact telephone number.", "maxLength": 100, "type": "string" } }, "type": "object" }, "InvoiceCountry": { "description": "ISO 3166-1 alpha-2 country code.", "pattern": "^[A-Z]{2}$", "type": "string" }, "InvoiceDate": { "description": "Calendar date, YYYY-MM-DD.", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "type": "string" }, "InvoiceDecimal": { "description": "Decimal as a string (recommended) or a JSON number.", "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,6})?$", "type": [ "string", "number" ] }, "InvoiceDocumentAllowanceCharge": { "additionalProperties": false, "properties": { "amount": { "$ref": "#/components/schemas/InvoiceDecimal", "description": "BT-92/BT-99 Amount (without VAT)." }, "base_amount": { "$ref": "#/components/schemas/InvoiceDecimal", "description": "BT-93/BT-100 Base amount." }, "percent": { "$ref": "#/components/schemas/InvoiceDecimal", "description": "BT-94/BT-101 Percentage." }, "reason": { "description": "BT-97/BT-104 Reason (text).", "maxLength": 500, "type": "string" }, "reason_code": { "description": "BT-98/BT-105 Reason code (UNTDID 5189 for allowances, 7161 for charges).", "maxLength": 10, "type": "string" }, "tax_category": { "$ref": "#/components/schemas/InvoiceVatCategory", "description": "BT-95/BT-102 VAT category code." }, "tax_rate": { "$ref": "#/components/schemas/InvoiceDecimal", "description": "BT-96/BT-103 VAT rate (percent). Required unless the category is O." } }, "required": [ "amount", "tax_category" ], "type": "object" }, "InvoiceIdentifier": { "additionalProperties": false, "properties": { "id": { "maxLength": 200, "minLength": 1, "type": "string" }, "scheme": { "description": "Scheme identifier: ISO 6523 ICD for party identifiers (e.g. 0088 GLN), EAS for electronic addresses (e.g. EM e-mail, 9930 German VAT, 0204 Leitweg-ID).", "maxLength": 20, "type": "string" } }, "required": [ "id" ], "type": "object" }, "InvoiceLine": { "additionalProperties": false, "properties": { "accounting_reference": { "description": "BT-133 Invoice line buyer accounting reference.", "maxLength": 200, "type": "string" }, "allowances": { "description": "BG-27 Invoice line allowances.", "items": { "$ref": "#/components/schemas/InvoiceLineAllowanceCharge" }, "maxItems": 20, "type": "array" }, "charges": { "description": "BG-28 Invoice line charges.", "items": { "$ref": "#/components/schemas/InvoiceLineAllowanceCharge" }, "maxItems": 20, "type": "array" }, "id": { "description": "BT-126 Invoice line identifier (default: the 1-based position).", "maxLength": 50, "type": "string" }, "item": { "additionalProperties": false, "description": "BG-31 Item information.", "properties": { "attributes": { "description": "BG-32 Item attributes.", "items": { "additionalProperties": false, "properties": { "name": { "description": "BT-160 Item attribute name.", "maxLength": 200, "minLength": 1, "type": "string" }, "value": { "description": "BT-161 Item attribute value.", "maxLength": 500, "minLength": 1, "type": "string" } }, "required": [ "name", "value" ], "type": "object" }, "maxItems": 50, "type": "array" }, "buyer_id": { "description": "BT-156 Item buyer's identifier.", "maxLength": 100, "type": "string" }, "classifications": { "description": "BT-158 Item classification identifiers.", "items": { "additionalProperties": false, "properties": { "id": { "maxLength": 100, "minLength": 1, "type": "string" }, "scheme": { "description": "UNTDID 7143 list id, e.g. HS (Harmonized System), STI or TST; ids outside the list are rejected (BR-CL-13).", "maxLength": 10, "type": "string" }, "version": { "maxLength": 20, "type": "string" } }, "required": [ "id", "scheme" ], "type": "object" }, "maxItems": 10, "type": "array" }, "description": { "description": "BT-154 Item description.", "maxLength": 5000, "type": "string" }, "name": { "description": "BT-153 Item name.", "maxLength": 200, "minLength": 1, "type": "string" }, "origin_country": { "$ref": "#/components/schemas/InvoiceCountry", "description": "BT-159 Item country of origin." }, "seller_id": { "description": "BT-155 Item seller's identifier.", "maxLength": 100, "type": "string" }, "standard_id": { "$ref": "#/components/schemas/InvoiceIdentifier", "description": "BT-157 Item standard identifier (+ scheme, ISO 6523 ICD, e.g. 0160 GTIN)." } }, "required": [ "name" ], "type": "object" }, "net_amount": { "$ref": "#/components/schemas/InvoiceDecimal", "description": "BT-131 Invoice line net amount. Computed when omitted; checked (BR-CO-? consistency) when present." }, "note": { "description": "BT-127 Invoice line note.", "maxLength": 2000, "type": "string" }, "object_identifier": { "$ref": "#/components/schemas/InvoiceIdentifier", "description": "BT-128 Invoice line object identifier (+ scheme)." }, "order_line_reference": { "description": "BT-132 Referenced purchase order line reference.", "maxLength": 50, "type": "string" }, "period": { "$ref": "#/components/schemas/InvoicePeriod", "description": "BG-26 Invoice line period (BT-134 start, BT-135 end)." }, "price": { "additionalProperties": false, "description": "BG-29 Price details.", "properties": { "base_quantity": { "$ref": "#/components/schemas/InvoiceDecimal", "description": "BT-149 Item price base quantity (default 1)." }, "base_unit": { "description": "BT-150 Item price base quantity unit of measure code.", "pattern": "^[A-Z0-9]{1,3}$", "type": "string" }, "discount": { "$ref": "#/components/schemas/InvoiceDecimal", "description": "BT-147 Item price discount." }, "gross": { "$ref": "#/components/schemas/InvoiceDecimal", "description": "BT-148 Item gross price." }, "net": { "$ref": "#/components/schemas/InvoiceDecimal", "description": "BT-146 Item net price (after the price discount, without VAT)." } }, "required": [ "net" ], "type": "object" }, "quantity": { "$ref": "#/components/schemas/InvoiceDecimal", "description": "BT-129 Invoiced quantity." }, "tax": { "additionalProperties": false, "description": "BG-30 Line VAT information.", "properties": { "category": { "$ref": "#/components/schemas/InvoiceVatCategory", "description": "BT-151 Invoiced item VAT category code." }, "rate": { "$ref": "#/components/schemas/InvoiceDecimal", "description": "BT-152 Invoiced item VAT rate (percent). Required unless the category is O." } }, "required": [ "category" ], "type": "object" }, "unit": { "description": "BT-130 Unit of measure (UN/ECE Recommendation 20/21), e.g. C62 one, H87 piece, HUR hour, DAY day, KGM kilogram. Default C62.", "pattern": "^[A-Z0-9]{1,3}$", "type": "string" } }, "required": [ "quantity", "price", "tax", "item" ], "type": "object" }, "InvoiceLineAllowanceCharge": { "additionalProperties": false, "properties": { "amount": { "$ref": "#/components/schemas/InvoiceDecimal", "description": "BT-136/BT-141 Amount (without VAT)." }, "base_amount": { "$ref": "#/components/schemas/InvoiceDecimal", "description": "BT-137/BT-142 Base amount." }, "percent": { "$ref": "#/components/schemas/InvoiceDecimal", "description": "BT-138/BT-143 Percentage." }, "reason": { "description": "BT-139/BT-144 Reason (text).", "maxLength": 500, "type": "string" }, "reason_code": { "description": "BT-140/BT-145 Reason code (UNTDID 5189 / 7161).", "maxLength": 10, "type": "string" } }, "required": [ "amount" ], "type": "object" }, "InvoicePayment": { "additionalProperties": false, "description": "BG-16 Payment instructions (mandatory for XRECHNUNG).", "properties": { "card": { "additionalProperties": false, "description": "BG-18 Payment card information.", "properties": { "account_number": { "description": "BT-87 Payment card primary account number (only the last 4–6 digits).", "maxLength": 10, "minLength": 4, "type": "string" }, "holder": { "description": "BT-88 Payment card holder name.", "maxLength": 200, "type": "string" } }, "required": [ "account_number" ], "type": "object" }, "credit_transfers": { "description": "BG-17 Credit transfer accounts.", "items": { "additionalProperties": false, "properties": { "account_id": { "description": "BT-84 Payment account identifier (IBAN for SEPA).", "maxLength": 50, "minLength": 1, "type": "string" }, "account_name": { "description": "BT-85 Payment account name.", "maxLength": 200, "type": "string" }, "bic": { "description": "BT-86 Payment service provider identifier (BIC).", "maxLength": 11, "type": "string" } }, "required": [ "account_id" ], "type": "object" }, "maxItems": 10, "type": "array" }, "direct_debit": { "additionalProperties": false, "description": "BG-19 Direct debit.", "properties": { "creditor_id": { "description": "BT-90 Bank assigned creditor identifier.", "maxLength": 100, "type": "string" }, "debited_account": { "description": "BT-91 Debited account identifier (IBAN).", "maxLength": 50, "type": "string" }, "mandate_reference": { "description": "BT-89 Mandate reference identifier.", "maxLength": 100, "type": "string" } }, "type": "object" }, "means_code": { "description": "BT-81 Payment means type code (UNTDID 4461): 58 SEPA credit transfer, 30 credit transfer, 59 SEPA direct debit, 49 direct debit, 48 bank card, 54 credit card, 10 cash, 1 not defined, ZZZ mutually defined.", "pattern": "^([0-9]{1,3}|ZZZ)$", "type": "string" }, "means_text": { "description": "BT-82 Payment means text.", "maxLength": 200, "type": "string" }, "remittance_information": { "description": "BT-83 Remittance information (payment reference).", "maxLength": 200, "type": "string" } }, "required": [ "means_code" ], "type": "object" }, "InvoicePeriod": { "additionalProperties": false, "properties": { "end": { "$ref": "#/components/schemas/InvoiceDate" }, "start": { "$ref": "#/components/schemas/InvoiceDate" } }, "type": "object" }, "InvoiceSeller": { "additionalProperties": false, "description": "BG-4 Seller.", "properties": { "address": { "$ref": "#/components/schemas/InvoiceAddress", "description": "BG-5/BG-8 Postal address." }, "contact": { "$ref": "#/components/schemas/InvoiceContact", "description": "BG-6/BG-9 Contact (seller contact name, phone and e-mail are mandatory for XRECHNUNG)." }, "electronic_address": { "$ref": "#/components/schemas/InvoiceIdentifier", "description": "BT-34/BT-49 Electronic address; `scheme` (EAS code) is required, e.g. {\"id\": \"invoices@example.com\", \"scheme\": \"EM\"}. Mandatory for XRECHNUNG." }, "identifiers": { "description": "BT-29 Seller identifier(s) / BT-46 Buyer identifier (one) with ISO 6523 ICD scheme.", "items": { "$ref": "#/components/schemas/InvoiceIdentifier" }, "maxItems": 10, "type": "array" }, "legal_info": { "description": "BT-33 Seller additional legal information.", "maxLength": 1000, "type": "string" }, "legal_registration": { "$ref": "#/components/schemas/InvoiceIdentifier", "description": "BT-30/BT-47 Legal registration identifier (+ scheme), e.g. HRB 12345." }, "name": { "description": "BT-27/BT-44 Name.", "maxLength": 200, "minLength": 1, "type": "string" }, "tax_number": { "description": "BT-32 Seller tax registration identifier (local tax number, e.g. the German Steuernummer).", "maxLength": 50, "type": "string" }, "trading_name": { "description": "BT-28/BT-45 Trading name.", "maxLength": 200, "type": "string" }, "vat_id": { "description": "BT-31/BT-48 VAT identifier with ISO 3166-1 country prefix, e.g. DE123456789.", "maxLength": 50, "minLength": 3, "type": "string" } }, "required": [ "name", "address" ], "type": "object" }, "InvoiceVatCategory": { "description": "VAT category code (UNTDID 5305 subset of EN 16931): S standard, Z zero rated, E exempt, AE reverse charge, K intra-community supply, G export outside the EU, O not subject to VAT, L Canary Islands IGIC, M Ceuta/Melilla IPSI.", "enum": [ "S", "Z", "E", "AE", "K", "G", "O", "L", "M" ], "type": "string" }, "ManagedTemplate": { "description": "`POST /v1/templates` and `POST /v1/templates/{id}/rollback` (docs/05 §6).\n\nThe read endpoints (`GET /v1/templates*`) answer from the regional mirror and use the `Template`\nschema; this is the control-plane representation, which also carries the draft revision.", "properties": { "created_at": { "format": "date-time", "type": "string" }, "default_options": { "additionalProperties": {}, "description": "Output options of the live version.", "type": [ "object", "null" ] }, "deleted_at": { "format": "date-time", "type": [ "string", "null" ] }, "description": { "type": "string" }, "draft_revision": { "type": "integer" }, "engine": { "description": "Engine channel, e.g. `2026.4`.", "type": "string" }, "folder": { "oneOf": [ { "$ref": "#/components/schemas/TemplateFolder" }, { "type": "null" } ] }, "id": { "description": "`tpl_…`", "type": "string" }, "live_version": { "oneOf": [ { "$ref": "#/components/schemas/TemplateWriteVersion" }, { "type": "null" } ] }, "name": { "type": "string" }, "object": { "default": "template", "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" }, "thumbnail_url": { "format": "uri", "type": [ "string", "null" ] }, "type": { "description": "* `pdf_code` - pdf_code\n* `pdf_markdown` - pdf_markdown\n* `image_canvas` - image_canvas\n* `docx` - docx\n* `pdf_form` - pdf_form", "enum": [ "pdf_code", "pdf_markdown", "image_canvas", "docx", "pdf_form" ], "type": "string", "x-spec-enum-id": "e4bfa130e14b2d4e" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "created_at", "default_options", "deleted_at", "description", "draft_revision", "engine", "folder", "id", "live_version", "name", "tags", "thumbnail_url", "type", "updated_at" ], "type": "object" }, "Margin": { "additionalProperties": false, "properties": { "bottom": { "anyOf": [ { "maxLength": 16, "pattern": "^(0|\\d+(\\.\\d+)?(mm|cm|in|px|pt|pc))$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Bottom" }, "left": { "anyOf": [ { "maxLength": 16, "pattern": "^(0|\\d+(\\.\\d+)?(mm|cm|in|px|pt|pc))$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Left" }, "right": { "anyOf": [ { "maxLength": 16, "pattern": "^(0|\\d+(\\.\\d+)?(mm|cm|in|px|pt|pc))$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Right" }, "top": { "anyOf": [ { "maxLength": 16, "pattern": "^(0|\\d+(\\.\\d+)?(mm|cm|in|px|pt|pc))$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Top" } }, "title": "Margin", "type": "object" }, "MarkdownInputSpec": { "additionalProperties": false, "properties": { "allow_raw_html": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Allow Raw Html" }, "css": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Css" }, "markdown": { "title": "Markdown", "type": "string" }, "templating": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Templating" }, "theme": { "default": "default", "enum": [ "default", "github", "academic", "minimal", "none" ], "title": "Theme", "type": "string" }, "type": { "const": "markdown", "title": "Type", "type": "string" } }, "required": [ "type", "markdown" ], "title": "MarkdownInputSpec", "type": "object" }, "MergeRequest": { "additionalProperties": false, "properties": { "bookmarks": { "default": "filenames", "enum": [ "filenames", "none" ], "title": "Bookmarks", "type": "string" }, "delivery": { "anyOf": [ { "$ref": "#/components/schemas/DeliverySpec" }, { "type": "null" } ], "default": null }, "filename": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Filename" }, "metadata": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "propertyNames": { "maxLength": 40, "minLength": 1 }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Metadata" }, "mode": { "default": "sync", "enum": [ "sync", "async" ], "title": "Mode", "type": "string" }, "priority": { "default": "normal", "enum": [ "normal", "low" ], "title": "Priority", "type": "string" }, "reference": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Reference" }, "sources": { "items": { "$ref": "#/components/schemas/PdfSourceSpec" }, "maxItems": 200, "minItems": 2, "title": "Sources", "type": "array" }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Test" }, "timeout_behavior": { "default": "continue", "enum": [ "continue", "cancel" ], "title": "Timeout Behavior", "type": "string" }, "webhook": { "anyOf": [ { "$ref": "#/components/schemas/WebhookSpec" }, { "type": "null" } ], "default": null } }, "required": [ "sources" ], "title": "MergeRequest", "type": "object" }, "OutputSpec": { "additionalProperties": false, "properties": { "einvoice": { "anyOf": [ { "$ref": "#/components/schemas/EInvoiceSpec" }, { "type": "null" } ], "default": null, "description": "Hybrid e-invoice (Factur-X / ZUGFeRD / XRechnung): the PDF becomes PDF/A-3b with the invoice XML embedded. Needs `format: pdf`; included in the render (no extra billed render). A PDF template can store a default (`options.einvoice = {profile, invoice_path}`): an object here replaces it, `null` turns it off for this request, and without `einvoicing` in the plan the default is skipped with the warning `einvoice_skipped_plan`." }, "filename": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "default": null, "title": "Filename" }, "format": { "anyOf": [ { "enum": [ "pdf", "png", "jpeg", "webp", "html" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Format" }, "image": { "anyOf": [ { "$ref": "#/components/schemas/ImageOptions" }, { "type": "null" } ], "default": null }, "pdf": { "anyOf": [ { "$ref": "#/components/schemas/PdfOptions" }, { "type": "null" } ], "default": null } }, "title": "OutputSpec", "type": "object" }, "Paper": { "additionalProperties": false, "properties": { "height": { "anyOf": [ { "maxLength": 16, "pattern": "^(0|\\d+(\\.\\d+)?(mm|cm|in|px|pt|pc))$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Height" }, "size": { "anyOf": [ { "enum": [ "A0", "A1", "A2", "A3", "A4", "A5", "A6", "B4", "B5", "Letter", "Legal", "Tabloid", "Ledger" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Size" }, "width": { "anyOf": [ { "maxLength": 16, "pattern": "^(0|\\d+(\\.\\d+)?(mm|cm|in|px|pt|pc))$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Width" } }, "title": "Paper", "type": "object" }, "PatchedEmailConnectionWrite": { "properties": { "config": { "additionalProperties": {}, "description": "Per provider: SMTP `{host, port, username}` (port 587 or 2525); Postmark `{message_stream}` (default `outbound`, also when empty or null); Amazon SES `{region, configuration_set?}`; Microsoft 365 `{tenant_id, client_id, sender}` (`sender`: the mailbox that sends); Brevo and Resend none. Every provider: `attachment_budget_bytes`, the bytes of files attached per email (default / maximum: Brevo 10 / 13 MiB, SMTP 6 / 25 MiB, Postmark 6 / 6 MiB, Resend 10 / 25 MiB, Amazon SES 10 / 25 MiB, Microsoft 365 2 / 2 MiB), and `max_per_second` (1 to 100, default 10).", "type": "object" }, "credentials": { "additionalProperties": {}, "description": "Write-only: Brevo `{api_key}` (an API key, not its SMTP key), SMTP `{password}`, Postmark `{server_token}`, Resend `{api_key}`, Amazon SES `{access_key_id, secret_access_key}`, Microsoft 365 `{client_secret}`. A PATCH without them keeps them.", "type": "object" }, "default_from": { "$ref": "#/components/schemas/EmailDefaultFromWrite" }, "name": { "maxLength": 100, "type": "string" }, "provider": { "description": "`brevo`, `smtp`, `postmark`, `resend`, `ses` (Amazon SES) or `graph` (Microsoft 365); it can't change after creation.\n\n* `brevo` - Brevo\n* `smtp` - SMTP\n* `postmark` - Postmark\n* `resend` - Resend\n* `ses` - Amazon SES\n* `graph` - Microsoft 365 (Graph)", "enum": [ "brevo", "smtp", "postmark", "resend", "ses", "graph" ], "type": "string", "x-spec-enum-id": "e7a31054cb3443ae" }, "reply_to": { "maxLength": 254, "type": [ "string", "null" ] }, "test_mode": { "description": "Test renders: `sandbox` (Brevo only, and its default: Brevo checks the email without delivering it), `redirect` (to `test_recipient`, subject prefixed `[Test] `), `skip` (no provider call; the default for every other provider).\n\n* `sandbox` - Sandbox\n* `redirect` - Redirect\n* `skip` - Skip", "enum": [ "sandbox", "redirect", "skip" ], "type": "string", "x-spec-enum-id": "edd83b93494872a4" }, "test_recipient": { "description": "The verified address of a workspace member; required with `test_mode: redirect`.", "maxLength": 254, "type": [ "string", "null" ] } }, "type": "object" }, "PatchedEmailRuleWrite": { "properties": { "attach_formats": { "description": "Only files of these formats; empty = every file.", "items": { "description": "* `pdf` - pdf\n* `png` - png\n* `jpeg` - jpeg\n* `webp` - webp\n* `html` - html\n* `xml` - xml\n* `zip` - zip", "enum": [ "pdf", "png", "jpeg", "webp", "html", "xml", "zip" ], "type": "string", "x-spec-enum-id": "22bc71b676b2a590" }, "maxItems": 7, "type": "array" }, "attachments": { "default": "attach_or_link", "description": "* `attach_or_link` - Attach Or Link\n* `attach` - Attach\n* `link` - Link\n* `none` - None", "enum": [ "attach_or_link", "attach", "link", "none" ], "type": "string", "x-spec-enum-id": "31eaadd397405cc6" }, "bcc": { "type": [ "string", "null" ] }, "cc": { "type": [ "string", "null" ] }, "condition": { "description": "An expression; the rule sends when it is true. Empty = always.", "type": [ "string", "null" ] }, "connection_id": { "description": "`emc_…` of this workspace.", "type": "string" }, "enabled": { "default": true, "type": "boolean" }, "from_email": { "description": "Literal; empty = the connection's default sender. One the provider hasn't verified is saved with the warning `email_sender_unverified`.", "maxLength": 254, "type": [ "string", "null" ] }, "from_name": { "description": "Template source; one line after rendering.", "type": [ "string", "null" ] }, "html": { "description": "Template source, values HTML-escaped (≤ 256 KiB).", "type": [ "string", "null" ] }, "name": { "maxLength": 100, "type": "string" }, "position": { "description": "0 to 4; the others move. Default: the end.", "maximum": 4, "minimum": 0, "type": "integer" }, "provider_template": { "oneOf": [ { "$ref": "#/components/schemas/EmailProviderTemplate" }, { "type": "null" } ] }, "reply_to": { "description": "Template source; one line after rendering.", "type": [ "string", "null" ] }, "subject": { "description": "Template source; required unless a provider template gives it.", "type": [ "string", "null" ] }, "text": { "description": "Template source; empty = derived from `html`.", "type": [ "string", "null" ] }, "to": { "description": "Template source rendering to addresses separated by `,` `;` or line breaks.", "type": [ "string", "null" ] } }, "type": "object" }, "PatchedSignedLinkWrite": { "properties": { "access": { "default": "signed", "description": "`open` accepts unsigned requests within `allowed_params` and `param_limits`.\n\n* `signed` - signed\n* `open` - open", "enum": [ "signed", "open" ], "type": "string", "x-spec-enum-id": "897113911536df41" }, "allowed_params": { "description": "Dynamic properties callers may set, e.g. `title.text`.", "items": { "maxLength": 120, "type": "string" }, "maxItems": 100, "type": "array" }, "allowed_referrers": { "items": { "maxLength": 255, "type": "string" }, "maxItems": 50, "type": "array" }, "cache_ttl_seconds": { "minimum": 60, "type": [ "integer", "null" ] }, "defaults": { "additionalProperties": {}, "type": "object" }, "enabled": { "type": "boolean" }, "expires_at": { "format": "date-time", "type": [ "string", "null" ] }, "fallback_image_asset_id": { "description": "Ready image asset (`ast_…`) returned instead of 402 `render_limit_reached`; null clears.", "maxLength": 40, "type": [ "string", "null" ] }, "formats": { "items": { "description": "* `png` - png\n* `jpeg` - jpeg\n* `webp` - webp\n* `pdf` - pdf", "enum": [ "png", "jpeg", "webp", "pdf" ], "type": "string", "x-spec-enum-id": "66096331f0c3a912" }, "minItems": 1, "type": "array" }, "name": { "maxLength": 80, "type": "string" }, "param_limits": { "additionalProperties": {}, "type": "object" }, "quota_total": { "minimum": 1, "type": [ "integer", "null" ] }, "rate_limit_per_ip_per_hour": { "maximum": 100000, "minimum": 1, "type": [ "integer", "null" ] }, "template_id": { "type": "string" } }, "type": "object" }, "PatchedStorageDestinationWrite": { "properties": { "config": { "additionalProperties": {}, "type": "object" }, "credentials": { "additionalProperties": {}, "description": "Never returned again; send it only when it changes.", "type": "object" }, "is_default": { "default": false, "type": "boolean" }, "keep_hosted_copy": { "default": true, "type": "boolean" }, "name": { "maxLength": 80, "type": "string" }, "path_template": { "default": "", "maxLength": 500, "type": "string" }, "provider": { "description": "* `s3` - Amazon S3\n* `s3_compatible` - S3-compatible\n* `azure_blob` - Azure Blob Storage\n* `gcs` - Google Cloud Storage\n* `sftp` - SFTP", "enum": [ "s3", "s3_compatible", "azure_blob", "gcs", "sftp" ], "type": "string", "x-spec-enum-id": "52b8262084245aab" } }, "type": "object" }, "PatchedWebhookEndpointWrite": { "properties": { "description": { "maxLength": 255, "type": "string" }, "enabled": { "default": true, "type": "boolean" }, "events": { "items": { "description": "* `render.succeeded` - render.succeeded\n* `render.failed` - render.failed\n* `render.expired` - render.expired\n* `batch.progress` - batch.progress\n* `batch.completed` - batch.completed\n* `storage.upload_failed` - storage.upload_failed\n* `email.sent` - email.sent\n* `email.send_failed` - email.send_failed\n* `email.delivered` - email.delivered\n* `email.bounced` - email.bounced\n* `email.complained` - email.complained\n* `usage.threshold_reached` - usage.threshold_reached\n* `template.published` - template.published\n* `api_key.expiring` - api_key.expiring", "enum": [ "render.succeeded", "render.failed", "render.expired", "batch.progress", "batch.completed", "storage.upload_failed", "email.sent", "email.send_failed", "email.delivered", "email.bounced", "email.complained", "usage.threshold_reached", "template.published", "api_key.expiring" ], "type": "string", "x-spec-enum-id": "14c12aefcc309c17" }, "minItems": 1, "type": "array" }, "headers": { "additionalProperties": { "maxLength": 1000, "type": "string" }, "description": "Extra request headers.", "type": "object" }, "is_default": { "description": "Receive events from renders without an inline `webhook`.", "type": "boolean" }, "template_ids": { "description": "Only deliver events for these templates.", "items": { "type": "string" }, "maxItems": 200, "type": "array" }, "url": { "description": "Absolute https URL; no credentials.", "format": "uri", "maxLength": 2048, "type": "string" } }, "type": "object" }, "PdfAttachment": { "additionalProperties": false, "description": "A file embedded in the PDF (proto/README.md §26.2): exactly one of `url`, `data_uri` and `upload_id`.\n\n`url` is fetched by the renderer like an asset, `upload_id` names an upload (`POST /v1/uploads`), and\n`data_uri` (`data:;base64,…`) holds at most 5 MB, a document's data URIs at most 8 MB of\nbase64 together. Each file holds at most 10 MiB, and a document's files at most 25 MiB together.\n`mime_type` defaults to the type of the name's extension, else `application/octet-stream`;\n`relationship` to `Unspecified`.", "properties": { "data_uri": { "anyOf": [ { "maxLength": 7000000, "type": "string" }, { "type": "null" } ], "default": null, "title": "Data Uri" }, "description": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "mime_type": { "anyOf": [ { "maxLength": 127, "type": "string" }, { "type": "null" } ], "default": null, "title": "Mime Type" }, "name": { "maxLength": 255, "minLength": 1, "title": "Name", "type": "string" }, "relationship": { "anyOf": [ { "enum": [ "Source", "Data", "Alternative", "Supplement", "Unspecified" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Relationship" }, "upload_id": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "default": null, "title": "Upload Id" }, "url": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "default": null, "title": "Url" } }, "required": [ "name" ], "title": "PdfAttachment", "type": "object" }, "PdfCodeDraftWrite": { "properties": { "content": { "additionalProperties": true, "description": "The whole content in one object, instead of the separate fields.", "type": "object" }, "head": { "description": "Extra `` markup (styles, fonts).", "type": "string" }, "header_footer": { "additionalProperties": true, "description": "`{header, footer}`: header/footer objects as in PdfOptions (§2.4).", "type": "object" }, "html": { "description": "Jinja HTML of the body.", "type": "string" }, "options": { "additionalProperties": true, "description": "Default output options (`RenderOptions`: `output_format`, `filename`, `pdf` — PdfOptions §2.4 —, `image`, `strict_undefined`, and for PDF templates `einvoice: {profile, invoice_path}`, a default hybrid e-invoice that every render embeds unless the request sends `output.einvoice`).", "type": "object" }, "schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ] } }, "title": "PdfCode draft", "type": "object" }, "PdfCodeTemplateCreate": { "properties": { "content": { "additionalProperties": true, "description": "The whole content in one object, instead of the separate fields.", "type": "object" }, "datasets": { "description": "Sample data sets `{name, data, is_default}` (rendered when publishing).", "items": { "additionalProperties": true, "type": "object" }, "maxItems": 50, "type": "array" }, "description": { "maxLength": 5000, "type": "string" }, "head": { "description": "Extra `` markup (styles, fonts).", "type": "string" }, "header_footer": { "additionalProperties": true, "description": "`{header, footer}`: header/footer objects as in PdfOptions (§2.4).", "type": "object" }, "html": { "description": "Jinja HTML of the body.", "type": "string" }, "name": { "maxLength": 120, "type": "string" }, "options": { "additionalProperties": true, "description": "Default output options (`RenderOptions`: `output_format`, `filename`, `pdf` — PdfOptions §2.4 —, `image`, `strict_undefined`, and for PDF templates `einvoice: {profile, invoice_path}`, a default hybrid e-invoice that every render embeds unless the request sends `output.einvoice`).", "type": "object" }, "schema": { "anyOf": [ { "additionalProperties": true, "description": "JSON Schema.", "type": "object" }, { "type": "null" } ] }, "type": { "enum": [ "pdf_code" ], "type": "string" } }, "required": [ "name", "type" ], "title": "PdfCode template", "type": "object" }, "PdfMarkdownDraftWrite": { "properties": { "content": { "additionalProperties": true, "description": "The whole content in one object, instead of the separate fields.", "type": "object" }, "css": { "type": "string" }, "head": { "type": "string" }, "header_footer": { "additionalProperties": true, "description": "`{header, footer}`: header/footer objects as in PdfOptions (§2.4).", "type": "object" }, "markdown": { "description": "Jinja-enabled Markdown.", "type": "string" }, "options": { "additionalProperties": true, "description": "Default output options (`RenderOptions`: `output_format`, `filename`, `pdf` — PdfOptions §2.4 —, `image`, `strict_undefined`, and for PDF templates `einvoice: {profile, invoice_path}`, a default hybrid e-invoice that every render embeds unless the request sends `output.einvoice`).", "type": "object" }, "schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ] }, "theme": { "description": "`default`, `github`, `academic`, `minimal` or `none`.", "type": "string" } }, "title": "PdfMarkdown draft", "type": "object" }, "PdfMarkdownTemplateCreate": { "properties": { "content": { "additionalProperties": true, "description": "The whole content in one object, instead of the separate fields.", "type": "object" }, "css": { "type": "string" }, "datasets": { "description": "Sample data sets `{name, data, is_default}` (rendered when publishing).", "items": { "additionalProperties": true, "type": "object" }, "maxItems": 50, "type": "array" }, "description": { "maxLength": 5000, "type": "string" }, "head": { "type": "string" }, "header_footer": { "additionalProperties": true, "description": "`{header, footer}`: header/footer objects as in PdfOptions (§2.4).", "type": "object" }, "markdown": { "description": "Jinja-enabled Markdown.", "type": "string" }, "name": { "maxLength": 120, "type": "string" }, "options": { "additionalProperties": true, "description": "Default output options (`RenderOptions`: `output_format`, `filename`, `pdf` — PdfOptions §2.4 —, `image`, `strict_undefined`, and for PDF templates `einvoice: {profile, invoice_path}`, a default hybrid e-invoice that every render embeds unless the request sends `output.einvoice`).", "type": "object" }, "schema": { "anyOf": [ { "additionalProperties": true, "description": "JSON Schema.", "type": "object" }, { "type": "null" } ] }, "theme": { "description": "`default`, `github`, `academic`, `minimal` or `none`.", "type": "string" }, "type": { "enum": [ "pdf_markdown" ], "type": "string" } }, "required": [ "name", "type" ], "title": "PdfMarkdown template", "type": "object" }, "PdfMetadata": { "additionalProperties": false, "properties": { "author": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "default": null, "title": "Author" }, "creator": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "default": null, "title": "Creator" }, "keywords": { "items": { "maxLength": 100, "type": "string" }, "maxItems": 50, "title": "Keywords", "type": "array" }, "lang": { "anyOf": [ { "maxLength": 35, "type": "string" }, { "type": "null" } ], "default": null, "title": "Lang" }, "subject": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "default": null, "title": "Subject" }, "title": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" } }, "title": "PdfMetadata", "type": "object" }, "PdfMetadataRequest": { "additionalProperties": false, "properties": { "delivery": { "anyOf": [ { "$ref": "#/components/schemas/DeliverySpec" }, { "type": "null" } ], "default": null }, "filename": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Filename" }, "metadata": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "propertyNames": { "maxLength": 40, "minLength": 1 }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Metadata" }, "mode": { "default": "sync", "enum": [ "sync", "async" ], "title": "Mode", "type": "string" }, "priority": { "default": "normal", "enum": [ "normal", "low" ], "title": "Priority", "type": "string" }, "reference": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Reference" }, "set": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Set" }, "source": { "$ref": "#/components/schemas/PdfSourceSpec" }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Test" }, "timeout_behavior": { "default": "continue", "enum": [ "continue", "cancel" ], "title": "Timeout Behavior", "type": "string" }, "webhook": { "anyOf": [ { "$ref": "#/components/schemas/WebhookSpec" }, { "type": "null" } ], "default": null } }, "required": [ "source" ], "title": "PdfMetadataRequest", "type": "object" }, "PdfOptions": { "additionalProperties": false, "properties": { "attachments": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PdfAttachment" }, "maxItems": 20, "type": "array" }, { "type": "null" } ], "default": null, "title": "Attachments" }, "emulate_media": { "anyOf": [ { "enum": [ "print", "screen" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Emulate Media" }, "footer": { "anyOf": [ { "$ref": "#/components/schemas/HeaderFooter" }, { "type": "null" } ], "default": null }, "header": { "anyOf": [ { "$ref": "#/components/schemas/HeaderFooter" }, { "type": "null" } ], "default": null }, "javascript": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Javascript" }, "locale": { "anyOf": [ { "maxLength": 35, "type": "string" }, { "type": "null" } ], "default": null, "title": "Locale" }, "margin": { "anyOf": [ { "$ref": "#/components/schemas/Margin" }, { "type": "null" } ], "default": null }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/PdfMetadata" }, { "type": "null" } ], "default": null }, "orientation": { "anyOf": [ { "enum": [ "portrait", "landscape" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Orientation" }, "outline": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Outline" }, "page_ranges": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "default": null, "title": "Page Ranges" }, "paper": { "anyOf": [ { "$ref": "#/components/schemas/Paper" }, { "type": "null" } ], "default": null }, "pdfa": { "anyOf": [ { "enum": [ "2b", "3b" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Pdfa" }, "pdfua": { "anyOf": [ { "const": "1", "type": "string" }, { "type": "null" } ], "default": null, "description": "`\"1\"`: a PDF/UA-1 (ISO 14289-1) document, validated with veraPDF (report in `result.conformance.pdfua`); a file that fails validation fails the render with `pdfua_validation_failed`. Implies `tagged`; combines with `pdfa`, `einvoice`, `attachments` and `protect` (which keeps assistive-technology access). PDF output only, and not for canvas templates (their PDFs carry no tags); needs the Growth plan or higher. The document needs a title and a language: `metadata.title` and `metadata.lang`, or the page's `` and `<html lang>`.", "title": "Pdfua" }, "prefer_css_page_size": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Prefer Css Page Size" }, "print_background": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Print Background" }, "protect": { "anyOf": [ { "$ref": "#/components/schemas/Protect" }, { "type": "null" } ], "default": null }, "scale": { "anyOf": [ { "maximum": 2.0, "minimum": 0.1, "type": "number" }, { "type": "null" } ], "default": null, "title": "Scale" }, "single_page": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Single Page" }, "tagged": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "A tagged PDF (accessibility structure). Without `pdfua` the PDF/UA-1 report in `result.conformance.pdfua` is information only.", "title": "Tagged" }, "timezone": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "default": null, "title": "Timezone" }, "wait": { "anyOf": [ { "$ref": "#/components/schemas/Wait" }, { "type": "null" } ], "default": null } }, "title": "PdfOptions", "type": "object" }, "PdfSourceSpec": { "additionalProperties": false, "description": "Exactly one of `url`, `render_id` (+ optional `file_id`), `upload_id` or `data_uri`.", "properties": { "data_uri": { "anyOf": [ { "maxLength": 7000000, "type": "string" }, { "type": "null" } ], "default": null, "title": "Data Uri" }, "file_id": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "default": null, "title": "File Id" }, "render_id": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "default": null, "title": "Render Id" }, "upload_id": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "default": null, "title": "Upload Id" }, "url": { "anyOf": [ { "maxLength": 2048, "minLength": 8, "type": "string" }, { "type": "null" } ], "default": null, "title": "Url" } }, "title": "PdfSourceSpec", "type": "object" }, "PdfaConformance": { "properties": { "errors": { "items": { "$ref": "#/components/schemas/ConformanceFinding" }, "maxItems": 100, "type": "array" }, "level": { "enum": [ "2b", "3b" ], "type": "string" }, "profile": { "anyOf": [ { "description": "veraPDF validation profile; `null` when veraPDF did not run.", "example": "PDF/A-3B validation profile", "type": "string" }, { "type": "null" } ] }, "status": { "description": "`unavailable`: the validator was not configured or did not answer in time; the file was delivered unvalidated (warning `pdfa_validation_unavailable`).", "enum": [ "passed", "failed", "unavailable" ], "type": "string" }, "validator": { "anyOf": [ { "description": "`null` when veraPDF did not run (conversion failed, or unavailable).", "example": "veraPDF 1.30.2", "type": "string" }, { "type": "null" } ] }, "warnings": { "items": { "$ref": "#/components/schemas/ConformanceFinding" }, "maxItems": 100, "type": "array" } }, "required": [ "level", "status", "validator", "profile", "errors", "warnings" ], "type": "object" }, "PdfaRequest": { "additionalProperties": false, "description": "`POST /v1/pdf-tools/pdfa` (proto/README.md §20.1): convert to PDF/A and validate with veraPDF.", "properties": { "delivery": { "anyOf": [ { "$ref": "#/components/schemas/DeliverySpec" }, { "type": "null" } ], "default": null }, "filename": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Filename" }, "level": { "description": "PDF/A conformance level: `2b` (ISO 19005-2) or `3b` (ISO 19005-3, allows attachments).", "enum": [ "2b", "3b" ], "title": "Level", "type": "string" }, "metadata": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "propertyNames": { "maxLength": 40, "minLength": 1 }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Metadata" }, "mode": { "default": "sync", "enum": [ "sync", "async" ], "title": "Mode", "type": "string" }, "priority": { "default": "normal", "enum": [ "normal", "low" ], "title": "Priority", "type": "string" }, "reference": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Reference" }, "source": { "$ref": "#/components/schemas/PdfSourceSpec" }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Test" }, "timeout_behavior": { "default": "continue", "enum": [ "continue", "cancel" ], "title": "Timeout Behavior", "type": "string" }, "webhook": { "anyOf": [ { "$ref": "#/components/schemas/WebhookSpec" }, { "type": "null" } ], "default": null } }, "required": [ "source", "level" ], "title": "PdfaRequest", "type": "object" }, "PdfuaConformance": { "description": "veraPDF's PDF/UA-1 check of a render with `pdf.pdfua` or `pdf.tagged`. With `pdfua`, `failed` fails the render (`pdfua_validation_failed`); with `tagged` alone, and in previews, the report is information. The machine checks don't judge whether alt text is meaningful or the reading order right.", "properties": { "errors": { "items": { "$ref": "#/components/schemas/ConformanceFinding" }, "maxItems": 100, "type": "array" }, "profile": { "anyOf": [ { "description": "veraPDF validation profile; `null` when veraPDF did not run.", "example": "PDF/UA-1 validation profile", "type": "string" }, { "type": "null" } ] }, "standard": { "enum": [ "PDF/UA-1" ], "type": "string" }, "status": { "description": "`unavailable`: the validator was not configured or did not answer in time; the file was delivered unvalidated (warning `pdfua_validation_unavailable`).", "enum": [ "passed", "failed", "unavailable" ], "type": "string" }, "validator": { "anyOf": [ { "description": "`null` when veraPDF did not run (the title or language was missing, or unavailable).", "example": "veraPDF 1.30.2", "type": "string" }, { "type": "null" } ] }, "warnings": { "items": { "$ref": "#/components/schemas/ConformanceFinding" }, "maxItems": 100, "type": "array" } }, "required": [ "standard", "status", "validator", "profile", "errors", "warnings" ], "type": "object" }, "Permissions": { "additionalProperties": false, "description": "Permissions of a protected PDF (docs/05 §2.4).\n\nProtecting a document restricts editing, not reading: an omitted flag must never end up denied.\n`Permissions` on the wire has explicit presence per flag, and the renderer applies exactly these\ndefaults to the ones a job leaves unset (`DEFAULT_PERMISSIONS` in\n`worker/bins/renderer/src/job.rs`) — the two lists must stay identical.", "properties": { "annotate": { "default": false, "title": "Annotate", "type": "boolean" }, "assemble": { "default": false, "title": "Assemble", "type": "boolean" }, "copy": { "default": true, "title": "Copy", "type": "boolean" }, "fill_forms": { "default": true, "title": "Fill Forms", "type": "boolean" }, "modify": { "default": false, "title": "Modify", "type": "boolean" }, "print": { "default": true, "title": "Print", "type": "boolean" }, "print_high_res": { "default": true, "title": "Print High Res", "type": "boolean" } }, "title": "Permissions", "type": "object" }, "PreviewContent": { "additionalProperties": true, "description": "Unsaved draft content (proto/README.md §9 `content` JSON).", "properties": { "css": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Css" }, "head": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Head" }, "header_footer": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Header Footer" }, "html": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Html" }, "markdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Markdown" }, "options": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Options" }, "scene": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Scene" }, "theme": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Theme" } }, "title": "PreviewContent", "type": "object" }, "Problem": { "description": "RFC 9457 problem details (docs: /errors).", "properties": { "code": { "example": "validation_error", "type": "string" }, "detail": { "type": "string" }, "doc_url": { "format": "uri", "type": "string" }, "errors": { "items": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "path": { "example": "/data/items/0/qty", "type": "string" } }, "type": "object" }, "type": "array" }, "render_error": { "$ref": "#/components/schemas/RenderError" }, "render_id": { "example": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "type": "string" }, "request_id": { "type": "string" }, "result": { "anyOf": [ { "$ref": "#/components/schemas/RenderResult" }, { "type": "null" } ], "description": "The failed render's `result`: the conformance report for `einvoice_invalid`, `einvoice_validation_failed`, `pdfa_conversion_failed` and `pdfua_validation_failed`." }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail" ], "type": "object" }, "Protect": { "additionalProperties": false, "properties": { "owner_password": { "anyOf": [ { "maxLength": 127, "type": "string" }, { "type": "null" } ], "default": null, "title": "Owner Password" }, "permissions": { "anyOf": [ { "$ref": "#/components/schemas/Permissions" }, { "type": "null" } ], "default": null }, "user_password": { "anyOf": [ { "maxLength": 127, "type": "string" }, { "type": "null" } ], "default": null, "title": "User Password" } }, "title": "Protect", "type": "object" }, "ProtectRequest": { "additionalProperties": false, "properties": { "delivery": { "anyOf": [ { "$ref": "#/components/schemas/DeliverySpec" }, { "type": "null" } ], "default": null }, "filename": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Filename" }, "metadata": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "propertyNames": { "maxLength": 40, "minLength": 1 }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Metadata" }, "mode": { "default": "sync", "enum": [ "sync", "async" ], "title": "Mode", "type": "string" }, "owner_password": { "anyOf": [ { "maxLength": 127, "type": "string" }, { "type": "null" } ], "default": null, "title": "Owner Password" }, "permissions": { "anyOf": [ { "additionalProperties": { "type": "boolean" }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Permissions" }, "priority": { "default": "normal", "enum": [ "normal", "low" ], "title": "Priority", "type": "string" }, "reference": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Reference" }, "source": { "$ref": "#/components/schemas/PdfSourceSpec" }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Test" }, "timeout_behavior": { "default": "continue", "enum": [ "continue", "cancel" ], "title": "Timeout Behavior", "type": "string" }, "user_password": { "anyOf": [ { "maxLength": 127, "type": "string" }, { "type": "null" } ], "default": null, "title": "User Password" }, "webhook": { "anyOf": [ { "$ref": "#/components/schemas/WebhookSpec" }, { "type": "null" } ], "default": null } }, "required": [ "source" ], "title": "ProtectRequest", "type": "object" }, "PublishRun": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "draft_revision": { "type": "integer" }, "error": { "additionalProperties": {}, "type": [ "object", "null" ] }, "errors": { "description": "Flattened, with `step`.", "items": { "additionalProperties": {}, "type": "object" }, "type": "array" }, "finished_at": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "`pub_…`", "type": "string" }, "note": { "type": "string" }, "object": { "default": "publish_run", "type": "string" }, "status": { "description": "* `running` - running\n* `succeeded` - succeeded\n* `failed` - failed", "enum": [ "running", "succeeded", "failed" ], "type": "string", "x-spec-enum-id": "4939c1db23091193" }, "steps": { "items": { "$ref": "#/components/schemas/PublishStep" }, "type": "array" }, "template_id": { "type": "string" }, "version": { "additionalProperties": {}, "description": "`{id, number, content_hash, published_at, note}` once published.", "type": [ "object", "null" ] }, "warnings": { "items": { "additionalProperties": {}, "type": "object" }, "type": "array" } }, "required": [ "created_at", "draft_revision", "error", "errors", "finished_at", "id", "note", "status", "steps", "template_id", "version", "warnings" ], "type": "object" }, "PublishStep": { "properties": { "duration_ms": { "type": "integer" }, "errors": { "items": { "additionalProperties": {}, "type": "object" }, "type": "array" }, "name": { "description": "`lock`, `compile`, `options`, `syntax`, `datasets`, …", "type": "string" }, "status": { "description": "* `succeeded` - succeeded\n* `failed` - failed\n* `skipped` - skipped\n* `running` - running", "enum": [ "succeeded", "failed", "skipped", "running" ], "type": "string", "x-spec-enum-id": "cfc96a6e0450d85c" }, "warnings": { "items": { "additionalProperties": {}, "type": "object" }, "type": "array" } }, "required": [ "errors", "name", "status", "warnings" ], "type": "object" }, "Render": { "properties": { "batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "billed_renders": { "description": "Renders billed for this request (0 for test renders, previews, failed and canceled renders).", "example": 1, "type": "integer" }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "email": { "description": "The render's email sends in creation order (docs/05 §8.4). The deliverer creates them when it processes the result, so a render still running (or a sync response) lists none yet; `render.succeeded` shows them as created: `pending`, or `skipped` / `failed`.", "items": { "$ref": "#/components/schemas/RenderEmail" }, "type": "array" }, "engine": { "example": "2026.4", "type": "string" }, "engine_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "error": { "anyOf": [ { "$ref": "#/components/schemas/RenderError" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "files": { "items": { "$ref": "#/components/schemas/RenderFile" }, "type": "array" }, "id": { "example": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "type": "string" }, "input_type": { "enum": [ "template", "html", "url", "markdown", "pdf_tool", "einvoice" ], "type": "string" }, "kind": { "example": "pdf_template", "type": "string" }, "metadata": { "additionalProperties": true, "type": "object" }, "mode": { "enum": [ "sync", "async" ], "type": "string" }, "object": { "enum": [ "render" ], "type": "string" }, "output_format": { "enum": [ "pdf", "png", "jpeg", "webp", "html", "zip", "xml" ], "type": "string" }, "pages": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "region": { "example": "eu", "type": "string" }, "result": { "anyOf": [ { "$ref": "#/components/schemas/RenderResult" }, { "type": "null" } ] }, "source": { "example": "api", "type": "string" }, "status": { "enum": [ "queued", "processing", "succeeded", "failed", "canceled", "expired" ], "type": "string" }, "storage": { "items": { "$ref": "#/components/schemas/StorageResult" }, "type": "array" }, "template": { "anyOf": [ { "properties": { "id": { "type": "string" }, "version": { "anyOf": [ { "type": "integer" }, { "type": "string" } ] }, "version_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "type": "object" }, { "type": "null" } ] }, "test": { "type": "boolean" }, "timings": { "additionalProperties": { "type": "integer" }, "example": { "queued_ms": 3, "render_ms": 612, "total_ms": 681, "upload_ms": 38 }, "type": "object" }, "warnings": { "description": "Non-fatal: `slow_asset`, `asset_failed`, `wait_timeout` (the wait condition timed out and `wait.strict` is off, so the page was rendered as it was), `header_footer_overlap` (a header or footer is taller than its margin and may cover the body), `locale_unsupported` (the engine doesn't support `locale`), `feature_unavailable` (something in the request or template was ignored; the message names it), `font_fallback_used` (canvas templates: an unavailable font was replaced by Noto Sans; HTML renders fall back silently), `data_coerced` (canvas templates: a data value couldn't be used as given), `text_overflow` (canvas templates: text was cut off or overflows its box), `storage_upload_failed`, `einvoice_validation_warning`, `einvoice_validation_unavailable`, `pdfa_validation_unavailable`, `pdfua_validation_unavailable` (veraPDF was not reachable: the PDF/UA file is delivered unvalidated), `accessibility_validation_unavailable` (`tagged` without `pdfua`: no PDF/UA report, veraPDF was not reachable), `einvoice_skipped_plan`, `storage_skipped_plan`, `email_skipped_plan` (the template's email rules need the Growth plan or higher; no email was sent), `email_skipped_zero_retention` (zero-retention renders have no file to email), `invoice_totals_unavailable`.", "items": { "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "type": "array" } }, "required": [ "id", "object", "status", "mode", "test", "region", "files", "created_at" ], "type": "object" }, "RenderEmail": { "description": "One email send of the render.", "properties": { "error": { "anyOf": [ { "$ref": "#/components/schemas/EmailSendError" }, { "type": "null" } ] }, "id": { "example": "ems_01J9ZM1X3F7R8K2C4V6B8N0P2T", "type": "string" }, "provider_message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rule_id": { "example": "emr_01J9ZK3M7Q8V5W2X4Y6Z8A0B1E", "type": "string" }, "sent_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "pending", "sending", "retrying", "sent", "sandboxed", "skipped", "failed", "unknown", "canceled" ], "type": "string" }, "to": { "description": "The `to` addresses.", "items": { "type": "string" }, "type": "array" } }, "required": [ "id", "rule_id", "status", "to", "provider_message_id", "error", "sent_at" ], "type": "object" }, "RenderError": { "properties": { "code": { "example": "template_runtime_error", "type": "string" }, "column": { "type": "integer" }, "detail": { "type": "string" }, "excerpt": { "type": "string" }, "line": { "type": "integer" }, "message": { "type": "string" } }, "type": "object" }, "RenderFile": { "properties": { "bytes": { "example": 48213, "type": "integer" }, "content_base64": { "description": "Only with `delivery.type=base64`.", "type": "string" }, "content_type": { "example": "application/pdf", "type": "string" }, "filename": { "example": "invoice-42.pdf", "type": "string" }, "format": { "enum": [ "pdf", "png", "jpeg", "webp", "html", "zip", "xml" ], "type": "string" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "id": { "example": "file_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "type": "string" }, "pages": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "sha256": { "type": "string" }, "url": { "description": "Signed URL (omitted when not hosted).", "format": "uri", "type": "string" }, "url_expires_at": { "format": "date-time", "type": "string" }, "variant": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "id", "format", "filename", "bytes" ], "type": "object" }, "RenderList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Render" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "object": { "enum": [ "list" ], "type": "string" } }, "required": [ "object", "data", "has_more" ], "type": "object" }, "RenderLog": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "logging": { "enum": [ "metadata", "full" ], "type": "string" }, "object": { "enum": [ "render_log" ], "type": "string" }, "render_id": { "type": "string" }, "request": { "additionalProperties": true, "type": "object" }, "response": { "additionalProperties": true, "type": "object" }, "retained_until": { "format": "date-time", "type": "string" } }, "type": "object" }, "RenderPreviewRequest": { "additionalProperties": false, "properties": { "content": { "anyOf": [ { "$ref": "#/components/schemas/PreviewContent" }, { "type": "null" } ], "default": null }, "data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Data" }, "engine": { "anyOf": [ { "pattern": "^\\d{4}\\.\\d{1,6}$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Engine" }, "output": { "anyOf": [ { "$ref": "#/components/schemas/OutputSpec" }, { "type": "null" } ], "default": null }, "template_id": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "default": null, "title": "Template Id" }, "template_type": { "anyOf": [ { "enum": [ "pdf_code", "pdf_markdown", "image_canvas" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Template Type" }, "version": { "anyOf": [ { "enum": [ "live", "draft" ], "type": "string" }, { "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null, "title": "Version" } }, "title": "RenderPreviewRequest", "type": "object" }, "RenderRequest": { "additionalProperties": false, "properties": { "data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Data" }, "data_url": { "anyOf": [ { "maxLength": 2048, "minLength": 8, "type": "string" }, { "type": "null" } ], "default": null, "title": "Data Url" }, "delivery": { "anyOf": [ { "$ref": "#/components/schemas/DeliverySpec" }, { "type": "null" } ], "default": null }, "engine": { "anyOf": [ { "pattern": "^\\d{4}\\.\\d{1,6}$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Engine" }, "input": { "discriminator": { "mapping": { "html": "#/components/schemas/HtmlInputSpec", "markdown": "#/components/schemas/MarkdownInputSpec", "template": "#/components/schemas/TemplateInputSpec", "url": "#/components/schemas/UrlInputSpec" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/TemplateInputSpec" }, { "$ref": "#/components/schemas/HtmlInputSpec" }, { "$ref": "#/components/schemas/UrlInputSpec" }, { "$ref": "#/components/schemas/MarkdownInputSpec" } ], "title": "Input" }, "metadata": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "propertyNames": { "maxLength": 40, "minLength": 1 }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Metadata" }, "mode": { "default": "sync", "enum": [ "sync", "async" ], "title": "Mode", "type": "string" }, "output": { "anyOf": [ { "$ref": "#/components/schemas/OutputSpec" }, { "type": "null" } ], "default": null }, "overrides": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "maxItems": 500, "type": "array" }, { "type": "null" } ], "default": null, "title": "Overrides" }, "priority": { "default": "normal", "enum": [ "normal", "low" ], "title": "Priority", "type": "string" }, "reference": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Reference" }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Test" }, "timeout_behavior": { "default": "continue", "enum": [ "continue", "cancel" ], "title": "Timeout Behavior", "type": "string" }, "webhook": { "anyOf": [ { "$ref": "#/components/schemas/WebhookSpec" }, { "type": "null" } ], "default": null } }, "required": [ "input" ], "title": "RenderRequest", "type": "object" }, "RenderResult": { "additionalProperties": true, "description": "Structured result, `null` for most renders. PDF/A, PDF/UA, tagged and e-invoice renders carry their conformance report here — succeeded **and** failed ones; `pdf-tools/metadata` without `set` returns the document information (`pages`, `page_sizes`, `encrypted`, `metadata`).", "properties": { "conformance": { "$ref": "#/components/schemas/ConformanceReport" } }, "type": "object" }, "RenderWithEmailPreview": { "allOf": [ { "$ref": "#/components/schemas/Render" }, { "properties": { "email_preview": { "anyOf": [ { "$ref": "#/components/schemas/EmailPreview" }, { "type": "null" } ], "description": "`null` when the preview did not finish within the sync wait (202)." } }, "required": [ "email_preview" ], "type": "object" } ] }, "RollSecret": { "properties": { "expire_previous_in": { "default": 86400, "description": "Seconds the previous secret keeps signing deliveries (0 = immediately).", "maximum": 604800, "minimum": 0, "type": "integer" } }, "type": "object" }, "RotateRequest": { "additionalProperties": false, "properties": { "degrees": { "enum": [ 90, 180, 270, -90, -180, -270 ], "title": "Degrees", "type": "integer" }, "delivery": { "anyOf": [ { "$ref": "#/components/schemas/DeliverySpec" }, { "type": "null" } ], "default": null }, "filename": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Filename" }, "metadata": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "propertyNames": { "maxLength": 40, "minLength": 1 }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Metadata" }, "mode": { "default": "sync", "enum": [ "sync", "async" ], "title": "Mode", "type": "string" }, "pages": { "default": "all", "maxLength": 200, "pattern": "^\\s*(all|\\d+(\\s*-\\s*\\d*)?(\\s*,\\s*\\d+(\\s*-\\s*\\d*)?)*)\\s*$", "title": "Pages", "type": "string" }, "priority": { "default": "normal", "enum": [ "normal", "low" ], "title": "Priority", "type": "string" }, "reference": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Reference" }, "source": { "$ref": "#/components/schemas/PdfSourceSpec" }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Test" }, "timeout_behavior": { "default": "continue", "enum": [ "continue", "cancel" ], "title": "Timeout Behavior", "type": "string" }, "webhook": { "anyOf": [ { "$ref": "#/components/schemas/WebhookSpec" }, { "type": "null" } ], "default": null } }, "required": [ "source", "degrees" ], "title": "RotateRequest", "type": "object" }, "SignUrl": { "properties": { "expires_at": { "description": "Unix seconds; omit for a link that does not expire.", "minimum": 0, "type": "integer" }, "format": { "description": "* `png` - png\n* `jpeg` - jpeg\n* `webp` - webp\n* `pdf` - pdf", "enum": [ "png", "jpeg", "webp", "pdf" ], "type": "string", "x-spec-enum-id": "66096331f0c3a912" }, "name": { "default": "render", "description": "File name in the URL (cosmetic, but signed).", "maxLength": 80, "type": "string" }, "params": { "additionalProperties": { "maxLength": 2000, "type": "string" }, "type": "object" } }, "required": [ "format" ], "type": "object" }, "SignedLink": { "properties": { "access": { "description": "* `signed` - signed\n* `open` - open", "enum": [ "signed", "open" ], "type": "string", "x-spec-enum-id": "897113911536df41" }, "allowed_params": { "items": { "type": "string" }, "type": "array" }, "allowed_referrers": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "base_url": { "description": "Append `/{any-name}.{ext}?…` and a signature.", "format": "uri", "type": "string" }, "cache_ttl_seconds": { "type": [ "integer", "null" ] }, "created_at": { "format": "date-time", "type": "string" }, "defaults": { "additionalProperties": {}, "description": "Parameter values used when the URL omits them.", "type": "object" }, "enabled": { "type": "boolean" }, "expires_at": { "format": "date-time", "type": [ "string", "null" ] }, "fallback_image_asset_id": { "description": "`ast_…`: image served instead of 402 `render_limit_reached`.", "type": [ "string", "null" ] }, "formats": { "items": { "description": "* `png` - png\n* `jpeg` - jpeg\n* `webp` - webp\n* `pdf` - pdf", "enum": [ "png", "jpeg", "webp", "pdf" ], "type": "string", "x-spec-enum-id": "66096331f0c3a912" }, "type": "array" }, "id": { "description": "`lnk_…`", "type": "string" }, "name": { "type": "string" }, "object": { "default": "signed_link", "type": "string" }, "param_limits": { "additionalProperties": {}, "description": "e.g. `{\"title.text\": {\"max_length\": 80}}`.", "type": "object" }, "quota_total": { "type": [ "integer", "null" ] }, "quota_used": { "type": "integer" }, "rate_limit_per_ip_per_hour": { "type": [ "integer", "null" ] }, "template_id": { "type": "string" } }, "required": [ "access", "allowed_params", "allowed_referrers", "base_url", "cache_ttl_seconds", "created_at", "defaults", "enabled", "expires_at", "fallback_image_asset_id", "formats", "id", "name", "param_limits", "quota_total", "quota_used", "rate_limit_per_ip_per_hour", "template_id" ], "type": "object" }, "SignedLinkList": { "description": "Cursor-pagination envelope (docs/05 §1). Management lists are single-page today.", "properties": { "data": { "items": { "$ref": "#/components/schemas/SignedLink" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "object": { "default": "list", "type": "string" } }, "required": [ "data", "has_more", "next_cursor" ], "type": "object" }, "SignedLinkWithSecret": { "description": "Create response: the HMAC secret SDKs sign with locally is returned once.", "properties": { "access": { "description": "* `signed` - signed\n* `open` - open", "enum": [ "signed", "open" ], "type": "string", "x-spec-enum-id": "897113911536df41" }, "allowed_params": { "items": { "type": "string" }, "type": "array" }, "allowed_referrers": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "base_url": { "description": "Append `/{any-name}.{ext}?…` and a signature.", "format": "uri", "type": "string" }, "cache_ttl_seconds": { "type": [ "integer", "null" ] }, "created_at": { "format": "date-time", "type": "string" }, "defaults": { "additionalProperties": {}, "description": "Parameter values used when the URL omits them.", "type": "object" }, "enabled": { "type": "boolean" }, "expires_at": { "format": "date-time", "type": [ "string", "null" ] }, "fallback_image_asset_id": { "description": "`ast_…`: image served instead of 402 `render_limit_reached`.", "type": [ "string", "null" ] }, "formats": { "items": { "description": "* `png` - png\n* `jpeg` - jpeg\n* `webp` - webp\n* `pdf` - pdf", "enum": [ "png", "jpeg", "webp", "pdf" ], "type": "string", "x-spec-enum-id": "66096331f0c3a912" }, "type": "array" }, "id": { "description": "`lnk_…`", "type": "string" }, "name": { "type": "string" }, "object": { "default": "signed_link", "type": "string" }, "param_limits": { "additionalProperties": {}, "description": "e.g. `{\"title.text\": {\"max_length\": 80}}`.", "type": "object" }, "quota_total": { "type": [ "integer", "null" ] }, "quota_used": { "type": "integer" }, "rate_limit_per_ip_per_hour": { "type": [ "integer", "null" ] }, "secret": { "description": "base64url HMAC-SHA256 key. Shown once.", "type": "string" }, "template_id": { "type": "string" } }, "required": [ "access", "allowed_params", "allowed_referrers", "base_url", "cache_ttl_seconds", "created_at", "defaults", "enabled", "expires_at", "fallback_image_asset_id", "formats", "id", "name", "param_limits", "quota_total", "quota_used", "rate_limit_per_ip_per_hour", "secret", "template_id" ], "type": "object" }, "SignedLinkWrite": { "properties": { "access": { "default": "signed", "description": "`open` accepts unsigned requests within `allowed_params` and `param_limits`.\n\n* `signed` - signed\n* `open` - open", "enum": [ "signed", "open" ], "type": "string", "x-spec-enum-id": "897113911536df41" }, "allowed_params": { "description": "Dynamic properties callers may set, e.g. `title.text`.", "items": { "maxLength": 120, "type": "string" }, "maxItems": 100, "type": "array" }, "allowed_referrers": { "items": { "maxLength": 255, "type": "string" }, "maxItems": 50, "type": "array" }, "cache_ttl_seconds": { "minimum": 60, "type": [ "integer", "null" ] }, "defaults": { "additionalProperties": {}, "type": "object" }, "enabled": { "type": "boolean" }, "expires_at": { "format": "date-time", "type": [ "string", "null" ] }, "fallback_image_asset_id": { "description": "Ready image asset (`ast_…`) returned instead of 402 `render_limit_reached`; null clears.", "maxLength": 40, "type": [ "string", "null" ] }, "formats": { "items": { "description": "* `png` - png\n* `jpeg` - jpeg\n* `webp` - webp\n* `pdf` - pdf", "enum": [ "png", "jpeg", "webp", "pdf" ], "type": "string", "x-spec-enum-id": "66096331f0c3a912" }, "minItems": 1, "type": "array" }, "name": { "maxLength": 80, "type": "string" }, "param_limits": { "additionalProperties": {}, "type": "object" }, "quota_total": { "minimum": 1, "type": [ "integer", "null" ] }, "rate_limit_per_ip_per_hour": { "maximum": 100000, "minimum": 1, "type": [ "integer", "null" ] }, "template_id": { "type": "string" } }, "required": [ "formats", "name", "template_id" ], "type": "object" }, "SignedUrl": { "properties": { "object": { "default": "signed_url", "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "url" ], "type": "object" }, "SplitRequest": { "additionalProperties": false, "description": "`POST /v1/pdf-tools/split` (proto/README.md §26.1): one PDF per range or per run of `every` pages.", "properties": { "delivery": { "anyOf": [ { "$ref": "#/components/schemas/DeliverySpec" }, { "type": "null" } ], "default": null }, "every": { "anyOf": [ { "maximum": 10000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null, "description": "One output file per run of this many pages instead.", "title": "Every" }, "filename": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Filename" }, "metadata": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "propertyNames": { "maxLength": 40, "minLength": 1 }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Metadata" }, "mode": { "default": "sync", "enum": [ "sync", "async" ], "title": "Mode", "type": "string" }, "priority": { "default": "normal", "enum": [ "normal", "low" ], "title": "Priority", "type": "string" }, "ranges": { "anyOf": [ { "items": { "maxLength": 40, "pattern": "^\\s*(all|\\d+(\\s*-\\s*\\d*)?(\\s*,\\s*\\d+(\\s*-\\s*\\d*)?)*)\\s*$", "type": "string" }, "maxItems": 200, "type": "array" }, { "type": "null" } ], "default": null, "description": "Page lists, one output file each: `\"1-3\"`, `\"4-\"` (to the last page), `\"7\"`, `\"1,3-5\"`. Pages are numbered from 1.", "title": "Ranges" }, "reference": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Reference" }, "source": { "$ref": "#/components/schemas/PdfSourceSpec" }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Test" }, "timeout_behavior": { "default": "continue", "enum": [ "continue", "cancel" ], "title": "Timeout Behavior", "type": "string" }, "webhook": { "anyOf": [ { "$ref": "#/components/schemas/WebhookSpec" }, { "type": "null" } ], "default": null }, "zip": { "default": false, "description": "Deliver one ZIP (`<stem>.zip`) holding the parts instead of one file per part.", "title": "Zip", "type": "boolean" } }, "required": [ "source" ], "title": "SplitRequest", "type": "object" }, "StorageDestination": { "properties": { "config": { "additionalProperties": {}, "description": "Provider settings: bucket, region, endpoint, prefix, …; for SFTP host, port, username, prefix and host_key.", "type": "object" }, "created_at": { "format": "date-time", "type": "string" }, "credentials": { "additionalProperties": {}, "description": "Write-only: reads return `{\"configured\": true|false}` (docs/09 F-FILE-7).", "type": "object" }, "id": { "description": "`dst_…`", "type": "string" }, "is_default": { "type": "boolean" }, "keep_hosted_copy": { "type": "boolean" }, "last_test": { "$ref": "#/components/schemas/StorageLastTest" }, "name": { "type": "string" }, "object": { "default": "storage_destination", "type": "string" }, "path_template": { "description": "Jinja path for uploaded files.", "type": "string" }, "provider": { "description": "* `s3` - Amazon S3\n* `s3_compatible` - S3-compatible\n* `azure_blob` - Azure Blob Storage\n* `gcs` - Google Cloud Storage\n* `sftp` - SFTP", "enum": [ "s3", "s3_compatible", "azure_blob", "gcs", "sftp" ], "type": "string", "x-spec-enum-id": "52b8262084245aab" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "config", "created_at", "credentials", "id", "is_default", "keep_hosted_copy", "last_test", "name", "path_template", "provider", "updated_at" ], "type": "object" }, "StorageDestinationList": { "description": "Cursor-pagination envelope (docs/05 §1). Management lists are single-page today.", "properties": { "data": { "items": { "$ref": "#/components/schemas/StorageDestination" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "object": { "default": "list", "type": "string" } }, "required": [ "data", "has_more", "next_cursor" ], "type": "object" }, "StorageDestinationWrite": { "properties": { "config": { "additionalProperties": {}, "type": "object" }, "credentials": { "additionalProperties": {}, "description": "Never returned again; send it only when it changes.", "type": "object" }, "is_default": { "default": false, "type": "boolean" }, "keep_hosted_copy": { "default": true, "type": "boolean" }, "name": { "maxLength": 80, "type": "string" }, "path_template": { "default": "", "maxLength": 500, "type": "string" }, "provider": { "description": "* `s3` - Amazon S3\n* `s3_compatible` - S3-compatible\n* `azure_blob` - Azure Blob Storage\n* `gcs` - Google Cloud Storage\n* `sftp` - SFTP", "enum": [ "s3", "s3_compatible", "azure_blob", "gcs", "sftp" ], "type": "string", "x-spec-enum-id": "52b8262084245aab" } }, "required": [ "config", "name", "provider" ], "type": "object" }, "StorageLastTest": { "properties": { "at": { "format": "date-time", "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "status": { "description": "* `succeeded` - succeeded\n* `failed` - failed", "enum": [ "succeeded", "failed", null ], "type": [ "string", "null" ], "x-spec-enum-id": "c784105c2922494d" } }, "required": [ "at", "error", "status" ], "type": "object" }, "StorageResult": { "properties": { "destination_id": { "example": "dst_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "type": "string" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "pending", "succeeded", "failed", "skipped" ], "type": "string" } }, "type": "object" }, "StorageTargetSpec": { "additionalProperties": false, "properties": { "destination_id": { "maxLength": 64, "minLength": 1, "title": "Destination Id", "type": "string" }, "path": { "anyOf": [ { "maxLength": 1024, "type": "string" }, { "type": "null" } ], "default": null, "title": "Path" } }, "required": [ "destination_id" ], "title": "StorageTargetSpec", "type": "object" }, "StorageTest": { "properties": { "destination": { "$ref": "#/components/schemas/StorageDestination" }, "host_key": { "description": "SFTP: the SHA-256 fingerprint of the host key the server showed (`SHA256:…`). When it isn't `config.host_key`, the `host_key` step fails; update `config.host_key` once you checked it.", "type": "string" }, "object": { "default": "storage_test", "type": "string" }, "ok": { "type": "boolean" }, "steps": { "items": { "$ref": "#/components/schemas/StorageTestStep" }, "type": "array" } }, "required": [ "destination", "ok", "steps" ], "type": "object" }, "StorageTestStep": { "properties": { "detail": { "type": [ "string", "null" ] }, "name": { "description": "e.g. `credentials`, `write`, `read`, `delete`; SFTP starts with `connect` and `host_key`.", "type": "string" }, "ok": { "type": "boolean" } }, "required": [ "name", "ok" ], "type": "object" }, "Template": { "properties": { "default_output": { "additionalProperties": true, "type": "object" }, "engine": { "type": "string" }, "folder": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "example": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "type": "string" }, "live_version": { "anyOf": [ { "$ref": "#/components/schemas/TemplateVersionSummary" }, { "type": "null" } ] }, "name": { "type": "string" }, "object": { "enum": [ "template" ], "type": "string" }, "settings": { "additionalProperties": true, "type": "object" }, "tags": { "items": { "type": "string" }, "type": "array" }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "enum": [ "pdf_code", "pdf_markdown", "image_canvas", "docx", "pdf_form" ], "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "type": "object" }, "TemplateCreateRequest": { "description": "`POST /v1/templates`: the content fields depend on `type`; any type may instead send one `content` object.", "discriminator": { "mapping": { "image_canvas": "#/components/schemas/ImageCanvasTemplateCreate", "pdf_code": "#/components/schemas/PdfCodeTemplateCreate", "pdf_markdown": "#/components/schemas/PdfMarkdownTemplateCreate" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/PdfCodeTemplateCreate" }, { "$ref": "#/components/schemas/PdfMarkdownTemplateCreate" }, { "$ref": "#/components/schemas/ImageCanvasTemplateCreate" } ] }, "TemplateDeleted": { "properties": { "deleted": { "type": "boolean" }, "deleted_at": { "description": "Purged 30 days later (docs/05 §6).", "format": "date-time", "type": "string" }, "id": { "type": "string" }, "object": { "default": "template", "type": "string" } }, "required": [ "deleted", "deleted_at", "id" ], "type": "object" }, "TemplateDraft": { "properties": { "content": { "additionalProperties": {}, "description": "The content of the template's type: `html`/`head`, `markdown`, `doc`/`theme`, `scene`, and `options`.", "type": "object" }, "object": { "default": "template_draft", "type": "string" }, "revision": { "description": "Send it back as `If-Match` on the next write.", "type": "integer" }, "schema": { "additionalProperties": {}, "type": [ "object", "null" ] }, "template_id": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "content", "revision", "schema", "template_id", "updated_at" ], "type": "object" }, "TemplateDraftWriteRequest": { "anyOf": [ { "$ref": "#/components/schemas/PdfCodeDraftWrite" }, { "$ref": "#/components/schemas/PdfMarkdownDraftWrite" }, { "$ref": "#/components/schemas/ImageCanvasDraftWrite" } ], "description": "`PUT /v1/templates/{id}/draft`: the content fields of the template's type, or one `content` object." }, "TemplateFolder": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "TemplateInputSpec": { "additionalProperties": false, "properties": { "template_id": { "maxLength": 64, "minLength": 1, "title": "Template Id", "type": "string" }, "type": { "const": "template", "title": "Type", "type": "string" }, "version": { "anyOf": [ { "enum": [ "live", "draft" ], "type": "string" }, { "minimum": 1, "type": "integer" } ], "default": "live", "title": "Version" } }, "required": [ "type", "template_id" ], "title": "TemplateInputSpec", "type": "object" }, "TemplateList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Template" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "object": { "enum": [ "list" ], "type": "string" } }, "type": "object" }, "TemplatePublish": { "properties": { "note": { "default": "", "maxLength": 500, "type": "string" } }, "type": "object" }, "TemplateRollback": { "properties": { "version": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Version number (`7`) or a `tv_…` id." } }, "required": [ "version" ], "type": "object" }, "TemplateSchema": { "properties": { "declared": { "type": "boolean" }, "dynamic_properties": { "items": { "properties": { "default": {}, "key": { "example": "title.text", "type": "string" }, "max_length": { "type": "integer" }, "type": { "type": "string" } }, "type": "object" }, "type": "array" }, "object": { "enum": [ "template_schema" ], "type": "string" }, "schema": { "additionalProperties": true, "type": "object" }, "template_id": { "type": "string" }, "version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "type": "object" }, "TemplateVersion": { "allOf": [ { "$ref": "#/components/schemas/TemplateVersionSummary" }, { "properties": { "is_live": { "type": "boolean" }, "options": { "additionalProperties": true, "type": "object" }, "schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ] }, "sources": { "additionalProperties": { "type": "string" }, "type": "object" }, "template_id": { "type": "string" } }, "type": "object" } ] }, "TemplateVersionList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/TemplateVersionSummary" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "object": { "enum": [ "list" ], "type": "string" } }, "type": "object" }, "TemplateVersionSummary": { "properties": { "content_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "engine": { "type": "string" }, "id": { "example": "tv_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "type": "string" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "number": { "type": "integer" }, "object": { "enum": [ "template_version" ], "type": "string" }, "published_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "published_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "type": "object" }, "TemplateWriteVersion": { "properties": { "id": { "type": "string" }, "note": { "type": "string" }, "number": { "type": "integer" }, "published_at": { "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "id", "note", "number", "published_at" ], "type": "object" }, "TestEvent": { "properties": { "event": { "default": "render.succeeded", "description": "* `render.succeeded` - render.succeeded\n* `render.failed` - render.failed\n* `render.expired` - render.expired\n* `batch.progress` - batch.progress\n* `batch.completed` - batch.completed\n* `storage.upload_failed` - storage.upload_failed\n* `email.sent` - email.sent\n* `email.send_failed` - email.send_failed\n* `email.delivered` - email.delivered\n* `email.bounced` - email.bounced\n* `email.complained` - email.complained\n* `usage.threshold_reached` - usage.threshold_reached\n* `template.published` - template.published", "enum": [ "render.succeeded", "render.failed", "render.expired", "batch.progress", "batch.completed", "storage.upload_failed", "email.sent", "email.send_failed", "email.delivered", "email.bounced", "email.complained", "usage.threshold_reached", "template.published" ], "type": "string", "x-spec-enum-id": "57135a5088c9518d" } }, "type": "object" }, "UnlockRequest": { "additionalProperties": false, "properties": { "delivery": { "anyOf": [ { "$ref": "#/components/schemas/DeliverySpec" }, { "type": "null" } ], "default": null }, "filename": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Filename" }, "metadata": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "propertyNames": { "maxLength": 40, "minLength": 1 }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Metadata" }, "mode": { "default": "sync", "enum": [ "sync", "async" ], "title": "Mode", "type": "string" }, "password": { "maxLength": 127, "title": "Password", "type": "string" }, "priority": { "default": "normal", "enum": [ "normal", "low" ], "title": "Priority", "type": "string" }, "reference": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Reference" }, "source": { "$ref": "#/components/schemas/PdfSourceSpec" }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Test" }, "timeout_behavior": { "default": "continue", "enum": [ "continue", "cancel" ], "title": "Timeout Behavior", "type": "string" }, "webhook": { "anyOf": [ { "$ref": "#/components/schemas/WebhookSpec" }, { "type": "null" } ], "default": null } }, "required": [ "source", "password" ], "title": "UnlockRequest", "type": "object" }, "Upload": { "properties": { "bytes": { "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "filename": { "type": "string" }, "id": { "example": "upl_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "type": "string" }, "mime": { "example": "application/pdf", "type": "string" }, "object": { "enum": [ "upload" ], "type": "string" }, "sha256": { "type": "string" } }, "type": "object" }, "UrlInputSpec": { "additionalProperties": false, "properties": { "http": { "anyOf": [ { "$ref": "#/components/schemas/HttpOptions" }, { "type": "null" } ], "default": null }, "type": { "const": "url", "title": "Type", "type": "string" }, "url": { "maxLength": 2048, "minLength": 8, "title": "Url", "type": "string" } }, "required": [ "type", "url" ], "title": "UrlInputSpec", "type": "object" }, "Usage": { "properties": { "from": { "description": "Start of the range (UTC).", "format": "date-time", "type": "string" }, "granularity": { "enum": [ "hour", "day" ], "type": "string" }, "group_by": { "anyOf": [ { "description": "template_id · key_id · source · region · kind", "type": "string" }, { "type": "null" } ] }, "object": { "enum": [ "usage" ], "type": "string" }, "series": { "items": { "properties": { "key": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "points": { "items": { "properties": { "billed_renders": { "type": "integer" }, "pages": { "type": "integer" }, "renders_failed": { "type": "integer" }, "renders_succeeded": { "type": "integer" }, "ts": { "format": "date-time", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" }, "to": { "description": "End of the range (exclusive).", "format": "date-time", "type": "string" } }, "type": "object" }, "Viewport": { "additionalProperties": false, "properties": { "height": { "maximum": 8192, "minimum": 16, "title": "Height", "type": "integer" }, "width": { "maximum": 8192, "minimum": 16, "title": "Width", "type": "integer" } }, "required": [ "width", "height" ], "title": "Viewport", "type": "object" }, "Wait": { "additionalProperties": false, "properties": { "delay_ms": { "anyOf": [ { "maximum": 10000, "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null, "title": "Delay Ms" }, "selector": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "default": null, "title": "Selector" }, "strict": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Strict" }, "timeout_ms": { "anyOf": [ { "maximum": 300000, "minimum": 100, "type": "integer" }, { "type": "null" } ], "default": null, "title": "Timeout Ms" }, "until": { "anyOf": [ { "enum": [ "load", "networkidle", "selector", "ready_flag", "delay" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Until" } }, "title": "Wait", "type": "object" }, "WebhookDelivery": { "properties": { "attempt": { "type": "integer" }, "attempts": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "endpoint_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "event_id": { "type": "string" }, "event_type": { "example": "render.succeeded", "type": "string" }, "id": { "example": "whd_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "type": "string" }, "is_test": { "type": "boolean" }, "latency_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "next_attempt_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "object": { "enum": [ "webhook_delivery" ], "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "render_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "replay_of": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "response_code": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "response_excerpt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "pending", "succeeded", "failed", "exhausted" ], "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "WebhookDeliveryList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/WebhookDelivery" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "object": { "enum": [ "list" ], "type": "string" } }, "type": "object" }, "WebhookEndpoint": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "description": { "type": "string" }, "disabled_reason": { "description": "Set when Dynamic Document API disabled the endpoint after repeated failures.", "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "events": { "items": { "description": "* `render.succeeded` - render.succeeded\n* `render.failed` - render.failed\n* `render.expired` - render.expired\n* `batch.progress` - batch.progress\n* `batch.completed` - batch.completed\n* `storage.upload_failed` - storage.upload_failed\n* `email.sent` - email.sent\n* `email.send_failed` - email.send_failed\n* `email.delivered` - email.delivered\n* `email.bounced` - email.bounced\n* `email.complained` - email.complained\n* `usage.threshold_reached` - usage.threshold_reached\n* `template.published` - template.published\n* `api_key.expiring` - api_key.expiring", "enum": [ "render.succeeded", "render.failed", "render.expired", "batch.progress", "batch.completed", "storage.upload_failed", "email.sent", "email.send_failed", "email.delivered", "email.bounced", "email.complained", "usage.threshold_reached", "template.published", "api_key.expiring" ], "type": "string", "x-spec-enum-id": "14c12aefcc309c17" }, "type": "array" }, "headers": { "additionalProperties": { "type": "string" }, "description": "Header names; the values are masked.", "type": "object" }, "id": { "description": "`whe_…`", "type": "string" }, "is_default": { "type": "boolean" }, "object": { "default": "webhook_endpoint", "type": "string" }, "secret_rotation": { "description": "Present while a previous secret is still accepted.", "oneOf": [ { "$ref": "#/components/schemas/WebhookSecretRotation" }, { "type": "null" } ] }, "template_ids": { "description": "Empty list = every template.", "items": { "type": "string" }, "type": "array" }, "updated_at": { "format": "date-time", "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "created_at", "description", "disabled_reason", "enabled", "events", "headers", "id", "is_default", "secret_rotation", "template_ids", "updated_at", "url" ], "type": "object" }, "WebhookEndpointList": { "description": "Cursor-pagination envelope (docs/05 §1). Management lists are single-page today.", "properties": { "data": { "items": { "$ref": "#/components/schemas/WebhookEndpoint" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "object": { "default": "list", "type": "string" } }, "required": [ "data", "has_more", "next_cursor" ], "type": "object" }, "WebhookEndpointWithSecret": { "description": "Create and roll-secret responses: the signing secret is returned once and never again.", "properties": { "created_at": { "format": "date-time", "type": "string" }, "description": { "type": "string" }, "disabled_reason": { "description": "Set when Dynamic Document API disabled the endpoint after repeated failures.", "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "events": { "items": { "description": "* `render.succeeded` - render.succeeded\n* `render.failed` - render.failed\n* `render.expired` - render.expired\n* `batch.progress` - batch.progress\n* `batch.completed` - batch.completed\n* `storage.upload_failed` - storage.upload_failed\n* `email.sent` - email.sent\n* `email.send_failed` - email.send_failed\n* `email.delivered` - email.delivered\n* `email.bounced` - email.bounced\n* `email.complained` - email.complained\n* `usage.threshold_reached` - usage.threshold_reached\n* `template.published` - template.published\n* `api_key.expiring` - api_key.expiring", "enum": [ "render.succeeded", "render.failed", "render.expired", "batch.progress", "batch.completed", "storage.upload_failed", "email.sent", "email.send_failed", "email.delivered", "email.bounced", "email.complained", "usage.threshold_reached", "template.published", "api_key.expiring" ], "type": "string", "x-spec-enum-id": "14c12aefcc309c17" }, "type": "array" }, "headers": { "additionalProperties": { "type": "string" }, "description": "Header names; the values are masked.", "type": "object" }, "id": { "description": "`whe_…`", "type": "string" }, "is_default": { "type": "boolean" }, "object": { "default": "webhook_endpoint", "type": "string" }, "secret": { "description": "`whsec_…`, base64 of 32 random bytes. Shown once.", "type": "string" }, "secret_rotation": { "description": "Present while a previous secret is still accepted.", "oneOf": [ { "$ref": "#/components/schemas/WebhookSecretRotation" }, { "type": "null" } ] }, "template_ids": { "description": "Empty list = every template.", "items": { "type": "string" }, "type": "array" }, "updated_at": { "format": "date-time", "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "created_at", "description", "disabled_reason", "enabled", "events", "headers", "id", "is_default", "secret", "secret_rotation", "template_ids", "updated_at", "url" ], "type": "object" }, "WebhookEndpointWrite": { "properties": { "description": { "maxLength": 255, "type": "string" }, "enabled": { "default": true, "type": "boolean" }, "events": { "items": { "description": "* `render.succeeded` - render.succeeded\n* `render.failed` - render.failed\n* `render.expired` - render.expired\n* `batch.progress` - batch.progress\n* `batch.completed` - batch.completed\n* `storage.upload_failed` - storage.upload_failed\n* `email.sent` - email.sent\n* `email.send_failed` - email.send_failed\n* `email.delivered` - email.delivered\n* `email.bounced` - email.bounced\n* `email.complained` - email.complained\n* `usage.threshold_reached` - usage.threshold_reached\n* `template.published` - template.published\n* `api_key.expiring` - api_key.expiring", "enum": [ "render.succeeded", "render.failed", "render.expired", "batch.progress", "batch.completed", "storage.upload_failed", "email.sent", "email.send_failed", "email.delivered", "email.bounced", "email.complained", "usage.threshold_reached", "template.published", "api_key.expiring" ], "type": "string", "x-spec-enum-id": "14c12aefcc309c17" }, "minItems": 1, "type": "array" }, "headers": { "additionalProperties": { "maxLength": 1000, "type": "string" }, "description": "Extra request headers.", "type": "object" }, "is_default": { "description": "Receive events from renders without an inline `webhook`.", "type": "boolean" }, "template_ids": { "description": "Only deliver events for these templates.", "items": { "type": "string" }, "maxItems": 200, "type": "array" }, "url": { "description": "Absolute https URL; no credentials.", "format": "uri", "maxLength": 2048, "type": "string" } }, "required": [ "events", "url" ], "type": "object" }, "WebhookSecretRotation": { "properties": { "previous_expires_at": { "description": "When the previous secret stops being accepted.", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "previous_expires_at" ], "type": "object" }, "WebhookSpec": { "additionalProperties": false, "properties": { "events": { "items": { "enum": [ "render.succeeded", "render.failed" ], "type": "string" }, "maxItems": 2, "minItems": 1, "title": "Events", "type": "array" }, "format": { "const": "standard", "default": "standard", "title": "Format", "type": "string" }, "url": { "maxLength": 2048, "minLength": 8, "title": "Url", "type": "string" } }, "required": [ "url" ], "title": "WebhookSpec", "type": "object" }, "WebhookTest": { "properties": { "delivery_id": { "description": "Follow it with `GET /v1/webhook-deliveries/{id}`.", "type": "string" }, "object": { "default": "webhook_test", "type": "string" } }, "required": [ "delivery_id" ], "type": "object" } }, "securitySchemes": { "ApiKey": { "bearerFormat": "dda_live_… | dda_test_…", "description": "`Authorization: Bearer dda_live_…` (or `dda_test_…` for test mode).", "scheme": "bearer", "type": "http" }, "ApiKeyHeader": { "description": "Alternative header for no-code tools.", "in": "header", "name": "X-API-Key", "type": "apiKey" }, "RegionToken": { "bearerFormat": "JWT", "description": "Short-lived region token issued to the Dynamic Document API dashboard.", "scheme": "bearer", "type": "http" } } }, "externalDocs": { "description": "Dynamic Document API documentation", "url": "https://docs.dynamicdocumentapi.com" }, "info": { "description": "The Dynamic Document API turns templates and JSON into PDFs and images.\n\n* Authenticate with `Authorization: Bearer dda_live_…` (test keys: `dda_test_…`).\n* Errors are RFC 9457 problem details (`application/problem+json`).\n* All POST endpoints accept an `Idempotency-Key` header.\n* Rate-limit headers: `RateLimit-Policy`, `RateLimit`, and `Retry-After` on 429.", "title": "Dynamic Document API", "version": "1.0.0" }, "openapi": "3.1.0", "paths": { "/l/{link_id}/{filename}": { "get": { "description": "The public image URL of a signed link (proto/README.md §22), served from `https://img.dynamicdocumentapi.com` without an API key. Checks, in order: unknown, disabled or deleted link, or a format the link does not enable → 404 `not_found`; expired link or a signed `exp` in the past → 410 `link_expired`; `access: signed` needs `sig` = base64url(HMAC-SHA256(secret, \"GET\\n/l/{link_id}/{name}.{ext}\\n\" + canonical query without `sig`)) → 403 `invalid_signature` (open links accept only allowed parameters that have `param_limits`); unknown parameters or a value over `max_length` → 400 `validation_error`; a `Referer` whose host is not in `allowed_referrers` → 403 `referrer_not_allowed`; the per-IP hourly limit → 429 `rate_limited`; the plan feature → 402 `plan_feature_unavailable`; the link quota → 429 `quota_exceeded`.\n\n A cached result is returned with `X-Billed-Renders: 0` and creates no render; a cache miss renders the template's live version (`X-Billed-Renders: 1`, `X-Render-Id`). Responses carry `ETag` (304 on `If-None-Match`), `Cache-Control: public, max-age=…` and `Access-Control-Allow-Origin: *`. `HEAD` runs the same checks and never renders. When the render limit is reached, a link with a fallback image returns it instead of 402 `render_limit_reached`.", "operationId": "render_signed_link", "parameters": [ { "description": "A previous `ETag`.", "in": "header", "name": "If-None-Match", "schema": { "type": "string" } }, { "description": "Expiry (Unix seconds), signed.", "in": "query", "name": "exp", "schema": { "type": "integer" } }, { "description": "`{name}.{ext}`: any name of 1 to 80 characters `[A-Za-z0-9_-]` and a format enabled for the link (`png`, `jpeg` or `jpg`, `webp`, `pdf`). The name only sets the download filename; both are signed.", "in": "path", "name": "filename", "required": true, "schema": { "type": "string" } }, { "description": "Signed link id (`lnk_…`).", "in": "path", "name": "link_id", "required": true, "schema": { "type": "string" } }, { "description": "The template parameters (`allowed_params`), e.g. `title.text=Summer%20Sale`.", "explode": true, "in": "query", "name": "params", "schema": { "additionalProperties": { "type": "string" }, "type": "object" }, "style": "form" }, { "description": "base64url HMAC-SHA256 signature (`access: signed`).", "in": "query", "name": "sig", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/pdf": { "schema": { "format": "binary", "type": "string" } }, "image/jpeg": { "schema": { "format": "binary", "type": "string" } }, "image/png": { "schema": { "format": "binary", "type": "string" } }, "image/webp": { "schema": { "format": "binary", "type": "string" } } }, "description": "The rendered file (PNG, JPEG, WebP or PDF per the extension)." }, "304": { "description": "Not modified (`If-None-Match`)." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Parameter not allowed, over `max_length`, malformed or over 8 KB of query." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "`plan_feature_unavailable` or `render_limit_reached` (no fallback image)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "`invalid_signature` or `referrer_not_allowed`." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Unknown, disabled or deleted link, or a format the link does not enable." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "`link_expired` (or the template was deleted)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The render failed (template error)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "`rate_limited` (per IP and hour, `Retry-After`) or `quota_exceeded`." } }, "security": [], "summary": "Render a signed link", "tags": [ "Signed links" ] }, "servers": [ { "description": "Signed-link renders", "url": "https://img.dynamicdocumentapi.com" } ] }, "/v1/account": { "get": { "operationId": "get_account", "responses": { "200": { "content": { "application/json": { "examples": { "GrowthPlan": { "summary": "Growth plan", "value": { "cycle": { "end": "2026-10-01T00:00:00Z", "start": "2026-09-01T00:00:00Z" }, "limits": { "bulk_concurrency": 10, "max_pages": 500, "max_payload_mb": 10, "rate_limit_rps": 20, "sync_concurrency": 20, "sync_timeout_s": 60 }, "plan": { "code": "growth", "interval": "month" }, "regions": [ "eu" ], "renders": { "included": 15000, "prepaid_remaining": 0, "remaining_included": 10790, "spend_cap_cents": 11800, "used": 4210 }, "workspace": { "id": "ws_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "name": "Acme" } } } }, "schema": { "$ref": "#/components/schemas/Account" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Control plane unavailable." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Plan, renders and limits", "tags": [ "Account" ] } }, "/v1/batches": { "get": { "description": "Newest first. Test keys see test batches only.", "operationId": "list_batches", "parameters": [ { "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "1 to 100 (default 50).", "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "in": "query", "name": "reference", "schema": { "type": "string" } }, { "in": "query", "name": "status", "schema": { "enum": [ "canceled", "completed", "failed", "processing", "queued" ], "type": "string" } }, { "in": "query", "name": "template_id", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "OneBatch": { "summary": "One batch", "value": { "data": [ { "canceled": 0, "combine": { "merged_pdf": false, "zip": true, "zip_filename": "certificates.zip" }, "completed_at": null, "created_at": "2026-09-17T15:06:33Z", "emails": { "canceled": 0, "failed": 0, "pending": 0, "sent": 431, "skipped": 0, "unknown": 0 }, "error": null, "failed": 2, "files": [], "id": "bat_01J9ZN4T6V8X0Z2B4D6F8H0K2M", "metadata": { "course": "safety-101" }, "object": "batch", "paused": null, "pending": 767, "progress": 0.3608, "reference": "course_2026_09", "status": "processing", "succeeded": 431, "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "template_version": 7, "test": false, "total": 1200 } ], "has_more": false, "next_cursor": null, "object": "list" } } }, "schema": { "$ref": "#/components/schemas/BatchList" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Unknown `status` or malformed `template_id`." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "List batches", "tags": [ "Batches" ] }, "post": { "description": "Renders one template version for many items — a JSON `items` array (≤ 25 MB body) or a CSV from `POST /v1/uploads` with an optional `csv_mapping` — sharing `output`, `delivery` and `webhook`. Items become ordinary renders (`source: batch`), released under your plan's bulk concurrency; `combine` adds a ZIP of all outputs and/or one merged PDF. Answers `202` right away; follow progress with `GET /v1/batches/{id}` or the `batch.progress` / `batch.completed` webhooks. Live items are billed as they are released: if the render limit is reached mid-batch, the batch pauses (`paused`, one `batch.progress`) and resumes on its own once renders are available again.", "operationId": "create_batch", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "CSVUploadWithAMapping": { "summary": "CSV upload with a mapping", "value": { "combine": { "merged_pdf": true }, "csv_mapping": { "course.title": "Course", "name": "Full Name" }, "csv_upload_id": "upl_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C" } }, "JSONItemsWithAZIP": { "summary": "JSON items with a ZIP", "value": { "combine": { "merged_pdf": false, "zip": true, "zip_filename": "certificates.zip" }, "items": [ { "data": { "course": "Safety 101", "name": "Ann Example" }, "filename": "ann.pdf", "reference": "cert_001" }, { "data": { "course": "Safety 101", "name": "Bob Example" }, "reference": "cert_002" } ], "metadata": { "course": "safety-101" }, "output": { "filename": "certificate-{{ name }}.pdf", "format": "pdf" }, "reference": "course_2026_09", "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "version": "live", "webhook": { "events": [ "batch.progress", "batch.completed" ], "url": "https://example.com/hooks/dynamic-document-api" } } } }, "schema": { "$ref": "#/components/schemas/BatchRequest" } } } }, "responses": { "202": { "content": { "application/json": { "examples": { "Accepted": { "value": { "canceled": 0, "combine": { "merged_pdf": false, "zip": true, "zip_filename": "certificates.zip" }, "completed_at": null, "created_at": "2026-09-17T15:06:33Z", "emails": { "canceled": 0, "failed": 0, "pending": 0, "sent": 431, "skipped": 0, "unknown": 0 }, "error": null, "failed": 0, "files": [], "id": "bat_01J9ZN4T6V8X0Z2B4D6F8H0K2M", "metadata": { "course": "safety-101" }, "object": "batch", "paused": null, "pending": 1200, "progress": 0.0, "reference": "course_2026_09", "status": "queued", "succeeded": 0, "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "template_version": 7, "test": false, "total": 1200 } } }, "schema": { "$ref": "#/components/schemas/Batch" } } }, "description": "Batch accepted (`Location: /v1/batches/{id}`)." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Invalid request, items or CSV (`errors[]` with `/items/<i>/…` or `/csv/row/<n>`)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Batches not on your plan, or render limit reached (`render_limit_reached`)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified; or `region_not_enabled`: the workspace's enabled regions leave out this region." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template, version or upload not found." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A request with this Idempotency-Key is still in progress." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template deleted." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Body over 25 MB or an item's data over 1 MB." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Item data does not match the template schema, or the webhook URL is not allowed." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Region degraded (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Create a batch", "tags": [ "Batches" ] } }, "/v1/batches/{batch_id}": { "get": { "description": "Counters, progress and — once combined — the ZIP / merged PDF with signed URLs.", "operationId": "get_batch", "parameters": [ { "description": "Batch id (`bat_…`).", "in": "path", "name": "batch_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "CompletedWithAZIP": { "summary": "Completed with a ZIP", "value": { "canceled": 0, "combine": { "merged_pdf": false, "zip": true, "zip_filename": "certificates.zip" }, "completed_at": "2026-09-17T15:21:08Z", "created_at": "2026-09-17T15:06:33Z", "emails": { "canceled": 0, "failed": 0, "pending": 0, "sent": 431, "skipped": 0, "unknown": 0 }, "error": null, "failed": 2, "files": [ { "bytes": 41873920, "content_type": "application/zip", "expires_at": "2026-10-17T15:21:08Z", "file_id": "file_01J9ZP0A2C4E6G8J0L2N4Q6S8U", "filename": "certificates.zip", "kind": "zip", "url": "https://files-eu.dynamicdocumentapi.com/f/…", "url_expires_at": "2026-09-17T16:21:08Z" } ], "id": "bat_01J9ZN4T6V8X0Z2B4D6F8H0K2M", "metadata": { "course": "safety-101" }, "object": "batch", "paused": null, "pending": 0, "progress": 1.0, "reference": "course_2026_09", "status": "completed", "succeeded": 1198, "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "template_version": 7, "test": false, "total": 1200 } }, "Failed:ItemFilesGoneBeforeTheCombine": { "summary": "Failed: item files gone before the combine", "value": { "canceled": 0, "combine": { "merged_pdf": false, "zip": true, "zip_filename": "certificates.zip" }, "completed_at": "2026-09-19T09:41:27Z", "created_at": "2026-09-17T15:06:33Z", "emails": { "canceled": 0, "failed": 0, "pending": 0, "sent": 0, "skipped": 0, "unknown": 0 }, "error": { "code": "item_files_expired", "items": [ 17, 18 ], "message": "The files of 2 succeeded items expired or were deleted before they could be combined: items 17 and 18." }, "failed": 0, "files": [], "id": "bat_01J9ZN4T6V8X0Z2B4D6F8H0K2M", "metadata": { "course": "safety-101" }, "object": "batch", "paused": null, "pending": 0, "progress": 1.0, "reference": "course_2026_09", "status": "failed", "succeeded": 1200, "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "template_version": 7, "test": false, "total": 1200 } }, "PausedUntilRendersAreAvailable": { "summary": "Paused until renders are available", "value": { "canceled": 0, "combine": { "merged_pdf": false, "zip": true, "zip_filename": "certificates.zip" }, "completed_at": null, "created_at": "2026-09-17T15:06:33Z", "emails": { "canceled": 0, "failed": 0, "pending": 0, "sent": 431, "skipped": 0, "unknown": 0 }, "error": null, "failed": 2, "files": [], "id": "bat_01J9ZN4T6V8X0Z2B4D6F8H0K2M", "metadata": { "course": "safety-101" }, "object": "batch", "paused": { "reason": "render_limit_reached", "since": "2026-09-17T15:14:52Z" }, "pending": 218, "progress": 0.8183, "reference": "course_2026_09", "status": "processing", "succeeded": 980, "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "template_version": 7, "test": false, "total": 1200 } }, "Processing": { "value": { "canceled": 0, "combine": { "merged_pdf": false, "zip": true, "zip_filename": "certificates.zip" }, "completed_at": null, "created_at": "2026-09-17T15:06:33Z", "emails": { "canceled": 0, "failed": 0, "pending": 0, "sent": 431, "skipped": 0, "unknown": 0 }, "error": null, "failed": 2, "files": [], "id": "bat_01J9ZN4T6V8X0Z2B4D6F8H0K2M", "metadata": { "course": "safety-101" }, "object": "batch", "paused": null, "pending": 767, "progress": 0.3608, "reference": "course_2026_09", "status": "processing", "succeeded": 431, "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "template_version": 7, "test": false, "total": 1200 } } }, "schema": { "$ref": "#/components/schemas/Batch" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Batch not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Retrieve a batch", "tags": [ "Batches" ] } }, "/v1/batches/{batch_id}/cancel": { "post": { "description": "Items not released yet are canceled; released renders are canceled when a worker picks them up (items already rendering may still finish and are counted). The batch is `canceled` at once and `batch.completed` fires. Canceled items are not billed.", "operationId": "cancel_batch", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } }, { "description": "Batch id (`bat_…`).", "in": "path", "name": "batch_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "Canceled": { "value": { "canceled": 767, "combine": { "merged_pdf": false, "zip": true, "zip_filename": "certificates.zip" }, "completed_at": "2026-09-17T15:09:12Z", "created_at": "2026-09-17T15:06:33Z", "emails": { "canceled": 0, "failed": 0, "pending": 0, "sent": 431, "skipped": 0, "unknown": 0 }, "error": null, "failed": 2, "files": [], "id": "bat_01J9ZN4T6V8X0Z2B4D6F8H0K2M", "metadata": { "course": "safety-101" }, "object": "batch", "paused": null, "pending": 0, "progress": 1.0, "reference": "course_2026_09", "status": "canceled", "succeeded": 431, "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "template_version": 7, "test": false, "total": 1200 } } }, "schema": { "$ref": "#/components/schemas/Batch" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Batch not found." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "`conflict`: the batch already finished." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Cancel a batch", "tags": [ "Batches" ] } }, "/v1/batches/{batch_id}/items": { "get": { "description": "Items in `index` order; `?status=failed` lists what `retry-failed` renders again.", "operationId": "list_batch_items", "parameters": [ { "description": "Batch id (`bat_…`).", "in": "path", "name": "batch_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "1 to 100 (default 50).", "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "in": "query", "name": "status", "schema": { "enum": [ "canceled", "failed", "pending", "queued", "succeeded" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "AFailedItem": { "summary": "A failed item", "value": { "data": [ { "error": { "code": "template_runtime_error", "message": "'dict object' has no attribute 'course'" }, "filename": null, "index": 17, "reference": "cert_018", "render_id": "rnd_01J9ZN5B7D9F1H3K5M7P9R1T3V", "status": "failed" } ], "has_more": false, "next_cursor": null, "object": "list" } } }, "schema": { "$ref": "#/components/schemas/BatchItemList" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Unknown `status`." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Batch not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "List batch items", "tags": [ "Batches" ] } }, "/v1/batches/{batch_id}/resend-emails": { "post": { "description": "For each item and rule, the newest email is resent when its status is listed (`failed` by default; `unknown` only when listed). Emails that can't be resent are listed in `skipped` with the reason (at most 100).", "operationId": "resend_batch_emails", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } }, { "description": "Batch id (`bat_…`).", "in": "path", "name": "batch_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "FailedAndUnknown": { "summary": "Failed and unknown", "value": { "statuses": [ "failed", "unknown" ] } } }, "schema": { "$ref": "#/components/schemas/BatchResendEmailsRequest" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "Resent": { "value": { "resent": 12, "skipped": [ { "code": "email_file_expired", "send_id": "ems_01J9ZM1X3F7R8K2C4V6B8N0P2T" } ] } } }, "schema": { "$ref": "#/components/schemas/BatchResendEmailsResult" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Unknown status." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Email delivery needs the Growth plan or higher (`plan_feature_unavailable`)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Batch not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Resend a batch's failed emails", "tags": [ "Batches" ] } }, "/v1/batches/{batch_id}/retry-failed": { "post": { "description": "For a finished batch with failed items: those items are rendered again as new renders (the old render id stays in `error.previous_render_id`), earlier combined files are dropped and the batch is `processing` until it finishes again. Zero-retention batches can't be retried: their items keep no data once they finish. Nor can a batch with `combine` whose succeeded items' files expired or were deleted: its new combined files couldn't hold those items.", "operationId": "retry_failed_batch", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } }, { "description": "Batch id (`bat_…`).", "in": "path", "name": "batch_id", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "examples": { "Retrying": { "value": { "canceled": 0, "combine": { "merged_pdf": false, "zip": true, "zip_filename": "certificates.zip" }, "completed_at": null, "created_at": "2026-09-17T15:06:33Z", "emails": { "canceled": 0, "failed": 0, "pending": 0, "sent": 431, "skipped": 0, "unknown": 0 }, "error": null, "failed": 0, "files": [], "id": "bat_01J9ZN4T6V8X0Z2B4D6F8H0K2M", "metadata": { "course": "safety-101" }, "object": "batch", "paused": null, "pending": 2, "progress": 0.9983, "reference": "course_2026_09", "status": "processing", "succeeded": 1198, "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "template_version": 7, "test": false, "total": 1200 } } }, "schema": { "$ref": "#/components/schemas/Batch" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Batch not found." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "`conflict`: the batch is still running or has no failed items. `zero_retention`: a zero-retention batch keeps no item data; submit the failed items in a new batch. `item_files_expired`: the batch has `combine` and the files of succeeded items expired or were deleted (`items` lists their indexes, at most 100); submit the failed items in a new batch." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Retry the failed items", "tags": [ "Batches" ] } }, "/v1/einvoices": { "post": { "description": "Generates a standalone e-invoice from the invoice model: UN/CEFACT CII (every profile) or UBL 2.1 (`EN16931`, `XRECHNUNG`), e.g. an XRechnung for German public buyers. The XML is validated with the KoSIT validator (report in `result.conformance.einvoice`) and delivered as one `application/xml` file; a model that breaks a profile rule fails with `einvoice_invalid` and the list of issues. Answers a Render object with `input_type: \"einvoice\"` and `kind: \"einvoice_xml\"`; `delivery`, `mode`, `webhook`, `reference`, `metadata` and `test` behave as on `POST /v1/renders`. 1 billed render. Test renders are free, and their XML has a TEST note as its first invoice note (BT-22; every profile but `MINIMUM`, which has no notes; `EXTENDED` also sets `TestIndicator`). To embed the invoice in a PDF instead, use `output.einvoice` on a render.", "operationId": "create_einvoice", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "XRechnung(CII)": { "summary": "XRechnung (CII)", "value": { "filename": "XR-2026-0007.xml", "invoice": { "buyer": { "address": { "city": "Bonn", "country": "DE", "line1": "Amtsweg 2", "postcode": "53113" }, "electronic_address": { "id": "04011000-12345-34", "scheme": "0204" }, "name": "Bundesamt für Beispiele" }, "buyer_reference": "04011000-12345-34", "currency": "EUR", "due_date": "2026-10-23", "invoice_period": { "end": "2026-09-30", "start": "2026-09-01" }, "issue_date": "2026-09-23", "lines": [ { "item": { "description": "Wartung Fachverfahren, September 2026", "name": "Softwarewartung" }, "price": { "net": "95.00" }, "quantity": "8", "tax": { "category": "S", "rate": "19" }, "unit": "HUR" }, { "allowances": [ { "amount": "25.00", "reason": "Rabatt" } ], "item": { "name": "Lizenz Modul Statistik" }, "price": { "net": "250.00" }, "quantity": "1", "tax": { "category": "S", "rate": "19" }, "unit": "C62" } ], "number": "XR-2026-0007", "payment": { "credit_transfers": [ { "account_id": "DE02120300000000202051", "account_name": "Größenwahn GmbH" } ], "means_code": "58", "remittance_information": "XR-2026-0007" }, "payment_terms": "Zahlbar innerhalb von 30 Tagen ohne Abzug.", "seller": { "address": { "city": "Berlin", "country": "DE", "line1": "Beispielstraße 1", "postcode": "10115" }, "contact": { "email": "erika.muster@groessenwahn.example", "name": "Erika Muster", "phone": "+49 30 1234567" }, "electronic_address": { "id": "rechnung@groessenwahn.example", "scheme": "EM" }, "legal_registration": { "id": "HRB 12345" }, "name": "Größenwahn GmbH", "tax_number": "30/123/45678", "vat_id": "DE123456789" } }, "profile": "XRECHNUNG", "reference": "XR-2026-0007", "syntax": "cii" } }, "XRechnung(UBL)": { "summary": "XRechnung (UBL)", "value": { "filename": "XR-2026-0007.xml", "invoice": { "buyer": { "address": { "city": "Bonn", "country": "DE", "line1": "Amtsweg 2", "postcode": "53113" }, "electronic_address": { "id": "04011000-12345-34", "scheme": "0204" }, "name": "Bundesamt für Beispiele" }, "buyer_reference": "04011000-12345-34", "currency": "EUR", "due_date": "2026-10-23", "invoice_period": { "end": "2026-09-30", "start": "2026-09-01" }, "issue_date": "2026-09-23", "lines": [ { "item": { "description": "Wartung Fachverfahren, September 2026", "name": "Softwarewartung" }, "price": { "net": "95.00" }, "quantity": "8", "tax": { "category": "S", "rate": "19" }, "unit": "HUR" }, { "allowances": [ { "amount": "25.00", "reason": "Rabatt" } ], "item": { "name": "Lizenz Modul Statistik" }, "price": { "net": "250.00" }, "quantity": "1", "tax": { "category": "S", "rate": "19" }, "unit": "C62" } ], "number": "XR-2026-0007", "payment": { "credit_transfers": [ { "account_id": "DE02120300000000202051", "account_name": "Größenwahn GmbH" } ], "means_code": "58", "remittance_information": "XR-2026-0007" }, "payment_terms": "Zahlbar innerhalb von 30 Tagen ohne Abzug.", "seller": { "address": { "city": "Berlin", "country": "DE", "line1": "Beispielstraße 1", "postcode": "10115" }, "contact": { "email": "erika.muster@groessenwahn.example", "name": "Erika Muster", "phone": "+49 30 1234567" }, "electronic_address": { "id": "rechnung@groessenwahn.example", "scheme": "EM" }, "legal_registration": { "id": "HRB 12345" }, "name": "Größenwahn GmbH", "tax_number": "30/123/45678", "vat_id": "DE123456789" } }, "profile": "XRECHNUNG", "reference": "XR-2026-0007", "syntax": "ubl" } } }, "schema": { "$ref": "#/components/schemas/EInvoiceRequest" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "XRechnungXML": { "summary": "XRechnung XML", "value": { "batch_id": null, "billed_renders": 1, "completed_at": "2026-09-23T10:06:34Z", "created_at": "2026-09-23T10:06:33Z", "email": [], "engine": "2026.4", "engine_version": "2026.4 (dda-einvoice)", "error": null, "expires_at": "2026-10-23T10:06:34Z", "files": [ { "bytes": 7342, "content_type": "application/xml", "filename": "XR-2026-0007.xml", "format": "xml", "height": null, "id": "file_01J9ZM1X3F7R8K2C4V6B8N0P2R", "pages": null, "sha256": "4b1e…", "url": "https://files-eu.dynamicdocumentapi.com/f/…", "url_expires_at": "2026-09-23T11:06:34Z", "variant": null, "width": null } ], "id": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "input_type": "einvoice", "kind": "einvoice_xml", "metadata": {}, "mode": "sync", "object": "render", "output_format": "xml", "pages": null, "reference": "XR-2026-0007", "region": "eu", "result": { "conformance": { "einvoice": { "errors": [], "profile": "XRECHNUNG", "scenario": "EN16931 XRechnung (CII)", "status": "passed", "syntax": "cii", "validator": "KoSIT Validator 1.6.3", "warnings": [] } } }, "source": "api", "status": "succeeded", "storage": [], "template": null, "test": false, "timings": { "queued_ms": 2, "render_ms": 184, "total_ms": 212, "upload_ms": 21 }, "warnings": [] } } }, "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "Sync render finished (`status=succeeded`). With `delivery.type=binary` the body is the file." }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "Async render accepted, or the sync timeout was exceeded (`Location: /v1/renders/{id}`)." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Malformed or invalid request (`errors[]` with JSON pointers), e.g. an unknown, switched-off or another template's rule at `/delivery/email/<i>/rule_id`." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render limit reached (`render_limit_reached`) or feature not on plan (`plan_feature_unavailable`, e.g. a `delivery.email` list below the Growth plan)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified; or `region_not_enabled`: the workspace's enabled regions leave out this region." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template or version not found." }, "408": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Sync timeout exceeded and the render was canceled (`timeout_behavior=cancel`)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A request with this Idempotency-Key is still in progress." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template deleted." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Payload or output too large." }, "422": { "content": { "application/json": { "examples": { "InvoiceBreaksAProfileRule": { "summary": "Invoice breaks a profile rule", "value": { "code": "einvoice_invalid", "detail": "The invoice breaks 1 rule of the XRECHNUNG profile.", "doc_url": "https://docs.dynamicdocumentapi.com/errors/einvoice_invalid", "render_error": { "code": "einvoice_invalid", "message": "The invoice breaks 1 rule of the XRECHNUNG profile." }, "render_id": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "request_id": "req_01J9ZM1X3F7R8K2C4V6B8N0P2S", "result": { "conformance": { "einvoice": { "errors": [ { "count": 1, "location": "invoice.seller.contact", "message": "The seller contact (BG-6) is mandatory for XRECHNUNG.", "rule": "BR-DE-2" } ], "profile": "XRECHNUNG", "scenario": null, "status": "failed", "syntax": "cii", "validator": null, "warnings": [] } } }, "status": 422, "title": "E-invoice invalid", "type": "https://docs.dynamicdocumentapi.com/errors/einvoice_invalid" } } }, "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render failed (`render_id`, `render_error`; `render_failed` when the worker reports no more specific code), schema mismatch, URL not allowed or idempotency key reused. `einvoice_invalid`, `einvoice_validation_failed`, `pdfa_conversion_failed` and `pdfua_validation_failed` also carry the conformance report as `result`. `email_needs_hosted_file`: `delivery.email` lists rules, but a zero-retention render keeps no file to email. `render_canceled`: the sync render was canceled, or its job expired, before it finished. `scene_invalid`, `data_invalid`: a canvas template's scene can't be rendered (e.g. an output over 16,384 px per side), or its `data` isn't an object or lacks a required dynamic property." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Region degraded (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Create an e-invoice XML", "tags": [ "E-invoices" ] } }, "/v1/email-connections": { "get": { "description": "The workspace's email provider accounts. Credentials are never returned; `egress_ips` are the addresses to authorize at the provider.", "operationId": "list_email_connections", "responses": { "200": { "content": { "application/json": { "examples": { "OneConnection": { "summary": "One connection", "value": { "data": [ { "config": { "attachment_budget_bytes": 10485760, "max_per_second": 10 }, "created_at": "2026-09-30T09:10:00Z", "credentials": { "configured": true }, "credentials_delete_at": null, "default_from": { "email": "billing@acme.example", "name": "Acme Billing" }, "egress_ips": [ "195.201.91.46" ], "events": { "eu": "registered" }, "id": "emc_01J9ZK3M7Q8V5W2X4Y6Z8A0B1F", "last_error": null, "last_test_at": "2026-09-30T09:12:00Z", "last_test_status": "succeeded", "name": "Brevo", "object": "email_connection", "provider": "brevo", "reply_to": "accounts@acme.example", "senders": [ { "email": "acme.example", "kind": "domain", "name": null, "verified": true } ], "status": "active", "test_mode": "sandbox", "test_recipient": null, "updated_at": "2026-09-30T09:12:00Z" } ], "egress_ips": [ "195.201.91.46" ], "has_more": false, "next_cursor": null, "object": "list" } } }, "schema": { "$ref": "#/components/schemas/EmailConnectionList" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "List email connections", "tags": [ "Email" ] }, "post": { "description": "Connects your own provider account. `provider` and what it takes:\n\n* `brevo`: `credentials.api_key`, an API key (Brevo's SMTP key is not accepted).\n* `smtp`: `config` `host`, `port` (587 or 2525, with STARTTLS) and `username`; `credentials.password`.\n* `postmark`: `config.message_stream` (default `outbound`); `credentials.server_token`.\n* `resend`: `credentials.api_key`.\n* `ses` (Amazon SES): `config.region` and optionally `config.configuration_set`; `credentials` `access_key_id` and `secret_access_key`.\n* `graph` (Microsoft 365): `config` `tenant_id`, `client_id` and `sender`, the mailbox that sends; `credentials.client_secret` of an app with the `Mail.Send` application permission.\n\nEvery provider takes `config.attachment_budget_bytes` and `config.max_per_second`; reads show them with the provider's defaults filled in. At most 10 connections per workspace; `provider` can't change later. `credentials` are encrypted and never returned. Authorize `egress_ips` at providers that restrict calling IPs (Brevo: Security → Authorized IPs).", "operationId": "create_email_connection", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "AmazonSES": { "summary": "Amazon SES", "value": { "config": { "configuration_set": "invoices", "region": "eu-central-1" }, "credentials": { "access_key_id": "AKIA…", "secret_access_key": "…" }, "default_from": { "email": "billing@acme.example" }, "name": "Amazon SES", "provider": "ses" } }, "Brevo": { "value": { "credentials": { "api_key": "xkeysib-…" }, "default_from": { "email": "billing@acme.example", "name": "Acme Billing" }, "name": "Brevo", "provider": "brevo", "reply_to": "accounts@acme.example", "test_mode": "sandbox" } }, "Microsoft365": { "summary": "Microsoft 365", "value": { "config": { "client_id": "0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0", "sender": "billing@acme.example", "tenant_id": "acme.onmicrosoft.com" }, "credentials": { "client_secret": "…" }, "default_from": { "email": "billing@acme.example" }, "name": "Microsoft 365", "provider": "graph" } }, "Postmark": { "value": { "config": { "message_stream": "outbound" }, "credentials": { "server_token": "…" }, "default_from": { "email": "billing@acme.example" }, "name": "Postmark", "provider": "postmark" } }, "Resend": { "value": { "credentials": { "api_key": "re_…" }, "default_from": { "email": "billing@acme.example" }, "name": "Resend", "provider": "resend" } }, "SMTP": { "value": { "config": { "host": "smtp.acme.example", "port": 587, "username": "billing@acme.example" }, "credentials": { "password": "…" }, "default_from": { "email": "billing@acme.example" }, "name": "Mail server", "provider": "smtp", "test_mode": "skip" } } }, "schema": { "$ref": "#/components/schemas/EmailConnectionWrite" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "Created": { "value": { "config": { "attachment_budget_bytes": 10485760, "max_per_second": 10 }, "created_at": "2026-09-30T09:10:00Z", "credentials": { "configured": true }, "credentials_delete_at": null, "default_from": { "email": "billing@acme.example", "name": "Acme Billing" }, "egress_ips": [ "195.201.91.46" ], "events": {}, "id": "emc_01J9ZK3M7Q8V5W2X4Y6Z8A0B1F", "last_error": null, "last_test_at": null, "last_test_status": null, "name": "Brevo", "object": "email_connection", "provider": "brevo", "reply_to": "accounts@acme.example", "senders": [], "status": "active", "test_mode": "sandbox", "test_recipient": null, "updated_at": "2026-09-30T09:12:00Z" } } }, "schema": { "$ref": "#/components/schemas/EmailConnection" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Invalid request body (`errors[]` with JSON pointers)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Email delivery needs the Growth plan or higher (`plan_feature_unavailable`)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified; or `feature_not_enabled`: email delivery isn't enabled for this workspace yet." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Create an email connection", "tags": [ "Email" ] } }, "/v1/email-connections/{connection_id}": { "delete": { "description": "A connection that rules use answers `409 email_connection_in_use`: delete or move those rules first. Works on every plan.", "operationId": "delete_email_connection", "parameters": [ { "description": "Email connection id (`emc_…`).", "in": "path", "name": "connection_id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Email connection not found." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rules use the connection (`email_connection_in_use`)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Delete an email connection", "tags": [ "Email" ] }, "get": { "description": "Common base: API key or OAuth only, never a dashboard region token.", "operationId": "get_email_connection", "parameters": [ { "description": "Email connection id (`emc_…`).", "in": "path", "name": "connection_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "Connection": { "value": { "config": { "attachment_budget_bytes": 10485760, "max_per_second": 10 }, "created_at": "2026-09-30T09:10:00Z", "credentials": { "configured": true }, "credentials_delete_at": null, "default_from": { "email": "billing@acme.example", "name": "Acme Billing" }, "egress_ips": [ "195.201.91.46" ], "events": { "eu": "registered" }, "id": "emc_01J9ZK3M7Q8V5W2X4Y6Z8A0B1F", "last_error": null, "last_test_at": "2026-09-30T09:12:00Z", "last_test_status": "succeeded", "name": "Brevo", "object": "email_connection", "provider": "brevo", "reply_to": "accounts@acme.example", "senders": [ { "email": "acme.example", "kind": "domain", "name": null, "verified": true } ], "status": "active", "test_mode": "sandbox", "test_recipient": null, "updated_at": "2026-09-30T09:12:00Z" } } }, "schema": { "$ref": "#/components/schemas/EmailConnection" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Email connection not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Retrieve an email connection", "tags": [ "Email" ] }, "patch": { "description": "Partial update; a body without `credentials` keeps them. A `config` replaces the stored one as a whole. `provider` is immutable.", "operationId": "update_email_connection", "parameters": [ { "description": "Email connection id (`emc_…`).", "in": "path", "name": "connection_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "NewAPIKey": { "summary": "New API key", "value": { "credentials": { "api_key": "xkeysib-…" } } }, "RedirectTestRenders": { "summary": "Redirect test renders", "value": { "test_mode": "redirect", "test_recipient": "erika@acme.example" } } }, "schema": { "$ref": "#/components/schemas/PatchedEmailConnectionWrite" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "Updated": { "value": { "config": { "attachment_budget_bytes": 10485760, "max_per_second": 10 }, "created_at": "2026-09-30T09:10:00Z", "credentials": { "configured": true }, "credentials_delete_at": null, "default_from": { "email": "billing@acme.example", "name": "Acme Billing" }, "egress_ips": [ "195.201.91.46" ], "events": { "eu": "registered" }, "id": "emc_01J9ZK3M7Q8V5W2X4Y6Z8A0B1F", "last_error": null, "last_test_at": "2026-09-30T09:12:00Z", "last_test_status": "succeeded", "name": "Brevo", "object": "email_connection", "provider": "brevo", "reply_to": "accounts@acme.example", "senders": [ { "email": "acme.example", "kind": "domain", "name": null, "verified": true } ], "status": "active", "test_mode": "skip", "test_recipient": null, "updated_at": "2026-09-30T09:12:00Z" } } }, "schema": { "$ref": "#/components/schemas/EmailConnection" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Invalid request body (`errors[]` with JSON pointers)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Email delivery needs the Growth plan or higher (`plan_feature_unavailable`)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified; or `feature_not_enabled`: email delivery isn't enabled for this workspace yet." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Email connection not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Update an email connection", "tags": [ "Email" ] } }, "/v1/email-connections/{connection_id}/test": { "post": { "description": "Checks the saved settings from the region that sends, step by step:\n\n* `brevo`: `credentials`, `senders` (the verified senders and domains) and `sandbox_send` (Brevo checks an email from the default sender without delivering it).\n* `smtp`: `connect`, `starttls`, `smtp_auth`.\n* `postmark`: `credentials`.\n* `resend`: `credentials`, which also lists the verified domains.\n* `ses`: `credentials`, `senders` (the verified identities; it fails when there are none).\n* `graph`: `credentials` (Microsoft Entra ID issues a token).\n\nThe senders found are stored as the connection's `senders`. `send_to` adds a real test email (`send`) to a verified member address. `200` with `ok: false` means a step failed; the test stops there. A failed `credentials` or `smtp_auth` step marks the connection `failing`.", "operationId": "test_email_connection", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } }, { "description": "Email connection id (`emc_…`).", "in": "path", "name": "connection_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "AlsoSendToMe": { "summary": "Also send to me", "value": { "send_to": "erika@acme.example" } } }, "schema": { "$ref": "#/components/schemas/EmailConnectionTestRequest" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "Succeeded": { "value": { "connection": { "config": { "attachment_budget_bytes": 10485760, "max_per_second": 10 }, "created_at": "2026-09-30T09:10:00Z", "credentials": { "configured": true }, "credentials_delete_at": null, "default_from": { "email": "billing@acme.example", "name": "Acme Billing" }, "egress_ips": [ "195.201.91.46" ], "events": { "eu": "registered" }, "id": "emc_01J9ZK3M7Q8V5W2X4Y6Z8A0B1F", "last_error": null, "last_test_at": "2026-09-30T09:12:00Z", "last_test_status": "succeeded", "name": "Brevo", "object": "email_connection", "provider": "brevo", "reply_to": "accounts@acme.example", "senders": [ { "email": "acme.example", "kind": "domain", "name": null, "verified": true } ], "status": "active", "test_mode": "sandbox", "test_recipient": null, "updated_at": "2026-09-30T09:12:00Z" }, "object": "email_connection_test", "ok": true, "senders": [ { "email": "acme.example", "kind": "domain", "name": null, "verified": true } ], "steps": [ { "detail": "Brevo accepted the API key (account: Acme GmbH).", "name": "credentials", "ok": true }, { "detail": "Verified: 0 senders and 1 domain.", "name": "senders", "ok": true }, { "detail": "Brevo accepted a sandboxed email from billing@acme.example; nothing was delivered.", "name": "sandbox_send", "ok": true } ] } } }, "schema": { "$ref": "#/components/schemas/EmailConnectionTest" } } }, "description": "The test ran; check `ok`." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Invalid request body (`errors[]` with JSON pointers)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Email delivery needs the Growth plan or higher (`plan_feature_unavailable`)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified; or `feature_not_enabled`: email delivery isn't enabled for this workspace yet." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Email connection not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Test an email connection", "tags": [ "Email" ] } }, "/v1/email-rules/preview": { "post": { "description": "A watermarked preview render of the template (its live version, else its draft) with the rule's email rendered in the document's context: the fields, the recipients as parsed and the attachments as they would be planned. Nothing is sent and nothing is billed. The data is `data`, else the dataset `dataset_id`, else the template's default dataset, else `{}`. `rule.connection_id` names the connection.", "operationId": "preview_unsaved_email_rule", "requestBody": { "content": { "application/json": { "examples": { "NewRule": { "summary": "New rule", "value": { "rule": { "attach_formats": [ "pdf" ], "attachments": "attach_or_link", "cc": "{{ data.customer.accounting_email }}", "condition": "data.send_invoice", "connection_id": "emc_01J9ZK3M7Q8V5W2X4Y6Z8A0B1F", "enabled": true, "from_email": "billing@acme.example", "from_name": "Acme Billing", "html": "<p>Dear {{ data.customer.name }},</p><p>please find invoice {{ render.invoice.number }} attached.</p>", "name": "Invoice to customer", "subject": "Invoice {{ render.invoice.number }}", "to": "{{ data.customer.name }} <{{ data.customer.email }}>" }, "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C" } } }, "schema": { "$ref": "#/components/schemas/EmailRuleDraftPreviewRequest" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "WouldSend": { "summary": "Would send", "value": { "batch_id": null, "billed_renders": 0, "completed_at": "2026-09-17T15:06:34Z", "created_at": "2026-09-17T15:06:33Z", "email": [], "email_preview": { "attachments": [ { "bytes": 48213, "file_id": "file_01J9ZM1X3F7R8K2C4V6B8N0P2R", "filename": "R-2026-0042.pdf", "mode": "attached" } ], "bcc": [], "cc": [ { "email": "buchhaltung@groessenwahn.example", "name": null } ], "error": null, "from_email": "billing@acme.example", "from_name": "Acme Billing", "html": "<p>Dear Erika Muster,</p><p>please find invoice R-2026-0042 attached.</p>", "provider_template": null, "recipient_errors": [], "reply_to": "accounts@acme.example", "send": true, "skip_reason": null, "subject": "Invoice R-2026-0042", "text": "", "to": [ { "email": "erika.muster@groessenwahn.example", "name": "Erika Muster" } ] }, "engine": "2026.4", "engine_version": "2026.4 (Chrome 153.0.8010.47)", "error": null, "expires_at": "2026-10-01T10:15:02Z", "files": [ { "bytes": 48213, "content_type": "application/pdf", "filename": "invoice-42.pdf", "format": "pdf", "height": null, "id": "file_01J9ZM1X3F7R8K2C4V6B8N0P2R", "pages": 2, "sha256": "9f2c…", "url": "https://files-eu.dynamicdocumentapi.com/f/…", "url_expires_at": "2026-09-17T16:06:34Z", "variant": null, "width": null } ], "id": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "input_type": "template", "kind": "pdf_template", "metadata": {}, "mode": "sync", "object": "render", "output_format": "pdf", "pages": 2, "reference": null, "region": "eu", "result": null, "source": "preview", "status": "succeeded", "storage": [], "template": { "id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "version": 7, "version_id": "tv_01J9ZK3M7Q8V5W2X4Y6Z8A0B1D" }, "test": true, "timings": { "postprocess_ms": 21, "queued_ms": 3, "render_ms": 612, "total_ms": 681, "upload_ms": 38 }, "warnings": [] } } }, "schema": { "$ref": "#/components/schemas/RenderWithEmailPreview" } } }, "description": "" }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenderWithEmailPreview" } } }, "description": "The preview did not finish within the sync wait (`email_preview: null`)." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Invalid request (`errors[]`), e.g. an unknown `rule.connection_id`." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Email delivery needs the Growth plan or higher (`plan_feature_unavailable`)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rule, template, connection or dataset not found." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template deleted." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The document failed to render (`render_error`)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Region degraded or the email checks are unavailable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Preview a rule that is not saved yet", "tags": [ "Email" ] } }, "/v1/email-rules/{rule_id}": { "delete": { "description": "Its emails that were not sent yet are canceled. Works on every plan.", "operationId": "delete_email_rule", "parameters": [ { "description": "Email rule id (`emr_…`).", "in": "path", "name": "rule_id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Email rule not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Delete an email rule", "tags": [ "Email" ] }, "get": { "description": "Common base: API key or OAuth only, never a dashboard region token.", "operationId": "get_email_rule", "parameters": [ { "description": "Email rule id (`emr_…`).", "in": "path", "name": "rule_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "Rule": { "value": { "attach_formats": [ "pdf" ], "attachments": "attach_or_link", "bcc": "", "cc": "{{ data.customer.accounting_email }}", "condition": "data.send_invoice", "connection_id": "emc_01J9ZK3M7Q8V5W2X4Y6Z8A0B1F", "created_at": "2026-09-30T09:20:00Z", "enabled": true, "from_email": "billing@acme.example", "from_name": "Acme Billing", "html": "<p>Dear {{ data.customer.name }},</p><p>please find invoice {{ render.invoice.number }} attached.</p>", "id": "emr_01J9ZK3M7Q8V5W2X4Y6Z8A0B1E", "name": "Invoice to customer", "object": "email_rule", "position": 0, "provider_template": null, "reply_to": "", "subject": "Invoice {{ render.invoice.number }}", "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "text": "", "to": "{{ data.customer.name }} <{{ data.customer.email }}>", "updated_at": "2026-09-30T09:20:00Z" } } }, "schema": { "$ref": "#/components/schemas/EmailRule" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Email rule not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Retrieve an email rule", "tags": [ "Email" ] }, "patch": { "description": "Partial update; changing `position` moves the others. Switching a rule off (`enabled: false`) also cancels its emails that were not sent yet. Below the Growth plan, or while email delivery isn't enabled for the workspace, an update may only switch the rule off.", "operationId": "update_email_rule", "parameters": [ { "description": "Email rule id (`emr_…`).", "in": "path", "name": "rule_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "SwitchOff": { "summary": "Switch off", "value": { "enabled": false } } }, "schema": { "$ref": "#/components/schemas/PatchedEmailRuleWrite" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "SwitchedOff": { "summary": "Switched off", "value": { "attach_formats": [ "pdf" ], "attachments": "attach_or_link", "bcc": "", "cc": "{{ data.customer.accounting_email }}", "condition": "data.send_invoice", "connection_id": "emc_01J9ZK3M7Q8V5W2X4Y6Z8A0B1F", "created_at": "2026-09-30T09:20:00Z", "enabled": false, "from_email": "billing@acme.example", "from_name": "Acme Billing", "html": "<p>Dear {{ data.customer.name }},</p><p>please find invoice {{ render.invoice.number }} attached.</p>", "id": "emr_01J9ZK3M7Q8V5W2X4Y6Z8A0B1E", "name": "Invoice to customer", "object": "email_rule", "position": 0, "provider_template": null, "reply_to": "", "subject": "Invoice {{ render.invoice.number }}", "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "text": "", "to": "{{ data.customer.name }} <{{ data.customer.email }}>", "updated_at": "2026-09-30T09:20:00Z", "warnings": [] } } }, "schema": { "$ref": "#/components/schemas/EmailRule" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Invalid request body (`errors[]` with JSON pointers)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Email delivery needs the Growth plan or higher (`plan_feature_unavailable`)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified; or `feature_not_enabled`: email delivery isn't enabled for this workspace yet." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Email rule not found." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A field does not compile (`email_template_error`)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Update an email rule", "tags": [ "Email" ] } }, "/v1/email-rules/{rule_id}/preview": { "post": { "description": "A watermarked preview render of the template (its live version, else its draft) with the rule's email rendered in the document's context: the fields, the recipients as parsed and the attachments as they would be planned. Nothing is sent and nothing is billed. The data is `data`, else the dataset `dataset_id`, else the template's default dataset, else `{}`. Works for switched-off rules; `rule` previews unsaved fields instead of the saved ones.", "operationId": "preview_email_rule", "parameters": [ { "description": "Email rule id (`emr_…`).", "in": "path", "name": "rule_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "UnsavedSubject": { "summary": "Unsaved subject", "value": { "dataset_id": "ds_01J9ZK3M7Q8V5W2X4Y6Z8A0B1G", "rule": { "attach_formats": [ "pdf" ], "attachments": "attach_or_link", "cc": "{{ data.customer.accounting_email }}", "condition": "data.send_invoice", "connection_id": "emc_01J9ZK3M7Q8V5W2X4Y6Z8A0B1F", "enabled": true, "from_email": "billing@acme.example", "from_name": "Acme Billing", "html": "<p>Dear {{ data.customer.name }},</p><p>please find invoice {{ render.invoice.number }} attached.</p>", "name": "Invoice to customer", "subject": "Your invoice", "to": "{{ data.customer.name }} <{{ data.customer.email }}>" } } }, "WithData": { "summary": "With data", "value": { "data": { "customer": { "name": "Erika Muster" } } } } }, "schema": { "$ref": "#/components/schemas/EmailRulePreviewRequest" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "WouldSend": { "summary": "Would send", "value": { "batch_id": null, "billed_renders": 0, "completed_at": "2026-09-17T15:06:34Z", "created_at": "2026-09-17T15:06:33Z", "email": [], "email_preview": { "attachments": [ { "bytes": 48213, "file_id": "file_01J9ZM1X3F7R8K2C4V6B8N0P2R", "filename": "R-2026-0042.pdf", "mode": "attached" } ], "bcc": [], "cc": [ { "email": "buchhaltung@groessenwahn.example", "name": null } ], "error": null, "from_email": "billing@acme.example", "from_name": "Acme Billing", "html": "<p>Dear Erika Muster,</p><p>please find invoice R-2026-0042 attached.</p>", "provider_template": null, "recipient_errors": [], "reply_to": "accounts@acme.example", "send": true, "skip_reason": null, "subject": "Invoice R-2026-0042", "text": "", "to": [ { "email": "erika.muster@groessenwahn.example", "name": "Erika Muster" } ] }, "engine": "2026.4", "engine_version": "2026.4 (Chrome 153.0.8010.47)", "error": null, "expires_at": "2026-10-01T10:15:02Z", "files": [ { "bytes": 48213, "content_type": "application/pdf", "filename": "invoice-42.pdf", "format": "pdf", "height": null, "id": "file_01J9ZM1X3F7R8K2C4V6B8N0P2R", "pages": 2, "sha256": "9f2c…", "url": "https://files-eu.dynamicdocumentapi.com/f/…", "url_expires_at": "2026-09-17T16:06:34Z", "variant": null, "width": null } ], "id": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "input_type": "template", "kind": "pdf_template", "metadata": {}, "mode": "sync", "object": "render", "output_format": "pdf", "pages": 2, "reference": null, "region": "eu", "result": null, "source": "preview", "status": "succeeded", "storage": [], "template": { "id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "version": 7, "version_id": "tv_01J9ZK3M7Q8V5W2X4Y6Z8A0B1D" }, "test": true, "timings": { "postprocess_ms": 21, "queued_ms": 3, "render_ms": 612, "total_ms": 681, "upload_ms": 38 }, "warnings": [] } } }, "schema": { "$ref": "#/components/schemas/RenderWithEmailPreview" } } }, "description": "" }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenderWithEmailPreview" } } }, "description": "The preview did not finish within the sync wait (`email_preview: null`)." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Invalid request (`errors[]`), e.g. an unknown `rule.connection_id`." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Email delivery needs the Growth plan or higher (`plan_feature_unavailable`)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rule, template, connection or dataset not found." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template deleted." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The document failed to render (`render_error`)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Region degraded or the email checks are unavailable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Preview an email rule", "tags": [ "Email" ] } }, "/v1/email-rules/{rule_id}/test": { "post": { "description": "Renders the template (its live version, else its draft) as a test render (free, watermarked) whose one email is this rule's, redirected to `to` with the subject prefixed `[Test] `. `to` must be the verified address of an active member of the workspace. Works for switched-off rules; `rule` tests unsaved fields. Follow the render: its `email[]` shows the send.", "operationId": "test_email_rule", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } }, { "description": "Email rule id (`emr_…`).", "in": "path", "name": "rule_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "ToMe,WithData": { "summary": "To me, with data", "value": { "data": { "customer": { "name": "Erika Muster" } }, "to": "erika@acme.example" } } }, "schema": { "$ref": "#/components/schemas/EmailRuleTestRequest" } } } }, "responses": { "202": { "content": { "application/json": { "examples": { "Queued": { "value": { "batch_id": null, "billed_renders": 0, "completed_at": null, "created_at": "2026-09-17T15:06:33Z", "email": [], "engine": "2026.4", "engine_version": "2026.4 (Chrome 153.0.8010.47)", "error": null, "expires_at": null, "files": [], "id": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "input_type": "template", "kind": "pdf_template", "metadata": {}, "mode": "async", "object": "render", "output_format": "pdf", "pages": null, "reference": null, "region": "eu", "result": null, "source": "api", "status": "queued", "storage": [], "template": { "id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "version": 7, "version_id": "tv_01J9ZK3M7Q8V5W2X4Y6Z8A0B1D" }, "test": true, "timings": {}, "warnings": [] } } }, "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "The test render was queued (`Location: /v1/renders/{id}`)." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Invalid request, or `to` is not a verified member address (`/to`)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Email delivery needs the Growth plan or higher (`plan_feature_unavailable`)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rule, template, connection or dataset not found." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template deleted." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Zero-retention workspaces keep no file to email (`email_needs_hosted_file`)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Region degraded (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Send a test email", "tags": [ "Email" ] } }, "/v1/email-sends": { "get": { "description": "Newest first; sends are kept for 30 days. Test keys see test sends only.", "operationId": "list_email_sends", "parameters": [ { "in": "query", "name": "batch_id", "schema": { "type": "string" } }, { "in": "query", "name": "connection_id", "schema": { "type": "string" } }, { "in": "query", "name": "created_after", "schema": { "format": "date-time", "type": "string" } }, { "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "1 to 100 (default 50).", "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "in": "query", "name": "render_id", "schema": { "type": "string" } }, { "in": "query", "name": "rule_id", "schema": { "type": "string" } }, { "in": "query", "name": "status", "schema": { "enum": [ "canceled", "failed", "pending", "retrying", "sandboxed", "sending", "sent", "skipped", "unknown" ], "type": "string" } }, { "in": "query", "name": "template_id", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "OneSend": { "summary": "One send", "value": { "data": [ { "attachments": [ { "bytes": 48213, "file_id": "file_01J9ZM1X3F7R8K2C4V6B8N0P2R", "filename": "R-2026-0042.pdf", "mode": "attached" } ], "attempts": 1, "batch_id": null, "bcc_count": 0, "cc_count": 1, "connection_id": "emc_01J9ZK3M7Q8V5W2X4Y6Z8A0B1F", "created_at": "2026-09-30T10:15:01Z", "delivery": { "blocked": 0, "bounced": 0, "complained": 0, "deferred": 0, "delivered": 2, "invalid": 0 }, "error": null, "id": "ems_01J9ZM1X3F7R8K2C4V6B8N0P2T", "mode": "live", "object": "email_send", "provider": "brevo", "provider_message_id": "<202609301015.12345678901@smtp-relay.mailin.fr>", "render_id": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "resend_of": null, "rule_id": "emr_01J9ZK3M7Q8V5W2X4Y6Z8A0B1E", "sandbox": false, "sent_at": "2026-09-30T10:15:02Z", "skip_reason": null, "status": "sent", "subject": "Invoice R-2026-0042", "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "test": false, "to": [ "erika.muster@groessenwahn.example" ] } ], "has_more": false, "next_cursor": null, "object": "list" } } }, "schema": { "$ref": "#/components/schemas/EmailSendList" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Malformed id, unknown `status` or invalid `created_after`." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "List email sends", "tags": [ "Email" ] } }, "/v1/email-sends/stats": { "get": { "description": "Today's recipients of live emails in this region against the daily cap (it resets at 00:00 UTC), and the sends of the last 30 days by status.", "operationId": "get_email_stats", "responses": { "200": { "content": { "application/json": { "examples": { "Stats": { "value": { "last_30_days": { "canceled": 0, "failed": 12, "sandboxed": 41, "sent": 18423, "skipped": 305, "unknown": 1 }, "object": "email_stats", "today": { "limit": 15000, "recipients": 1204, "resets_at": "2026-10-01T00:00:00Z" } } } }, "schema": { "$ref": "#/components/schemas/EmailStats" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Region degraded (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Email statistics", "tags": [ "Email" ] } }, "/v1/email-sends/{send_id}": { "get": { "operationId": "get_email_send", "parameters": [ { "description": "Email send id (`ems_…`).", "in": "path", "name": "send_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "OverTheDailyCap": { "summary": "Over the daily cap", "value": { "attachments": [ { "bytes": 48213, "file_id": "file_01J9ZM1X3F7R8K2C4V6B8N0P2R", "filename": "R-2026-0042.pdf", "mode": "attached" } ], "attempts": 1, "batch_id": null, "bcc_count": 0, "cc_count": 1, "connection_id": "emc_01J9ZK3M7Q8V5W2X4Y6Z8A0B1F", "created_at": "2026-09-30T10:15:01Z", "delivery": { "blocked": 0, "bounced": 0, "complained": 0, "deferred": 0, "delivered": 0, "invalid": 0 }, "error": { "code": "email_daily_cap_reached", "message": "The workspace's daily limit of 15,000 email recipients is reached; it resets at 00:00 UTC." }, "id": "ems_01J9ZM1X3F7R8K2C4V6B8N0P2T", "mode": "live", "object": "email_send", "provider": "brevo", "provider_message_id": null, "render_id": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "resend_of": null, "rule_id": "emr_01J9ZK3M7Q8V5W2X4Y6Z8A0B1E", "sandbox": false, "sent_at": null, "skip_reason": null, "status": "failed", "subject": "Invoice R-2026-0042", "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "test": false, "to": [ "erika.muster@groessenwahn.example" ] } }, "Sent": { "value": { "attachments": [ { "bytes": 48213, "file_id": "file_01J9ZM1X3F7R8K2C4V6B8N0P2R", "filename": "R-2026-0042.pdf", "mode": "attached" } ], "attempts": 1, "batch_id": null, "bcc_count": 0, "cc_count": 1, "connection_id": "emc_01J9ZK3M7Q8V5W2X4Y6Z8A0B1F", "created_at": "2026-09-30T10:15:01Z", "delivery": { "blocked": 0, "bounced": 0, "complained": 0, "deferred": 0, "delivered": 2, "invalid": 0 }, "error": null, "id": "ems_01J9ZM1X3F7R8K2C4V6B8N0P2T", "mode": "live", "object": "email_send", "provider": "brevo", "provider_message_id": "<202609301015.12345678901@smtp-relay.mailin.fr>", "render_id": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "resend_of": null, "rule_id": "emr_01J9ZK3M7Q8V5W2X4Y6Z8A0B1E", "sandbox": false, "sent_at": "2026-09-30T10:15:02Z", "skip_reason": null, "status": "sent", "subject": "Invoice R-2026-0042", "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "test": false, "to": [ "erika.muster@groessenwahn.example" ] } } }, "schema": { "$ref": "#/components/schemas/EmailSend" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Email send not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Retrieve an email send", "tags": [ "Email" ] } }, "/v1/email-sends/{send_id}/events": { "get": { "description": "What Brevo reported after it accepted the email (delivered, deferred, bounces, blocks, spam complaints, invalid addresses), oldest first. Only Brevo connections have delivery events: other providers' sends list none. Also sent as the webhooks `email.delivered`, `email.bounced` and `email.complained`.", "operationId": "list_email_send_events", "parameters": [ { "description": "Email send id (`ems_…`).", "in": "path", "name": "send_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "Delivered": { "value": { "data": [ { "event": "delivered", "occurred_at": "2026-09-30T10:15:04Z", "reason": "", "recipient": "erika.muster@groessenwahn.example" } ], "has_more": false, "next_cursor": null, "object": "list" } } }, "schema": { "$ref": "#/components/schemas/EmailSendEventList" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Email send not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "List a send's delivery events", "tags": [ "Email" ] } }, "/v1/email-sends/{send_id}/resend": { "post": { "description": "Sends a `failed`, `unknown` or `sent` email again as a new send (`resend_of` set) with the same content and files; it counts toward today's cap. An email that failed before it was sent (template, recipients or attachments) or whose content was not kept (request logging off) answers `409 email_not_resendable`; a file that is no longer hosted `409 email_file_expired`.", "operationId": "resend_email_send", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } }, { "description": "Email send id (`ems_…`).", "in": "path", "name": "send_id", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "examples": { "Queued": { "value": { "attachments": [ { "bytes": 48213, "file_id": "file_01J9ZM1X3F7R8K2C4V6B8N0P2R", "filename": "R-2026-0042.pdf", "mode": "attached" } ], "attempts": 0, "batch_id": null, "bcc_count": 0, "cc_count": 1, "connection_id": "emc_01J9ZK3M7Q8V5W2X4Y6Z8A0B1F", "created_at": "2026-10-01T08:00:00Z", "delivery": { "blocked": 0, "bounced": 0, "complained": 0, "deferred": 0, "delivered": 0, "invalid": 0 }, "error": null, "id": "ems_01J9ZN4T6V8X0Z2B4D6F8H0K2M", "mode": "live", "object": "email_send", "provider": "brevo", "provider_message_id": null, "render_id": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "resend_of": "ems_01J9ZM1X3F7R8K2C4V6B8N0P2T", "rule_id": "emr_01J9ZK3M7Q8V5W2X4Y6Z8A0B1E", "sandbox": false, "sent_at": null, "skip_reason": null, "status": "pending", "subject": "Invoice R-2026-0042", "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "test": false, "to": [ "erika.muster@groessenwahn.example" ] } } }, "schema": { "$ref": "#/components/schemas/EmailSend" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Email delivery needs the Growth plan or higher (`plan_feature_unavailable`)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Email send not found." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "`email_not_resendable` or `email_file_expired`." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Region degraded (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Resend an email", "tags": [ "Email" ] } }, "/v1/images/from-html": { "post": { "description": "Convenience wrapper over `POST /v1/renders` with flat, no-code friendly fields.", "operationId": "create_image_from_html", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Data" }, "data_url": { "anyOf": [ { "maxLength": 2048, "minLength": 8, "type": "string" }, { "type": "null" } ], "default": null, "title": "Data Url" }, "delivery": { "anyOf": [ { "$ref": "#/components/schemas/DeliverySpec" }, { "enum": [ "url", "binary", "base64", "none" ], "type": "string" } ] }, "engine": { "anyOf": [ { "pattern": "^\\d{4}\\.\\d{1,6}$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Engine" }, "expires_in": { "default": 3600, "maximum": 604800, "minimum": 60, "title": "Expires In", "type": "integer" }, "filename": { "description": "Jinja-enabled filename.", "maxLength": 500, "type": "string" }, "format": { "default": "png", "enum": [ "png", "jpeg", "webp" ], "type": "string" }, "head": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Head" }, "hosted": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Keep the hosted copy; `false` deletes it once the storage uploads and email sends have succeeded. Absent or `null`: `false` when every storage destination of the render has `keep_hosted_copy: false`, else `true`. Zero-retention renders never keep one.", "title": "Hosted" }, "html": { "title": "Html", "type": "string" }, "image": { "anyOf": [ { "$ref": "#/components/schemas/ImageOptions" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "propertyNames": { "maxLength": 40, "minLength": 1 }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Metadata" }, "mode": { "default": "sync", "enum": [ "sync", "async" ], "title": "Mode", "type": "string" }, "priority": { "default": "normal", "enum": [ "normal", "low" ], "title": "Priority", "type": "string" }, "reference": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Reference" }, "retention_days": { "anyOf": [ { "maximum": 36500, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null, "title": "Retention Days" }, "templating": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Templating" }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Test" }, "timeout_behavior": { "default": "continue", "enum": [ "continue", "cancel" ], "title": "Timeout Behavior", "type": "string" }, "webhook": { "anyOf": [ { "$ref": "#/components/schemas/WebhookSpec" }, { "type": "null" } ], "default": null }, "webhook_url": { "format": "uri", "type": "string" } }, "required": [ "html" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "Succeeded": { "value": { "batch_id": null, "billed_renders": 1, "completed_at": "2026-09-17T15:06:34Z", "created_at": "2026-09-17T15:06:33Z", "email": [], "engine": "2026.4", "engine_version": "2026.4 (Chrome 153.0.8010.47)", "error": null, "expires_at": "2026-10-17T15:06:34Z", "files": [ { "bytes": 48213, "content_type": "application/pdf", "filename": "invoice-42.pdf", "format": "pdf", "height": null, "id": "file_01J9ZM1X3F7R8K2C4V6B8N0P2R", "pages": 2, "sha256": "9f2c…", "url": "https://files-eu.dynamicdocumentapi.com/f/…", "url_expires_at": "2026-09-17T16:06:34Z", "variant": null, "width": null } ], "id": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "input_type": "template", "kind": "pdf_template", "metadata": { "customer_id": "c_981" }, "mode": "sync", "object": "render", "output_format": "pdf", "pages": 2, "reference": "inv_2026_0042", "region": "eu", "result": null, "source": "api", "status": "succeeded", "storage": [], "template": { "id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "version": 7, "version_id": "tv_01J9ZK3M7Q8V5W2X4Y6Z8A0B1D" }, "test": false, "timings": { "postprocess_ms": 21, "queued_ms": 3, "render_ms": 612, "total_ms": 681, "upload_ms": 38 }, "warnings": [] } } }, "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "Sync render finished (`status=succeeded`). With `delivery.type=binary` the body is the file." }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "Async render accepted, or the sync timeout was exceeded (`Location: /v1/renders/{id}`)." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Malformed or invalid request (`errors[]` with JSON pointers), e.g. an unknown, switched-off or another template's rule at `/delivery/email/<i>/rule_id`." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render limit reached (`render_limit_reached`) or feature not on plan (`plan_feature_unavailable`, e.g. a `delivery.email` list below the Growth plan)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified; or `region_not_enabled`: the workspace's enabled regions leave out this region." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template or version not found." }, "408": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Sync timeout exceeded and the render was canceled (`timeout_behavior=cancel`)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A request with this Idempotency-Key is still in progress." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template deleted." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Payload or output too large." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render failed (`render_id`, `render_error`; `render_failed` when the worker reports no more specific code), schema mismatch, URL not allowed or idempotency key reused. `einvoice_invalid`, `einvoice_validation_failed`, `pdfa_conversion_failed` and `pdfua_validation_failed` also carry the conformance report as `result`. `email_needs_hosted_file`: `delivery.email` lists rules, but a zero-retention render keeps no file to email. `render_canceled`: the sync render was canceled, or its job expired, before it finished. `scene_invalid`, `data_invalid`: a canvas template's scene can't be rendered (e.g. an output over 16,384 px per side), or its `data` isn't an object or lacks a required dynamic property." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Region degraded (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Screenshot of HTML", "tags": [ "Renders" ] } }, "/v1/images/from-template": { "post": { "description": "Convenience wrapper over `POST /v1/renders` with flat, no-code friendly fields.", "operationId": "create_image_from_template", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Data" }, "data_url": { "anyOf": [ { "maxLength": 2048, "minLength": 8, "type": "string" }, { "type": "null" } ], "default": null, "title": "Data Url" }, "delivery": { "anyOf": [ { "$ref": "#/components/schemas/DeliverySpec" }, { "enum": [ "url", "binary", "base64", "none" ], "type": "string" } ] }, "engine": { "anyOf": [ { "pattern": "^\\d{4}\\.\\d{1,6}$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Engine" }, "expires_in": { "default": 3600, "maximum": 604800, "minimum": 60, "title": "Expires In", "type": "integer" }, "filename": { "description": "Jinja-enabled filename.", "maxLength": 500, "type": "string" }, "format": { "default": "png", "enum": [ "png", "jpeg", "webp" ], "type": "string" }, "hosted": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Keep the hosted copy; `false` deletes it once the storage uploads and email sends have succeeded. Absent or `null`: `false` when every storage destination of the render has `keep_hosted_copy: false`, else `true`. Zero-retention renders never keep one.", "title": "Hosted" }, "image": { "anyOf": [ { "$ref": "#/components/schemas/ImageOptions" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "propertyNames": { "maxLength": 40, "minLength": 1 }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Metadata" }, "mode": { "default": "sync", "enum": [ "sync", "async" ], "title": "Mode", "type": "string" }, "overrides": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "maxItems": 500, "type": "array" }, { "type": "null" } ], "default": null, "title": "Overrides" }, "priority": { "default": "normal", "enum": [ "normal", "low" ], "title": "Priority", "type": "string" }, "reference": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Reference" }, "retention_days": { "anyOf": [ { "maximum": 36500, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null, "title": "Retention Days" }, "template_id": { "maxLength": 64, "minLength": 1, "title": "Template Id", "type": "string" }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Test" }, "timeout_behavior": { "default": "continue", "enum": [ "continue", "cancel" ], "title": "Timeout Behavior", "type": "string" }, "version": { "anyOf": [ { "enum": [ "live", "draft" ], "type": "string" }, { "minimum": 1, "type": "integer" } ], "default": "live", "title": "Version" }, "webhook": { "anyOf": [ { "$ref": "#/components/schemas/WebhookSpec" }, { "type": "null" } ], "default": null }, "webhook_url": { "format": "uri", "type": "string" } }, "required": [ "template_id" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "Succeeded": { "value": { "batch_id": null, "billed_renders": 1, "completed_at": "2026-09-17T15:06:34Z", "created_at": "2026-09-17T15:06:33Z", "email": [], "engine": "2026.4", "engine_version": "2026.4 (Chrome 153.0.8010.47)", "error": null, "expires_at": "2026-10-17T15:06:34Z", "files": [ { "bytes": 48213, "content_type": "application/pdf", "filename": "invoice-42.pdf", "format": "pdf", "height": null, "id": "file_01J9ZM1X3F7R8K2C4V6B8N0P2R", "pages": 2, "sha256": "9f2c…", "url": "https://files-eu.dynamicdocumentapi.com/f/…", "url_expires_at": "2026-09-17T16:06:34Z", "variant": null, "width": null } ], "id": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "input_type": "template", "kind": "pdf_template", "metadata": { "customer_id": "c_981" }, "mode": "sync", "object": "render", "output_format": "pdf", "pages": 2, "reference": "inv_2026_0042", "region": "eu", "result": null, "source": "api", "status": "succeeded", "storage": [], "template": { "id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "version": 7, "version_id": "tv_01J9ZK3M7Q8V5W2X4Y6Z8A0B1D" }, "test": false, "timings": { "postprocess_ms": 21, "queued_ms": 3, "render_ms": 612, "total_ms": 681, "upload_ms": 38 }, "warnings": [] } } }, "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "Sync render finished (`status=succeeded`). With `delivery.type=binary` the body is the file." }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "Async render accepted, or the sync timeout was exceeded (`Location: /v1/renders/{id}`)." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Malformed or invalid request (`errors[]` with JSON pointers), e.g. an unknown, switched-off or another template's rule at `/delivery/email/<i>/rule_id`." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render limit reached (`render_limit_reached`) or feature not on plan (`plan_feature_unavailable`, e.g. a `delivery.email` list below the Growth plan)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified; or `region_not_enabled`: the workspace's enabled regions leave out this region." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template or version not found." }, "408": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Sync timeout exceeded and the render was canceled (`timeout_behavior=cancel`)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A request with this Idempotency-Key is still in progress." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template deleted." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Payload or output too large." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render failed (`render_id`, `render_error`; `render_failed` when the worker reports no more specific code), schema mismatch, URL not allowed or idempotency key reused. `einvoice_invalid`, `einvoice_validation_failed`, `pdfa_conversion_failed` and `pdfua_validation_failed` also carry the conformance report as `result`. `email_needs_hosted_file`: `delivery.email` lists rules, but a zero-retention render keeps no file to email. `render_canceled`: the sync render was canceled, or its job expired, before it finished. `scene_invalid`, `data_invalid`: a canvas template's scene can't be rendered (e.g. an output over 16,384 px per side), or its `data` isn't an object or lacks a required dynamic property." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Region degraded (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Image from a template", "tags": [ "Renders" ] } }, "/v1/images/from-url": { "post": { "description": "Convenience wrapper over `POST /v1/renders` with flat, no-code friendly fields.", "operationId": "create_image_from_url", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Data" }, "data_url": { "anyOf": [ { "maxLength": 2048, "minLength": 8, "type": "string" }, { "type": "null" } ], "default": null, "title": "Data Url" }, "delivery": { "anyOf": [ { "$ref": "#/components/schemas/DeliverySpec" }, { "enum": [ "url", "binary", "base64", "none" ], "type": "string" } ] }, "engine": { "anyOf": [ { "pattern": "^\\d{4}\\.\\d{1,6}$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Engine" }, "expires_in": { "default": 3600, "maximum": 604800, "minimum": 60, "title": "Expires In", "type": "integer" }, "filename": { "description": "Jinja-enabled filename.", "maxLength": 500, "type": "string" }, "format": { "default": "png", "enum": [ "png", "jpeg", "webp" ], "type": "string" }, "hosted": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Keep the hosted copy; `false` deletes it once the storage uploads and email sends have succeeded. Absent or `null`: `false` when every storage destination of the render has `keep_hosted_copy: false`, else `true`. Zero-retention renders never keep one.", "title": "Hosted" }, "http": { "anyOf": [ { "$ref": "#/components/schemas/HttpOptions" }, { "type": "null" } ], "default": null }, "image": { "anyOf": [ { "$ref": "#/components/schemas/ImageOptions" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "propertyNames": { "maxLength": 40, "minLength": 1 }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Metadata" }, "mode": { "default": "sync", "enum": [ "sync", "async" ], "title": "Mode", "type": "string" }, "priority": { "default": "normal", "enum": [ "normal", "low" ], "title": "Priority", "type": "string" }, "reference": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Reference" }, "retention_days": { "anyOf": [ { "maximum": 36500, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null, "title": "Retention Days" }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Test" }, "timeout_behavior": { "default": "continue", "enum": [ "continue", "cancel" ], "title": "Timeout Behavior", "type": "string" }, "url": { "maxLength": 2048, "minLength": 8, "title": "Url", "type": "string" }, "webhook": { "anyOf": [ { "$ref": "#/components/schemas/WebhookSpec" }, { "type": "null" } ], "default": null }, "webhook_url": { "format": "uri", "type": "string" } }, "required": [ "url" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "Succeeded": { "value": { "batch_id": null, "billed_renders": 1, "completed_at": "2026-09-17T15:06:34Z", "created_at": "2026-09-17T15:06:33Z", "email": [], "engine": "2026.4", "engine_version": "2026.4 (Chrome 153.0.8010.47)", "error": null, "expires_at": "2026-10-17T15:06:34Z", "files": [ { "bytes": 48213, "content_type": "application/pdf", "filename": "invoice-42.pdf", "format": "pdf", "height": null, "id": "file_01J9ZM1X3F7R8K2C4V6B8N0P2R", "pages": 2, "sha256": "9f2c…", "url": "https://files-eu.dynamicdocumentapi.com/f/…", "url_expires_at": "2026-09-17T16:06:34Z", "variant": null, "width": null } ], "id": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "input_type": "template", "kind": "pdf_template", "metadata": { "customer_id": "c_981" }, "mode": "sync", "object": "render", "output_format": "pdf", "pages": 2, "reference": "inv_2026_0042", "region": "eu", "result": null, "source": "api", "status": "succeeded", "storage": [], "template": { "id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "version": 7, "version_id": "tv_01J9ZK3M7Q8V5W2X4Y6Z8A0B1D" }, "test": false, "timings": { "postprocess_ms": 21, "queued_ms": 3, "render_ms": 612, "total_ms": 681, "upload_ms": 38 }, "warnings": [] } } }, "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "Sync render finished (`status=succeeded`). With `delivery.type=binary` the body is the file." }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "Async render accepted, or the sync timeout was exceeded (`Location: /v1/renders/{id}`)." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Malformed or invalid request (`errors[]` with JSON pointers), e.g. an unknown, switched-off or another template's rule at `/delivery/email/<i>/rule_id`." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render limit reached (`render_limit_reached`) or feature not on plan (`plan_feature_unavailable`, e.g. a `delivery.email` list below the Growth plan)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified; or `region_not_enabled`: the workspace's enabled regions leave out this region." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template or version not found." }, "408": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Sync timeout exceeded and the render was canceled (`timeout_behavior=cancel`)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A request with this Idempotency-Key is still in progress." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template deleted." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Payload or output too large." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render failed (`render_id`, `render_error`; `render_failed` when the worker reports no more specific code), schema mismatch, URL not allowed or idempotency key reused. `einvoice_invalid`, `einvoice_validation_failed`, `pdfa_conversion_failed` and `pdfua_validation_failed` also carry the conformance report as `result`. `email_needs_hosted_file`: `delivery.email` lists rules, but a zero-retention render keeps no file to email. `render_canceled`: the sync render was canceled, or its job expired, before it finished. `scene_invalid`, `data_invalid`: a canvas template's scene can't be rendered (e.g. an output over 16,384 px per side), or its `data` isn't an object or lacks a required dynamic property." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Region degraded (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Screenshot of a URL", "tags": [ "Renders" ] } }, "/v1/pdf-tools/merge": { "post": { "description": "Merge 2-200 PDFs into one document (docs/05 §5). Answers a Render object with `input_type: \"pdf_tool\"`; `delivery`, `mode`, `webhook`, `reference`, `metadata` and `test` behave as on `POST /v1/renders`.", "operationId": "pdf_tools_merge", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "MergePDFs": { "summary": "Merge PDFs", "value": { "bookmarks": "filenames", "filename": "contract.pdf", "sources": [ { "url": "https://example.com/cover.pdf" }, { "render_id": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q" } ] } } }, "schema": { "$ref": "#/components/schemas/MergeRequest" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "Succeeded": { "value": { "batch_id": null, "billed_renders": 1, "completed_at": "2026-09-17T15:06:34Z", "created_at": "2026-09-17T15:06:33Z", "email": [], "engine": "2026.4", "engine_version": "2026.4 (Chrome 153.0.8010.47)", "error": null, "expires_at": "2026-10-17T15:06:34Z", "files": [ { "bytes": 48213, "content_type": "application/pdf", "filename": "invoice-42.pdf", "format": "pdf", "height": null, "id": "file_01J9ZM1X3F7R8K2C4V6B8N0P2R", "pages": 2, "sha256": "9f2c…", "url": "https://files-eu.dynamicdocumentapi.com/f/…", "url_expires_at": "2026-09-17T16:06:34Z", "variant": null, "width": null } ], "id": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "input_type": "template", "kind": "pdf_template", "metadata": { "customer_id": "c_981" }, "mode": "sync", "object": "render", "output_format": "pdf", "pages": 2, "reference": "inv_2026_0042", "region": "eu", "result": null, "source": "api", "status": "succeeded", "storage": [], "template": { "id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "version": 7, "version_id": "tv_01J9ZK3M7Q8V5W2X4Y6Z8A0B1D" }, "test": false, "timings": { "postprocess_ms": 21, "queued_ms": 3, "render_ms": 612, "total_ms": 681, "upload_ms": 38 }, "warnings": [] } } }, "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "Sync render finished (`status=succeeded`). With `delivery.type=binary` the body is the file." }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "Async render accepted, or the sync timeout was exceeded (`Location: /v1/renders/{id}`)." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Malformed or invalid request (`errors[]` with JSON pointers), e.g. an unknown, switched-off or another template's rule at `/delivery/email/<i>/rule_id`." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render limit reached (`render_limit_reached`) or feature not on plan (`plan_feature_unavailable`, e.g. a `delivery.email` list below the Growth plan)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified; or `region_not_enabled`: the workspace's enabled regions leave out this region." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template or version not found." }, "408": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Sync timeout exceeded and the render was canceled (`timeout_behavior=cancel`)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A request with this Idempotency-Key is still in progress." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template deleted." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Payload or output too large." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render failed (`render_id`, `render_error`; `render_failed` when the worker reports no more specific code), schema mismatch, URL not allowed or idempotency key reused. `einvoice_invalid`, `einvoice_validation_failed`, `pdfa_conversion_failed` and `pdfua_validation_failed` also carry the conformance report as `result`. `email_needs_hosted_file`: `delivery.email` lists rules, but a zero-retention render keeps no file to email. `render_canceled`: the sync render was canceled, or its job expired, before it finished. `scene_invalid`, `data_invalid`: a canvas template's scene can't be rendered (e.g. an output over 16,384 px per side), or its `data` isn't an object or lacks a required dynamic property." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Region degraded (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Merge PDFs", "tags": [ "PDF tools" ] } }, "/v1/pdf-tools/metadata": { "post": { "description": "Without `set`: no file, and the render's `result` is `{pages, page_sizes, encrypted, pdf_version, metadata}`. `page_sizes` lists runs of pages shown at one size (`{\"width\": \"210mm\", \"height\": \"297mm\", \"pages\": \"1-10\"}`); `metadata` holds `title`, `author`, `subject`, `keywords` (a list), `creator`, `producer`, `created`, `modified` and `lang`, null when absent. A PDF that needs a password still answers `pages` and `encrypted: true`, with `metadata` null. With `set` (`title`, `author`, `subject`, `keywords`, `creator`, `producer`, `lang`): the PDF with only those fields changed (`\"\"`, `null` or `[]` clears one) and the same `result` for it; an encrypted source fails with `pdf_password_required` (422). A read cannot use `delivery.type: \"binary\"`. 1 billed render. Answers a Render object with `input_type: \"pdf_tool\"`; `delivery`, `mode`, `webhook`, `reference`, `metadata` and `test` behave as on `POST /v1/renders`.", "operationId": "pdf_tools_metadata", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "ReadOrSetPDFMetadata": { "summary": "Read or set PDF metadata", "value": { "set": { "author": "Acme", "title": "Invoice 42" }, "source": { "upload_id": "upl_01J9ZM1X3F7R8K2C4V6B8N0P2Q" } } } }, "schema": { "$ref": "#/components/schemas/PdfMetadataRequest" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "Succeeded": { "value": { "batch_id": null, "billed_renders": 1, "completed_at": "2026-09-17T15:06:34Z", "created_at": "2026-09-17T15:06:33Z", "email": [], "engine": "2026.4", "engine_version": "2026.4 (Chrome 153.0.8010.47)", "error": null, "expires_at": "2026-10-17T15:06:34Z", "files": [ { "bytes": 48213, "content_type": "application/pdf", "filename": "invoice-42.pdf", "format": "pdf", "height": null, "id": "file_01J9ZM1X3F7R8K2C4V6B8N0P2R", "pages": 2, "sha256": "9f2c…", "url": "https://files-eu.dynamicdocumentapi.com/f/…", "url_expires_at": "2026-09-17T16:06:34Z", "variant": null, "width": null } ], "id": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "input_type": "template", "kind": "pdf_template", "metadata": { "customer_id": "c_981" }, "mode": "sync", "object": "render", "output_format": "pdf", "pages": 2, "reference": "inv_2026_0042", "region": "eu", "result": null, "source": "api", "status": "succeeded", "storage": [], "template": { "id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "version": 7, "version_id": "tv_01J9ZK3M7Q8V5W2X4Y6Z8A0B1D" }, "test": false, "timings": { "postprocess_ms": 21, "queued_ms": 3, "render_ms": 612, "total_ms": 681, "upload_ms": 38 }, "warnings": [] } } }, "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "Sync render finished (`status=succeeded`). With `delivery.type=binary` the body is the file." }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "Async render accepted, or the sync timeout was exceeded (`Location: /v1/renders/{id}`)." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Malformed or invalid request (`errors[]` with JSON pointers), e.g. an unknown, switched-off or another template's rule at `/delivery/email/<i>/rule_id`." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render limit reached (`render_limit_reached`) or feature not on plan (`plan_feature_unavailable`, e.g. a `delivery.email` list below the Growth plan)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified; or `region_not_enabled`: the workspace's enabled regions leave out this region." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template or version not found." }, "408": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Sync timeout exceeded and the render was canceled (`timeout_behavior=cancel`)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A request with this Idempotency-Key is still in progress." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template deleted." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Payload or output too large." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render failed (`render_id`, `render_error`; `render_failed` when the worker reports no more specific code), schema mismatch, URL not allowed or idempotency key reused. `einvoice_invalid`, `einvoice_validation_failed`, `pdfa_conversion_failed` and `pdfua_validation_failed` also carry the conformance report as `result`. `email_needs_hosted_file`: `delivery.email` lists rules, but a zero-retention render keeps no file to email. `render_canceled`: the sync render was canceled, or its job expired, before it finished. `scene_invalid`, `data_invalid`: a canvas template's scene can't be rendered (e.g. an output over 16,384 px per side), or its `data` isn't an object or lacks a required dynamic property." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Region degraded (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Read or set PDF metadata", "tags": [ "PDF tools" ] } }, "/v1/pdf-tools/pdfa": { "post": { "description": "Converts any PDF to PDF/A-2b or PDF/A-3b (best effort: fonts must be embedded and the source must not be encrypted) and validates the result with veraPDF; the report is `result.conformance.pdfa`. A PDF that cannot be made conformant fails with `pdfa_conversion_failed`. 1 billed render. Answers a Render object with `input_type: \"pdf_tool\"`; `delivery`, `mode`, `webhook`, `reference`, `metadata` and `test` behave as on `POST /v1/renders`.", "operationId": "pdf_tools_pdfa", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "ConvertAPDFToPDF/A": { "summary": "Convert a PDF to PDF/A", "value": { "filename": "archive.pdf", "level": "2b", "source": { "render_id": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q" } } } }, "schema": { "$ref": "#/components/schemas/PdfaRequest" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "Succeeded": { "value": { "batch_id": null, "billed_renders": 1, "completed_at": "2026-09-17T15:06:34Z", "created_at": "2026-09-17T15:06:33Z", "email": [], "engine": "2026.4", "engine_version": "2026.4 (Chrome 153.0.8010.47)", "error": null, "expires_at": "2026-10-17T15:06:34Z", "files": [ { "bytes": 48213, "content_type": "application/pdf", "filename": "invoice-42.pdf", "format": "pdf", "height": null, "id": "file_01J9ZM1X3F7R8K2C4V6B8N0P2R", "pages": 2, "sha256": "9f2c…", "url": "https://files-eu.dynamicdocumentapi.com/f/…", "url_expires_at": "2026-09-17T16:06:34Z", "variant": null, "width": null } ], "id": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "input_type": "template", "kind": "pdf_template", "metadata": { "customer_id": "c_981" }, "mode": "sync", "object": "render", "output_format": "pdf", "pages": 2, "reference": "inv_2026_0042", "region": "eu", "result": null, "source": "api", "status": "succeeded", "storage": [], "template": { "id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "version": 7, "version_id": "tv_01J9ZK3M7Q8V5W2X4Y6Z8A0B1D" }, "test": false, "timings": { "postprocess_ms": 21, "queued_ms": 3, "render_ms": 612, "total_ms": 681, "upload_ms": 38 }, "warnings": [] } } }, "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "Sync render finished (`status=succeeded`). With `delivery.type=binary` the body is the file." }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "Async render accepted, or the sync timeout was exceeded (`Location: /v1/renders/{id}`)." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Malformed or invalid request (`errors[]` with JSON pointers), e.g. an unknown, switched-off or another template's rule at `/delivery/email/<i>/rule_id`." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render limit reached (`render_limit_reached`) or feature not on plan (`plan_feature_unavailable`, e.g. a `delivery.email` list below the Growth plan)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified; or `region_not_enabled`: the workspace's enabled regions leave out this region." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template or version not found." }, "408": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Sync timeout exceeded and the render was canceled (`timeout_behavior=cancel`)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A request with this Idempotency-Key is still in progress." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template deleted." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Payload or output too large." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render failed (`render_id`, `render_error`; `render_failed` when the worker reports no more specific code), schema mismatch, URL not allowed or idempotency key reused. `einvoice_invalid`, `einvoice_validation_failed`, `pdfa_conversion_failed` and `pdfua_validation_failed` also carry the conformance report as `result`. `email_needs_hosted_file`: `delivery.email` lists rules, but a zero-retention render keeps no file to email. `render_canceled`: the sync render was canceled, or its job expired, before it finished. `scene_invalid`, `data_invalid`: a canvas template's scene can't be rendered (e.g. an output over 16,384 px per side), or its `data` isn't an object or lacks a required dynamic property." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Region degraded (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Convert a PDF to PDF/A", "tags": [ "PDF tools" ] } }, "/v1/pdf-tools/protect": { "post": { "description": "AES-256 encryption with a user and/or owner password, as the `pdf.protect` render option does. Unset `permissions` flags take the same defaults: `print`, `print_high_res`, `copy` and `fill_forms` allowed, `modify`, `annotate` and `assemble` denied. An encrypted source fails with `pdf_password_required` (422). 1 billed render. Answers a Render object with `input_type: \"pdf_tool\"`; `delivery`, `mode`, `webhook`, `reference`, `metadata` and `test` behave as on `POST /v1/renders`.", "operationId": "pdf_tools_protect", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "Password-protectAPDF": { "summary": "Password-protect a PDF", "value": { "permissions": { "copy": false, "modify": false, "print": true }, "source": { "render_id": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q" }, "user_password": "s3cret" } } }, "schema": { "$ref": "#/components/schemas/ProtectRequest" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "Succeeded": { "value": { "batch_id": null, "billed_renders": 1, "completed_at": "2026-09-17T15:06:34Z", "created_at": "2026-09-17T15:06:33Z", "email": [], "engine": "2026.4", "engine_version": "2026.4 (Chrome 153.0.8010.47)", "error": null, "expires_at": "2026-10-17T15:06:34Z", "files": [ { "bytes": 48213, "content_type": "application/pdf", "filename": "invoice-42.pdf", "format": "pdf", "height": null, "id": "file_01J9ZM1X3F7R8K2C4V6B8N0P2R", "pages": 2, "sha256": "9f2c…", "url": "https://files-eu.dynamicdocumentapi.com/f/…", "url_expires_at": "2026-09-17T16:06:34Z", "variant": null, "width": null } ], "id": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "input_type": "template", "kind": "pdf_template", "metadata": { "customer_id": "c_981" }, "mode": "sync", "object": "render", "output_format": "pdf", "pages": 2, "reference": "inv_2026_0042", "region": "eu", "result": null, "source": "api", "status": "succeeded", "storage": [], "template": { "id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "version": 7, "version_id": "tv_01J9ZK3M7Q8V5W2X4Y6Z8A0B1D" }, "test": false, "timings": { "postprocess_ms": 21, "queued_ms": 3, "render_ms": 612, "total_ms": 681, "upload_ms": 38 }, "warnings": [] } } }, "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "Sync render finished (`status=succeeded`). With `delivery.type=binary` the body is the file." }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "Async render accepted, or the sync timeout was exceeded (`Location: /v1/renders/{id}`)." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Malformed or invalid request (`errors[]` with JSON pointers), e.g. an unknown, switched-off or another template's rule at `/delivery/email/<i>/rule_id`." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render limit reached (`render_limit_reached`) or feature not on plan (`plan_feature_unavailable`, e.g. a `delivery.email` list below the Growth plan)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified; or `region_not_enabled`: the workspace's enabled regions leave out this region." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template or version not found." }, "408": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Sync timeout exceeded and the render was canceled (`timeout_behavior=cancel`)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A request with this Idempotency-Key is still in progress." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template deleted." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Payload or output too large." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render failed (`render_id`, `render_error`; `render_failed` when the worker reports no more specific code), schema mismatch, URL not allowed or idempotency key reused. `einvoice_invalid`, `einvoice_validation_failed`, `pdfa_conversion_failed` and `pdfua_validation_failed` also carry the conformance report as `result`. `email_needs_hosted_file`: `delivery.email` lists rules, but a zero-retention render keeps no file to email. `render_canceled`: the sync render was canceled, or its job expired, before it finished. `scene_invalid`, `data_invalid`: a canvas template's scene can't be rendered (e.g. an output over 16,384 px per side), or its `data` isn't an object or lacks a required dynamic property." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Region degraded (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Password-protect a PDF", "tags": [ "PDF tools" ] } }, "/v1/pdf-tools/rotate": { "post": { "description": "Adds `degrees` (90, 180 or 270; negative turns anticlockwise) to the rotation of the pages in `pages` (`\"all\"`, `\"1,3-5\"`, `\"4-\"`); other pages keep theirs. A page outside the document fails with `validation_error` (422), naming it; an encrypted source with `pdf_password_required` (unlock it first). 1 billed render. Answers a Render object with `input_type: \"pdf_tool\"`; `delivery`, `mode`, `webhook`, `reference`, `metadata` and `test` behave as on `POST /v1/renders`.", "operationId": "pdf_tools_rotate", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "RotatePDFPages": { "summary": "Rotate PDF pages", "value": { "degrees": 90, "pages": "1,3-5", "source": { "upload_id": "upl_01J9ZM1X3F7R8K2C4V6B8N0P2Q" } } } }, "schema": { "$ref": "#/components/schemas/RotateRequest" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "Succeeded": { "value": { "batch_id": null, "billed_renders": 1, "completed_at": "2026-09-17T15:06:34Z", "created_at": "2026-09-17T15:06:33Z", "email": [], "engine": "2026.4", "engine_version": "2026.4 (Chrome 153.0.8010.47)", "error": null, "expires_at": "2026-10-17T15:06:34Z", "files": [ { "bytes": 48213, "content_type": "application/pdf", "filename": "invoice-42.pdf", "format": "pdf", "height": null, "id": "file_01J9ZM1X3F7R8K2C4V6B8N0P2R", "pages": 2, "sha256": "9f2c…", "url": "https://files-eu.dynamicdocumentapi.com/f/…", "url_expires_at": "2026-09-17T16:06:34Z", "variant": null, "width": null } ], "id": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "input_type": "template", "kind": "pdf_template", "metadata": { "customer_id": "c_981" }, "mode": "sync", "object": "render", "output_format": "pdf", "pages": 2, "reference": "inv_2026_0042", "region": "eu", "result": null, "source": "api", "status": "succeeded", "storage": [], "template": { "id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "version": 7, "version_id": "tv_01J9ZK3M7Q8V5W2X4Y6Z8A0B1D" }, "test": false, "timings": { "postprocess_ms": 21, "queued_ms": 3, "render_ms": 612, "total_ms": 681, "upload_ms": 38 }, "warnings": [] } } }, "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "Sync render finished (`status=succeeded`). With `delivery.type=binary` the body is the file." }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "Async render accepted, or the sync timeout was exceeded (`Location: /v1/renders/{id}`)." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Malformed or invalid request (`errors[]` with JSON pointers), e.g. an unknown, switched-off or another template's rule at `/delivery/email/<i>/rule_id`." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render limit reached (`render_limit_reached`) or feature not on plan (`plan_feature_unavailable`, e.g. a `delivery.email` list below the Growth plan)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified; or `region_not_enabled`: the workspace's enabled regions leave out this region." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template or version not found." }, "408": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Sync timeout exceeded and the render was canceled (`timeout_behavior=cancel`)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A request with this Idempotency-Key is still in progress." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template deleted." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Payload or output too large." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render failed (`render_id`, `render_error`; `render_failed` when the worker reports no more specific code), schema mismatch, URL not allowed or idempotency key reused. `einvoice_invalid`, `einvoice_validation_failed`, `pdfa_conversion_failed` and `pdfua_validation_failed` also carry the conformance report as `result`. `email_needs_hosted_file`: `delivery.email` lists rules, but a zero-retention render keeps no file to email. `render_canceled`: the sync render was canceled, or its job expired, before it finished. `scene_invalid`, `data_invalid`: a canvas template's scene can't be rendered (e.g. an output over 16,384 px per side), or its `data` isn't an object or lacks a required dynamic property." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Region degraded (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Rotate PDF pages", "tags": [ "PDF tools" ] } }, "/v1/pdf-tools/split": { "post": { "description": "One file per entry of `ranges` (`\"1-3\"`, `\"4-\"` to the last page, `\"1,3-5\"`) or per run of `every` pages, at most 200, named `<stem>-<n>.pdf` (n from 1; `<stem>` is `filename` without `.pdf`, else `split`) and listed in that order in `files`. With `zip: true` a single `<stem>.zip` holds them instead. `delivery.type: \"binary\"` needs a single output (`zip: true` or exactly one range); `base64` carries every file, and storage destinations get every file (`file.index` in path templates). A page outside the document fails with `validation_error` (422), naming it; an encrypted source with `pdf_password_required` (unlock it first). 1 billed render. Answers a Render object with `input_type: \"pdf_tool\"`; `delivery`, `mode`, `webhook`, `reference`, `metadata` and `test` behave as on `POST /v1/renders`.", "operationId": "pdf_tools_split", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "SplitAPDF": { "summary": "Split a PDF", "value": { "ranges": [ "1-3", "4-" ], "source": { "upload_id": "upl_01J9ZM1X3F7R8K2C4V6B8N0P2Q" }, "zip": true } } }, "schema": { "$ref": "#/components/schemas/SplitRequest" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "Succeeded": { "value": { "batch_id": null, "billed_renders": 1, "completed_at": "2026-09-17T15:06:34Z", "created_at": "2026-09-17T15:06:33Z", "email": [], "engine": "2026.4", "engine_version": "2026.4 (Chrome 153.0.8010.47)", "error": null, "expires_at": "2026-10-17T15:06:34Z", "files": [ { "bytes": 48213, "content_type": "application/pdf", "filename": "invoice-42.pdf", "format": "pdf", "height": null, "id": "file_01J9ZM1X3F7R8K2C4V6B8N0P2R", "pages": 2, "sha256": "9f2c…", "url": "https://files-eu.dynamicdocumentapi.com/f/…", "url_expires_at": "2026-09-17T16:06:34Z", "variant": null, "width": null } ], "id": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "input_type": "template", "kind": "pdf_template", "metadata": { "customer_id": "c_981" }, "mode": "sync", "object": "render", "output_format": "pdf", "pages": 2, "reference": "inv_2026_0042", "region": "eu", "result": null, "source": "api", "status": "succeeded", "storage": [], "template": { "id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "version": 7, "version_id": "tv_01J9ZK3M7Q8V5W2X4Y6Z8A0B1D" }, "test": false, "timings": { "postprocess_ms": 21, "queued_ms": 3, "render_ms": 612, "total_ms": 681, "upload_ms": 38 }, "warnings": [] } } }, "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "Sync render finished (`status=succeeded`). With `delivery.type=binary` the body is the file." }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "Async render accepted, or the sync timeout was exceeded (`Location: /v1/renders/{id}`)." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Malformed or invalid request (`errors[]` with JSON pointers), e.g. an unknown, switched-off or another template's rule at `/delivery/email/<i>/rule_id`." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render limit reached (`render_limit_reached`) or feature not on plan (`plan_feature_unavailable`, e.g. a `delivery.email` list below the Growth plan)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified; or `region_not_enabled`: the workspace's enabled regions leave out this region." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template or version not found." }, "408": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Sync timeout exceeded and the render was canceled (`timeout_behavior=cancel`)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A request with this Idempotency-Key is still in progress." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template deleted." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Payload or output too large." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render failed (`render_id`, `render_error`; `render_failed` when the worker reports no more specific code), schema mismatch, URL not allowed or idempotency key reused. `einvoice_invalid`, `einvoice_validation_failed`, `pdfa_conversion_failed` and `pdfua_validation_failed` also carry the conformance report as `result`. `email_needs_hosted_file`: `delivery.email` lists rules, but a zero-retention render keeps no file to email. `render_canceled`: the sync render was canceled, or its job expired, before it finished. `scene_invalid`, `data_invalid`: a canvas template's scene can't be rendered (e.g. an output over 16,384 px per side), or its `data` isn't an object or lacks a required dynamic property." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Region degraded (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Split a PDF", "tags": [ "PDF tools" ] } }, "/v1/pdf-tools/unlock": { "post": { "description": "Decrypts a PDF with its user or owner password and removes its restrictions. A wrong password fails with `pdf_password_required` (422); an unencrypted PDF comes back unchanged. 1 billed render. Answers a Render object with `input_type: \"pdf_tool\"`; `delivery`, `mode`, `webhook`, `reference`, `metadata` and `test` behave as on `POST /v1/renders`.", "operationId": "pdf_tools_unlock", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "RemoveAPDFPassword": { "summary": "Remove a PDF password", "value": { "password": "s3cret", "source": { "upload_id": "upl_01J9ZM1X3F7R8K2C4V6B8N0P2Q" } } } }, "schema": { "$ref": "#/components/schemas/UnlockRequest" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "Succeeded": { "value": { "batch_id": null, "billed_renders": 1, "completed_at": "2026-09-17T15:06:34Z", "created_at": "2026-09-17T15:06:33Z", "email": [], "engine": "2026.4", "engine_version": "2026.4 (Chrome 153.0.8010.47)", "error": null, "expires_at": "2026-10-17T15:06:34Z", "files": [ { "bytes": 48213, "content_type": "application/pdf", "filename": "invoice-42.pdf", "format": "pdf", "height": null, "id": "file_01J9ZM1X3F7R8K2C4V6B8N0P2R", "pages": 2, "sha256": "9f2c…", "url": "https://files-eu.dynamicdocumentapi.com/f/…", "url_expires_at": "2026-09-17T16:06:34Z", "variant": null, "width": null } ], "id": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "input_type": "template", "kind": "pdf_template", "metadata": { "customer_id": "c_981" }, "mode": "sync", "object": "render", "output_format": "pdf", "pages": 2, "reference": "inv_2026_0042", "region": "eu", "result": null, "source": "api", "status": "succeeded", "storage": [], "template": { "id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "version": 7, "version_id": "tv_01J9ZK3M7Q8V5W2X4Y6Z8A0B1D" }, "test": false, "timings": { "postprocess_ms": 21, "queued_ms": 3, "render_ms": 612, "total_ms": 681, "upload_ms": 38 }, "warnings": [] } } }, "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "Sync render finished (`status=succeeded`). With `delivery.type=binary` the body is the file." }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "Async render accepted, or the sync timeout was exceeded (`Location: /v1/renders/{id}`)." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Malformed or invalid request (`errors[]` with JSON pointers), e.g. an unknown, switched-off or another template's rule at `/delivery/email/<i>/rule_id`." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render limit reached (`render_limit_reached`) or feature not on plan (`plan_feature_unavailable`, e.g. a `delivery.email` list below the Growth plan)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified; or `region_not_enabled`: the workspace's enabled regions leave out this region." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template or version not found." }, "408": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Sync timeout exceeded and the render was canceled (`timeout_behavior=cancel`)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A request with this Idempotency-Key is still in progress." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template deleted." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Payload or output too large." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render failed (`render_id`, `render_error`; `render_failed` when the worker reports no more specific code), schema mismatch, URL not allowed or idempotency key reused. `einvoice_invalid`, `einvoice_validation_failed`, `pdfa_conversion_failed` and `pdfua_validation_failed` also carry the conformance report as `result`. `email_needs_hosted_file`: `delivery.email` lists rules, but a zero-retention render keeps no file to email. `render_canceled`: the sync render was canceled, or its job expired, before it finished. `scene_invalid`, `data_invalid`: a canvas template's scene can't be rendered (e.g. an output over 16,384 px per side), or its `data` isn't an object or lacks a required dynamic property." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Region degraded (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Remove a PDF password", "tags": [ "PDF tools" ] } }, "/v1/pdf/from-html": { "post": { "description": "Convenience wrapper over `POST /v1/renders` with flat, no-code friendly fields.", "operationId": "create_pdf_from_html", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Data" }, "data_url": { "anyOf": [ { "maxLength": 2048, "minLength": 8, "type": "string" }, { "type": "null" } ], "default": null, "title": "Data Url" }, "delivery": { "anyOf": [ { "$ref": "#/components/schemas/DeliverySpec" }, { "enum": [ "url", "binary", "base64", "none" ], "type": "string" } ] }, "einvoice": { "anyOf": [ { "$ref": "#/components/schemas/EInvoiceSpec" }, { "type": "null" } ] }, "engine": { "anyOf": [ { "pattern": "^\\d{4}\\.\\d{1,6}$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Engine" }, "expires_in": { "default": 3600, "maximum": 604800, "minimum": 60, "title": "Expires In", "type": "integer" }, "filename": { "description": "Jinja-enabled filename.", "maxLength": 500, "type": "string" }, "head": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Head" }, "hosted": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Keep the hosted copy; `false` deletes it once the storage uploads and email sends have succeeded. Absent or `null`: `false` when every storage destination of the render has `keep_hosted_copy: false`, else `true`. Zero-retention renders never keep one.", "title": "Hosted" }, "html": { "title": "Html", "type": "string" }, "metadata": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "propertyNames": { "maxLength": 40, "minLength": 1 }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Metadata" }, "mode": { "default": "sync", "enum": [ "sync", "async" ], "title": "Mode", "type": "string" }, "pdf": { "anyOf": [ { "$ref": "#/components/schemas/PdfOptions" }, { "type": "null" } ] }, "priority": { "default": "normal", "enum": [ "normal", "low" ], "title": "Priority", "type": "string" }, "reference": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Reference" }, "retention_days": { "anyOf": [ { "maximum": 36500, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null, "title": "Retention Days" }, "templating": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Templating" }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Test" }, "timeout_behavior": { "default": "continue", "enum": [ "continue", "cancel" ], "title": "Timeout Behavior", "type": "string" }, "webhook": { "anyOf": [ { "$ref": "#/components/schemas/WebhookSpec" }, { "type": "null" } ], "default": null }, "webhook_url": { "format": "uri", "type": "string" } }, "required": [ "html" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "Succeeded": { "value": { "batch_id": null, "billed_renders": 1, "completed_at": "2026-09-17T15:06:34Z", "created_at": "2026-09-17T15:06:33Z", "email": [], "engine": "2026.4", "engine_version": "2026.4 (Chrome 153.0.8010.47)", "error": null, "expires_at": "2026-10-17T15:06:34Z", "files": [ { "bytes": 48213, "content_type": "application/pdf", "filename": "invoice-42.pdf", "format": "pdf", "height": null, "id": "file_01J9ZM1X3F7R8K2C4V6B8N0P2R", "pages": 2, "sha256": "9f2c…", "url": "https://files-eu.dynamicdocumentapi.com/f/…", "url_expires_at": "2026-09-17T16:06:34Z", "variant": null, "width": null } ], "id": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "input_type": "template", "kind": "pdf_template", "metadata": { "customer_id": "c_981" }, "mode": "sync", "object": "render", "output_format": "pdf", "pages": 2, "reference": "inv_2026_0042", "region": "eu", "result": null, "source": "api", "status": "succeeded", "storage": [], "template": { "id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "version": 7, "version_id": "tv_01J9ZK3M7Q8V5W2X4Y6Z8A0B1D" }, "test": false, "timings": { "postprocess_ms": 21, "queued_ms": 3, "render_ms": 612, "total_ms": 681, "upload_ms": 38 }, "warnings": [] } } }, "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "Sync render finished (`status=succeeded`). With `delivery.type=binary` the body is the file." }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "Async render accepted, or the sync timeout was exceeded (`Location: /v1/renders/{id}`)." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Malformed or invalid request (`errors[]` with JSON pointers), e.g. an unknown, switched-off or another template's rule at `/delivery/email/<i>/rule_id`." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render limit reached (`render_limit_reached`) or feature not on plan (`plan_feature_unavailable`, e.g. a `delivery.email` list below the Growth plan)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified; or `region_not_enabled`: the workspace's enabled regions leave out this region." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template or version not found." }, "408": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Sync timeout exceeded and the render was canceled (`timeout_behavior=cancel`)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A request with this Idempotency-Key is still in progress." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template deleted." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Payload or output too large." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render failed (`render_id`, `render_error`; `render_failed` when the worker reports no more specific code), schema mismatch, URL not allowed or idempotency key reused. `einvoice_invalid`, `einvoice_validation_failed`, `pdfa_conversion_failed` and `pdfua_validation_failed` also carry the conformance report as `result`. `email_needs_hosted_file`: `delivery.email` lists rules, but a zero-retention render keeps no file to email. `render_canceled`: the sync render was canceled, or its job expired, before it finished. `scene_invalid`, `data_invalid`: a canvas template's scene can't be rendered (e.g. an output over 16,384 px per side), or its `data` isn't an object or lacks a required dynamic property." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Region degraded (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "PDF from HTML", "tags": [ "Renders" ] } }, "/v1/pdf/from-markdown": { "post": { "description": "Convenience wrapper over `POST /v1/renders` with flat, no-code friendly fields.", "operationId": "create_pdf_from_markdown", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "allow_raw_html": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Allow Raw Html" }, "css": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Css" }, "data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Data" }, "data_url": { "anyOf": [ { "maxLength": 2048, "minLength": 8, "type": "string" }, { "type": "null" } ], "default": null, "title": "Data Url" }, "delivery": { "anyOf": [ { "$ref": "#/components/schemas/DeliverySpec" }, { "enum": [ "url", "binary", "base64", "none" ], "type": "string" } ] }, "einvoice": { "anyOf": [ { "$ref": "#/components/schemas/EInvoiceSpec" }, { "type": "null" } ] }, "engine": { "anyOf": [ { "pattern": "^\\d{4}\\.\\d{1,6}$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Engine" }, "expires_in": { "default": 3600, "maximum": 604800, "minimum": 60, "title": "Expires In", "type": "integer" }, "filename": { "description": "Jinja-enabled filename.", "maxLength": 500, "type": "string" }, "hosted": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Keep the hosted copy; `false` deletes it once the storage uploads and email sends have succeeded. Absent or `null`: `false` when every storage destination of the render has `keep_hosted_copy: false`, else `true`. Zero-retention renders never keep one.", "title": "Hosted" }, "markdown": { "title": "Markdown", "type": "string" }, "metadata": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "propertyNames": { "maxLength": 40, "minLength": 1 }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Metadata" }, "mode": { "default": "sync", "enum": [ "sync", "async" ], "title": "Mode", "type": "string" }, "pdf": { "anyOf": [ { "$ref": "#/components/schemas/PdfOptions" }, { "type": "null" } ] }, "priority": { "default": "normal", "enum": [ "normal", "low" ], "title": "Priority", "type": "string" }, "reference": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Reference" }, "retention_days": { "anyOf": [ { "maximum": 36500, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null, "title": "Retention Days" }, "templating": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Templating" }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Test" }, "theme": { "default": "default", "enum": [ "default", "github", "academic", "minimal", "none" ], "title": "Theme", "type": "string" }, "timeout_behavior": { "default": "continue", "enum": [ "continue", "cancel" ], "title": "Timeout Behavior", "type": "string" }, "webhook": { "anyOf": [ { "$ref": "#/components/schemas/WebhookSpec" }, { "type": "null" } ], "default": null }, "webhook_url": { "format": "uri", "type": "string" } }, "required": [ "markdown" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "Succeeded": { "value": { "batch_id": null, "billed_renders": 1, "completed_at": "2026-09-17T15:06:34Z", "created_at": "2026-09-17T15:06:33Z", "email": [], "engine": "2026.4", "engine_version": "2026.4 (Chrome 153.0.8010.47)", "error": null, "expires_at": "2026-10-17T15:06:34Z", "files": [ { "bytes": 48213, "content_type": "application/pdf", "filename": "invoice-42.pdf", "format": "pdf", "height": null, "id": "file_01J9ZM1X3F7R8K2C4V6B8N0P2R", "pages": 2, "sha256": "9f2c…", "url": "https://files-eu.dynamicdocumentapi.com/f/…", "url_expires_at": "2026-09-17T16:06:34Z", "variant": null, "width": null } ], "id": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "input_type": "template", "kind": "pdf_template", "metadata": { "customer_id": "c_981" }, "mode": "sync", "object": "render", "output_format": "pdf", "pages": 2, "reference": "inv_2026_0042", "region": "eu", "result": null, "source": "api", "status": "succeeded", "storage": [], "template": { "id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "version": 7, "version_id": "tv_01J9ZK3M7Q8V5W2X4Y6Z8A0B1D" }, "test": false, "timings": { "postprocess_ms": 21, "queued_ms": 3, "render_ms": 612, "total_ms": 681, "upload_ms": 38 }, "warnings": [] } } }, "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "Sync render finished (`status=succeeded`). With `delivery.type=binary` the body is the file." }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "Async render accepted, or the sync timeout was exceeded (`Location: /v1/renders/{id}`)." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Malformed or invalid request (`errors[]` with JSON pointers), e.g. an unknown, switched-off or another template's rule at `/delivery/email/<i>/rule_id`." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render limit reached (`render_limit_reached`) or feature not on plan (`plan_feature_unavailable`, e.g. a `delivery.email` list below the Growth plan)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified; or `region_not_enabled`: the workspace's enabled regions leave out this region." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template or version not found." }, "408": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Sync timeout exceeded and the render was canceled (`timeout_behavior=cancel`)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A request with this Idempotency-Key is still in progress." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template deleted." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Payload or output too large." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render failed (`render_id`, `render_error`; `render_failed` when the worker reports no more specific code), schema mismatch, URL not allowed or idempotency key reused. `einvoice_invalid`, `einvoice_validation_failed`, `pdfa_conversion_failed` and `pdfua_validation_failed` also carry the conformance report as `result`. `email_needs_hosted_file`: `delivery.email` lists rules, but a zero-retention render keeps no file to email. `render_canceled`: the sync render was canceled, or its job expired, before it finished. `scene_invalid`, `data_invalid`: a canvas template's scene can't be rendered (e.g. an output over 16,384 px per side), or its `data` isn't an object or lacks a required dynamic property." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Region degraded (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "PDF from Markdown", "tags": [ "Renders" ] } }, "/v1/pdf/from-template": { "post": { "description": "Convenience wrapper over `POST /v1/renders` with flat, no-code friendly fields.", "operationId": "create_pdf_from_template", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Data" }, "data_url": { "anyOf": [ { "maxLength": 2048, "minLength": 8, "type": "string" }, { "type": "null" } ], "default": null, "title": "Data Url" }, "delivery": { "anyOf": [ { "$ref": "#/components/schemas/DeliverySpec" }, { "enum": [ "url", "binary", "base64", "none" ], "type": "string" } ] }, "einvoice": { "anyOf": [ { "$ref": "#/components/schemas/EInvoiceSpec" }, { "type": "null" } ] }, "engine": { "anyOf": [ { "pattern": "^\\d{4}\\.\\d{1,6}$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Engine" }, "expires_in": { "default": 3600, "maximum": 604800, "minimum": 60, "title": "Expires In", "type": "integer" }, "filename": { "description": "Jinja-enabled filename.", "maxLength": 500, "type": "string" }, "hosted": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Keep the hosted copy; `false` deletes it once the storage uploads and email sends have succeeded. Absent or `null`: `false` when every storage destination of the render has `keep_hosted_copy: false`, else `true`. Zero-retention renders never keep one.", "title": "Hosted" }, "metadata": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "propertyNames": { "maxLength": 40, "minLength": 1 }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Metadata" }, "mode": { "default": "sync", "enum": [ "sync", "async" ], "title": "Mode", "type": "string" }, "overrides": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "maxItems": 500, "type": "array" }, { "type": "null" } ], "default": null, "title": "Overrides" }, "pdf": { "anyOf": [ { "$ref": "#/components/schemas/PdfOptions" }, { "type": "null" } ] }, "priority": { "default": "normal", "enum": [ "normal", "low" ], "title": "Priority", "type": "string" }, "reference": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Reference" }, "retention_days": { "anyOf": [ { "maximum": 36500, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null, "title": "Retention Days" }, "template_id": { "maxLength": 64, "minLength": 1, "title": "Template Id", "type": "string" }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Test" }, "timeout_behavior": { "default": "continue", "enum": [ "continue", "cancel" ], "title": "Timeout Behavior", "type": "string" }, "version": { "anyOf": [ { "enum": [ "live", "draft" ], "type": "string" }, { "minimum": 1, "type": "integer" } ], "default": "live", "title": "Version" }, "webhook": { "anyOf": [ { "$ref": "#/components/schemas/WebhookSpec" }, { "type": "null" } ], "default": null }, "webhook_url": { "format": "uri", "type": "string" } }, "required": [ "template_id" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "Succeeded": { "value": { "batch_id": null, "billed_renders": 1, "completed_at": "2026-09-17T15:06:34Z", "created_at": "2026-09-17T15:06:33Z", "email": [], "engine": "2026.4", "engine_version": "2026.4 (Chrome 153.0.8010.47)", "error": null, "expires_at": "2026-10-17T15:06:34Z", "files": [ { "bytes": 48213, "content_type": "application/pdf", "filename": "invoice-42.pdf", "format": "pdf", "height": null, "id": "file_01J9ZM1X3F7R8K2C4V6B8N0P2R", "pages": 2, "sha256": "9f2c…", "url": "https://files-eu.dynamicdocumentapi.com/f/…", "url_expires_at": "2026-09-17T16:06:34Z", "variant": null, "width": null } ], "id": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "input_type": "template", "kind": "pdf_template", "metadata": { "customer_id": "c_981" }, "mode": "sync", "object": "render", "output_format": "pdf", "pages": 2, "reference": "inv_2026_0042", "region": "eu", "result": null, "source": "api", "status": "succeeded", "storage": [], "template": { "id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "version": 7, "version_id": "tv_01J9ZK3M7Q8V5W2X4Y6Z8A0B1D" }, "test": false, "timings": { "postprocess_ms": 21, "queued_ms": 3, "render_ms": 612, "total_ms": 681, "upload_ms": 38 }, "warnings": [] } } }, "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "Sync render finished (`status=succeeded`). With `delivery.type=binary` the body is the file." }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "Async render accepted, or the sync timeout was exceeded (`Location: /v1/renders/{id}`)." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Malformed or invalid request (`errors[]` with JSON pointers), e.g. an unknown, switched-off or another template's rule at `/delivery/email/<i>/rule_id`." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render limit reached (`render_limit_reached`) or feature not on plan (`plan_feature_unavailable`, e.g. a `delivery.email` list below the Growth plan)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified; or `region_not_enabled`: the workspace's enabled regions leave out this region." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template or version not found." }, "408": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Sync timeout exceeded and the render was canceled (`timeout_behavior=cancel`)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A request with this Idempotency-Key is still in progress." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template deleted." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Payload or output too large." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render failed (`render_id`, `render_error`; `render_failed` when the worker reports no more specific code), schema mismatch, URL not allowed or idempotency key reused. `einvoice_invalid`, `einvoice_validation_failed`, `pdfa_conversion_failed` and `pdfua_validation_failed` also carry the conformance report as `result`. `email_needs_hosted_file`: `delivery.email` lists rules, but a zero-retention render keeps no file to email. `render_canceled`: the sync render was canceled, or its job expired, before it finished. `scene_invalid`, `data_invalid`: a canvas template's scene can't be rendered (e.g. an output over 16,384 px per side), or its `data` isn't an object or lacks a required dynamic property." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Region degraded (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "PDF from a template", "tags": [ "Renders" ] } }, "/v1/pdf/from-url": { "post": { "description": "Convenience wrapper over `POST /v1/renders` with flat, no-code friendly fields.", "operationId": "create_pdf_from_url", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Data" }, "data_url": { "anyOf": [ { "maxLength": 2048, "minLength": 8, "type": "string" }, { "type": "null" } ], "default": null, "title": "Data Url" }, "delivery": { "anyOf": [ { "$ref": "#/components/schemas/DeliverySpec" }, { "enum": [ "url", "binary", "base64", "none" ], "type": "string" } ] }, "einvoice": { "anyOf": [ { "$ref": "#/components/schemas/EInvoiceSpec" }, { "type": "null" } ] }, "engine": { "anyOf": [ { "pattern": "^\\d{4}\\.\\d{1,6}$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Engine" }, "expires_in": { "default": 3600, "maximum": 604800, "minimum": 60, "title": "Expires In", "type": "integer" }, "filename": { "description": "Jinja-enabled filename.", "maxLength": 500, "type": "string" }, "hosted": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Keep the hosted copy; `false` deletes it once the storage uploads and email sends have succeeded. Absent or `null`: `false` when every storage destination of the render has `keep_hosted_copy: false`, else `true`. Zero-retention renders never keep one.", "title": "Hosted" }, "http": { "anyOf": [ { "$ref": "#/components/schemas/HttpOptions" }, { "type": "null" } ], "default": null }, "metadata": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "propertyNames": { "maxLength": 40, "minLength": 1 }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Metadata" }, "mode": { "default": "sync", "enum": [ "sync", "async" ], "title": "Mode", "type": "string" }, "pdf": { "anyOf": [ { "$ref": "#/components/schemas/PdfOptions" }, { "type": "null" } ] }, "priority": { "default": "normal", "enum": [ "normal", "low" ], "title": "Priority", "type": "string" }, "reference": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Reference" }, "retention_days": { "anyOf": [ { "maximum": 36500, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null, "title": "Retention Days" }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Test" }, "timeout_behavior": { "default": "continue", "enum": [ "continue", "cancel" ], "title": "Timeout Behavior", "type": "string" }, "url": { "maxLength": 2048, "minLength": 8, "title": "Url", "type": "string" }, "webhook": { "anyOf": [ { "$ref": "#/components/schemas/WebhookSpec" }, { "type": "null" } ], "default": null }, "webhook_url": { "format": "uri", "type": "string" } }, "required": [ "url" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "Succeeded": { "value": { "batch_id": null, "billed_renders": 1, "completed_at": "2026-09-17T15:06:34Z", "created_at": "2026-09-17T15:06:33Z", "email": [], "engine": "2026.4", "engine_version": "2026.4 (Chrome 153.0.8010.47)", "error": null, "expires_at": "2026-10-17T15:06:34Z", "files": [ { "bytes": 48213, "content_type": "application/pdf", "filename": "invoice-42.pdf", "format": "pdf", "height": null, "id": "file_01J9ZM1X3F7R8K2C4V6B8N0P2R", "pages": 2, "sha256": "9f2c…", "url": "https://files-eu.dynamicdocumentapi.com/f/…", "url_expires_at": "2026-09-17T16:06:34Z", "variant": null, "width": null } ], "id": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "input_type": "template", "kind": "pdf_template", "metadata": { "customer_id": "c_981" }, "mode": "sync", "object": "render", "output_format": "pdf", "pages": 2, "reference": "inv_2026_0042", "region": "eu", "result": null, "source": "api", "status": "succeeded", "storage": [], "template": { "id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "version": 7, "version_id": "tv_01J9ZK3M7Q8V5W2X4Y6Z8A0B1D" }, "test": false, "timings": { "postprocess_ms": 21, "queued_ms": 3, "render_ms": 612, "total_ms": 681, "upload_ms": 38 }, "warnings": [] } } }, "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "Sync render finished (`status=succeeded`). With `delivery.type=binary` the body is the file." }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "Async render accepted, or the sync timeout was exceeded (`Location: /v1/renders/{id}`)." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Malformed or invalid request (`errors[]` with JSON pointers), e.g. an unknown, switched-off or another template's rule at `/delivery/email/<i>/rule_id`." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render limit reached (`render_limit_reached`) or feature not on plan (`plan_feature_unavailable`, e.g. a `delivery.email` list below the Growth plan)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified; or `region_not_enabled`: the workspace's enabled regions leave out this region." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template or version not found." }, "408": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Sync timeout exceeded and the render was canceled (`timeout_behavior=cancel`)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A request with this Idempotency-Key is still in progress." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template deleted." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Payload or output too large." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render failed (`render_id`, `render_error`; `render_failed` when the worker reports no more specific code), schema mismatch, URL not allowed or idempotency key reused. `einvoice_invalid`, `einvoice_validation_failed`, `pdfa_conversion_failed` and `pdfua_validation_failed` also carry the conformance report as `result`. `email_needs_hosted_file`: `delivery.email` lists rules, but a zero-retention render keeps no file to email. `render_canceled`: the sync render was canceled, or its job expired, before it finished. `scene_invalid`, `data_invalid`: a canvas template's scene can't be rendered (e.g. an output over 16,384 px per side), or its `data` isn't an object or lacks a required dynamic property." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Region degraded (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "PDF from a URL", "tags": [ "Renders" ] } }, "/v1/previews/html": { "post": { "operationId": "preview_html", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HtmlPreviewRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HtmlPreview" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template syntax/runtime error or fuel exhausted." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Preview engine unavailable." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Live HTML preview (dashboard)", "tags": [ "Previews" ] } }, "/v1/previews/image": { "post": { "operationId": "preview_image", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenderPreviewRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "" }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified; or `region_not_enabled`: the workspace's enabled regions leave out this region." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render failed." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Image preview (dashboard, watermarked, free)", "tags": [ "Previews" ] } }, "/v1/previews/pdf": { "post": { "description": "With `pdf.pdfua` (or `pdf.tagged`) the preview is a tagged PDF with the PDF/UA-1 report in `result.conformance.pdfua`, but it never fails on the report, so the editor can show what to fix.", "operationId": "preview_pdf", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenderPreviewRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "" }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified; or `region_not_enabled`: the workspace's enabled regions leave out this region." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render failed." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "PDF preview (dashboard, watermarked, free)", "tags": [ "Previews" ] } }, "/v1/renders": { "get": { "operationId": "list_renders", "parameters": [ { "in": "query", "name": "batch_id", "schema": { "type": "string" } }, { "in": "query", "name": "created[gte]", "schema": { "format": "date-time", "type": "string" } }, { "in": "query", "name": "created[lte]", "schema": { "format": "date-time", "type": "string" } }, { "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "in": "query", "name": "input_type", "schema": { "enum": [ "einvoice", "html", "markdown", "pdf_tool", "template", "url" ], "type": "string" } }, { "description": "1 to 100 (default 50).", "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "description": "Filter by a metadata key/value.", "in": "query", "name": "metadata[key]", "schema": { "type": "string" } }, { "in": "query", "name": "output_format", "schema": { "enum": [ "html", "jpeg", "pdf", "png", "webp", "xml", "zip" ], "type": "string" } }, { "in": "query", "name": "reference", "schema": { "type": "string" } }, { "in": "query", "name": "source", "schema": { "type": "string" } }, { "description": "Repeat it (or comma-separate the values) to match any of several statuses.", "explode": true, "in": "query", "name": "status", "schema": { "oneOf": [ { "enum": [ "queued", "processing", "succeeded", "failed", "canceled", "expired" ], "type": "string" }, { "items": { "enum": [ "queued", "processing", "succeeded", "failed", "canceled", "expired" ], "type": "string" }, "type": "array" } ] }, "style": "form" }, { "in": "query", "name": "template_id", "schema": { "type": "string" } }, { "in": "query", "name": "test", "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenderList" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "List renders", "tags": [ "Renders" ] }, "post": { "description": "Unified endpoint for template, HTML, URL and Markdown inputs → PDF, images or HTML. `output.pdf.pdfa` makes the PDF PDF/A-2b or -3b; `output.pdf.pdfua` makes it PDF/UA-1 (accessible, Growth plan and up); `output.einvoice` embeds a Factur-X / ZUGFeRD / XRechnung invoice (a hybrid PDF/A-3b, no extra billed render). All are validated (veraPDF, KoSIT); the report is the render's `result`.", "operationId": "create_render", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "AccessiblePDF": { "summary": "Accessible PDF (PDF/UA-1)", "value": { "data": { "customer": "Acme", "number": 42 }, "input": { "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "type": "template", "version": "live" }, "output": { "filename": "invoice-{{ data.number }}.pdf", "format": "pdf", "pdf": { "metadata": { "lang": "en-GB", "title": "Invoice 42" }, "pdfua": "1" } } } }, "HybridE-invoice(XRechnung)": { "summary": "Hybrid e-invoice (XRechnung)", "value": { "data": { "invoice": { "buyer": { "address": { "city": "Bonn", "country": "DE", "line1": "Amtsweg 2", "postcode": "53113" }, "electronic_address": { "id": "04011000-12345-34", "scheme": "0204" }, "name": "Bundesamt für Beispiele" }, "buyer_reference": "04011000-12345-34", "currency": "EUR", "due_date": "2026-10-23", "invoice_period": { "end": "2026-09-30", "start": "2026-09-01" }, "issue_date": "2026-09-23", "lines": [ { "item": { "description": "Wartung Fachverfahren, September 2026", "name": "Softwarewartung" }, "price": { "net": "95.00" }, "quantity": "8", "tax": { "category": "S", "rate": "19" }, "unit": "HUR" }, { "allowances": [ { "amount": "25.00", "reason": "Rabatt" } ], "item": { "name": "Lizenz Modul Statistik" }, "price": { "net": "250.00" }, "quantity": "1", "tax": { "category": "S", "rate": "19" }, "unit": "C62" } ], "number": "XR-2026-0007", "payment": { "credit_transfers": [ { "account_id": "DE02120300000000202051", "account_name": "Größenwahn GmbH" } ], "means_code": "58", "remittance_information": "XR-2026-0007" }, "payment_terms": "Zahlbar innerhalb von 30 Tagen ohne Abzug.", "seller": { "address": { "city": "Berlin", "country": "DE", "line1": "Beispielstraße 1", "postcode": "10115" }, "contact": { "email": "erika.muster@groessenwahn.example", "name": "Erika Muster", "phone": "+49 30 1234567" }, "electronic_address": { "id": "rechnung@groessenwahn.example", "scheme": "EM" }, "legal_registration": { "id": "HRB 12345" }, "name": "Größenwahn GmbH", "tax_number": "30/123/45678", "vat_id": "DE123456789" } } }, "input": { "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "type": "template", "version": "live" }, "output": { "einvoice": { "invoice_path": "invoice", "profile": "XRECHNUNG" }, "filename": "{{ invoice.number }}.pdf", "format": "pdf" } } }, "InvoiceFromATemplate": { "summary": "Invoice from a template", "value": { "data": { "customer": "Acme", "number": 42 }, "delivery": { "expires_in": 3600, "type": "url" }, "input": { "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "type": "template", "version": "live" }, "metadata": { "customer_id": "c_981" }, "mode": "sync", "output": { "filename": "invoice-{{ data.number }}.pdf", "format": "pdf", "pdf": { "paper": { "size": "A4" } } }, "reference": "inv_2026_0042" } } }, "schema": { "$ref": "#/components/schemas/RenderRequest" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "Succeeded": { "value": { "batch_id": null, "billed_renders": 1, "completed_at": "2026-09-17T15:06:34Z", "created_at": "2026-09-17T15:06:33Z", "email": [], "engine": "2026.4", "engine_version": "2026.4 (Chrome 153.0.8010.47)", "error": null, "expires_at": "2026-10-17T15:06:34Z", "files": [ { "bytes": 48213, "content_type": "application/pdf", "filename": "invoice-42.pdf", "format": "pdf", "height": null, "id": "file_01J9ZM1X3F7R8K2C4V6B8N0P2R", "pages": 2, "sha256": "9f2c…", "url": "https://files-eu.dynamicdocumentapi.com/f/…", "url_expires_at": "2026-09-17T16:06:34Z", "variant": null, "width": null } ], "id": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "input_type": "template", "kind": "pdf_template", "metadata": { "customer_id": "c_981" }, "mode": "sync", "object": "render", "output_format": "pdf", "pages": 2, "reference": "inv_2026_0042", "region": "eu", "result": null, "source": "api", "status": "succeeded", "storage": [], "template": { "id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "version": 7, "version_id": "tv_01J9ZK3M7Q8V5W2X4Y6Z8A0B1D" }, "test": false, "timings": { "postprocess_ms": 21, "queued_ms": 3, "render_ms": 612, "total_ms": 681, "upload_ms": 38 }, "warnings": [] } } }, "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "Sync render finished (`status=succeeded`). With `delivery.type=binary` the body is the file." }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "Async render accepted, or the sync timeout was exceeded (`Location: /v1/renders/{id}`)." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Malformed or invalid request (`errors[]` with JSON pointers), e.g. an unknown, switched-off or another template's rule at `/delivery/email/<i>/rule_id`." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render limit reached (`render_limit_reached`) or feature not on plan (`plan_feature_unavailable`, e.g. a `delivery.email` list below the Growth plan)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified; or `region_not_enabled`: the workspace's enabled regions leave out this region." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template or version not found." }, "408": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Sync timeout exceeded and the render was canceled (`timeout_behavior=cancel`)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A request with this Idempotency-Key is still in progress." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template deleted." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Payload or output too large." }, "422": { "content": { "application/json": { "examples": { "AccessibilityCheckFailed": { "summary": "PDF/UA validation failed", "value": { "code": "pdfua_validation_failed", "detail": "The PDF fails 1 PDF/UA-1 rule (7.3-1): images need alternative text.", "doc_url": "https://docs.dynamicdocumentapi.com/errors/pdfua_validation_failed", "render_error": { "code": "pdfua_validation_failed", "message": "The PDF fails 1 PDF/UA-1 rule (7.3-1): images need alternative text." }, "render_id": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "request_id": "req_01J9ZM1X3F7R8K2C4V6B8N0P2S", "result": { "conformance": { "pdfua": { "errors": [ { "count": 2, "location": "root/document[0]/StructTreeRoot[0]/K[0]/K[3](SEFigure Figure)", "message": "Figure tags shall include an alternative representation or replacement text.", "rule": "7.3-1" } ], "profile": "PDF/UA-1 validation profile", "standard": "PDF/UA-1", "status": "failed", "validator": "veraPDF 1.30.2", "warnings": [] } } }, "status": 422, "title": "PDF/UA validation failed", "type": "https://docs.dynamicdocumentapi.com/errors/pdfua_validation_failed" } } }, "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render failed (`render_id`, `render_error`; `render_failed` when the worker reports no more specific code), schema mismatch, URL not allowed or idempotency key reused. `einvoice_invalid`, `einvoice_validation_failed`, `pdfa_conversion_failed` and `pdfua_validation_failed` also carry the conformance report as `result`. `email_needs_hosted_file`: `delivery.email` lists rules, but a zero-retention render keeps no file to email. `render_canceled`: the sync render was canceled, or its job expired, before it finished. `scene_invalid`, `data_invalid`: a canvas template's scene can't be rendered (e.g. an output over 16,384 px per side), or its `data` isn't an object or lacks a required dynamic property." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Region degraded (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Create a render", "tags": [ "Renders" ] } }, "/v1/renders/{render_id}": { "get": { "description": "Fresh signed file URLs are issued on every retrieve while files are hosted.", "operationId": "get_render", "parameters": [ { "in": "path", "name": "render_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Retrieve a render", "tags": [ "Renders" ] } }, "/v1/renders/{render_id}/cancel": { "post": { "description": "Best effort: queued renders are canceled immediately; processing renders finish.", "operationId": "cancel_render", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } }, { "in": "path", "name": "render_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render not found." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "`conflict`: the render already finished." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Cancel a render", "tags": [ "Renders" ] } }, "/v1/renders/{render_id}/files": { "delete": { "description": "Deletes hosted copies now; the render becomes `expired`. BYOS copies are untouched. For a zero-retention render it deletes the transient copies its storage uploads read (uploads still pending then fail), and the status stays.", "operationId": "delete_render_files", "parameters": [ { "in": "path", "name": "render_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Render" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render not found." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "`conflict`: the render is still running; cancel it first." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Purge stored files", "tags": [ "Renders" ] } }, "/v1/renders/{render_id}/files/{file_id}": { "get": { "operationId": "get_render_file", "parameters": [ { "description": "Attachment disposition.", "in": "query", "name": "download", "schema": { "type": "boolean" } }, { "in": "path", "name": "file_id", "required": true, "schema": { "type": "string" } }, { "description": "Stream through the API instead of 302.", "in": "query", "name": "inline", "schema": { "type": "boolean" } }, { "in": "path", "name": "render_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/octet-stream": { "schema": { "format": "binary", "type": "string" } } }, "description": "File (`?inline=true`)." }, "302": { "description": "Redirect to a signed URL." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Render or file not found. Every file of a zero-retention render answers 404: its copies for storage destinations can't be opened." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "File expired or deleted." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Download a render file", "tags": [ "Renders" ] } }, "/v1/renders/{render_id}/logs": { "get": { "operationId": "get_render_logs", "parameters": [ { "in": "path", "name": "render_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenderLog" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Logging disabled or log expired." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Request/response log", "tags": [ "Renders" ] } }, "/v1/signed-links": { "get": { "description": "Image links that render a template straight from a URL. Secrets are never returned by a read.", "operationId": "list_signed_links", "responses": { "200": { "content": { "application/json": { "examples": { "OneItem": { "summary": "One item", "value": { "data": [ { "access": "signed", "allowed_params": [ "title.text", "hero.src" ], "allowed_referrers": null, "base_url": "https://img.dynamicdocumentapi.com/l/lnk_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "cache_ttl_seconds": null, "created_at": "2026-09-17T15:06:33Z", "defaults": { "title.text": "Summer Sale" }, "enabled": true, "expires_at": null, "formats": [ "png", "jpeg" ], "id": "lnk_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "name": "Summer campaign banners", "object": "signed_link", "param_limits": { "title.text": { "max_length": 80 } }, "quota_total": null, "quota_used": 0, "rate_limit_per_ip_per_hour": null, "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C" } ], "has_more": false, "next_cursor": null, "object": "list" } } }, "schema": { "$ref": "#/components/schemas/SignedLinkList" } } }, "description": "Every object in the workspace (a single page today)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "List signed links", "tags": [ "Signed links" ] }, "post": { "description": "Returns `base_url` and the HMAC `secret` **once**; SDKs sign URLs locally with it (docs/05 §7). Use `access: \"open\"` for tools that cannot compute an HMAC.", "operationId": "create_signed_link", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "CampaignBanners": { "summary": "Campaign banners", "value": { "access": "signed", "allowed_params": [ "title.text", "hero.src" ], "defaults": { "title.text": "Summer Sale" }, "formats": [ "png", "jpeg" ], "name": "Summer campaign banners", "param_limits": { "title.text": { "max_length": 80 } }, "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C" } } }, "schema": { "$ref": "#/components/schemas/SignedLinkWrite" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "Created": { "value": { "access": "signed", "allowed_params": [ "title.text", "hero.src" ], "allowed_referrers": null, "base_url": "https://img.dynamicdocumentapi.com/l/lnk_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "cache_ttl_seconds": null, "created_at": "2026-09-17T15:06:33Z", "defaults": { "title.text": "Summer Sale" }, "enabled": true, "expires_at": null, "formats": [ "png", "jpeg" ], "id": "lnk_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "name": "Summer campaign banners", "object": "signed_link", "param_limits": { "title.text": { "max_length": 80 } }, "quota_total": null, "quota_used": 0, "rate_limit_per_ip_per_hour": null, "secret": "qUuQz3s4Xg0sy5EmqHgy0yvHwJA9mhHP0fW6cTzx7mI", "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C" } } }, "schema": { "$ref": "#/components/schemas/SignedLinkWithSecret" } } }, "description": "Created; `secret` is shown once." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Invalid request body (`errors[]` with JSON pointers)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Create a signed link", "tags": [ "Signed links" ] } }, "/v1/signed-links/{link_id}": { "delete": { "description": "Existing URLs stop working immediately (cached CDN copies expire on their own).", "operationId": "delete_signed_link", "parameters": [ { "description": "Signed link id (`lnk_…`).", "in": "path", "name": "link_id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Signed link not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Delete a signed link", "tags": [ "Signed links" ] }, "get": { "description": "Common base: API key or OAuth only, never a dashboard region token.", "operationId": "get_signed_link", "parameters": [ { "description": "Signed link id (`lnk_…`).", "in": "path", "name": "link_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "Link": { "value": { "access": "signed", "allowed_params": [ "title.text", "hero.src" ], "allowed_referrers": null, "base_url": "https://img.dynamicdocumentapi.com/l/lnk_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "cache_ttl_seconds": null, "created_at": "2026-09-17T15:06:33Z", "defaults": { "title.text": "Summer Sale" }, "enabled": true, "expires_at": null, "formats": [ "png", "jpeg" ], "id": "lnk_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "name": "Summer campaign banners", "object": "signed_link", "param_limits": { "title.text": { "max_length": 80 } }, "quota_total": null, "quota_used": 0, "rate_limit_per_ip_per_hour": null, "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C" } } }, "schema": { "$ref": "#/components/schemas/SignedLink" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Signed link not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Retrieve a signed link", "tags": [ "Signed links" ] }, "patch": { "description": "Partial update. `template_id` is immutable and the secret is unchanged.", "operationId": "update_signed_link", "parameters": [ { "description": "Signed link id (`lnk_…`).", "in": "path", "name": "link_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "CapTheTraffic": { "summary": "Cap the traffic", "value": { "rate_limit_per_ip_per_hour": 120 } }, "DisableTheLink": { "summary": "Disable the link", "value": { "enabled": false } } }, "schema": { "$ref": "#/components/schemas/PatchedSignedLinkWrite" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "Updated": { "value": { "access": "signed", "allowed_params": [ "title.text", "hero.src" ], "allowed_referrers": null, "base_url": "https://img.dynamicdocumentapi.com/l/lnk_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "cache_ttl_seconds": null, "created_at": "2026-09-17T15:06:33Z", "defaults": { "title.text": "Summer Sale" }, "enabled": false, "expires_at": null, "formats": [ "png", "jpeg" ], "id": "lnk_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "name": "Summer campaign banners", "object": "signed_link", "param_limits": { "title.text": { "max_length": 80 } }, "quota_total": null, "quota_used": 0, "rate_limit_per_ip_per_hour": null, "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C" } } }, "schema": { "$ref": "#/components/schemas/SignedLink" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Invalid request body (`errors[]` with JSON pointers)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Signed link not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Update a signed link", "tags": [ "Signed links" ] } }, "/v1/signed-links/{link_id}/sign": { "post": { "description": "Convenience for languages without an SDK: signs `params` with the link secret. Signing locally avoids the round trip (docs/05 §7).", "operationId": "sign_link_url", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } }, { "description": "Signed link id (`lnk_…`).", "in": "path", "name": "link_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "OneBanner": { "summary": "One banner", "value": { "format": "png", "name": "banner", "params": { "title.text": "Summer Sale" } } } }, "schema": { "$ref": "#/components/schemas/SignUrl" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "Signed": { "value": { "object": "signed_url", "url": "https://img.dynamicdocumentapi.com/l/lnk_01J9ZM1X3F7R8K2C4V6B8N0P2Q/banner.png?title.text=Summer%20Sale&exp=1789661194&sig=BsM0_V6iRJeeRIjIhywJ3zFHrW6j0plh" } } }, "schema": { "$ref": "#/components/schemas/SignedUrl" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Invalid request body (`errors[]` with JSON pointers)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Signed link not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Sign a link URL", "tags": [ "Signed links" ] } }, "/v1/storage-destinations": { "get": { "description": "Your own buckets that renders can be uploaded to. Credentials are never returned.", "operationId": "list_storage_destinations", "responses": { "200": { "content": { "application/json": { "examples": { "OneItem": { "summary": "One item", "value": { "data": [ { "config": { "bucket": "acme-docs", "prefix": "dynamic-document-api/", "region": "eu-central-1", "storage_class": "STANDARD_IA" }, "created_at": "2026-09-17T15:06:33Z", "credentials": { "configured": true }, "id": "dst_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "is_default": true, "keep_hosted_copy": false, "last_test": { "at": "2026-09-17T15:06:33Z", "error": null, "status": "succeeded" }, "name": "Acme S3", "object": "storage_destination", "path_template": "{{ render.template_id }}/{{ render.id }}.{{ file.ext }}", "provider": "s3", "updated_at": "2026-09-17T15:06:33Z" } ], "has_more": false, "next_cursor": null, "object": "list" } } }, "schema": { "$ref": "#/components/schemas/StorageDestinationList" } } }, "description": "Every object in the workspace (a single page today)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "List storage destinations", "tags": [ "Storage" ] }, "post": { "description": "`credentials` are encrypted at rest and never returned; reads answer `{\"configured\": true}`. Reference the destination from `delivery.storage[]` on a render. On Amazon S3, `config.storage_class` sets the class of every uploaded object and of the connection test's probe: `STANDARD`, `STANDARD_IA`, `ONEZONE_IA`, `INTELLIGENT_TIERING` or `GLACIER_IR`; leave it out for the bucket's default. Archive classes (`GLACIER`, `DEEP_ARCHIVE`) and classes on other providers answer `400`. `config.force_path_style` (S3 and S3-compatible) puts the bucket in the path (`true`, `<endpoint>/<bucket>/<key>`) or in the host name (`false`, `<bucket>.<endpoint host>`); left out, it is `false` for Amazon S3 and `true` for S3-compatible services. Bucket names with dots, underscores or capitals and IP-address endpoints always use the path. Uploaded objects get the file's content type.", "operationId": "create_storage_destination", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "S3-compatible(R2)": { "summary": "S3-compatible (R2)", "value": { "config": { "bucket": "docs", "endpoint": "https://account.eu.r2.cloudflarestorage.com", "force_path_style": true, "region": "auto" }, "credentials": { "access_key_id": "…", "secret_access_key": "…" }, "name": "R2 EU", "provider": "s3_compatible" } }, "S3WithAccessKeys": { "summary": "S3 with access keys", "value": { "config": { "bucket": "acme-docs", "prefix": "dynamic-document-api/", "region": "eu-central-1", "storage_class": "STANDARD_IA" }, "credentials": { "access_key_id": "…", "secret_access_key": "…" }, "is_default": true, "keep_hosted_copy": false, "name": "Acme S3", "path_template": "{{ render.template_id }}/{{ render.created_at | format_date('%Y/%m') }}/{{ render.id }}.{{ file.ext }}", "provider": "s3" } }, "SFTPWithAKey": { "description": "`host_key` pins the server: the SHA-256 fingerprint of its Ed25519 key (else ECDSA, else RSA), e.g. from `ssh-keyscan -t ed25519 sftp.acme.com | ssh-keygen -lf -`.", "summary": "SFTP with a key", "value": { "config": { "host": "sftp.acme.com", "host_key": "SHA256:e2uuyLCsFPfkWbJjOEXNLQO/3MSsf1kJQ/7eLsf3BEM", "port": 22, "prefix": "/incoming/invoices", "username": "renders" }, "credentials": { "passphrase": "…", "private_key": "-----BEGIN OPENSSH PRIVATE KEY-----\n…" }, "name": "Invoices server", "provider": "sftp" } } }, "schema": { "$ref": "#/components/schemas/StorageDestinationWrite" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "Created": { "value": { "config": { "bucket": "acme-docs", "prefix": "dynamic-document-api/", "region": "eu-central-1", "storage_class": "STANDARD_IA" }, "created_at": "2026-09-17T15:06:33Z", "credentials": { "configured": true }, "id": "dst_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "is_default": true, "keep_hosted_copy": false, "last_test": { "at": null, "error": null, "status": null }, "name": "Acme S3", "object": "storage_destination", "path_template": "{{ render.template_id }}/{{ render.id }}.{{ file.ext }}", "provider": "s3", "updated_at": "2026-09-17T15:06:33Z" } } }, "schema": { "$ref": "#/components/schemas/StorageDestination" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Invalid request body (`errors[]` with JSON pointers)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Create a storage destination", "tags": [ "Storage" ] } }, "/v1/storage-destinations/{destination_id}": { "delete": { "description": "Files already uploaded to your bucket are untouched. Uploads that haven't succeeded yet stop: each fails at its next attempt, without connecting, with `storage.upload_failed`.", "operationId": "delete_storage_destination", "parameters": [ { "description": "Storage destination id (`dst_…`).", "in": "path", "name": "destination_id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Storage destination not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Delete a storage destination", "tags": [ "Storage" ] }, "get": { "description": "Common base: API key or OAuth only, never a dashboard region token.", "operationId": "get_storage_destination", "parameters": [ { "description": "Storage destination id (`dst_…`).", "in": "path", "name": "destination_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "Destination": { "value": { "config": { "bucket": "acme-docs", "prefix": "dynamic-document-api/", "region": "eu-central-1", "storage_class": "STANDARD_IA" }, "created_at": "2026-09-17T15:06:33Z", "credentials": { "configured": true }, "id": "dst_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "is_default": true, "keep_hosted_copy": false, "last_test": { "at": "2026-09-17T15:06:33Z", "error": null, "status": "succeeded" }, "name": "Acme S3", "object": "storage_destination", "path_template": "{{ render.template_id }}/{{ render.id }}.{{ file.ext }}", "provider": "s3", "updated_at": "2026-09-17T15:06:33Z" } } }, "schema": { "$ref": "#/components/schemas/StorageDestination" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Storage destination not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Retrieve a storage destination", "tags": [ "Storage" ] }, "patch": { "description": "Partial update. `provider` is immutable — create a new destination to change it.", "operationId": "update_storage_destination", "parameters": [ { "description": "Storage destination id (`dst_…`).", "in": "path", "name": "destination_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "KeepHostedCopies": { "summary": "Keep hosted copies", "value": { "keep_hosted_copy": true } }, "RotateCredentials": { "summary": "Rotate credentials", "value": { "credentials": { "access_key_id": "…", "secret_access_key": "…" } } } }, "schema": { "$ref": "#/components/schemas/PatchedStorageDestinationWrite" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "Updated": { "value": { "config": { "bucket": "acme-docs", "prefix": "dynamic-document-api/", "region": "eu-central-1", "storage_class": "STANDARD_IA" }, "created_at": "2026-09-17T15:06:33Z", "credentials": { "configured": true }, "id": "dst_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "is_default": false, "keep_hosted_copy": false, "last_test": { "at": "2026-09-17T15:06:33Z", "error": null, "status": "succeeded" }, "name": "Acme S3", "object": "storage_destination", "path_template": "{{ render.template_id }}/{{ render.id }}.{{ file.ext }}", "provider": "s3", "updated_at": "2026-09-17T15:06:33Z" } } }, "schema": { "$ref": "#/components/schemas/StorageDestination" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Invalid request body (`errors[]` with JSON pointers)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Storage destination not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Update a storage destination", "tags": [ "Storage" ] } }, "/v1/storage-destinations/{destination_id}/test": { "post": { "description": "Writes, reads back and deletes a small probe object from the region that owns the workspace. `200` with `ok: false` means the credentials or the bucket policy are wrong — `steps[]` says which check failed. The result is also stored as `last_test`.", "operationId": "test_storage_destination", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } }, { "description": "Storage destination id (`dst_…`).", "in": "path", "name": "destination_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "RejectedByTheBucket": { "summary": "Rejected by the bucket", "value": { "destination": { "config": { "bucket": "acme-docs", "prefix": "dynamic-document-api/", "region": "eu-central-1", "storage_class": "STANDARD_IA" }, "created_at": "2026-09-17T15:06:33Z", "credentials": { "configured": true }, "id": "dst_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "is_default": true, "keep_hosted_copy": false, "last_test": { "at": "2026-09-17T15:06:33Z", "error": "AccessDenied", "status": "failed" }, "name": "Acme S3", "object": "storage_destination", "path_template": "{{ render.template_id }}/{{ render.id }}.{{ file.ext }}", "provider": "s3", "updated_at": "2026-09-17T15:06:33Z" }, "object": "storage_test", "ok": false, "steps": [ { "detail": "AccessDenied", "name": "write", "ok": false } ] } }, "SFTPServerWithAnotherKey": { "summary": "SFTP server with another key", "value": { "destination": { "config": { "host": "sftp.acme.com", "host_key": "SHA256:e2uuyLCsFPfkWbJjOEXNLQO/3MSsf1kJQ/7eLsf3BEM", "port": 22, "prefix": "/incoming/invoices", "username": "renders" }, "created_at": "2026-09-17T15:06:33Z", "credentials": { "configured": true }, "id": "dst_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "is_default": true, "keep_hosted_copy": false, "last_test": { "at": "2026-09-17T15:06:33Z", "error": null, "status": "succeeded" }, "name": "Acme S3", "object": "storage_destination", "path_template": "{{ render.template_id }}/{{ render.id }}.{{ file.ext }}", "provider": "sftp", "updated_at": "2026-09-17T15:06:33Z" }, "host_key": "SHA256:JtdbIoON4RIWKDK1VdyGufcuk6PmTcXOdUusf5ZbbJw", "object": "storage_test", "ok": false, "steps": [ { "detail": "sftp.acme.com:22", "name": "connect", "ok": true }, { "detail": "The server's host key is SHA256:JtdbIoON4RIWKDK1VdyGufcuk6PmTcXOdUusf5ZbbJw, not the trusted SHA256:e2uuyLCsFPfkWbJjOEXNLQO/3MSsf1kJQ/7eLsf3BEM.", "name": "host_key", "ok": false } ] } }, "Succeeded": { "value": { "destination": { "config": { "bucket": "acme-docs", "prefix": "dynamic-document-api/", "region": "eu-central-1", "storage_class": "STANDARD_IA" }, "created_at": "2026-09-17T15:06:33Z", "credentials": { "configured": true }, "id": "dst_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "is_default": true, "keep_hosted_copy": false, "last_test": { "at": "2026-09-17T15:06:33Z", "error": null, "status": "succeeded" }, "name": "Acme S3", "object": "storage_destination", "path_template": "{{ render.template_id }}/{{ render.id }}.{{ file.ext }}", "provider": "s3", "updated_at": "2026-09-17T15:06:33Z" }, "object": "storage_test", "ok": true, "steps": [ { "detail": null, "name": "write", "ok": true }, { "detail": null, "name": "read", "ok": true }, { "detail": null, "name": "delete", "ok": true } ] } } }, "schema": { "$ref": "#/components/schemas/StorageTest" } } }, "description": "The probe ran; check `ok`." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Invalid request body (`errors[]` with JSON pointers)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Storage destination not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Test a storage destination", "tags": [ "Storage" ] } }, "/v1/templates": { "get": { "operationId": "list_templates", "parameters": [ { "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "in": "query", "name": "q", "schema": { "type": "string" } }, { "in": "query", "name": "type", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateList" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "List templates", "tags": [ "Templates" ] }, "post": { "description": "Creates a `pdf_code`, `pdf_markdown` or `image_canvas` template. The content fields depend on `type` (any type may send one `content` object instead); they land in the draft — publish it to get a live version (docs/05 §6).", "operationId": "create_template", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "CanvasBanner": { "summary": "Canvas banner", "value": { "name": "Launch banner", "options": { "output_format": "png" }, "scene": { "artboard": { "height": 630, "width": 1200 }, "elements": { "title": { "bindings": { "text": { "maxLength": 60 } }, "height": 150, "id": "title", "name": "title", "runs": [ { "text": "Launch day" } ], "style": { "color": "#0f172a", "fontSize": 72 }, "type": "text", "width": 1040, "x": 80, "y": 240 } }, "rootIds": [ "title" ], "schemaVersion": 1 }, "type": "image_canvas" } }, "HTMLInvoice": { "summary": "HTML invoice", "value": { "head": "<style>h1{font-family:Inter}</style>", "html": "<h1>Invoice {{ number }}</h1>", "name": "Invoice", "options": { "output_format": "pdf", "pdf": { "paper": { "size": "A4" } } }, "type": "pdf_code" } }, "MarkdownReleaseNotes": { "summary": "Markdown release notes", "value": { "markdown": "# Release {{ version }}\n\n{{ notes }}", "name": "Release notes", "options": { "output_format": "pdf" }, "theme": "github", "type": "pdf_markdown" } } }, "schema": { "$ref": "#/components/schemas/TemplateCreateRequest" } } } }, "responses": { "201": { "content": { "application/json": { "examples": { "Created": { "value": { "created_at": "2026-09-01T09:12:00Z", "default_options": null, "deleted_at": null, "description": "", "draft_revision": 1, "engine": "2026.4", "folder": null, "id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "live_version": null, "name": "Invoice", "object": "template", "tags": [], "thumbnail_url": null, "type": "pdf_code", "updated_at": "2026-09-17T15:06:33Z" } } }, "schema": { "$ref": "#/components/schemas/ManagedTemplate" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Invalid request body (`errors[]` with JSON pointers)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified; or `template_not_allowed_for_key`: the key is restricted to specific templates." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Create a template", "tags": [ "Templates" ] } }, "/v1/templates/{template_id}": { "delete": { "description": "Soft delete: the template moves to the trash and is purged after 30 days. Renders that reference it keep working until then; new renders answer `410 template_deleted`.", "operationId": "delete_template", "parameters": [ { "description": "Template id (`tpl_…`).", "in": "path", "name": "template_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "Deleted": { "value": { "deleted": true, "deleted_at": "2026-09-17T15:06:33Z", "id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "object": "template" } } }, "schema": { "$ref": "#/components/schemas/TemplateDeleted" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Invalid request body (`errors[]` with JSON pointers)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template not found." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template already deleted." }, "423": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The template is locked (`template_locked`); Owners and Admins unlock it in the dashboard." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Delete a template", "tags": [ "Templates" ] }, "get": { "operationId": "get_template", "parameters": [ { "in": "path", "name": "template_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template not found." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template deleted." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Retrieve a template", "tags": [ "Templates" ] } }, "/v1/templates/{template_id}/draft": { "put": { "description": "Replaces the draft with the content fields of the template's type (see `POST /v1/templates`) or one `content` object. Send `If-Match: <revision>` (the `revision` of the draft you edited) to detect concurrent edits; a stale revision answers `409 draft_revision_conflict`. The response carries the new revision in `ETag`. `image_canvas` drafts are compiled when published — and by `version: draft` renders, which answer `422` with JSON pointers under `/template/draft` when the draft does not compile.", "operationId": "update_template_draft", "parameters": [ { "description": "Draft revision you based the edit on.", "in": "header", "name": "If-Match", "schema": { "type": "string" } }, { "description": "Template id (`tpl_…`).", "in": "path", "name": "template_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "CanvasDraft": { "summary": "Canvas draft", "value": { "options": { "output_format": "png" }, "scene": { "artboard": { "height": 630, "width": 1200 }, "elements": { "title": { "bindings": { "text": { "maxLength": 60 } }, "height": 150, "id": "title", "name": "title", "runs": [ { "text": "Launch day" } ], "style": { "color": "#0f172a", "fontSize": 72 }, "type": "text", "width": 1040, "x": 80, "y": 240 } }, "rootIds": [ "title" ], "schemaVersion": 1 } } }, "HTMLDraft": { "summary": "HTML draft", "value": { "head": "<style>h1{font-family:Inter}</style>", "html": "<h1>Invoice {{ number }}</h1>", "options": { "output_format": "pdf", "pdf": { "paper": { "size": "A4" } } } } }, "MarkdownDraft": { "summary": "Markdown draft", "value": { "markdown": "# Release {{ version }}\n\n{{ notes }}", "options": { "output_format": "pdf" }, "theme": "github" } } }, "schema": { "$ref": "#/components/schemas/TemplateDraftWriteRequest" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "Saved": { "value": { "content": { "head": "", "html": "<h1>Invoice {{ number }}</h1>", "options": { "output_format": "pdf" } }, "object": "template_draft", "revision": 13, "schema": null, "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "updated_at": "2026-09-17T15:06:33Z" } } }, "schema": { "$ref": "#/components/schemas/TemplateDraft" } } }, "description": "Saved. `ETag` holds the new revision." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Invalid request body (`errors[]` with JSON pointers)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template not found." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The draft changed since the revision in `If-Match` (`draft_revision_conflict`)." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template deleted." }, "423": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The template is locked (`template_locked`); Owners and Admins unlock it in the dashboard." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Replace the draft sources", "tags": [ "Templates" ] } }, "/v1/templates/{template_id}/email-rules": { "get": { "description": "0 to 5 rules in `position` order. Rules are live configuration, not versioned with the template: an edit applies to renders submitted afterwards.", "operationId": "list_email_rules", "parameters": [ { "description": "Template id (`tpl_…`).", "in": "path", "name": "template_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "OneRule": { "summary": "One rule", "value": { "data": [ { "attach_formats": [ "pdf" ], "attachments": "attach_or_link", "bcc": "", "cc": "{{ data.customer.accounting_email }}", "condition": "data.send_invoice", "connection_id": "emc_01J9ZK3M7Q8V5W2X4Y6Z8A0B1F", "created_at": "2026-09-30T09:20:00Z", "enabled": true, "from_email": "billing@acme.example", "from_name": "Acme Billing", "html": "<p>Dear {{ data.customer.name }},</p><p>please find invoice {{ render.invoice.number }} attached.</p>", "id": "emr_01J9ZK3M7Q8V5W2X4Y6Z8A0B1E", "name": "Invoice to customer", "object": "email_rule", "position": 0, "provider_template": null, "reply_to": "", "subject": "Invoice {{ render.invoice.number }}", "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "text": "", "to": "{{ data.customer.name }} <{{ data.customer.email }}>", "updated_at": "2026-09-30T09:20:00Z" } ], "has_more": false, "next_cursor": null, "object": "list" } } }, "schema": { "$ref": "#/components/schemas/EmailRuleList" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "List a template's email rules", "tags": [ "Email" ] }, "post": { "description": "`from_name`, `reply_to`, `to`, `cc`, `bcc`, `subject`, `html` and `text` use the template language with the document's context (data keys, `data`, `render` including `render.invoice`) plus `files` and `download_links`; `condition` is an expression. Every field must compile, else `422 email_template_error` with `errors[].path`, line and column. A `from_email` the provider hasn't verified is saved with the warning `email_sender_unverified`.", "operationId": "create_email_rule", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } }, { "description": "Template id (`tpl_…`).", "in": "path", "name": "template_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "InvoiceToCustomer": { "summary": "Invoice to customer", "value": { "attach_formats": [ "pdf" ], "attachments": "attach_or_link", "cc": "{{ data.customer.accounting_email }}", "condition": "data.send_invoice", "connection_id": "emc_01J9ZK3M7Q8V5W2X4Y6Z8A0B1F", "enabled": true, "from_email": "billing@acme.example", "from_name": "Acme Billing", "html": "<p>Dear {{ data.customer.name }},</p><p>please find invoice {{ render.invoice.number }} attached.</p>", "name": "Invoice to customer", "subject": "Invoice {{ render.invoice.number }}", "to": "{{ data.customer.name }} <{{ data.customer.email }}>" } } }, "schema": { "$ref": "#/components/schemas/EmailRuleWrite" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "Created": { "value": { "attach_formats": [ "pdf" ], "attachments": "attach_or_link", "bcc": "", "cc": "{{ data.customer.accounting_email }}", "condition": "data.send_invoice", "connection_id": "emc_01J9ZK3M7Q8V5W2X4Y6Z8A0B1F", "created_at": "2026-09-30T09:20:00Z", "enabled": true, "from_email": "billing@acme.example", "from_name": "Acme Billing", "html": "<p>Dear {{ data.customer.name }},</p><p>please find invoice {{ render.invoice.number }} attached.</p>", "id": "emr_01J9ZK3M7Q8V5W2X4Y6Z8A0B1E", "name": "Invoice to customer", "object": "email_rule", "position": 0, "provider_template": null, "reply_to": "", "subject": "Invoice {{ render.invoice.number }}", "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "text": "", "to": "{{ data.customer.name }} <{{ data.customer.email }}>", "updated_at": "2026-09-30T09:20:00Z", "warnings": [] } } }, "schema": { "$ref": "#/components/schemas/EmailRule" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Invalid request body (`errors[]` with JSON pointers)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Email delivery needs the Growth plan or higher (`plan_feature_unavailable`)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified; or `feature_not_enabled`: email delivery isn't enabled for this workspace yet." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template or connection not found." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A field does not compile (`email_template_error`)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Create an email rule", "tags": [ "Email" ] } }, "/v1/templates/{template_id}/publish": { "post": { "description": "Validates the draft (compile, options, syntax, datasets) and publishes a new live version. `201` when the run finished, `202` when validation is still running, `422` when a step failed — the problem details then carry the run in `publish_run`.", "operationId": "publish_template", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } }, { "description": "Template id (`tpl_…`).", "in": "path", "name": "template_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "WithANote": { "summary": "With a note", "value": { "note": "Add VAT column" } } }, "schema": { "$ref": "#/components/schemas/TemplatePublish" } } } }, "responses": { "201": { "content": { "application/json": { "examples": { "PublishedVersion7": { "summary": "Published version 7", "value": { "created_at": "2026-09-17T15:06:33Z", "draft_revision": 13, "error": null, "errors": [], "finished_at": "2026-09-17T15:06:34Z", "id": "pub_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "note": "Add VAT column", "object": "publish_run", "status": "succeeded", "steps": [ { "duration_ms": 1, "errors": [], "name": "compile", "status": "succeeded", "warnings": [] } ], "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "version": { "content_hash": "d907757…", "id": "tv_01J9ZK3M7Q8V5W2X4Y6Z8A0B1D", "note": "Add VAT column", "number": 7, "published_at": "2026-09-17T15:06:33Z" }, "warnings": [] } } }, "schema": { "$ref": "#/components/schemas/PublishRun" } } }, "description": "Published." }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishRun" } } }, "description": "Validation is still running." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Invalid request body (`errors[]` with JSON pointers)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template not found." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template deleted." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Validation failed; `publish_run` holds the failing steps." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Publish the draft", "tags": [ "Templates" ] } }, "/v1/templates/{template_id}/rollback": { "post": { "description": "Points `live_version` at an existing version. Nothing is re-rendered and no new version is created.", "operationId": "rollback_template", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } }, { "description": "Template id (`tpl_…`).", "in": "path", "name": "template_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "ById": { "summary": "By id", "value": { "version": "tv_01J9ZK3M7Q8V5W2X4Y6Z8A0B1D" } }, "ByNumber": { "summary": "By number", "value": { "version": 6 } } }, "schema": { "$ref": "#/components/schemas/TemplateRollback" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "RolledBack": { "summary": "Rolled back", "value": { "created_at": "2026-09-01T09:12:00Z", "default_options": { "output_format": "pdf", "pdf": { "paper": { "size": "A4" } } }, "deleted_at": null, "description": "", "draft_revision": 12, "engine": "2026.4", "folder": null, "id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C", "live_version": { "id": "tv_01J9ZK3M7Q8V5W2X4Y6Z8A0B1D", "note": "Add VAT column", "number": 7, "published_at": "2026-09-17T15:06:33Z" }, "name": "Invoice", "object": "template", "tags": [], "thumbnail_url": null, "type": "pdf_code", "updated_at": "2026-09-17T15:06:33Z" } } }, "schema": { "$ref": "#/components/schemas/ManagedTemplate" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Invalid request body (`errors[]` with JSON pointers)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template or version not found." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template deleted." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Roll back to a version", "tags": [ "Templates" ] } }, "/v1/templates/{template_id}/schema": { "get": { "operationId": "get_template_schema", "parameters": [ { "in": "path", "name": "template_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateSchema" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Template not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Data schema of a template", "tags": [ "Templates" ] } }, "/v1/templates/{template_id}/versions": { "get": { "operationId": "list_template_versions", "parameters": [ { "in": "path", "name": "template_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateVersionList" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "List template versions", "tags": [ "Templates" ] } }, "/v1/templates/{template_id}/versions/{number}": { "get": { "operationId": "get_template_version", "parameters": [ { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "template_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateVersion" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Version not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Retrieve a template version", "tags": [ "Templates" ] } }, "/v1/uploads": { "post": { "operationId": "create_upload", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "file": { "format": "binary", "type": "string" } }, "required": [ "file" ], "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upload" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "File too large." }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Unsupported file type." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Upload a file (≤ 50 MB, kept 24 h)", "tags": [ "Uploads" ] } }, "/v1/usage": { "get": { "operationId": "get_usage", "parameters": [ { "description": "`YYYY-MM-DD` or ISO-8601; default: cycle start.", "in": "query", "name": "from", "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "granularity", "schema": { "enum": [ "day", "hour" ], "type": "string" } }, { "in": "query", "name": "group_by", "schema": { "enum": [ "key_id", "kind", "region", "source", "template_id" ], "type": "string" } }, { "description": "`YYYY-MM-DD` (inclusive) or ISO-8601 (exclusive).", "in": "query", "name": "to", "schema": { "format": "date", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "DailyBilledRenders": { "summary": "Daily billed renders", "value": { "from": "2026-09-01T00:00:00Z", "granularity": "day", "group_by": null, "object": "usage", "series": [ { "key": "total", "points": [ { "billed_renders": 128, "pages": 214, "renders_failed": 2, "renders_succeeded": 126, "ts": "2026-09-17T00:00:00Z" } ] } ], "to": "2026-09-30T00:00:00Z" } } }, "schema": { "$ref": "#/components/schemas/Usage" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Invalid `from`/`to`, `granularity` or `group_by`." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Control plane unavailable." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Usage time series", "tags": [ "Account" ] } }, "/v1/webhook-deliveries": { "get": { "operationId": "list_webhook_deliveries", "parameters": [ { "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "in": "query", "name": "endpoint_id", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "in": "query", "name": "render_id", "schema": { "type": "string" } }, { "in": "query", "name": "status", "schema": { "enum": [ "exhausted", "failed", "pending", "succeeded" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryList" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "List webhook deliveries", "tags": [ "Webhooks" ] } }, "/v1/webhook-deliveries/{delivery_id}": { "get": { "operationId": "get_webhook_delivery", "parameters": [ { "in": "path", "name": "delivery_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Retrieve a webhook delivery", "tags": [ "Webhooks" ] } }, "/v1/webhook-deliveries/{delivery_id}/replay": { "post": { "description": "Sends the stored event again as a new delivery (`replay_of` set, same event id). An endpoint's delivery goes to the endpoint's current URL. A delivery to a render's or batch's own `webhook.url` goes to that URL again, signed with the secret of the endpoint that signed the original (the workspace's default endpoint).", "operationId": "replay_webhook_delivery", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } }, { "in": "path", "name": "delivery_id", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Not found." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "`conflict`: the endpoint is deleted, or disabled; for a delivery to a per-request `webhook.url`, the endpoint whose secret signs it. Test events can still be replayed to a disabled endpoint." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Replay a webhook delivery", "tags": [ "Webhooks" ] } }, "/v1/webhook-endpoints": { "get": { "description": "Endpoints registered for this workspace. Secrets are never returned by a read.", "operationId": "list_webhook_endpoints", "responses": { "200": { "content": { "application/json": { "examples": { "OneItem": { "summary": "One item", "value": { "data": [ { "created_at": "2026-09-17T15:06:33Z", "description": "Invoice pipeline", "disabled_reason": null, "enabled": true, "events": [ "render.succeeded", "render.failed" ], "headers": { "X-Tenant": "••••••" }, "id": "whe_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "is_default": true, "object": "webhook_endpoint", "secret_rotation": null, "template_ids": [], "updated_at": "2026-09-17T15:06:33Z", "url": "https://example.com/hooks/dynamic-document-api" } ], "has_more": false, "next_cursor": null, "object": "list" } } }, "schema": { "$ref": "#/components/schemas/WebhookEndpointList" } } }, "description": "Every object in the workspace (a single page today)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "List webhook endpoints", "tags": [ "Webhooks" ] }, "post": { "description": "The response carries the signing `secret` **once** — store it now. Deliveries are signed per [Standard Webhooks](https://www.standardwebhooks.com/) (docs/05 §8.1).", "operationId": "create_webhook_endpoint", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "RenderEvents": { "summary": "Render events", "value": { "description": "Invoice pipeline", "enabled": true, "events": [ "render.succeeded", "render.failed" ], "headers": { "X-Tenant": "acme" }, "url": "https://example.com/hooks/dynamic-document-api" } } }, "schema": { "$ref": "#/components/schemas/WebhookEndpointWrite" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "Created": { "value": { "created_at": "2026-09-17T15:06:33Z", "description": "Invoice pipeline", "disabled_reason": null, "enabled": true, "events": [ "render.succeeded", "render.failed" ], "headers": { "X-Tenant": "••••••" }, "id": "whe_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "is_default": true, "object": "webhook_endpoint", "secret": "whsec_Tk6RHskPlFGHZVbs0TUEF930Fg1DP8SxiADOq0BgA=", "secret_rotation": null, "template_ids": [], "updated_at": "2026-09-17T15:06:33Z", "url": "https://example.com/hooks/dynamic-document-api" } } }, "schema": { "$ref": "#/components/schemas/WebhookEndpointWithSecret" } } }, "description": "Created; `secret` is shown once." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Invalid request body (`errors[]` with JSON pointers)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Create a webhook endpoint", "tags": [ "Webhooks" ] } }, "/v1/webhook-endpoints/{endpoint_id}": { "delete": { "description": "Pending deliveries for this endpoint stop; the delivery log is kept.", "operationId": "delete_webhook_endpoint", "parameters": [ { "description": "Webhook endpoint id (`whe_…`).", "in": "path", "name": "endpoint_id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Webhook endpoint not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Delete a webhook endpoint", "tags": [ "Webhooks" ] }, "get": { "description": "Common base: API key or OAuth only, never a dashboard region token.", "operationId": "get_webhook_endpoint", "parameters": [ { "description": "Webhook endpoint id (`whe_…`).", "in": "path", "name": "endpoint_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "Endpoint": { "value": { "created_at": "2026-09-17T15:06:33Z", "description": "Invoice pipeline", "disabled_reason": null, "enabled": true, "events": [ "render.succeeded", "render.failed" ], "headers": { "X-Tenant": "••••••" }, "id": "whe_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "is_default": true, "object": "webhook_endpoint", "secret_rotation": null, "template_ids": [], "updated_at": "2026-09-17T15:06:33Z", "url": "https://example.com/hooks/dynamic-document-api" } } }, "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Webhook endpoint not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Retrieve a webhook endpoint", "tags": [ "Webhooks" ] }, "patch": { "description": "Partial update; omitted fields keep their value. The secret is not changed — use `POST /v1/webhook-endpoints/{id}/roll-secret`.", "operationId": "update_webhook_endpoint", "parameters": [ { "description": "Webhook endpoint id (`whe_…`).", "in": "path", "name": "endpoint_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "NarrowTheEvents": { "summary": "Narrow the events", "value": { "events": [ "render.succeeded" ], "template_ids": [ "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C" ] } }, "PauseDeliveries": { "summary": "Pause deliveries", "value": { "enabled": false } } }, "schema": { "$ref": "#/components/schemas/PatchedWebhookEndpointWrite" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "Updated": { "value": { "created_at": "2026-09-17T15:06:33Z", "description": "Invoice pipeline", "disabled_reason": null, "enabled": false, "events": [ "render.succeeded", "render.failed" ], "headers": { "X-Tenant": "••••••" }, "id": "whe_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "is_default": true, "object": "webhook_endpoint", "secret_rotation": null, "template_ids": [], "updated_at": "2026-09-17T15:06:33Z", "url": "https://example.com/hooks/dynamic-document-api" } } }, "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Invalid request body (`errors[]` with JSON pointers)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Webhook endpoint not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Update a webhook endpoint", "tags": [ "Webhooks" ] } }, "/v1/webhook-endpoints/{endpoint_id}/roll-secret": { "post": { "description": "Returns a new `secret` once. Deliveries carry both signatures until the previous secret expires, so receivers can be updated without downtime.", "operationId": "roll_webhook_endpoint_secret", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } }, { "description": "Webhook endpoint id (`whe_…`).", "in": "path", "name": "endpoint_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "KeepTheOldSecretForADay": { "summary": "Keep the old secret for a day", "value": { "expire_previous_in": 86400 } } }, "schema": { "$ref": "#/components/schemas/RollSecret" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "Rolled": { "value": { "created_at": "2026-09-17T15:06:33Z", "description": "Invoice pipeline", "disabled_reason": null, "enabled": true, "events": [ "render.succeeded", "render.failed" ], "headers": { "X-Tenant": "••••••" }, "id": "whe_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "is_default": true, "object": "webhook_endpoint", "secret": "whsec_GnN8ZIowv6F9L6QbW6y9oqYbxMjGEHW9vwrzT2CTCPk=", "secret_rotation": { "previous_expires_at": "2026-09-18T15:06:33Z" }, "template_ids": [], "updated_at": "2026-09-17T15:06:33Z", "url": "https://example.com/hooks/dynamic-document-api" } } }, "schema": { "$ref": "#/components/schemas/WebhookEndpointWithSecret" } } }, "description": "The new secret, shown once." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Invalid request body (`errors[]` with JSON pointers)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Webhook endpoint not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Roll the signing secret", "tags": [ "Webhooks" ] } }, "/v1/webhook-endpoints/{endpoint_id}/test": { "post": { "description": "Queues a signed sample event (`test: true`) to the endpoint and returns the delivery id; follow it with `GET /v1/webhook-deliveries/{id}`. Every event type that fires today can be tested (all but `api_key.expiring`); the sample `data` has the real event's shape, including `data.event` for `email.delivered`, `email.bounced` and `email.complained`. Ids are made up and files have no URL.", "operationId": "test_webhook_endpoint", "parameters": [ { "description": "Replays the stored response for 24 h; a different body with the same key → 422.", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } }, { "description": "Webhook endpoint id (`whe_…`).", "in": "path", "name": "endpoint_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "SampleRender": { "summary": "Sample render", "value": { "event": "render.succeeded" } } }, "schema": { "$ref": "#/components/schemas/TestEvent" } } } }, "responses": { "202": { "content": { "application/json": { "examples": { "Queued": { "value": { "delivery_id": "whd_01J9ZM1X3F7R8K2C4V6B8N0P2Q", "object": "webhook_test" } } }, "schema": { "$ref": "#/components/schemas/WebhookTest" } } }, "description": "Queued." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Invalid request body (`errors[]` with JSON pointers)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Missing, invalid, expired or revoked credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Webhook endpoint not found, or not replicated to this region yet." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Rate limited (`Retry-After`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The control plane is unreachable (`Retry-After`)." } }, "security": [ { "ApiKey": [] }, { "ApiKeyHeader": [] }, { "RegionToken": [] } ], "summary": "Send a test event", "tags": [ "Webhooks" ] } } }, "servers": [ { "description": "Region eu", "url": "http://127.0.0.1:8001" } ], "tags": [ { "description": "Create and manage renders (PDFs, images, HTML).", "name": "Renders" }, { "description": "Render one template for many items (JSON or CSV), plus an optional ZIP / merged PDF.", "name": "Batches" }, { "description": "Read published templates, versions and data schemas; create, publish and roll back.", "name": "Templates" }, { "description": "Merge, split, rotate, protect, unlock, inspect PDFs and convert them to PDF/A.", "name": "PDF tools" }, { "description": "XRechnung, Factur-X / ZUGFeRD and EN 16931 invoices: standalone CII or UBL XML here; hybrid PDF/A-3b invoices through `output.einvoice` on any PDF render. Validated with KoSIT.", "name": "E-invoices" }, { "description": "Temporary files for PDF tools and batches.", "name": "Uploads" }, { "description": "Webhook endpoints, the delivery log and replays.", "name": "Webhooks" }, { "description": "Your own S3/Azure/GCS buckets for render output (BYOS).", "name": "Storage" }, { "description": "Image URLs rendered straight from a template.", "name": "Signed links" }, { "description": "Email renders through your own provider account (Brevo, SMTP, Postmark, Resend, Amazon SES or Microsoft 365): connections, rules per template, previews, tests, sends, delivery events and resends. Growth plan and up. While email delivery isn't enabled for a workspace yet, writes to its connections and rules answer `403 feature_not_enabled`.", "name": "Email" }, { "description": "Plan, renders, limits and usage.", "name": "Account" }, { "description": "Editor previews (dashboard region tokens).", "name": "Previews" } ] }