openapi: 3.0.1
info:
  title: PDF Generator Documents API
  description: Template-based document and PDF generation API. Merge JSON data with reusable templates to produce PDFs and other documents synchronously, asynchronously, or in batches, manage templates and their data fields, and partition work across multi-tenant workspaces. All requests are authenticated with a short-lived JSON Web Token (JWT) signed (HS256) using your API secret, with your API key as the issuer (iss) and the workspace identifier as the subject (sub).
  termsOfService: https://pdfgeneratorapi.com/terms
  contact:
    name: PDF Generator API Support
    url: https://pdfgeneratorapi.com
    email: support@pdfgeneratorapi.com
  version: '4.0'
servers:
- url: https://us1.pdfgeneratorapi.com/api/v4
  description: Production base URL
security:
- JWT: []
tags:
- name: Documents
  description: Generate, store, and retrieve documents.
paths:
  /documents/generate:
    post:
      operationId: generateDocument
      tags:
      - Documents
      summary: Generate document
      description: Merges a template with data and returns the document as a base64-encoded string or a public URL.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateRequest'
      responses:
        '200':
          description: The generated document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateResponse'
  /documents/generate/async:
    post:
      operationId: generateDocumentAsync
      tags:
      - Documents
      summary: Generate document asynchronously
      description: Merges a template with data as an asynchronous job and notifies a callback URL on completion.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateRequest'
      responses:
        '200':
          description: The accepted async job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncJobResponse'
  /documents/generate/batch:
    post:
      operationId: generateDocumentBatch
      tags:
      - Documents
      summary: Generate batch of documents
      description: Merges multiple templates with data into a single document.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/GenerateRequest'
      responses:
        '200':
          description: The generated document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateResponse'
  /documents/generate/batch/async:
    post:
      operationId: generateDocumentBatchAsync
      tags:
      - Documents
      summary: Generate batch of documents asynchronously
      description: Batch document generation executed as an asynchronous job with a callback.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/GenerateRequest'
      responses:
        '200':
          description: The accepted async job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncJobResponse'
  /documents/async/{jobId}:
    get:
      operationId: getAsyncJobStatus
      tags:
      - Documents
      summary: Get async job status
      description: Returns the current status of an asynchronous document generation job.
      parameters:
      - name: jobId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The async job status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncJobResponse'
  /documents:
    get:
      operationId: getDocuments
      tags:
      - Documents
      summary: Get documents
      description: Returns a list of generated documents created by the authorized workspace and stored in PDF Generator API.
      responses:
        '200':
          description: A list of stored documents.
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: array
                    items:
                      $ref: '#/components/schemas/Document'
    post:
      operationId: storeDocument
      tags:
      - Documents
      summary: Store document
      description: Uploads a PDF to Document Storage via a URL or a base64-encoded string.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: The stored document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
  /documents/{publicId}:
    get:
      operationId: getDocument
      tags:
      - Documents
      summary: Get document
      description: Retrieves a single document from Document Storage.
      parameters:
      - $ref: '#/components/parameters/PublicId'
      responses:
        '200':
          description: The requested document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
  /documents/{publicId}/actions:
    get:
      operationId: getDocumentActions
      tags:
      - Documents
      summary: Get document actions
      description: Returns a list of actions performed on a stored document.
      parameters:
      - $ref: '#/components/parameters/PublicId'
      responses:
        '200':
          description: A list of document actions.
    delete:
      operationId: deleteDocument
      tags:
      - Documents
      summary: Delete document
      description: Removes a document from Document Storage.
      parameters:
      - $ref: '#/components/parameters/PublicId'
      responses:
        '200':
          description: Document deleted.
  /documents/{publicId}/versions:
    get:
      operationId: getDocumentVersions
      tags:
      - Documents
      summary: Get document versions
      description: Returns a list of versions for a stored document.
      parameters:
      - $ref: '#/components/parameters/PublicId'
      responses:
        '200':
          description: A list of document versions.
components:
  schemas:
    Document:
      type: object
      properties:
        public_id:
          type: string
        name:
          type: string
        created_at:
          type: string
    AsyncJobResponse:
      type: object
      properties:
        response:
          type: object
          properties:
            job_id:
              type: string
            status:
              type: string
              enum:
              - pending
              - processing
              - completed
              - failed
    GenerateResponse:
      type: object
      properties:
        response:
          type: string
          description: Base64-encoded document or a public URL, depending on output.
        meta:
          type: object
          properties:
            name:
              type: string
            display_name:
              type: string
            encoding:
              type: string
            output_type:
              type: string
    GenerateRequest:
      type: object
      required:
      - template
      - data
      properties:
        template:
          type: object
          properties:
            id:
              type: integer
            data:
              type: object
        format:
          type: string
          enum:
          - pdf
          - html
          - zip
          - xlsx
          default: pdf
        output:
          type: string
          enum:
          - base64
          - url
          - file
          - i
          default: base64
        name:
          type: string
        data:
          type: object
          description: JSON data merged into the template.
  parameters:
    PublicId:
      name: publicId
      in: path
      required: true
      description: Public identifier of a stored document.
      schema:
        type: string
  securitySchemes:
    JWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Short-lived JSON Web Token signed with HS256 using your API secret. Claims: iss (API key), sub (workspace identifier), exp (expiration).'