openapi: 3.0.0
info:
  title: QuietPDF Developer API
  version: 1.0.0
  description: |
    QuietPDF exposes an authenticated job-based API for PDF processing.

    Basic flow:
    1. Submit one or more files to `/process`.
    2. Poll `/jobs/{jobId}` until the job is complete.
    3. Download the output from `/jobs/{jobId}/download`.

    Core PDF processing, OCR, PDF to Word, and Word to PDF are available within fair-use limits.
    Some advanced features are not part of the current public API surface.

    Direct clients send `x-api-key`. RapidAPI subscribers send `X-RapidAPI-Key`
    and `X-RapidAPI-Host`; the RapidAPI gateway adds the private backend credential.

servers:
  - url: http://localhost:3000/api/v1
    description: Local Development
  - url: https://quietpdf.com/api/v1
    description: Production Server
  - url: https://quietpdf.p.rapidapi.com/api/v1
    description: RapidAPI Gateway

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
    RapidApiKeyAuth:
      type: apiKey
      in: header
      name: X-RapidAPI-Key
    RapidApiHost:
      type: apiKey
      in: header
      name: X-RapidAPI-Host

security:
  - ApiKeyAuth: []
  - RapidApiKeyAuth: []
    RapidApiHost: []

paths:
  /process:
    post:
      summary: Queue a processing job
      description: |
        Queues one or more processing jobs for the authenticated API account.
        Use repeated `file` fields for multi-file tools such as `merge-pdf` and `jpg-to-pdf`.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
                - tool
              properties:
                file:
                  type: string
                  format: binary
                  description: Input file. Repeat this field for multi-file tools.
                tool:
                  type: string
                  description: The tool slug (for example `compress-pdf`, `pdf-to-excel`, `split-pdf`, or `svg-to-png`). SVG requests accept width, height, preserveAspectRatio, scalePercent, pixelRatio, density, and background in the params JSON string.
                  example: compress-pdf
                params:
                  type: string
                  description: Optional JSON string with tool parameters.
                  example: '{"quality":"ebook"}'
                webhook_url:
                  type: string
                  format: uri
                  description: Optional HTTPS webhook URL for completion/failure notifications.
      responses:
        '202':
          description: Job accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  jobId:
                    type: string
                    nullable: true
                  jobIds:
                    type: array
                    items:
                      type: string
                  jobs:
                    type: array
                    items:
                      type: object
                      properties:
                        jobId:
                          type: string
                        statusUrl:
                          type: string
                        downloadUrl:
                          type: string
        '401':
          description: Invalid or missing API Key
        '403':
          description: API access is not enabled for this account
        '429':
          description: Quota Exceeded
        '503':
          description: Queue is busy
  /jobs/{jobId}:
    get:
      summary: Get job status
      parameters:
        - in: path
          name: jobId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Job status
        '401':
          description: Invalid or missing API Key
        '404':
          description: Job not found
  /jobs/{jobId}/download:
    get:
      summary: Download completed output
      parameters:
        - in: path
          name: jobId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Completed output file returned directly in free public beta mode
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '302':
          description: Redirects to a signed download URL outside free public beta mode
        '401':
          description: Invalid or missing API Key
        '404':
          description: Output file not available