REST API for generating, managing, and retrieving PDF documents using Handlebars templates and JSON data payloads. Supports asynchronous and synchronous generation modes, document lifecycle management, and webhook notifications for real-time event handling.
{
"openapi": "3.1.0",
"info": {
"title": "PDF Monkey API",
"description": "REST API for generating, managing, and retrieving PDF documents using Handlebars/Liquid templates and JSON data payloads. Supports asynchronous and synchronous generation modes, document lifecycle management, template management, and webhook notifications for real-time event handling.",
"version": "1.0.0",
"contact": {
"url": "https://pdfmonkey.io/docs/"
},
"termsOfService": "https://www.pdfmonkey.io/terms",
"license": {
"name": "Proprietary"
}
},
"servers": [
{
"url": "https://api.pdfmonkey.io/api/v1",
"description": "PDF Monkey Production API"
}
],
"security": [
{
"bearerAuth": []
}
],
"paths": {
"/current_user": {
"get": {
"operationId": "getCurrentUser",
"summary": "Get current user",
"description": "Retrieve the current authenticated user account information. Useful for verifying API credentials.",
"tags": ["Authentication"],
"responses": {
"200": {
"description": "Authenticated user details",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CurrentUserResponse"
},
"example": {
"current_user": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"auth_token": "your_api_key_here",
"available_documents": 500,
"created_at": "2024-01-15T10:30:00Z",
"current_plan": "starter",
"current_plan_interval": "monthly",
"desired_name": "Acme Corp",
"email": "[email protected]",
"lang": "en",
"paying_customer": true,
"trial_ends_on": null,
"updated_at": "2024-06-01T08:00:00Z",
"block_resources": false,
"share_links": true
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/documents": {
"post": {
"operationId": "createDocument",
"summary": "Create a document",
"description": "Asynchronously create a new PDF document from a template. Returns immediately with status 'pending'. Poll the document_cards endpoint or use webhooks to detect completion.",
"tags": ["Documents"],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentCreateRequest"
},
"example": {
"document": {
"document_template_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"payload": {
"customer_name": "Jane Doe",
"invoice_number": "INV-2024-001",
"total": 1250.00
},
"meta": {
"order_id": "ORD-789"
},
"status": "pending"
}
}
}
}
},
"responses": {
"201": {
"description": "Document created and queued for generation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/documents/sync": {
"post": {
"operationId": "createDocumentSync",
"summary": "Create a document synchronously",
"description": "Synchronously create and generate a PDF document. The request waits until generation is complete (up to 6 minutes) before returning. Returns a lightweight DocumentCard object.",
"tags": ["Documents"],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentCreateRequest"
},
"example": {
"document": {
"document_template_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"payload": {
"customer_name": "Jane Doe",
"invoice_number": "INV-2024-001"
},
"status": "pending"
}
}
}
}
},
"responses": {
"200": {
"description": "Document generated synchronously",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentCardResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/documents/{id}": {
"get": {
"operationId": "getDocument",
"summary": "Get a document",
"description": "Retrieve the full document object including payload and generation logs. Use document_cards/{id} when the full payload is not needed.",
"tags": ["Documents"],
"parameters": [
{
"$ref": "#/components/parameters/DocumentId"
}
],
"responses": {
"200": {
"description": "Full document object",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"put": {
"operationId": "updateDocument",
"summary": "Update a document",
"description": "Update a document's properties. Set status to 'pending' to trigger regeneration.",
"tags": ["Documents"],
"parameters": [
{
"$ref": "#/components/parameters/DocumentId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentUpdateRequest"
},
"example": {
"document": {
"payload": {
"customer_name": "John Doe",
"invoice_number": "INV-2024-002"
},
"status": "pending"
}
}
}
}
},
"responses": {
"200": {
"description": "Updated document object",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
},
"delete": {
"operationId": "deleteDocument",
"summary": "Delete a document",
"description": "Permanently delete a document and its generated file.",
"tags": ["Documents"],
"parameters": [
{
"$ref": "#/components/parameters/DocumentId"
}
],
"responses": {
"204": {
"description": "Document deleted successfully"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/document_cards": {
"get": {
"operationId": "listDocumentCards",
"summary": "List document cards",
"description": "Retrieve a paginated list of lightweight document card objects. Supports filtering by template, status, workspace, and update time. Returns up to 24 documents per page.",
"tags": ["Documents"],
"parameters": [
{
"name": "page[number]",
"in": "query",
"description": "Page number for pagination",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
}
},
{
"name": "q[document_template_id]",
"in": "query",
"description": "Filter by template UUID or comma-separated list of UUIDs",
"schema": {
"type": "string"
}
},
{
"name": "q[status]",
"in": "query",
"description": "Filter by document status",
"schema": {
"$ref": "#/components/schemas/DocumentStatus"
}
},
{
"name": "q[workspace_id]",
"in": "query",
"description": "Filter by workspace UUID",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "q[updated_since]",
"in": "query",
"description": "Filter documents updated after this timestamp (Unix timestamp or ISO 8601)",
"schema": {
"type": "string"
}
},
{
"name": "q[search]",
"in": "query",
"description": "Search by document ID (exact) or filename (partial match)",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Paginated list of document cards",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentCardListResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/document_cards/{id}": {
"get": {
"operationId": "getDocumentCard",
"summary": "Get a document card",
"description": "Retrieve a lightweight document card object. Recommended for polling document generation status as it excludes the large payload and generation_logs fields.",
"tags": ["Documents"],
"parameters": [
{
"$ref": "#/components/parameters/DocumentId"
}
],
"responses": {
"200": {
"description": "Document card object",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentCardResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/document_template_cards": {
"get": {
"operationId": "listTemplateCards",
"summary": "List template cards",
"description": "Retrieve a paginated list of lightweight template card objects for a given workspace.",
"tags": ["Templates"],
"parameters": [
{
"name": "q[workspace_id]",
"in": "query",
"required": true,
"description": "Workspace UUID to filter templates by",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "q[folders]",
"in": "query",
"description": "Comma-separated folder IDs; use 'none' for root or 'all' for all folders",
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"description": "Page number for pagination",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
}
},
{
"name": "sort",
"in": "query",
"description": "Sort attribute",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Paginated list of template cards",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TemplateCardListResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/document_templates": {
"post": {
"operationId": "createTemplate",
"summary": "Create a template",
"description": "Create a new document template with HTML/Liquid body, SCSS styles, sample data, and generation settings.",
"tags": ["Templates"],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TemplateCreateRequest"
},
"example": {
"document_template": {
"app_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"identifier": "invoice-template",
"body": "<h1>Invoice</h1><p>Customer: {{ customer_name }}</p>",
"scss_style": "body { font-family: Arial, sans-serif; }",
"sample_data": "{\"customer_name\": \"Jane Doe\"}",
"output_type": "pdf",
"edition_mode": "code"
}
}
}
}
},
"responses": {
"201": {
"description": "Template created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TemplateResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/document_templates/{id}": {
"get": {
"operationId": "getTemplate",
"summary": "Get a template",
"description": "Retrieve the full document template object including body, styles, settings, and test data.",
"tags": ["Templates"],
"parameters": [
{
"$ref": "#/components/parameters/TemplateId"
}
],
"responses": {
"200": {
"description": "Full template object",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TemplateResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"put": {
"operationId": "updateTemplate",
"summary": "Update a template",
"description": "Update an existing document template's properties.",
"tags": ["Templates"],
"parameters": [
{
"$ref": "#/components/parameters/TemplateId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TemplateUpdateRequest"
}
}
}
},
"responses": {
"200": {
"description": "Updated template object",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TemplateResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
},
"delete": {
"operationId": "deleteTemplate",
"summary": "Delete a template",
"description": "Permanently delete a document template.",
"tags": ["Templates"],
"parameters": [
{
"$ref": "#/components/parameters/TemplateId"
}
],
"responses": {
"204": {
"description": "Template deleted successfully"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Authenticate using your PDF Monkey API secret key as a Bearer token in the Authorization header."
}
},
"parameters": {
"DocumentId": {
"name": "id",
"in": "path",
"required": true,
"description": "Document UUID",
"schema": {
"type": "string",
"format": "uuid"
}
},
"TemplateId": {
"name": "id",
"in": "path",
"required": true,
"description": "Template UUID",
"schema": {
"type": "string",
"format": "uuid"
}
}
},
"schemas": {
"DocumentStatus": {
"type": "string",
"enum": ["draft", "pending", "generating", "success", "failure"],
"description": "Current generation status of a document"
},
"PaginationMeta": {
"type": "object",
"properties": {
"current_page": {
"type": "integer",
"description": "Current page number"
},
"next_page": {
"type": ["integer", "null"],
"description": "Next page number, null if on last page"
},
"prev_page": {
"type": ["integer", "null"],
"description": "Previous page number, null if on first page"
},
"total_pages": {
"type": "integer",
"description": "Total number of pages"
}
}
},
"CurrentUser": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "User unique identifier"
},
"auth_token": {
"type": "string",
"description": "Current API authentication token"
},
"available_documents": {
"type": "integer",
"description": "Number of remaining documents available in the current billing period"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Account creation timestamp"
},
"current_plan": {
"type": "string",
"description": "Name of the current subscription plan"
},
"current_plan_interval": {
"type": "string",
"enum": ["monthly", "yearly"],
"description": "Billing interval for the current plan"
},
"desired_name": {
"type": "string",
"description": "Display name for the account"
},
"email": {
"type": "string",
"format": "email",
"description": "Account email address"
},
"lang": {
"type": "string",
"description": "Preferred language code"
},
"paying_customer": {
"type": "boolean",
"description": "Whether this is a paying customer"
},
"trial_ends_on": {
"type": ["string", "null"],
"format": "date",
"description": "Date when trial ends, null if not in trial"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Last account update timestamp"
},
"block_resources": {
"type": "boolean",
"description": "Whether external resources are blocked in PDF generation"
},
"share_links": {
"type": "boolean",
"description": "Whether public share links are enabled"
}
}
},
"CurrentUserResponse": {
"type": "object",
"properties": {
"current_user": {
"$ref": "#/components/schemas/CurrentUser"
}
}
},
"Document": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Document unique identifier"
},
"app_id": {
"type": "string",
"format": "uuid",
"description": "Workspace (app) identifier"
},
"checksum": {
"type": ["string", "null"],
"description": "MD5 checksum of the generated PDF file"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Document creation timestamp"
},
"document_template_id": {
"type": "string",
"format": "uuid",
"description": "ID of the template used to generate this document"
},
"download_url": {
"type": ["string", "null"],
"format": "uri",
"description": "Temporary signed URL to download the generated PDF. Valid for 1 hour. Null until generation completes."
},
"failure_cause": {
"type": ["string", "null"],
"description": "Reason for generation failure, null if not failed"
},
"filename": {
"type": ["string", "null"],
"description": "Generated filename for the PDF"
},
"generation_logs": {
"type": ["array", "null"],
"description": "Logs from the PDF generation process",
"items": {
"type": "object"
}
},
"meta": {
"description": "Custom metadata attached to the document (max 200 KB)",
"oneOf": [
{"type": "object"},
{"type": "string"}
]
},
"output_type": {
"type": "string",
"enum": ["pdf", "image"],
"description": "Output format type"
},
"payload": {
"description": "JSON data payload used to render the template",
"oneOf": [
{"type": "object"},
{"type": "string"}
]
},
"preview_url": {
"type": ["string", "null"],
"format": "uri",
"description": "URL for document preview"
},
"public_share_link": {
"type": ["string", "null"],
"format": "uri",
"description": "Public shareable link for the document, if share links are enabled"
},
"status": {
"$ref": "#/components/schemas/DocumentStatus"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Last document update timestamp"
}
}
},
"DocumentCard": {
"type": "object",
"description": "Lightweight document object excluding payload and generation_logs",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Document unique identifier"
},
"app_id": {
"type": "string",
"format": "uuid",
"description": "Workspace (app) identifier"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Document creation timestamp"
},
"document_template_id": {
"type": "string",
"format": "uuid",
"description": "ID of the template used"
},
"document_template_identifier": {
"type": ["string", "null"],
"description": "Human-readable identifier of the template"
},
"download_url": {
"type": ["string", "null"],
"format": "uri",
"description": "Temporary signed URL to download the generated PDF. Valid for 1 hour."
},
"failure_cause": {
"type": ["string", "null"],
"description": "Reason for generation failure"
},
"filename": {
"type": ["string", "null"],
"description": "Generated filename"
},
"meta": {
"description": "Custom metadata",
"oneOf": [
{"type": "object"},
{"type": "string"}
]
},
"output_type": {
"type": "string",
"enum": ["pdf", "image"]
},
"preview_url": {
"type": ["string", "null"],
"format": "uri"
},
"public_share_link": {
"type": ["string", "null"],
"format": "uri"
},
"status": {
"$ref": "#/components/schemas/DocumentStatus"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
},
"DocumentResponse": {
"type": "object",
"properties": {
"document": {
"$ref": "#/components/schemas/Document"
}
}
},
"DocumentCardResponse": {
"type": "object",
"properties": {
"document_card": {
"$ref": "#/components/schemas/DocumentCard"
}
}
},
"DocumentCardListResponse": {
"type": "object",
"properties": {
"document_cards": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DocumentCard"
}
},
"meta": {
"$ref": "#/components/schemas/PaginationMeta"
}
}
},
"DocumentCreateRequest": {
"type": "object",
"required": ["document"],
"properties": {
"document": {
"type": "object",
"required": ["document_template_id"],
"properties": {
"document_template_id": {
"type": "string",
"format": "uuid",
"description": "UUID of the template to use for generation"
},
"payload": {
"description": "JSON data payload to render into the template",
"oneOf": [
{"type": "object"},
{"type": "string"}
]
},
"meta": {
"description": "Custom metadata to attach to the document (max 200 KB)",
"oneOf": [
{"type": "object"},
{"type": "string"}
]
},
"status": {
"type": "string",
"enum": ["draft", "pending"],
"default": "draft",
"description": "Set to 'pending' to immediately trigger generation"
}
}
}
}
},
"DocumentUpdateRequest": {
"type": "object",
"required": ["document"],
"properties": {
"document": {
"type": "object",
"properties": {
"document_template_id": {
"type": "string",
"format": "uuid"
},
"payload": {
"oneOf": [
{"type": "object"},
{"type": "string"}
]
},
"meta": {
"oneOf": [
{"type": "object"},
{"type": "string"}
]
},
"status": {
"type": "string",
"enum": ["draft", "pending"],
"description": "Set to 'pending' to trigger regeneration"
}
}
}
}
},
"TemplateSettings": {
"type": "object",
"description": "PDF generation settings for the template",
"properties": {
"footer": {
"type": "object",
"description": "Footer configuration with left, center, right, or content properties"
},
"header": {
"type": "object",
"description": "Header configuration with left, center, right, or content properties"
},
"inject_javascript": {
"type": "boolean",
"description": "Whether to inject and execute JavaScript during generation"
},
"margin": {
"type": "object",
"description": "Page margins in millimeters",
"properties": {
"top": {"type": "number"},
"bottom": {"type": "number"},
"left": {"type": "number"},
"right": {"type": "number"}
}
},
"orientation": {
"type": "string",
"enum": ["portrait", "landscape"],
"description": "Page orientation"
},
"paper_format": {
"type": "string",
"enum": ["a0", "a1", "a2", "a3", "a4", "a5", "a6", "letter", "custom"],
"description": "Paper size format"
},
"paper_height": {
"type": "number",
"description": "Custom paper height in millimeters (used when paper_format is 'custom')"
},
"paper_width": {
"type": "number",
"description": "Custom paper width in millimeters (used when paper_format is 'custom')"
},
"transparent_background": {
"type": "boolean",
"description": "Whether the PDF background should be transparent"
},
"use_emojis": {
"type": "boolean",
"description": "Whether emoji rendering is enabled"
},
"use_paged": {
"type": "boolean",
"description": "Whether to use Paged.js for print layout"
}
}
},
"DocumentTemplate": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Template unique identifier"
},
"app_id": {
"type": "string",
"format": "uuid",
"description": "Workspace (app) identifier"
},
"identifier": {
"type": "string",
"description": "Human-readable unique identifier for the template (1-100 chars)"
},
"edition_mode": {
"type": "string",
"enum": ["code", "builder"],
"description": "Whether the template uses code editor or visual builder"
},
"output_type": {
"type": "string",
"enum": ["pdf", "image"],
"description": "Outpu
# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pdf-monkey/refs/heads/main/openapi/openapi.json