openapi: 3.0.1
info:
  title: PDF Generator Documents Templates 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: Templates
  description: Manage reusable document templates and the template editor.
paths:
  /templates:
    get:
      operationId: getTemplates
      tags:
      - Templates
      summary: Get all templates
      description: Returns a list of templates available to the authenticated workspace.
      parameters:
      - name: access
        in: query
        schema:
          type: string
          enum:
          - organization
          - private
      - name: tags
        in: query
        schema:
          type: string
      responses:
        '200':
          description: A list of templates.
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: array
                    items:
                      $ref: '#/components/schemas/Template'
    post:
      operationId: createTemplate
      tags:
      - Templates
      summary: Create template
      description: Creates a new template in the authenticated workspace.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TemplateDefinition'
      responses:
        '201':
          description: The created template.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateResponse'
  /templates/{templateId}:
    get:
      operationId: getTemplate
      tags:
      - Templates
      summary: Get template
      description: Retrieves the configuration of a single template.
      parameters:
      - $ref: '#/components/parameters/TemplateId'
      responses:
        '200':
          description: The requested template.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateResponse'
    put:
      operationId: updateTemplate
      tags:
      - Templates
      summary: Update template
      description: Updates the configuration of an existing template.
      parameters:
      - $ref: '#/components/parameters/TemplateId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TemplateDefinition'
      responses:
        '200':
          description: The updated template.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateResponse'
    delete:
      operationId: deleteTemplate
      tags:
      - Templates
      summary: Delete template
      description: Removes a template from the workspace.
      parameters:
      - $ref: '#/components/parameters/TemplateId'
      responses:
        '200':
          description: Template deleted.
  /templates/{templateId}/copy:
    post:
      operationId: copyTemplate
      tags:
      - Templates
      summary: Copy template
      description: Creates a copy of a template into the workspace specified in the authentication parameters.
      parameters:
      - $ref: '#/components/parameters/TemplateId'
      - name: name
        in: query
        schema:
          type: string
      responses:
        '201':
          description: The copied template.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateResponse'
  /templates/{templateId}/data:
    get:
      operationId: getTemplateData
      tags:
      - Templates
      summary: Get template data fields
      description: Returns all data fields referenced within a template.
      parameters:
      - $ref: '#/components/parameters/TemplateId'
      responses:
        '200':
          description: A list of data fields used by the template.
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: array
                    items:
                      type: string
  /templates/{templateId}/editor:
    post:
      operationId: openEditor
      tags:
      - Templates
      summary: Open template editor
      description: Generates a unique URL that opens the browser-based template editor for a template.
      parameters:
      - $ref: '#/components/parameters/TemplateId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EditorData'
      responses:
        '200':
          description: A unique editor URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: string
                    format: uri
  /templates/import:
    post:
      operationId: importTemplate
      tags:
      - Templates
      summary: Import template
      description: Creates a template from an existing PDF.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: The imported template.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateResponse'
  /templates/validate:
    post:
      operationId: validateTemplate
      tags:
      - Templates
      summary: Validate template
      description: Validates whether the provided template configuration matches the template JSON schema.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TemplateDefinition'
      responses:
        '200':
          description: Validation result.
  /templates/schema:
    get:
      operationId: getTemplateSchema
      tags:
      - Templates
      summary: Get template schema
      description: Returns the JSON Schema that defines the structure of a template.
      responses:
        '200':
          description: The template JSON schema.
          content:
            application/json:
              schema:
                type: object
components:
  schemas:
    EditorData:
      type: object
      properties:
        data:
          type: object
          description: Sample data to preview inside the editor.
    Template:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier.
        name:
          type: string
          description: Template name.
        owner:
          type: boolean
          description: Whether the template is owned by the authenticated workspace.
        tags:
          type: array
          items:
            type: string
        created_at:
          type: string
        updated_at:
          type: string
    TemplateResponse:
      type: object
      properties:
        response:
          $ref: '#/components/schemas/Template'
        meta:
          type: object
    TemplateDefinition:
      type: object
      properties:
        name:
          type: string
        layout:
          type: object
        pages:
          type: array
          items:
            type: object
  parameters:
    TemplateId:
      name: templateId
      in: path
      required: true
      description: Unique identifier of the template.
      schema:
        type: integer
  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).'