Which document types are available?
GET /documents lists the registry, including invoices, receipts, quotes, and HR letters such as employment verification and offer letters. Each type has a stable schema and templateVersion 1.0.0.
Document Generation API
Registry Types
PDF / DOCX
Schema Validated
Structured JSON. Finished paperwork.
Generate branded invoices, letters, and HR forms from a code-owned registry. Validate once, then render HTML, PDF, or DOCX without custom templates.
1.0.0 · templatePDF · ChromiumDOCX · Office Open XML5 · batch cap
Turn invoice JSON into a file.
This calls the live Document Generation API. Browse the catalog, inspect the invoice example, or generate a canned DOCX. The demo waits for you to run it.
Request builder
Catalog, example payload, or canned DOCX.
GET /document-generation/documents
Output preview
Live response from the API, plus the exact request to reproduce it.
- Run the sample to list registry document types.
Live demo is locked to invoice. Generate uses a server-canned payload and DOCX to avoid Chromium. Huge base64 strings are truncated in the JSON viewer.
Why Document Generation API
One registry. Many documents.
Registry catalog
GET /documents lists types, categories, modes, and outputs so clients do not hard-code schemas.
Schema contracts
Per-type schema, JSON Schema, and example payloads keep agent and form builders in sync.
HTML previews
Blank GET render and filled POST render return printable HTML before a file is generated.
PDF and DOCX
POST generate returns Chromium PDF or Office Open XML DOCX as binary or base64.
Request branding
Logo text, primary and accent colors, and footer copy apply per request without remote assets.
Capped batch
POST /batch accepts one to five document requests and returns per-item HTML or base64 files.
/api/v1/document-generation
Endpoints, at a glance.
Discover types, inspect schemas and examples, then generate HTML, PDF, or DOCX. Health and metrics are included.
GET/api/v1/document-generation/documents
List document types
Registry catalog with id, name, category, modes, outputs, and templateVersion.
GET/api/v1/document-generation/:documentType/example
Example payload
Valid filled sample request for one registered document type.
POST/api/v1/document-generation/:documentType/generate
Generate PDF or DOCX
Validates data against the registry and returns binary or base64 output.
GET/api/v1/document-generation/:documentType/schema
Document schema
Public field contract, collections, and template version for one type.
POST/api/v1/document-generation/batch
Batch generate
One to five document requests with per-item HTML, PDF, or DOCX results.
GET/health
Service health
Status, service name, version, document count, timestamp, and correlation metadata.
GET/metrics
Prometheus metrics
Request counts and latency histograms in Prometheus exposition format.
| Parameter | Type | Required | Description |
|---|---|---|---|
| documentType | string | path | Registry id such as invoice or employment-verification. |
| mode | string | no | blank or filled. Default filled. |
| templateVersion | string | no | Supported contract version. Must be 1.0.0. |
| data | object | filled | Payload validated against the document schema. |
| output.type | string | no | pdf or docx for generate. html, pdf, or docx for batch. |
| output.responseType | string | no | binary or base64. Default binary. |
| output.format | string | no | PDF page size: A4, Letter, Legal, or Tabloid. |
| requests | array | batch | One to five document requests for POST /batch. |
Error reference
Failures you can plan for.
Validation failures include details field errors and metadata.correlationId for tracing.
400Validation Error
Invalid schema, missing required fields, unsupported template version, or malformed output.
401Authentication Error
Missing or invalid gateway API key. Send x-api-key or api_key with every request.
404Not Found
Unknown document type or unknown route under /api/v1/document-generation.
429Rate Limit Error
More than 20 requests in a 15-minute window per IP.
503Service Unavailable
Chromium render pool is saturated. Retry after the service reports capacity.
Example error response
{
"success": false,
"error": "Invalid input parameters",
"details": ["data.invoiceNumber is required"],
"metadata": { "correlationId": "req_abc123" }
}FAQ
API questions developers ask first.
How do I generate a PDF or DOCX?
POST /:documentType/generate with a validated data object. Set output.type to pdf or docx. Use responseType base64 for JSON, or binary for a downloadable file.
Can I preview a document before generating a file?
Yes. GET /:documentType/render returns a blank HTML form. POST the same path with filled data for an HTML preview. GET /:documentType/example returns a valid sample payload.
Does the API fetch remote logos or run custom templates?
No. v1 uses the local registry and request-scoped branding fields. Remote logo fetching and unsupported template versions are rejected.
How do I authenticate requests?
Send your Datpaq API key as an x-api-key header or an api_key query parameter. Keys are created in the Datpaq dashboard and a free tier is included.
Add document generation in one request.
Validated JSON in, branded HTML, PDF, or DOCX out, from a registry of business document types.