openapi: 3.0.3
info:
    title: pdfs
    description: The PDFs service takes a stored PDF template and fills in placeholder fields with the values you give it. It then sends back the completed PDF for you to save, email, or use however you want.
    version: 1.0.0
servers:
    - url: https://pdfs.platform.arb.inc
paths:
    /:
        get:
            summary: Get basic service information
            description: Returns a plain text welcome message with the service name and creation date.
            operationId: getRoot
            responses:
                '200':
                    description: Successfully retrieved welcome message.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: Welcome to the pdfs service. Created on August 7, 2025 by Al Beebe
            tags:
                - /
    /templates/fill:
        post:
            summary: Fill a PDF from a template
            description: Fills a PDF using a specified template and placeholder values.
            operationId: postTemplatesFill
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - templateID
                            properties:
                                documentID:
                                    type: string
                                    description: Identifier of the document to fill.
                                    example: "statementOfClaim"
                                placeholders:
                                    type: object
                                    description: Map of template placeholder names to their replacement values.
                                    additionalProperties:
                                        type: string
                                    example:
                                        attempts_at_resolution: "Attempt i made"
                                        claim_details: "My claim details"
            responses:
                '200':
                    description: PDF successfully filled.
                    content:
                        application/pdf:
                            schema:
                                type: string
                                format: binary
                '404':
                    description: Template not found.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: template not found
                '409':
                    description: Unknown placeholders were provided that do not exist in the template.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: 'unknown placeholders: customer_email, due_date'
            tags:
                - templates
    /templates/list:
        post:
            summary: List available templates
            description: Returns a list of templates the current user can access.
            operationId: postTemplatesList
            security:
                - bearerAuth: []
            responses:
                '200':
                    description: Templates successfully retrieved.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    templates:
                                        type: array
                                        description: Collection of template objects.
                                        items:
                                            type: object
                                            properties:
                                                documentID:
                                                    type: string
                                                    description: Identifier for the document.
                                                    example: "statementOfClaim"
                                                created:
                                                    type: string
                                                    format: date-time
                                                    description: Timestamp when the template was created.
                                                    example: "2025-02-18T14:23:11Z"
                                                updated:
                                                    type: string
                                                    format: date-time
                                                    description: Timestamp when the template was last updated.
                                                    example: "2025-07-01T09:45:00Z"
                                                fields:
                                                    type: array
                                                    description: List of fields that define the template's structure.
                                                    items:
                                                        type: string
                                                        description: Unique identifier for the field.
                                                        example: "headline"
                                required:
                                    - templates
            tags:
                - templates
    /templates/render:
        post:
            summary: Render a PDF from a template with PNG content
            description: >
                Renders a PDF using a template, placeholder values, and optional uploaded files. **Multipart order is required**: 1. `documentID` (text), 2. `placeholders` (JSON; may be `{}`), 3. zero or more file parts named `file.<areaName>`.

                Each `contentAreas.<areaName>` part must be a PNG image.

                The entire request body must not exceed **10 MiB**.

            operationId: postTemplatesRender
            requestBody:
                required: true
                content:
                    multipart/form-data:
                        schema:
                            type: object
                            required:
                                - documentID
                                - placeholders
                            properties:
                                documentID:
                                    type: string
                                    description: Identifier of the template to render.
                                    example: "statementOfClaim"
                                placeholders:
                                    type: object
                                    description: JSON object mapping placeholder names to values. May be empty (`{}`).
                                    additionalProperties:
                                        type: string
                                    example:
                                        attempts_at_resolution: "Attempt I made"
                                        claim_details: "My claim details"
                                files:
                                    type: object
                                    description: >
                                        **Dynamic file parts**: zero or more parts named `file.<placeholderName>` (e.g. `file.qrCode`, `file.attachment`). Each part must be a PNG image.

                                    additionalProperties:
                                        type: string
                                        format: binary
                        encoding:
                            placeholders:
                                contentType: application/json
                            files:
                                contentType: image/png
            responses:
                '200':
                    description: PDF successfully rendered.
                    content:
                        application/pdf:
                            schema:
                                type: string
                                format: binary
                '404':
                    description: Template not found.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: template not found
                '410':
                    description: Invalid file name.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: File names must begin with 'file.'
                '411':
                    description: Invalid file type.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: Invalid file type.
                '413':
                    description: Request or part too large (over 10 MiB).
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: request entity too large
            tags:
                - templates
    /templates/upload:
        post:
            summary: Upload a PDF template
            description: Uploads a PDF file as a template for a given document.
            operationId: uploadTemplate
            security:
                - bearerAuth: []
            requestBody:
                required: true
                content:
                    multipart/form-data:
                        schema:
                            type: object
                            required:
                                - documentID
                                - file
                            properties:
                                documentID:
                                    type: string
                                    description: The ID of the document to attach the template to.
                                    example: "statementOfClaim"
                                file:
                                    type: string
                                    format: binary
                                    description: >
                                        The PDF file to upload (field name **file**). Must be ≤ 25 MiB.

                                    example: "template.pdf"
            responses:
                '200':
                    description: Template successfully uploaded.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: successfully uploaded template
                '404':
                    description: The target document was not found.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: document not found
                '410':
                    description: The provided fields are invalid for this document.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "invalid fields: Missing fields: systemFiledTime. Unrecognized fields: filedTime."
                '413':
                    description: The uploaded file is too large.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "file too large: max 25 MiB"
            tags:
                - templates
components:
    securitySchemes:
        bearerAuth:
            type: http
            description: access token
            scheme: bearer
            bearerFormat: JWT
tags:
    - name: /
    - name: templates