@giveitsmaller/contracts 0.2.0 → 0.2.3

package/openapi/api.yaml

@@ -0,0 +1,2533 @@
+openapi: 3.1.0
+info:
+  title: GISL Compression API
+  description: |
+    REST API for the GISL (Give It Smaller) file compression and processing service.
+
+    **Architecture:**
+    - Upload files to get a `file_id`
+    - Create workflows referencing uploaded files with operations (compress, thumbnail, watermark, merge, archive, convert)
+    - Poll status, stream SSE events, or receive webhook callbacks
+    - Download results per operation output
+
+    **Response envelope:**
+    All mutation and query endpoints return `{ success: true, data: {...} }` on success
+    and `{ success: false, error: "...", details: [...] }` on failure.
+    Exceptions: `GET /api/operations/schema` returns raw JSON (CDN-cacheable),
+    health probes return flat objects, and `POST /api/contact` returns 204 with no body.
+  version: 2.0.0
+  contact:
+    name: API Support
+
+servers:
+  - url: http://localhost:8080
+    description: Local development
+  - url: https://api.staging.giveitsmaller.com
+    description: Staging environment
+
+tags:
+  - name: Upload
+    description: File upload operations (single and multipart)
+  - name: Workflow
+    description: Workflow creation, status, download, and real-time events
+  - name: Operations
+    description: Operation schema introspection and retry
+  - name: Health
+    description: Health check endpoints
+  - name: Contact
+    description: Contact form submissions
+
+paths:
+  # ============================================
+  # UPLOAD ENDPOINTS
+  # ============================================
+
+  /api/uploads:
+    post:
+      summary: Upload a file
+      description: |
+        Upload a single file for later use in workflows. Returns a `file_id` that can be
+        referenced when creating workflows.
+
+        No job or workflow is created — the file is stored in S3 and persisted in the
+        `uploads` table. Create a workflow via `POST /api/workflows` to process it.
+
+        For large files, use the multipart upload flow instead
+        (`POST /api/uploads/multipart/initiate`).
+      operationId: uploadFile
+      tags:
+        - Upload
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              $ref: '#/components/schemas/SingleUploadRequest'
+      responses:
+        '200':
+          description: File uploaded successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UploadSuccessEnvelope'
+              example:
+                success: true
+                data:
+                  file_id: "019539ab-1111-7000-8000-000000000001"
+                  original_name: "photo.jpg"
+                  mime_type: "image/jpeg"
+                  size_bytes: 2457600
+        '400':
+          description: Validation failed (missing file, invalid filename)
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "File is required"
+        '413':
+          description: File exceeds maximum upload size
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "File size exceeds maximum allowed (500MB)"
+        '415':
+          description: Unsupported file type
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "Unsupported MIME type: application/x-msdownload"
+        '429':
+          description: Rate limit exceeded
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
+  /api/uploads/multipart/initiate:
+    post:
+      summary: Initiate direct S3 multipart upload
+      description: |
+        Start a direct-to-S3 chunked upload. The client sends the first chunk (recommended
+        8MB) and the total file size. The API uses the first chunk for:
+        - MIME type detection (to validate supported formats)
+        - Upload throughput measurement (to calculate optimal chunk size)
+
+        The API stores the first chunk as S3 multipart upload part 1, calculates the
+        optimal chunk size and total number of parts, then returns pre-signed PUT URLs
+        for the remaining parts. The client uploads parts 2-N directly to S3.
+
+        **Chunk sizing strategy:**
+        - First chunk: fixed 8MB (sent to API)
+        - Remaining chunks: API calculates `recommended_chunk_size` from throughput * 5s,
+          clamped to 5MB-100MB
+        - The last part may be smaller than 5MB (S3 allows this for the final part)
+        - Maximum 500 parts per upload
+
+        **Pre-signed URL TTL:**
+        Dynamic based on estimated upload duration * 2, clamped between 900s and 3600s.
+
+        After all parts are uploaded to S3, call the complete endpoint to finalise.
+      operationId: multipartInitiate
+      tags:
+        - Upload
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              $ref: '#/components/schemas/MultipartInitiateRequest'
+      responses:
+        '200':
+          description: Multipart upload initiated, pre-signed URLs returned
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MultipartInitiateSuccessEnvelope'
+              example:
+                success: true
+                data:
+                  upload_id: "019539ab-1111-7000-8000-000000000001"
+                  mime_type: "image/jpeg"
+                  first_chunk_etag: '"d8e8fca2dc0f896fd7cb4cb0031ba249"'
+                  first_chunk_size_bytes: 8388608
+                  total_parts: 5
+                  recommended_chunk_size: 10485760
+                  presigned_urls:
+                    - part_number: 2
+                      url: "https://gisl-stg-euw1-input.s3.eu-west-1.amazonaws.com/uploads/...?X-Amz-Expires=1800&..."
+                      expires_at: "2026-03-06T12:30:00.000Z"
+                    - part_number: 3
+                      url: "https://gisl-stg-euw1-input.s3.eu-west-1.amazonaws.com/uploads/...?X-Amz-Expires=1800&..."
+                      expires_at: "2026-03-06T12:30:00.000Z"
+        '400':
+          description: Validation failed (missing fields, invalid file)
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "File is required"
+        '413':
+          description: File exceeds maximum upload size
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '415':
+          description: Unsupported file type
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '429':
+          description: Rate limit exceeded
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
+  /api/uploads/multipart/complete:
+    post:
+      summary: Complete direct S3 multipart upload
+      description: |
+        Finalise a direct-to-S3 multipart upload after all parts have been uploaded.
+
+        The client sends the `upload_id` (from the initiate response) and an array of
+        part ETags collected from the S3 PUT responses for parts 2-N. The API already
+        has the part 1 ETag from the initiate step.
+
+        The API calls S3 CompleteMultipartUpload and persists the upload record.
+        No job or workflow is created — use `POST /api/workflows` to process the file.
+      operationId: multipartComplete
+      tags:
+        - Upload
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/MultipartCompleteRequest'
+      responses:
+        '201':
+          description: |
+            Upload completed successfully. The returned `upload_id` is the identifier
+            of the finalised upload and can be passed as `file_id` when creating
+            workflows via `POST /api/workflows`. File metadata (original name, MIME
+            type, size) is available from `GET /api/uploads/{id}/metadata` if the
+            client did not retain the values captured during initiate.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MultipartCompleteSuccessEnvelope'
+              example:
+                success: true
+                data:
+                  upload_id: "019539ab-1111-7000-8000-000000000001"
+                  status: "completed"
+        '400':
+          description: Invalid upload_id, missing parts, or ETag mismatch
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "Missing ETags for parts: 3, 5"
+        '404':
+          description: Upload session not found or expired
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "Upload session not found or expired"
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
+  /api/uploads/{id}/metadata:
+    get:
+      summary: Get file metadata
+      description: |
+        Returns metadata extracted from an uploaded file. Useful for inspecting files
+        before building workflows (e.g. check dimensions to decide if resize is needed,
+        check codec to decide on compression options).
+
+        Fields vary by MIME type:
+        - **Images:** dimensions, color_space, dpi, has_alpha, exif, dominant_colors
+        - **Video:** dimensions, duration, codec, fps, audio_codec, bitrate
+        - **Audio:** duration, bitrate, channels, sample_rate, codec
+        - **Documents:** page_count, dimensions (for PDF)
+      operationId: getUploadMetadata
+      tags:
+        - Upload
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: Upload file ID (UUID v7)
+          schema:
+            $ref: '#/components/schemas/UuidV7'
+      responses:
+        '200':
+          description: File metadata retrieved
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MetadataSuccessEnvelope'
+              example:
+                success: true
+                data:
+                  file_id: "019539ab-1111-7000-8000-000000000001"
+                  original_name: "photo.jpg"
+                  mime_type: "image/jpeg"
+                  size_bytes: 4521984
+                  dimensions:
+                    width: 4032
+                    height: 3024
+                  color_space: "sRGB"
+                  dpi: 72
+                  has_alpha: false
+                  exif:
+                    camera: "iPhone 15 Pro"
+                    datetime: "2026-03-01T14:30:00Z"
+                    gps:
+                      lat: 51.5074
+                      lon: -0.1278
+                    copyright: null
+                  dominant_colors:
+                    - "#2a5c3f"
+                    - "#8b6f4e"
+                    - "#d4c5a9"
+        '404':
+          description: Upload not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
+  # ============================================
+  # WORKFLOW ENDPOINTS
+  # ============================================
+
+  /api/workflows:
+    post:
+      summary: Create a workflow
+      description: |
+        Create a workflow containing one or more jobs, each with one or more operations.
+        Jobs reference uploaded files by `file_id`, or depend on other jobs via `source`
+        (for single-input downstream jobs) or `inputs` (for multi-input jobs like merge/archive).
+
+        **Job source types (exactly one required per job):**
+        - `file_id`: Reference an uploaded file directly
+        - `source`: Reference another job's output (for DAG pipelines)
+        - `inputs`: Reference multiple job outputs (for merge/archive)
+
+        **Workflow edges** define job dependencies as a DAG. Jobs with no dependencies
+        start immediately. Jobs with dependencies wait for upstream jobs to complete.
+
+        **Default operation:** If `operations` is omitted on a single-input job with
+        `file_id`, the default is `[{ "type": "compress" }]` with default options for
+        the detected MIME type. Multi-input jobs must always specify operations explicitly.
+
+        **Multi-input constraint:** Multi-input jobs must have exactly one operation,
+        which must be a multi-input type (`merge` or `archive`). Chaining after a
+        multi-input operation is not valid — create a downstream edge-sourced job instead.
+      operationId: createWorkflow
+      tags:
+        - Workflow
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/WorkflowCreateRequest'
+      responses:
+        '201':
+          description: Workflow created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/WorkflowCreateSuccessEnvelope'
+              examples:
+                simple:
+                  summary: Single file, single operation
+                  value:
+                    success: true
+                    data:
+                      workflow_id: "019539ac-2222-7000-8000-000000000001"
+                      status: "pending"
+                      jobs:
+                        - ref: "main"
+                          job_id: "019539ad-3333-7000-8000-000000000001"
+                          status: "pending"
+                          depends_on: []
+                          operations:
+                            - id: "019539ae-4444-7000-8000-000000000001"
+                              type: "compress"
+                              status: "pending"
+                batch:
+                  summary: Batch compress (3 independent files)
+                  value:
+                    success: true
+                    data:
+                      workflow_id: "019539ac-2222-7000-8000-000000000002"
+                      status: "pending"
+                      jobs:
+                        - ref: "file1"
+                          job_id: "019539ad-3333-7000-8000-000000000002"
+                          status: "pending"
+                          depends_on: []
+                          operations:
+                            - id: "019539ae-4444-7000-8000-000000000002"
+                              type: "compress"
+                              status: "pending"
+                        - ref: "file2"
+                          job_id: "019539ad-3333-7000-8000-000000000003"
+                          status: "pending"
+                          depends_on: []
+                          operations:
+                            - id: "019539ae-4444-7000-8000-000000000003"
+                              type: "compress"
+                              status: "pending"
+                        - ref: "file3"
+                          job_id: "019539ad-3333-7000-8000-000000000004"
+                          status: "pending"
+                          depends_on: []
+                          operations:
+                            - id: "019539ae-4444-7000-8000-000000000004"
+                              type: "compress"
+                              status: "pending"
+        '400':
+          description: Validation failed (malformed request body)
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '404':
+          description: Referenced file_id not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "Upload not found: 019539ab-1111-7000-8000-999999999999"
+        '422':
+          description: |
+            Semantically invalid request. Valid JSON but contains errors such as:
+            unknown operation type, invalid option combinations, cyclic dependency
+            in workflow_edges, multi-input job with multiple operations, or
+            source ref pointing to a non-existent job.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ValidationErrorEnvelope'
+              example:
+                success: false
+                error: "INVALID_OPTIONS"
+                details:
+                  - operation: "compress"
+                    option: "quality"
+                    message: "Must be between 1 and 100"
+                  - operation: "thumbnail"
+                    option: "width"
+                    message: "Required field"
+        '429':
+          description: Rate limit exceeded
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
+  /api/workflows/{id}/status:
+    get:
+      summary: Get workflow status
+      description: |
+        Retrieve the current status of a workflow with nested job and operation breakdown.
+        Each operation includes its current progress and, when completed, its result
+        (download URL, size, metrics).
+      operationId: getWorkflowStatus
+      tags:
+        - Workflow
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: Workflow ID (UUID v7)
+          schema:
+            $ref: '#/components/schemas/UuidV7'
+      responses:
+        '200':
+          description: Workflow status retrieved
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/WorkflowStatusSuccessEnvelope'
+              examples:
+                in_progress:
+                  summary: Workflow in progress
+                  value:
+                    success: true
+                    data:
+                      workflow_id: "019539ac-2222-7000-8000-000000000001"
+                      status: "in_progress"
+                      jobs:
+                        - ref: "main"
+                          job_id: "019539ad-3333-7000-8000-000000000001"
+                          status: "in_progress"
+                          depends_on: []
+                          operations:
+                            - id: "019539ae-4444-7000-8000-000000000001"
+                              type: "compress"
+                              status: "in_progress"
+                              progress: 65
+                completed:
+                  summary: Workflow completed
+                  value:
+                    success: true
+                    data:
+                      workflow_id: "019539ac-2222-7000-8000-000000000001"
+                      status: "completed"
+                      jobs:
+                        - ref: "main"
+                          job_id: "019539ad-3333-7000-8000-000000000001"
+                          status: "completed"
+                          depends_on: []
+                          operations:
+                            - id: "019539ae-4444-7000-8000-000000000001"
+                              type: "compress"
+                              status: "completed"
+                              result:
+                                download_url: "https://cdn.giveitsmaller.com/jobs/019539ad-.../019539ae-.../photo.jpg?token=..."
+                                size_bytes: 1105920
+                                metrics:
+                                  compression_ratio: 0.45
+                                  duration_ms: 2340
+        '404':
+          description: Workflow not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
+  /api/workflows/{id}/downloads:
+    get:
+      summary: Get download URLs
+      description: |
+        Get download URLs for all completed operation outputs in a workflow.
+        Each job's operations are listed with their output files and pre-signed
+        download URLs.
+      operationId: getWorkflowDownloads
+      tags:
+        - Workflow
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: Workflow ID (UUID v7)
+          schema:
+            $ref: '#/components/schemas/UuidV7'
+      responses:
+        '200':
+          description: Download URLs retrieved
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/WorkflowDownloadSuccessEnvelope'
+              example:
+                success: true
+                data:
+                  downloads:
+                    - ref: "main"
+                      job_id: "019539ad-3333-7000-8000-000000000001"
+                      files:
+                        - operation: "compress"
+                          operation_id: "019539ae-4444-7000-8000-000000000001"
+                          filename: "photo.jpg"
+                          size_bytes: 1105920
+                          download_url: "https://cdn.giveitsmaller.com/jobs/019539ad-.../019539ae-.../photo.jpg?token=..."
+        '404':
+          description: Workflow not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
+  /api/workflows/{id}/events:
+    get:
+      summary: Stream workflow events (SSE)
+      description: |
+        Server-Sent Events endpoint for real-time workflow progress. The server pushes
+        events as workflow, job, and operation statuses change.
+
+        The connection stays open until the workflow reaches a terminal state
+        (`completed`, `failed`, `partially_failed`) or the client disconnects.
+
+        **Event types:**
+        - `operation.progress` — operation progress update (progress percentage)
+        - `operation.completed` — individual operation finished successfully
+        - `operation.failed` — individual operation failed
+        - `job.completed` — all operations in a job finished
+        - `job.failed` — job failed
+        - `workflow.completed` — all jobs completed successfully
+        - `workflow.failed` — all jobs finished, at least one failed
+        - `workflow.partially_failed` — some jobs succeeded, some failed
+
+        **Event data format:**
+        ```
+        event: operation.progress
+        data: {"job_ref":"main","operation_id":"op-uuid","type":"compress","progress":65}
+
+        event: operation.completed
+        data: {"job_ref":"main","operation_id":"op-uuid","type":"compress","status":"completed","progress":100}
+
+        event: workflow.completed
+        data: {"workflow_id":"wf-uuid","status":"completed"}
+        ```
+      operationId: streamWorkflowEvents
+      tags:
+        - Workflow
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: Workflow ID (UUID v7)
+          schema:
+            $ref: '#/components/schemas/UuidV7'
+      responses:
+        '200':
+          description: SSE event stream
+          content:
+            text/event-stream:
+              schema:
+                type: string
+                description: |
+                  Server-Sent Events stream. Each event has an `event` field (type)
+                  and a `data` field (JSON payload). See endpoint description for
+                  event types and payload shapes.
+        '404':
+          description: Workflow not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
+  # ============================================
+  # OPERATIONS ENDPOINTS
+  # ============================================
+
+  /api/operations/schema:
+    get:
+      summary: Get operation schema
+      description: |
+        Returns the operations schema describing all available operation types,
+        their options, constraints, and defaults — grouped by MIME type.
+
+        **This endpoint does NOT use the standard ResponseEnvelope.** It returns
+        the raw schema JSON directly for CDN cacheability (static resource).
+
+        Supports optional query parameters to filter the schema:
+        - `mime_type`: Filter to operations available for a specific MIME type
+        - `operation`: Filter to a specific operation type
+
+        The schema includes conditional validation rules using `depends_on`
+        (e.g. `quality` is only valid when `mode: lossy`). Clients should use
+        these to build dynamic forms.
+      operationId: getOperationsSchema
+      tags:
+        - Operations
+      parameters:
+        - name: mime_type
+          in: query
+          required: false
+          description: Filter by MIME type (e.g. `image/jpeg`, `video/mp4`)
+          schema:
+            type: string
+            example: "image/jpeg"
+        - name: operation
+          in: query
+          required: false
+          description: Filter by operation type
+          schema:
+            $ref: '#/components/schemas/OperationType'
+      responses:
+        '200':
+          description: Operation schema (raw JSON, no ResponseEnvelope)
+          headers:
+            Cache-Control:
+              schema:
+                type: string
+              description: Cache headers for CDN
+              example: "public, max-age=3600"
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OperationsSchemaResponse'
+              examples:
+                full_schema:
+                  summary: Full schema (truncated for brevity)
+                  value:
+                    schema_version: "1.0.0"
+                    operations:
+                      compress:
+                        description: "Reduce file size while maintaining acceptable quality"
+                        default: true
+                        input_model: "single"
+                        options:
+                          mode:
+                            type: "enum"
+                            values: ["lossy", "lossless", "auto"]
+                          quality:
+                            type: "integer"
+                            min: 1
+                            max: 100
+                            depends_on:
+                              mode: "lossy"
+                          width:
+                            type: "integer"
+                            min: 1
+                            max: 16384
+                          height:
+                            type: "integer"
+                            min: 1
+                            max: 16384
+                      thumbnail:
+                        description: "Generate a preview image from the source file"
+                        default: false
+                        input_model: "single"
+                        options:
+                          width:
+                            type: "integer"
+                            min: 1
+                            max: 4096
+                            required: true
+                          height:
+                            type: "integer"
+                            min: 1
+                            max: 4096
+                            required: true
+                          fit:
+                            type: "enum"
+                            values: ["max", "crop", "scale"]
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
+  /api/operations/{id}/retry:
+    post:
+      summary: Retry a failed operation
+      description: |
+        Retry a failed operation without recreating the entire workflow. Creates a new
+        operation that replaces the failed one, using the same source file and options.
+
+        The original failed operation is marked as `retried` and a new operation with
+        a new ID is created in `pending` state.
+      operationId: retryOperation
+      tags:
+        - Operations
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: Failed operation ID (UUID v7)
+          schema:
+            $ref: '#/components/schemas/UuidV7'
+      responses:
+        '202':
+          description: Retry accepted, new operation queued
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RetrySuccessEnvelope'
+              example:
+                success: true
+                data:
+                  operation_id: "019539af-5555-7000-8000-000000000001"
+                  original_operation_id: "019539ae-4444-7000-8000-000000000001"
+                  status: "pending"
+        '404':
+          description: Operation not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '409':
+          description: Operation is not in a failed state, or has already been retried
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "Operation is not in a failed state"
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
+  # ============================================
+  # HEALTH ENDPOINTS
+  # ============================================
+
+  /healthz:
+    get:
+      summary: Liveness probe
+      description: Kubernetes liveness probe endpoint
+      operationId: liveness
+      tags:
+        - Health
+      responses:
+        '200':
+          description: Application is alive
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/LivenessResponse'
+              example:
+                app: true
+
+  /readyz:
+    get:
+      summary: Readiness probe
+      description: Kubernetes readiness probe endpoint - checks database and cache connectivity
+      operationId: readiness
+      tags:
+        - Health
+      responses:
+        '200':
+          description: Application is ready to receive traffic
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ReadinessResponse'
+        '503':
+          description: Application is not ready
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ReadinessResponse'
+
+  # ============================================
+  # CONTACT ENDPOINT
+  # ============================================
+
+  /api/contact:
+    post:
+      summary: Submit contact form
+      description: |
+        Submit a contact form message. All fields except `name` and `website` are required.
+
+        The `website` field is a honeypot for bot detection. It is hidden from real users
+        via CSS. Legitimate submissions must omit this field or send an empty string.
+        The API rejects any request where `website` is non-empty.
+
+        On success, returns 204 with no body. The API sends the message via its
+        configured delivery channel (e.g. email, queue).
+      operationId: submitContact
+      tags:
+        - Contact
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ContactRequest'
+            example:
+              name: "Jane Doe"
+              email: "jane@example.com"
+              subject: "general_enquiry"
+              message: "I have a question about supported file formats."
+      responses:
+        '204':
+          description: Contact form submitted successfully. No response body.
+        '400':
+          description: Validation failed - one or more fields are invalid
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ContactValidationErrorResponse'
+              example:
+                errors:
+                  email:
+                    - "This value is not a valid email address."
+                  message:
+                    - "This field is required."
+        '429':
+          description: Rate limit exceeded
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
+# ============================================
+# WEBHOOKS (outbound callbacks to consumer URLs)
+# ============================================
+
+webhooks:
+  workflowCallback:
+    post:
+      summary: Workflow event callback
+      operationId: webhookWorkflowCallback
+      description: |
+        POSTed to the `callback_url` provided in `WorkflowCreateRequest` when a
+        subscribed event occurs. The consumer endpoint must return a 2xx status
+        to acknowledge receipt.
+      parameters:
+        - name: X-GIS-Signature
+          in: header
+          required: true
+          schema:
+            type: string
+            pattern: '^sha256=[0-9a-f]{64}$'
+          description: |
+            HMAC-SHA256 signature of the raw request body using the per-workflow
+            `webhook_secret` as the key. Format: `sha256=<hex-digest>`.
+
+            Verification pseudocode:
+            ```
+            expected = "sha256=" + hex(hmac_sha256(webhook_secret, raw_body))
+            valid = constant_time_equal(header_value, expected)
+            ```
+          example: "sha256=a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/WebhookPayload'
+      responses:
+        '200':
+          description: Callback acknowledged
+        '202':
+          description: Callback accepted for processing
+        '204':
+          description: Callback acknowledged (no body)
+
+components:
+  schemas:
+    # ============================================
+    # SHARED PRIMITIVES
+    # ============================================
+
+    UuidV7:
+      type: string
+      format: uuid
+      pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$'
+      description: UUID v7 format identifier (time-ordered)
+      example: "019539ab-1111-7000-8000-000000000001"
+
+    # ============================================
+    # RESPONSE ENVELOPES
+    # ============================================
+
+    ResponseEnvelope:
+      type: object
+      description: |
+        Standard response wrapper. All API responses (except GET /api/operations/schema,
+        health probes, and POST /api/contact) use this envelope.
+        Success: `{ success: true, data: {...} }`.
+        Error: `{ success: false, error: "...", details: [...] }`.
+      required:
+        - success
+      properties:
+        success:
+          type: boolean
+
+    ErrorEnvelope:
+      type: object
+      description: Error response envelope
+      required:
+        - success
+        - error
+      properties:
+        success:
+          type: boolean
+          const: false
+        error:
+          type: string
+          description: Human-readable error message
+
+    ValidationErrorEnvelope:
+      type: object
+      description: |
+        Validation error response with structured details.
+        Used for 422 responses where multiple validation issues are reported.
+      required:
+        - success
+        - error
+        - details
+      properties:
+        success:
+          type: boolean
+          const: false
+        error:
+          type: string
+          description: Error code (e.g. "INVALID_OPTIONS")
+        details:
+          type: array
+          description: List of individual validation errors
+          items:
+            type: object
+            required:
+              - message
+            properties:
+              operation:
+                type: string
+                description: Operation type where the error occurred
+              option:
+                type: string
+                description: Option name that failed validation
+              field:
+                type: string
+                description: Field path for non-operation validation errors
+              message:
+                type: string
+                description: Human-readable error message
+
+    # ============================================
+    # STATUS ENUMS
+    # ============================================
+
+    WorkflowStatus:
+      type: string
+      description: |
+        Workflow lifecycle status:
+        - pending: Created but no jobs have started
+        - in_progress: At least one job is running
+        - completed: All jobs completed successfully
+        - failed: All jobs finished, at least one failed, none succeeded
+        - partially_failed: Some jobs succeeded, some failed
+      enum:
+        - pending
+        - in_progress
+        - completed
+        - failed
+        - partially_failed
+
+    JobStatus:
+      type: string
+      description: |
+        Job lifecycle status:
+        - pending: Created, waiting to be scheduled
+        - waiting: Blocked by upstream job dependencies (workflow_edges)
+        - in_progress: At least one operation is running
+        - completed: All operations completed successfully
+        - failed: Job failed (at least one operation failed)
+      enum:
+        - pending
+        - waiting
+        - in_progress
+        - completed
+        - failed
+
+    OperationStatus:
+      type: string
+      description: |
+        Operation lifecycle status:
+        - pending: Created, waiting to start
+        - in_progress: Currently processing
+        - completed: Finished successfully
+        - failed: Encountered an error
+        - retried: Failed and replaced by a new retry operation
+      enum:
+        - pending
+        - in_progress
+        - completed
+        - failed
+        - retried
+
+    # ============================================
+    # OPERATION & JOB TYPES
+    # ============================================
+
+    OperationType:
+      type: string
+      description: |
+        Available operation types:
+        - compress: Reduce file size (images, audio, video, documents)
+        - thumbnail: Legacy thumbnail value. Generates a preview image
+          for any media type via a single Lambda. Currently the only
+          thumbnail value the compression_api publisher emits; retirement
+          is planned after the publisher adopts the four sub-type values
+          below in a follow-up API PR.
+        - thumbnail_image: Image thumbnail sub-type. Backed by a dedicated
+          Rust image Lambda. Not yet emitted by the publisher.
+        - thumbnail_video: Video thumbnail sub-type. Backed by a dedicated
+          FFmpeg Lambda. Not yet emitted.
+        - thumbnail_document: PDF/EPUB thumbnail sub-type. Backed by a
+          dedicated Ghostscript Lambda. Not yet emitted.
+        - thumbnail_office: Office document (DOCX/XLSX/PPTX/ODT/ODS/ODP)
+          thumbnail sub-type. Backed by a dedicated LibreOffice Lambda.
+          Not yet emitted.
+        - watermark: Apply branding/protection (images only)
+        - merge: Concatenate/combine multiple files into one (images, video, audio, documents/PDF). Multi-input.
+        - archive: Bundle files into ZIP/tar.gz (all types). Multi-input.
+        - convert: Change file format (all types)
+
+        Both the legacy `thumbnail` value and the four sub-type values
+        are valid routing targets today during the thumbnail migration
+        window. See `asyncapi/events.yaml` for the full routing
+        vocabulary and the publisher branching rule.
+      enum:
+        - compress
+        - thumbnail
+        - thumbnail_image
+        - thumbnail_video
+        - thumbnail_document
+        - thumbnail_office
+        - watermark
+        - merge
+        - archive
+        - convert
+
+    OperationInputModel:
+      type: string
+      description: |
+        Whether the operation accepts a single file or multiple files:
+        - single: One input file (compress, thumbnail, thumbnail_image,
+          thumbnail_video, thumbnail_document, thumbnail_office,
+          watermark, convert)
+        - multi: Multiple input files (merge, archive)
+      enum:
+        - single
+        - multi
+
+    JobType:
+      type: string
+      description: |
+        Media type category derived from MIME type. Used as the
+        `job_type` SNS message attribute on the `job-requests` topic —
+        the single filter attribute that routes compression traffic to
+        per-media-type compression queues. Not used by any other SNS
+        topic; non-compression operations are routed by `operation_type`
+        on the separate `operations` topic.
+
+        Derivation:
+        - image/* -> image
+        - video/* -> video
+        - audio/* -> audio
+        - document types -> document (PDF, DOCX, XLSX, PPTX, ODT, ODS, ODP, EPUB)
+      enum:
+        - image
+        - video
+        - audio
+        - document
+
+    # ============================================
+    # UPLOAD SCHEMAS
+    # ============================================
+
+    SingleUploadRequest:
+      type: object
+      required:
+        - file
+      properties:
+        file:
+          type: string
+          format: binary
+          description: The file to upload
+        filename:
+          type: string
+          maxLength: 255
+          pattern: '^[^/\\]+$'
+          description: |
+            Original filename with extension (e.g. "photo.jpg").
+            Optional — browsers include filename automatically in multipart uploads.
+            Must not contain directory separators (/ or \).
+          example: "photo.jpg"
+
+    UploadResponse:
+      type: object
+      description: Upload result data (same shape for single and multipart complete)
+      required:
+        - file_id
+        - original_name
+        - mime_type
+        - size_bytes
+      properties:
+        file_id:
+          $ref: '#/components/schemas/UuidV7'
+          description: Unique file identifier for use in workflow creation
+        original_name:
+          type: string
+          description: Original filename
+          example: "photo.jpg"
+        mime_type:
+          type: string
+          description: Detected MIME type
+          example: "image/jpeg"
+        size_bytes:
+          type: integer
+          format: int64
+          minimum: 1
+          description: File size in bytes
+          example: 2457600
+
+    UploadSuccessEnvelope:
+      type: object
+      required:
+        - success
+        - data
+      properties:
+        success:
+          type: boolean
+          const: true
+        data:
+          $ref: '#/components/schemas/UploadResponse'
+
+    MultipartInitiateRequest:
+      type: object
+      required:
+        - file
+        - filename
+        - total_size
+      properties:
+        file:
+          type: string
+          format: binary
+          description: |
+            First chunk of the file (recommended 8MB).
+            Used for MIME type detection and throughput measurement.
+            Stored as S3 multipart upload part 1.
+        filename:
+          type: string
+          maxLength: 255
+          pattern: '^[^/\\]+$'
+          description: Original filename with extension. Must not contain directory separators.
+          example: "photo.jpg"
+        total_size:
+          type: integer
+          format: int64
+          minimum: 1
+          description: Total file size in bytes (all chunks combined)
+
+    MultipartInitiateResponse:
+      type: object
+      required:
+        - upload_id
+        - mime_type
+        - first_chunk_etag
+        - first_chunk_size_bytes
+        - total_parts
+        - recommended_chunk_size
+        - presigned_urls
+      properties:
+        upload_id:
+          $ref: '#/components/schemas/UuidV7'
+          description: |
+            Multipart upload session identifier. Pass this as `upload_id` in the
+            complete request; after completion, pass the same value as `file_id`
+            when creating workflows via `POST /api/workflows`.
+        mime_type:
+          type: string
+          description: MIME type detected from the first chunk
+          example: "image/jpeg"
+        first_chunk_etag:
+          type: string
+          description: ETag of the first chunk stored as S3 part 1
+          example: '"d8e8fca2dc0f896fd7cb4cb0031ba249"'
+        first_chunk_size_bytes:
+          type: integer
+          description: Size of the first chunk received (for client validation)
+          example: 8388608
+        total_parts:
+          type: integer
+          minimum: 2
+          maximum: 500
+          description: |
+            Total number of parts. The client slices the remaining file into
+            exactly (total_parts - 1) chunks using recommended_chunk_size.
+            The last chunk may be smaller.
+          example: 5
+        recommended_chunk_size:
+          type: integer
+          minimum: 5242880
+          maximum: 104857600
+          description: |
+            Chunk size in bytes for remaining parts. Calculated from first chunk
+            throughput * 5s target, clamped to 5MB-100MB. The last chunk may be
+            smaller than 5MB.
+          example: 10485760
+        presigned_urls:
+          type: array
+          description: |
+            Pre-signed S3 PUT URLs for parts 2 through total_parts.
+            Each URL accepts a PUT request with raw chunk bytes as body.
+            Collect the ETag from each S3 response for the complete request.
+          items:
+            $ref: '#/components/schemas/PresignedUrlPart'
+
+    MultipartInitiateSuccessEnvelope:
+      type: object
+      required:
+        - success
+        - data
+      properties:
+        success:
+          type: boolean
+          const: true
+        data:
+          $ref: '#/components/schemas/MultipartInitiateResponse'
+
+    PresignedUrlPart:
+      type: object
+      required:
+        - part_number
+        - url
+        - expires_at
+      properties:
+        part_number:
+          type: integer
+          minimum: 2
+          description: S3 multipart part number (starts at 2, API handled part 1)
+        url:
+          type: string
+          format: uri
+          description: Pre-signed S3 PUT URL. Send PUT with raw binary chunk as body.
+        expires_at:
+          type: string
+          format: date-time
+          description: |
+            ISO 8601 expiry timestamp. TTL is dynamic: estimated_upload_duration * 2,
+            clamped between 900s and 3600s.
+
+    MultipartCompleteRequest:
+      type: object
+      required:
+        - upload_id
+        - parts
+      properties:
+        upload_id:
+          $ref: '#/components/schemas/UuidV7'
+          description: Multipart upload session identifier from the initiate response
+        parts:
+          type: array
+          description: |
+            ETags for parts 2 through total_parts, collected from S3 PUT responses.
+            Part 1 ETag is already known from the initiate step.
+          minItems: 1
+          items:
+            type: object
+            required:
+              - part_number
+              - etag
+            properties:
+              part_number:
+                type: integer
+                minimum: 2
+                description: S3 part number (must match presigned_urls part_number)
+              etag:
+                type: string
+                description: ETag from S3 PUT response header
+                example: '"d8e8fca2dc0f896fd7cb4cb0031ba249"'
+
+    MultipartCompleteResponse:
+      type: object
+      description: |
+        Result of finalising a multipart upload. Intentionally narrower than
+        `UploadResponse` (single-upload shape) — the server returns only the
+        finalised `upload_id` and a completion status. Clients who need file
+        metadata (original name, MIME type, size) can use the values captured
+        during initiate, or call `GET /api/uploads/{id}/metadata`.
+      required:
+        - upload_id
+        - status
+      properties:
+        upload_id:
+          $ref: '#/components/schemas/UuidV7'
+          description: |
+            Identifier of the finalised upload. Pass this as `file_id` when
+            creating workflows via `POST /api/workflows` — the `file_id`
+            parameter on the workflows endpoint accepts any upload identifier.
+        status:
+          type: string
+          enum:
+            - completed
+          description: Terminal status of the multipart upload session.
+
+    MultipartCompleteSuccessEnvelope:
+      type: object
+      required:
+        - success
+        - data
+      properties:
+        success:
+          type: boolean
+          const: true
+        data:
+          $ref: '#/components/schemas/MultipartCompleteResponse'
+
+    # ============================================
+    # METADATA SCHEMAS
+    # ============================================
+
+    MetadataResponse:
+      type: object
+      description: |
+        File metadata. Fields vary by MIME type. Common fields are always present;
+        type-specific fields (dimensions, exif, duration, etc.) are included when
+        available for the file type.
+      required:
+        - file_id
+        - original_name
+        - mime_type
+        - size_bytes
+      properties:
+        file_id:
+          $ref: '#/components/schemas/UuidV7'
+        original_name:
+          type: string
+          example: "photo.jpg"
+        mime_type:
+          type: string
+          example: "image/jpeg"
+        size_bytes:
+          type: integer
+          format: int64
+          example: 4521984
+        # Image fields
+        dimensions:
+          type: object
+          description: Image/video dimensions (images, video, PDF)
+          properties:
+            width:
+              type: integer
+              example: 4032
+            height:
+              type: integer
+              example: 3024
+        color_space:
+          type: string
+          description: Color space (images)
+          example: "sRGB"
+        dpi:
+          type: integer
+          description: Dots per inch (images, PDF)
+          example: 72
+        has_alpha:
+          type: boolean
+          description: Whether the image has an alpha channel (images)
+        exif:
+          type: object
+          description: EXIF metadata (images)
+          properties:
+            camera:
+              type: string
+              example: "iPhone 15 Pro"
+            datetime:
+              type: string
+              format: date-time
+            gps:
+              type: object
+              properties:
+                lat:
+                  type: number
+                  format: double
+                lon:
+                  type: number
+                  format: double
+            copyright:
+              type:
+                - string
+                - "null"
+        dominant_colors:
+          type: array
+          description: Dominant colors as hex strings (images)
+          items:
+            type: string
+            pattern: '^#[0-9a-fA-F]{6}$'
+          example: ["#2a5c3f", "#8b6f4e", "#d4c5a9"]
+        # Video/Audio fields
+        duration:
+          type: number
+          format: double
+          description: Duration in seconds (video, audio)
+        codec:
+          type: string
+          description: Video/audio codec
+        fps:
+          type: number
+          format: double
+          description: Frames per second (video)
+        audio_codec:
+          type: string
+          description: Audio codec (video)
+        bitrate:
+          type: integer
+          description: Bitrate in bps (video, audio)
+        channels:
+          type: integer
+          description: Audio channels (audio)
+        sample_rate:
+          type: integer
+          description: Sample rate in Hz (audio)
+        # Document fields
+        page_count:
+          type: integer
+          description: Number of pages (documents)
+
+    MetadataSuccessEnvelope:
+      type: object
+      required:
+        - success
+        - data
+      properties:
+        success:
+          type: boolean
+          const: true
+        data:
+          $ref: '#/components/schemas/MetadataResponse'
+
+    # ============================================
+    # WORKFLOW REQUEST SCHEMAS
+    # ============================================
+
+    WorkflowCreateRequest:
+      type: object
+      required:
+        - jobs
+      properties:
+        jobs:
+          type: array
+          description: List of jobs in this workflow
+          minItems: 1
+          items:
+            $ref: '#/components/schemas/JobDefinition'
+        workflow_edges:
+          type: array
+          description: |
+            DAG dependency edges between jobs. Each edge defines that a downstream
+            job depends on an upstream job's output. Jobs with no incoming edges
+            start immediately. Jobs with dependencies wait for all upstream jobs.
+          items:
+            $ref: '#/components/schemas/WorkflowEdge'
+        callback_url:
+          type:
+            - string
+            - "null"
+          format: uri
+          pattern: '^https://'
+          description: |
+            Webhook URL (HTTPS only). The API POSTs a `WebhookPayload` JSON body to
+            this URL when matching events occur. The payload includes event type,
+            delivery ID, timestamp, and full workflow state with job results and
+            download URLs. Must use HTTPS to prevent credential leakage and SSRF
+            against internal endpoints.
+
+            **Signature verification:**
+            Each request includes an `X-GIS-Signature` header containing an
+            HMAC-SHA256 hex digest of the raw request body, using the per-workflow
+            `webhook_secret` (returned in the workflow creation response) as the key.
+            Header format: `sha256=<hex(hmac-sha256(webhook_secret, raw_body))>`.
+            Consumers MUST verify the signature before processing the payload.
+        callback_events:
+          type: array
+          description: |
+            Which events trigger the webhook callback. Defaults to terminal events only.
+          items:
+            $ref: '#/components/schemas/CallbackEventType'
+          default:
+            - "workflow.completed"
+            - "workflow.failed"
+            - "workflow.partially_failed"
+        export:
+          $ref: '#/components/schemas/ExportConfig'
+
+    JobDefinition:
+      type: object
+      description: |
+        A job within a workflow. Each job must have exactly one source:
+        - `file_id`: Direct reference to an uploaded file
+        - `source`: Reference another job's output (single-input downstream)
+        - `inputs`: Reference multiple job outputs (multi-input: merge/archive)
+
+        Future versions will add `url` and `import` source types for external
+        file references (V2).
+
+        For single-input jobs with `file_id`, `operations` defaults to
+        `[{ "type": "compress" }]` if omitted. Multi-input jobs must specify
+        operations explicitly.
+      required:
+        - ref
+      properties:
+        ref:
+          type: string
+          description: |
+            Unique reference label within this workflow. Used in workflow_edges,
+            source references, and response payloads to identify jobs.
+          example: "main"
+        file_id:
+          $ref: '#/components/schemas/UuidV7'
+          description: Reference to an uploaded file
+        source:
+          $ref: '#/components/schemas/JobSource'
+        inputs:
+          type: array
+          description: |
+            Multiple input references for multi-input operations (merge, archive).
+            Each input references a specific job's operation output.
+          minItems: 2
+          items:
+            $ref: '#/components/schemas/JobInput'
+        operations:
+          type: array
+          description: |
+            Ordered list of operations to perform. Executed sequentially — each
+            operation consumes the previous operation's output. All intermediate
+            and final outputs are kept.
+
+            Multi-input jobs must have exactly one operation (merge or archive).
+          items:
+            $ref: '#/components/schemas/OperationDefinition'
+      oneOf:
+        - required: [file_id]
+          description: Single-input job referencing an uploaded file
+        - required: [source]
+          description: Single-input downstream job referencing another job's output
+        - required: [inputs]
+          description: Multi-input job (merge/archive)
+      allOf:
+        - if:
+            required: [inputs]
+          then:
+            properties:
+              operations:
+                minItems: 1
+                maxItems: 1
+                items:
+                  properties:
+                    type:
+                      enum: [merge, archive]
+            required: [operations]
+            description: |
+              Multi-input jobs must have exactly one operation, and it must be
+              a multi-input type (merge or archive).
+
+    JobSource:
+      type: object
+      description: |
+        Reference to another job's output for single-input downstream jobs.
+        The input is the referenced job's output, resolved via the incoming
+        workflow edge.
+      required:
+        - ref
+      properties:
+        ref:
+          type: string
+          description: Reference label of the upstream job
+          example: "compress-step"
+        operation:
+          type: string
+          description: |
+            Specific operation output to use from the upstream job.
+            If omitted, uses the last operation's output.
+
+    JobInput:
+      type: object
+      description: |
+        Single input reference for multi-input operations. Each references a
+        specific job and optionally a specific operation output from that job.
+      required:
+        - ref
+      properties:
+        ref:
+          type: string
+          description: Reference label of the upstream job
+          example: "intro"
+        operation:
+          type: string
+          description: |
+            Specific operation output to use. If omitted, uses the last
+            operation's output.
+        per_input_options:
+          type: object
+          description: |
+            Per-input option overrides. For merge operations, individual inputs
+            can override global transition settings for the join point preceding
+            this input. Keys are option names, values are the override values.
+          additionalProperties: true
+
+    OperationDefinition:
+      type: object
+      description: Definition of a single operation within a job
+      required:
+        - type
+      properties:
+        type:
+          $ref: '#/components/schemas/OperationType'
+        options:
+          type: object
+          description: |
+            Operation-specific options. The available options and their validation
+            rules depend on the operation type and the input file's MIME type.
+            See `GET /api/operations/schema` for the full schema.
+
+            Options are validated against the schema using JSON Schema if/then/else
+            rules. For example, `quality` is only valid when `mode: lossy` for
+            compress operations.
+          additionalProperties: true
+
+    WorkflowEdge:
+      type: object
+      description: |
+        Directed edge in the workflow DAG. Defines that the downstream job
+        depends on the upstream job completing successfully.
+      required:
+        - from
+        - to
+      properties:
+        from:
+          type: string
+          description: Reference label of the upstream job
+          example: "compress-intro"
+        to:
+          type: string
+          description: Reference label of the downstream job
+          example: "merge-all"
+
+    # ============================================
+    # WORKFLOW RESPONSE SCHEMAS
+    # ============================================
+
+    WorkflowCreateResponse:
+      type: object
+      required:
+        - workflow_id
+        - status
+        - jobs
+      properties:
+        workflow_id:
+          $ref: '#/components/schemas/UuidV7'
+        status:
+          $ref: '#/components/schemas/WorkflowStatus'
+        jobs:
+          type: array
+          items:
+            $ref: '#/components/schemas/JobResponse'
+        webhook_secret:
+          type:
+            - string
+            - "null"
+          readOnly: true
+          minLength: 64
+          maxLength: 64
+          pattern: '^[0-9a-f]{64}$'
+          description: |
+            HMAC-SHA256 signing key for webhook verification. Present only when
+            `callback_url` was provided in the request. This is the only time the
+            secret is exposed — it does not appear in status queries.
+
+            Use this key to verify the `X-GIS-Signature` header on incoming webhook
+            requests: `sha256=<hex(hmac-sha256(webhook_secret, raw_body))>`.
+          example: "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
+
+    WorkflowCreateSuccessEnvelope:
+      type: object
+      required:
+        - success
+        - data
+      properties:
+        success:
+          type: boolean
+          const: true
+        data:
+          $ref: '#/components/schemas/WorkflowCreateResponse'
+
+    WorkflowStatusResponse:
+      type: object
+      required:
+        - workflow_id
+        - status
+        - jobs
+      properties:
+        workflow_id:
+          $ref: '#/components/schemas/UuidV7'
+        status:
+          $ref: '#/components/schemas/WorkflowStatus'
+        jobs:
+          type: array
+          items:
+            $ref: '#/components/schemas/JobResponse'
+
+    WorkflowStatusSuccessEnvelope:
+      type: object
+      required:
+        - success
+        - data
+      properties:
+        success:
+          type: boolean
+          const: true
+        data:
+          $ref: '#/components/schemas/WorkflowStatusResponse'
+
+    JobResponse:
+      type: object
+      description: Job status within a workflow response
+      required:
+        - ref
+        - job_id
+        - status
+        - depends_on
+        - operations
+      properties:
+        ref:
+          type: string
+          description: Job reference label
+          example: "main"
+        job_id:
+          $ref: '#/components/schemas/UuidV7'
+        status:
+          $ref: '#/components/schemas/JobStatus'
+        depends_on:
+          type: array
+          description: List of upstream job refs this job depends on
+          items:
+            type: string
+        operations:
+          type: array
+          items:
+            $ref: '#/components/schemas/OperationResponse'
+
+    OperationResponse:
+      type: object
+      description: Operation status within a job response
+      required:
+        - id
+        - type
+        - status
+      properties:
+        id:
+          $ref: '#/components/schemas/UuidV7'
+        type:
+          $ref: '#/components/schemas/OperationType'
+        status:
+          $ref: '#/components/schemas/OperationStatus'
+        progress:
+          type: integer
+          minimum: 0
+          maximum: 100
+          description: Progress percentage (0-100). Present when in_progress or completed.
+        result:
+          $ref: '#/components/schemas/OperationResult'
+
+    OperationResult:
+      type: object
+      description: |
+        Result of a completed operation. Present only when operation status is `completed`.
+      required:
+        - download_url
+        - size_bytes
+      properties:
+        download_url:
+          type: string
+          format: uri
+          description: Pre-signed download URL for the operation output
+        size_bytes:
+          type: integer
+          format: int64
+          description: Output file size in bytes
+        export_key:
+          type: string
+          description: Key in the customer's export destination (if export configured)
+        metrics:
+          type: object
+          description: Operation-specific performance metrics
+          properties:
+            compression_ratio:
+              type: number
+              format: double
+              description: Ratio of output size to input size (e.g. 0.45 = 55% reduction)
+            duration_ms:
+              type: integer
+              description: Processing time in milliseconds
+
+    # ============================================
+    # WORKFLOW DOWNLOAD SCHEMAS
+    # ============================================
+
+    WorkflowDownloadResponse:
+      type: object
+      required:
+        - downloads
+      properties:
+        downloads:
+          type: array
+          items:
+            $ref: '#/components/schemas/JobDownload'
+
+    WorkflowDownloadSuccessEnvelope:
+      type: object
+      required:
+        - success
+        - data
+      properties:
+        success:
+          type: boolean
+          const: true
+        data:
+          $ref: '#/components/schemas/WorkflowDownloadResponse'
+
+    JobDownload:
+      type: object
+      required:
+        - ref
+        - job_id
+        - files
+      properties:
+        ref:
+          type: string
+          description: Job reference label
+        job_id:
+          $ref: '#/components/schemas/UuidV7'
+        files:
+          type: array
+          items:
+            $ref: '#/components/schemas/OperationDownload'
+
+    OperationDownload:
+      type: object
+      required:
+        - operation
+        - operation_id
+        - filename
+        - size_bytes
+        - download_url
+      properties:
+        operation:
+          type: string
+          description: Operation type that produced this file
+        operation_id:
+          $ref: '#/components/schemas/UuidV7'
+        filename:
+          type: string
+          description: Output filename
+          example: "photo.jpg"
+        size_bytes:
+          type: integer
+          format: int64
+          description: Output file size in bytes
+        download_url:
+          type: string
+          format: uri
+          description: Pre-signed download URL
+
+    # ============================================
+    # SSE EVENT SCHEMAS
+    # ============================================
+
+    SseEventType:
+      type: string
+      description: |
+        Server-Sent Event types pushed on the /events endpoint:
+        - operation.progress: Progress update for an operation
+        - operation.completed: Operation finished successfully
+        - operation.failed: Operation encountered an error
+        - job.completed: All operations in a job completed
+        - job.failed: Job failed
+        - workflow.completed: All jobs completed successfully
+        - workflow.failed: All jobs finished, at least one failed
+        - workflow.partially_failed: Some succeeded, some failed
+      enum:
+        - operation.progress
+        - operation.completed
+        - operation.failed
+        - job.completed
+        - job.failed
+        - workflow.completed
+        - workflow.failed
+        - workflow.partially_failed
+
+    SseOperationProgressData:
+      type: object
+      description: Payload for `operation.progress` events
+      required:
+        - job_ref
+        - operation_id
+        - type
+        - progress
+      properties:
+        job_ref:
+          type: string
+        operation_id:
+          $ref: '#/components/schemas/UuidV7'
+        type:
+          $ref: '#/components/schemas/OperationType'
+        progress:
+          type: integer
+          minimum: 0
+          maximum: 100
+
+    SseOperationCompletedData:
+      type: object
+      description: Payload for `operation.completed` events
+      required:
+        - job_ref
+        - operation_id
+        - type
+        - status
+        - progress
+      properties:
+        job_ref:
+          type: string
+        operation_id:
+          $ref: '#/components/schemas/UuidV7'
+        type:
+          $ref: '#/components/schemas/OperationType'
+        status:
+          type: string
+          const: "completed"
+        progress:
+          type: integer
+          const: 100
+        result:
+          $ref: '#/components/schemas/OperationResult'
+
+    SseOperationFailedData:
+      type: object
+      description: Payload for `operation.failed` events
+      required:
+        - job_ref
+        - operation_id
+        - type
+        - status
+        - error_code
+        - error_message
+      properties:
+        job_ref:
+          type: string
+        operation_id:
+          $ref: '#/components/schemas/UuidV7'
+        type:
+          $ref: '#/components/schemas/OperationType'
+        status:
+          type: string
+          const: "failed"
+        error_code:
+          type: string
+        error_message:
+          type: string
+
+    SseJobCompletedData:
+      type: object
+      description: Payload for `job.completed` events
+      required:
+        - job_ref
+        - job_id
+        - status
+      properties:
+        job_ref:
+          type: string
+        job_id:
+          $ref: '#/components/schemas/UuidV7'
+        status:
+          type: string
+          const: "completed"
+
+    SseJobFailedData:
+      type: object
+      description: Payload for `job.failed` events
+      required:
+        - job_ref
+        - job_id
+        - status
+      properties:
+        job_ref:
+          type: string
+        job_id:
+          $ref: '#/components/schemas/UuidV7'
+        status:
+          type: string
+          const: "failed"
+
+    SseWorkflowTerminalData:
+      type: object
+      description: |
+        Payload for workflow terminal events
+        (workflow.completed, workflow.failed, workflow.partially_failed)
+      required:
+        - workflow_id
+        - status
+      properties:
+        workflow_id:
+          $ref: '#/components/schemas/UuidV7'
+        status:
+          type: string
+          enum:
+            - completed
+            - failed
+            - partially_failed
+
+    # ============================================
+    # OPERATIONS SCHEMA ENDPOINT RESPONSE
+    # ============================================
+
+    OperationsSchemaResponse:
+      type: object
+      description: |
+        Operations meta-schema. Describes all available operation types, their options,
+        constraints, defaults, and MIME type applicability. Returned raw (no envelope)
+        for CDN cacheability.
+
+        Each operation defines options with types, constraints, and conditional
+        dependencies (via `depends_on`). Clients use this to build dynamic forms
+        and validate options before submission.
+      required:
+        - schema_version
+        - operations
+      properties:
+        schema_version:
+          type: string
+          description: Schema version for cache-busting
+          example: "1.0.0"
+        operations:
+          type: object
+          description: Map of operation type to its schema definition
+          additionalProperties:
+            $ref: '#/components/schemas/OperationSchemaDefinition'
+
+    OperationSchemaDefinition:
+      type: object
+      description: Schema for a single operation type
+      required:
+        - description
+        - input_model
+        - options
+      properties:
+        description:
+          type: string
+          description: Human-readable description of what the operation does
+        default:
+          type: boolean
+          description: Whether this is the default operation when none specified
+        input_model:
+          $ref: '#/components/schemas/OperationInputModel'
+        min_inputs:
+          type: integer
+          description: Minimum number of inputs (multi-input operations only)
+          minimum: 2
+        max_inputs:
+          type: integer
+          description: Maximum number of inputs (multi-input operations only)
+        accepts_mixed_types:
+          type: boolean
+          description: Whether mixed MIME types are allowed (archive only)
+        mime_groups:
+          type: object
+          description: |
+            MIME-type-specific option schemas. When present, options are grouped
+            by MIME category (image, video, audio, document). Each group lists
+            the supported MIME types and group-specific options.
+          additionalProperties:
+            $ref: '#/components/schemas/MimeGroupSchema'
+        options:
+          type: object
+          description: |
+            Global options applicable regardless of MIME type, keyed by option name.
+            For operations with mime_groups, these are the common options.
+          additionalProperties:
+            $ref: '#/components/schemas/OptionSchema'
+        per_input_options:
+          type: object
+          description: |
+            Options that can be overridden per-input for multi-input operations,
+            keyed by option name. For merge: per-join-point transition overrides.
+          additionalProperties:
+            $ref: '#/components/schemas/OptionSchema'
+
+    MimeGroupSchema:
+      type: object
+      description: MIME-group-specific option schema
+      required:
+        - mimes
+        - options
+      properties:
+        mimes:
+          type: array
+          description: List of MIME types in this group
+          items:
+            type: string
+          example: ["image/jpeg", "image/png", "image/webp"]
+        options:
+          type: object
+          description: Options specific to this MIME group, keyed by option name
+          additionalProperties:
+            $ref: '#/components/schemas/OptionSchema'
+        per_input_options:
+          type: object
+          description: Per-input overrides for this MIME group, keyed by option name (multi-input only)
+          additionalProperties:
+            $ref: '#/components/schemas/OptionSchema'
+
+    OptionSchema:
+      type: object
+      description: Schema for a single operation option
+      required:
+        - type
+      properties:
+        type:
+          type: string
+          description: Option value type
+          enum:
+            - integer
+            - float
+            - boolean
+            - enum
+            - string
+        description:
+          type: string
+          description: Human-readable description
+        required:
+          type: boolean
+          description: Whether the option is required
+        default:
+          description: Default value if not specified
+        values:
+          type: array
+          description: Allowed values (for enum type)
+          items: {}
+        value_type:
+          type: string
+          description: |
+            Actual type of enum values when not strings (e.g. "integer" for numeric bitrate enums).
+            Consumers should parse/display values as this type rather than as strings.
+          enum:
+            - integer
+            - float
+        min:
+          type: number
+          description: Minimum value (for integer/float types)
+        max:
+          type: number
+          description: Maximum value (for integer/float types)
+        depends_on:
+          type: object
+          description: |
+            Conditional dependency. This option is only applicable when the condition is met.
+            Simple: `{ "mode": "lossy" }` — option applies when mode equals lossy.
+            Multi-value: `{ "output_format": ["jpeg", "webp"] }` — option applies when output_format is any listed value.
+            Set condition: `{ "width": "set", "height": "set", "logic": "or" }` — option applies when width or height is provided.
+            The "set" sentinel means the option has any value. "logic" can be "and" (default) or "or".
+          additionalProperties: true
+
+    # ============================================
+    # RETRY SCHEMAS
+    # ============================================
+
+    RetryResponse:
+      type: object
+      required:
+        - operation_id
+        - original_operation_id
+        - status
+      properties:
+        operation_id:
+          $ref: '#/components/schemas/UuidV7'
+          description: New operation ID for the retry
+        original_operation_id:
+          $ref: '#/components/schemas/UuidV7'
+          description: ID of the original failed operation
+        status:
+          type: string
+          enum:
+            - pending
+          description: Always "pending" for a new retry
+
+    RetrySuccessEnvelope:
+      type: object
+      required:
+        - success
+        - data
+      properties:
+        success:
+          type: boolean
+          const: true
+        data:
+          $ref: '#/components/schemas/RetryResponse'
+
+    # ============================================
+    # CALLBACK & EXPORT CONFIG
+    # ============================================
+
+    CallbackEventType:
+      type: string
+      description: |
+        Events that can trigger a webhook callback:
+        - workflow.completed: All jobs done successfully
+        - workflow.failed: At least one job failed, none in progress
+        - workflow.partially_failed: Some succeeded, some failed
+        - operation.completed: Individual operation done (opt-in for granular progress)
+      enum:
+        - workflow.completed
+        - workflow.failed
+        - workflow.partially_failed
+        - operation.completed
+
+    WebhookPayload:
+      type: object
+      description: |
+        Payload POSTed to the `callback_url` when a subscribed event occurs.
+        The `workflow` field contains the full current state including all jobs
+        and their operation results, matching the `WorkflowStatusResponse` shape.
+
+        For `operation.completed` events, the `operation` field identifies which
+        specific operation triggered the callback, so consumers do not need to
+        scan the entire workflow to find the change.
+      required:
+        - event_type
+        - delivery_id
+        - timestamp
+        - workflow
+      properties:
+        event_type:
+          $ref: '#/components/schemas/CallbackEventType'
+        delivery_id:
+          $ref: '#/components/schemas/UuidV7'
+          description: |
+            Unique identifier for this event. Stable across retry attempts —
+            the same delivery_id is sent if the API retries a failed delivery.
+            Consumers should use this for idempotency to avoid processing
+            the same event twice.
+        timestamp:
+          type: string
+          format: date-time
+          description: ISO 8601 timestamp of when the event occurred
+          example: "2026-03-13T14:30:00Z"
+        workflow:
+          $ref: '#/components/schemas/WorkflowStatusResponse'
+        operation:
+          $ref: '#/components/schemas/WebhookOperationContext'
+      allOf:
+        - if:
+            properties:
+              event_type:
+                const: operation.completed
+          then:
+            required: [operation]
+            properties:
+              operation:
+                type: object
+            description: operation.completed events must include operation context
+          else:
+            properties:
+              operation:
+                type: "null"
+            description: Workflow-level events have null operation context
+
+    WebhookOperationContext:
+      type:
+        - object
+        - "null"
+      description: |
+        Identifies which operation triggered the callback. Present only for
+        `operation.completed` events; null for workflow-level events.
+      required:
+        - job_ref
+        - operation_id
+      properties:
+        job_ref:
+          type: string
+          description: Reference label of the job containing the operation
+          example: "main"
+        operation_id:
+          $ref: '#/components/schemas/UuidV7'
+          description: ID of the operation that completed
+
+    ExportConfig:
+      type:
+        - object
+        - "null"
+      description: |
+        Export configuration. When set, all operation outputs are copied to the
+        customer's destination in addition to GISL's own S3 storage.
+        Currently supports AWS S3 via cross-account AssumeRole.
+      required:
+        - service
+        - bucket
+        - role_arn
+      properties:
+        service:
+          type: string
+          description: Destination service
+          enum:
+            - s3
+          example: "s3"
+        bucket:
+          type: string
+          description: Destination bucket name
+          example: "customer-output-bucket"
+        key_prefix:
+          type: string
+          description: Key prefix for exported files
+          example: "compressed/"
+        role_arn:
+          type: string
+          description: |
+            IAM role ARN in the customer's AWS account. GISL's Lambda assumes this
+            role to write to the customer's bucket. The customer must configure a
+            trust policy allowing GISL's execution role to assume it.
+          pattern: '^arn:aws:iam::\d{12}:role/.+$'
+          example: "arn:aws:iam::123456789012:role/giveitsmaller-write"
+
+    # ============================================
+    # HEALTH SCHEMAS
+    # ============================================
+
+    LivenessResponse:
+      type: object
+      required:
+        - app
+      properties:
+        app:
+          type: boolean
+          description: Application is running
+
+    ReadinessResponse:
+      type: object
+      properties:
+        database:
+          type: boolean
+          description: Database connection is healthy
+        cache:
+          type: boolean
+          description: Cache connection is healthy
+
+    # ============================================
+    # CONTACT SCHEMAS
+    # ============================================
+
+    ContactSubject:
+      type: string
+      enum:
+        - general_enquiry
+        - bug_report
+        - suggestion
+        - complaint
+        - business_enquiry
+      description: |
+        Subject category:
+        - general_enquiry: General questions
+        - bug_report: Report a bug or issue
+        - suggestion: Feature suggestion or improvement idea
+        - complaint: Complaint about the service
+        - business_enquiry: Business or partnership enquiry
+
+    ContactRequest:
+      type: object
+      required:
+        - email
+        - subject
+        - message
+      properties:
+        name:
+          type: string
+          maxLength: 100
+          description: Sender's name (optional)
+          example: "Jane Doe"
+        email:
+          type: string
+          format: email
+          maxLength: 254
+          description: Sender's email address
+          example: "jane@example.com"
+        subject:
+          $ref: '#/components/schemas/ContactSubject'
+        message:
+          type: string
+          minLength: 1
+          maxLength: 1000
+          description: Message body
+          example: "I have a question about supported file formats."
+        website:
+          type: string
+          maxLength: 255
+          description: |
+            Honeypot field for bot detection. Hidden from real users via CSS.
+            Legitimate submissions must omit this field or send an empty string.
+            The API rejects any request where this field is non-empty.
+
+    ContactValidationErrorResponse:
+      type: object
+      required:
+        - errors
+      properties:
+        errors:
+          type: object
+          description: |
+            Map of field names to arrays of validation error messages.
+          additionalProperties:
+            type: array
+            items:
+              type: string
+          example:
+            email:
+              - "This value is not a valid email address."
+            subject:
+              - "This value is not valid."