openapi: 3.0.3
info:
  title: PDFThin API
  version: "1.0"
servers:
  - url: /
paths:
  /api/jobs:
    post:
      summary: Create a job
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: PDF file(s). Use multiple entries for organize mode.
                mode:
                  type: string
                  enum: [optimize, split, organize]
                preset:
                  type: string
                  enum: [gmail25, outlook20, outlook25, custom]
                  description: Required for size targets when quality is not set.
                custom_mb:
                  type: integer
                  description: Required when preset=custom.
                quality:
                  type: string
                  enum: [screen, ebook, printer, prepress]
                quality_mode:
                  type: string
                  enum: [smart]
                watermark:
                  type: string
                  format: binary
                notify_email:
                  type: string
                  description: Optional email address to notify when job completes.
                notify_when:
                  type: string
                  enum: [done]
      responses:
        "202":
          description: Accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobStatusResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "413":
          description: Too large
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/jobs/{id}:
    get:
      summary: Get job status
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobStatusResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    delete:
      summary: Delete job
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: No Content
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/jobs/{id}/download:
    get:
      summary: Download result
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: query
          name: index
          schema:
            type: integer
      responses:
        "303":
          description: See Other
        "200":
          description: File stream
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
    JobStatusResponse:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum: [queued, processing, done, failed, cancelled]
        progress_pct:
          type: integer
        expires_at:
          type: string
          format: date-time
        started_at:
          type: string
          format: date-time
        timeout_at:
          type: string
          format: date-time
        result:
          $ref: "#/components/schemas/JobResult"
        error:
          $ref: "#/components/schemas/JobError"
    JobResult:
      type: object
      properties:
        kind:
          type: string
          enum: [single, zip, parts]
        files:
          type: array
          items:
            $ref: "#/components/schemas/JobResultFile"
    JobResultFile:
      type: object
      properties:
        name:
          type: string
        size:
          type: integer
        download_url:
          type: string
    JobError:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
