openapi: 3.0.1
info:
  title: PDFMonkey Document Cards Templates API
  description: PDFMonkey generates PDF (and image) documents from HTML + Liquid templates and a JSON data payload. The REST API lets you create, retrieve, update, and delete documents (asynchronously or synchronously), poll lightweight document cards for status and download URLs, and manage document templates.
  termsOfService: https://www.pdfmonkey.io/terms
  contact:
    name: PDFMonkey Support
    url: https://www.pdfmonkey.io
  version: '1.0'
servers:
- url: https://api.pdfmonkey.io/api/v1
  description: PDFMonkey API v1
security:
- bearerAuth: []
tags:
- name: Templates
  description: Manage document templates (HTML + Liquid, SCSS, settings).
paths:
  /document_templates:
    post:
      operationId: createDocumentTemplate
      tags:
      - Templates
      summary: Create a template
      description: Create a new document template.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentTemplateRequest'
      responses:
        '201':
          description: Template created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentTemplateResponse'
        '401':
          description: Unauthorized
        '422':
          description: Unprocessable entity
  /document_templates/{id}:
    get:
      operationId: getDocumentTemplate
      tags:
      - Templates
      summary: Fetch a template
      description: Retrieve full template details, including body, styles, and sample data.
      parameters:
      - $ref: '#/components/parameters/TemplateId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentTemplateResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not found
    put:
      operationId: updateDocumentTemplate
      tags:
      - Templates
      summary: Update a template
      description: Update an existing document template.
      parameters:
      - $ref: '#/components/parameters/TemplateId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentTemplateRequest'
      responses:
        '200':
          description: Template updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentTemplateResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '422':
          description: Unprocessable entity
    delete:
      operationId: deleteDocumentTemplate
      tags:
      - Templates
      summary: Delete a template
      description: Permanently delete a document template.
      parameters:
      - $ref: '#/components/parameters/TemplateId'
      responses:
        '204':
          description: Template deleted
        '401':
          description: Unauthorized
        '404':
          description: Not found
  /document_template_cards:
    get:
      operationId: listDocumentTemplateCards
      tags:
      - Templates
      summary: List template cards
      description: List templates as lightweight document template cards (no body, styles, or sample data), with pagination.
      parameters:
      - name: page[number]
        in: query
        description: Number of the page to show (default 1).
        schema:
          type: integer
          default: 1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentTemplateCardListResponse'
        '401':
          description: Unauthorized
components:
  schemas:
    DocumentTemplateResponse:
      type: object
      properties:
        document_template:
          $ref: '#/components/schemas/DocumentTemplate'
    DocumentTemplateRequest:
      type: object
      required:
      - document_template
      properties:
        document_template:
          type: object
          properties:
            identifier:
              type: string
              description: Human-readable template name.
            body:
              type: string
              description: Published HTML + Liquid body.
            body_draft:
              type: string
            scss_style:
              type: string
            scss_style_draft:
              type: string
            sample_data:
              type: string
            sample_data_draft:
              type: string
            settings:
              type: object
              additionalProperties: true
            settings_draft:
              type: object
              additionalProperties: true
    DocumentTemplateCard:
      type: object
      properties:
        id:
          type: string
          format: uuid
        identifier:
          type: string
        edition_mode:
          type: string
        output_type:
          type: string
        is_draft:
          type: boolean
        pdf_engine_name:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    DocumentTemplate:
      type: object
      properties:
        id:
          type: string
          format: uuid
        app_id:
          type: string
          format: uuid
        identifier:
          type: string
        edition_mode:
          type: string
        output_type:
          type: string
        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:
          type: object
          additionalProperties: true
        settings_draft:
          type: object
          additionalProperties: true
        pdf_engine_id:
          type: string
          format: uuid
        template_folder_id:
          type: string
          format: uuid
          nullable: true
        ttl:
          type: integer
          nullable: true
        preview_url:
          type: string
          format: uri
        checksum:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    DocumentTemplateCardListResponse:
      type: object
      properties:
        document_template_cards:
          type: array
          items:
            $ref: '#/components/schemas/DocumentTemplateCard'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    PaginationMeta:
      type: object
      properties:
        current_page:
          type: integer
        next_page:
          type: integer
          nullable: true
        prev_page:
          type: integer
          nullable: true
        total_pages:
          type: integer
        total_count:
          type: integer
  parameters:
    TemplateId:
      name: id
      in: path
      required: true
      description: The UUID of the document template.
      schema:
        type: string
        format: uuid
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Pass your secret API key from the dashboard as a Bearer token in the Authorization header.