{
  "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": "user@example.com",
                    "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": "Output format type"
          },
          "is_draft": {
            "type": "boolean",
            "description": "Whether this template is currently in draft state"
          },
          "body": {
            "type": "string",
            "description": "Published HTML + Liquid template body"
          },
          "body_draft": {
            "type": "string",
            "description": "Draft HTML + Liquid template body"
          },
          "scss_style": {
            "type": "string",
            "description": "Published CSS/SCSS styles"
          },
          "scss_style_draft": {
            "type": "string",
            "description": "Draft CSS/SCSS styles"
          },
          "sample_data": {
            "type": "string",
            "description": "Published JSON sample data for template preview"
          },
          "sample_data_draft": {
            "type": "string",
            "description": "Draft JSON sample data"
          },
          "settings": {
            "$ref": "#/components/schemas/TemplateSettings"
          },
          "settings_draft": {
            "$ref": "#/components/schemas/TemplateSettings"
          },
          "pdf_engine_id": {
            "type": ["string", "null"],
            "format": "uuid",
            "description": "PDF engine UUID used for generation"
          },
          "pdf_engine_draft_id": {
            "type": ["string", "null"],
            "format": "uuid"
          },
          "template_folder_id": {
            "type": ["string", "null"],
            "format": "uuid",
            "description": "Folder this template belongs to"
          },
          "ttl": {
            "type": ["integer", "null"],
            "description": "Time-to-live in seconds for generated documents"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "DocumentTemplateCard": {
        "type": "object",
        "description": "Lightweight template object for listing",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "app_id": {
            "type": "string",
            "format": "uuid"
          },
          "identifier": {
            "type": "string"
          },
          "edition_mode": {
            "type": "string",
            "enum": ["code", "builder"]
          },
          "output_type": {
            "type": "string",
            "enum": ["pdf", "image"]
          },
          "is_draft": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "pdf_engine_name": {
            "type": ["string", "null"],
            "description": "Name of the PDF rendering engine"
          },
          "pdf_engine_deprecated_on": {
            "type": ["string", "null"],
            "format": "date-time",
            "description": "Date when this engine will be deprecated, null if not deprecated"
          },
          "template_folder_id": {
            "type": ["string", "null"],
            "format": "uuid"
          },
          "template_folder_identifier": {
            "type": ["string", "null"]
          }
        }
      },
      "TemplateResponse": {
        "type": "object",
        "properties": {
          "document_template": {
            "$ref": "#/components/schemas/DocumentTemplate"
          }
        }
      },
      "TemplateCardListResponse": {
        "type": "object",
        "properties": {
          "document_template_cards": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DocumentTemplateCard"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/PaginationMeta"
          }
        }
      },
      "TemplateCreateRequest": {
        "type": "object",
        "required": ["document_template"],
        "properties": {
          "document_template": {
            "type": "object",
            "required": ["app_id", "identifier"],
            "properties": {
              "app_id": {
                "type": "string",
                "format": "uuid",
                "description": "Workspace UUID this template belongs to"
              },
              "identifier": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100,
                "description": "Unique human-readable identifier for the template"
              },
              "body": {
                "type": "string",
                "description": "HTML + Liquid template body (published version)"
              },
              "body_draft": {
                "type": "string",
                "description": "HTML + Liquid template body (draft version)"
              },
              "scss_style": {
                "type": "string",
                "description": "CSS/SCSS styles (published version)"
              },
              "scss_style_draft": {
                "type": "string",
                "description": "CSS/SCSS styles (draft version)"
              },
              "sample_data": {
                "type": "string",
                "description": "JSON sample data for template preview (published)"
              },
              "sample_data_draft": {
                "type": "string",
                "description": "JSON sample data (draft)"
              },
              "settings": {
                "$ref": "#/components/schemas/TemplateSettings"
              },
              "settings_draft": {
                "$ref": "#/components/schemas/TemplateSettings"
              },
              "pdf_engine_id": {
                "type": "string",
                "format": "uuid"
              },
              "pdf_engine_draft_id": {
                "type": "string",
                "format": "uuid"
              },
              "template_folder_id": {
                "type": "string",
                "format": "uuid"
              },
              "ttl": {
                "type": "integer",
                "description": "Time-to-live in seconds for generated documents"
              },
              "edition_mode": {
                "type": "string",
                "enum": ["code", "builder"],
                "default": "code"
              },
              "output_type": {
                "type": "string",
                "enum": ["pdf", "image"],
                "default": "pdf"
              }
            }
          }
        }
      },
      "TemplateUpdateRequest": {
        "type": "object",
        "required": ["document_template"],
        "properties": {
          "document_template": {
            "type": "object",
            "properties": {
              "identifier": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100
              },
              "body": {"type": "string"},
              "body_draft": {"type": "string"},
              "scss_style": {"type": "string"},
              "scss_style_draft": {"type": "string"},
              "sample_data": {"type": "string"},
              "sample_data_draft": {"type": "string"},
              "settings": {
                "$ref": "#/components/schemas/TemplateSettings"
              },
              "settings_draft": {
                "$ref": "#/components/schemas/TemplateSettings"
              },
              "pdf_engine_id": {
                "type": "string",
                "format": "uuid"
              },
              "pdf_engine_draft_id": {
                "type": "string",
                "format": "uuid"
              },
              "template_folder_id": {
                "type": "string",
                "format": "uuid"
              },
              "ttl": {
                "type": "integer"
              },
              "output_type": {
                "type": "string",
                "enum": ["pdf", "image"]
              }
            }
          }
        }
      },
      "ApiError": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "description": "HTTP status code as string"
          },
          "title": {
            "type": "string",
            "description": "Short error title"
          },
          "detail": {
            "type": "string",
            "description": "Detailed error description"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Authentication failed — missing or invalid API key",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "errors": [
                {
                  "status": "401",
                  "title": "Unauthorized",
                  "detail": "We were unable to authenticate you based on the provided API key."
                }
              ]
            }
          }
        }
      },
      "NotFound": {
        "description": "The requested resource was not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "UnprocessableEntity": {
        "description": "Validation errors — the request body is invalid",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Authentication",
      "description": "Endpoints for verifying API credentials and retrieving account information"
    },
    {
      "name": "Documents",
      "description": "Create, retrieve, update, delete, and list PDF documents"
    },
    {
      "name": "Templates",
      "description": "Manage document templates for PDF generation"
    }
  ]
}