openapi: 3.0.1
info:
  title: PDFMonkey 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: Documents
    description: Create, retrieve, update, and delete generated documents.
  - name: Document Cards
    description: Lightweight document representations for status polling and listing.
  - name: Templates
    description: Manage document templates (HTML + Liquid, SCSS, settings).
paths:
  /documents:
    post:
      operationId: createDocument
      tags:
        - Documents
      summary: Create a document
      description: >-
        Create a new document from a template and payload. Set status to
        "pending" to queue generation immediately, or leave as a draft.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentCreateRequest'
      responses:
        '201':
          description: Document created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentResponse'
        '401':
          description: Unauthorized
        '422':
          description: Unprocessable entity
  /documents/sync:
    post:
      operationId: createDocumentSync
      tags:
        - Documents
      summary: Create a document synchronously
      description: >-
        Create a document and block until generation completes, returning the
        finished document. Suited to prototyping and low-volume interactive
        use; webhooks are recommended for production.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentCreateRequest'
      responses:
        '201':
          description: Document generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentResponse'
        '401':
          description: Unauthorized
        '422':
          description: Unprocessable entity
  /documents/{id}:
    get:
      operationId: getDocument
      tags:
        - Documents
      summary: Fetch a document
      description: Retrieve a full document, including its payload and generation logs.
      parameters:
        - $ref: '#/components/parameters/DocumentId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not found
    put:
      operationId: updateDocument
      tags:
        - Documents
      summary: Update a document
      description: >-
        Update a draft document's payload, metadata, or template, or set its
        status to "pending" to trigger generation.
      parameters:
        - $ref: '#/components/parameters/DocumentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentUpdateRequest'
      responses:
        '200':
          description: Document updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '422':
          description: Unprocessable entity
    delete:
      operationId: deleteDocument
      tags:
        - Documents
      summary: Delete a document
      description: Permanently delete a document.
      parameters:
        - $ref: '#/components/parameters/DocumentId'
      responses:
        '204':
          description: Document deleted
        '401':
          description: Unauthorized
        '404':
          description: Not found
  /document_cards:
    get:
      operationId: listDocumentCards
      tags:
        - Document Cards
      summary: List document cards
      description: >-
        List documents as lightweight document cards (no payload), with
        pagination and filtering. The endpoint returns up to 24 items per page.
      parameters:
        - name: page[number]
          in: query
          description: Number of the page to show (default 1).
          schema:
            type: integer
            default: 1
        - name: q[document_template_id]
          in: query
          description: Filter on one or more template IDs.
          schema:
            type: string
        - name: q[status]
          in: query
          description: Filter on document status.
          schema:
            type: string
            enum:
              - draft
              - pending
              - generating
              - success
              - failure
        - name: q[workspace_id]
          in: query
          description: ID of a workspace to filter on.
          schema:
            type: string
        - name: q[updated_since]
          in: query
          description: Filter documents updated after a given point in time.
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentCardListResponse'
        '401':
          description: Unauthorized
  /document_cards/{id}:
    get:
      operationId: getDocumentCard
      tags:
        - Document Cards
      summary: Fetch a document card
      description: >-
        Retrieve a lightweight document card for a document. This is the
        recommended way to poll generation status and obtain the download URL,
        since it omits the heavy payload attribute.
      parameters:
        - $ref: '#/components/parameters/DocumentId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentCardResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not found
  /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:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Pass your secret API key from the dashboard as a Bearer token in the
        Authorization header.
  parameters:
    DocumentId:
      name: id
      in: path
      required: true
      description: The UUID of the document.
      schema:
        type: string
        format: uuid
    TemplateId:
      name: id
      in: path
      required: true
      description: The UUID of the document template.
      schema:
        type: string
        format: uuid
  schemas:
    DocumentCreateRequest:
      type: object
      required:
        - document
      properties:
        document:
          type: object
          required:
            - document_template_id
          properties:
            document_template_id:
              type: string
              format: uuid
              description: The template to generate from.
            status:
              type: string
              description: Set to "pending" to queue generation upon creation.
              enum:
                - draft
                - pending
            payload:
              type: object
              additionalProperties: true
              description: Dynamic JSON data made available to the template.
            meta:
              type: object
              additionalProperties: true
              description: >-
                Custom metadata passed through to webhooks. Supports the
                _filename key to set the output file name.
    DocumentUpdateRequest:
      type: object
      required:
        - document
      properties:
        document:
          type: object
          properties:
            document_template_id:
              type: string
              format: uuid
            status:
              type: string
              enum:
                - draft
                - pending
            payload:
              type: object
              additionalProperties: true
            meta:
              type: object
              additionalProperties: true
    Document:
      type: object
      properties:
        id:
          type: string
          format: uuid
        app_id:
          type: string
          format: uuid
          description: Workspace identifier.
        document_template_id:
          type: string
          format: uuid
        document_template_identifier:
          type: string
        status:
          type: string
          enum:
            - draft
            - pending
            - generating
            - success
            - failure
        payload:
          type: object
          nullable: true
          additionalProperties: true
        meta:
          type: object
          nullable: true
          additionalProperties: true
        filename:
          type: string
          nullable: true
        download_url:
          type: string
          format: uri
          nullable: true
          description: Temporary signed link, valid for about one hour.
        preview_url:
          type: string
          format: uri
        public_share_link:
          type: string
          format: uri
          nullable: true
        checksum:
          type: string
        generation_logs:
          type: array
          items:
            type: object
            additionalProperties: true
        failure_cause:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    DocumentResponse:
      type: object
      properties:
        document:
          $ref: '#/components/schemas/Document'
    DocumentCard:
      type: object
      description: >-
        Lightweight document representation. Same as a Document but without the
        payload attribute.
      properties:
        id:
          type: string
          format: uuid
        app_id:
          type: string
          format: uuid
        document_template_id:
          type: string
          format: uuid
        document_template_identifier:
          type: string
        status:
          type: string
          enum:
            - draft
            - pending
            - generating
            - success
            - failure
        meta:
          type: object
          nullable: true
          additionalProperties: true
        filename:
          type: string
          nullable: true
        download_url:
          type: string
          format: uri
          nullable: true
        preview_url:
          type: string
          format: uri
        public_share_link:
          type: string
          format: uri
          nullable: true
        output_type:
          type: string
        failure_cause:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    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'
    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
    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
    DocumentTemplateResponse:
      type: object
      properties:
        document_template:
          $ref: '#/components/schemas/DocumentTemplate'
    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
    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