openapi: 3.2.0
info:
  title: Pictomancer.ai Gateway Pipeline API
  version: 0.1.0
tags:
- name: Pipeline
paths:
  /v1/pipeline:
    post:
      summary: Run a multi-step image pipeline
      description: Chain multiple operations (resize, compress, convert, crop) in sequence. The image is fetched once, then each operation is applied to the output of the previous one. Max 10 operations per pipeline.
      operationId: image_pipeline
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PipelineRequest'
        required: true
      responses:
        '200':
          description: Processed image binary
          content:
            application/json:
              schema: {}
            image/jpeg:
              schema:
                type: string
                format: binary
            image/png:
              schema:
                type: string
                format: binary
            image/webp:
              schema:
                type: string
                format: binary
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Pipeline
components:
  schemas:
    PutUrlDelivery:
      properties:
        mode:
          type: string
          const: put_url
          title: Mode
        put_url:
          type: string
          maxLength: 2083
          minLength: 1
          format: uri
          title: Put Url
          description: Customer-signed presigned PUT URL where the optimized bytes will be written. Must be https://. Cloud credentials never reach our infrastructure; only the URL itself is used and discarded after the request.
        headers:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Headers
          description: Optional storage headers to include on the PUT call (Content-Type, Cache-Control, x-amz-acl, etc.). Whitelisted at SSRF layer.
      additionalProperties: false
      type: object
      required:
      - mode
      - put_url
      title: PutUrlDelivery
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    InlineDelivery:
      properties:
        mode:
          type: string
          const: inline
          title: Mode
          default: inline
      additionalProperties: false
      type: object
      title: InlineDelivery
    PipelineRequest:
      properties:
        delivery:
          oneOf:
          - $ref: '#/components/schemas/InlineDelivery'
          - $ref: '#/components/schemas/PutUrlDelivery'
          - $ref: '#/components/schemas/CallbackDelivery'
          title: Delivery
          discriminator:
            propertyName: mode
            mapping:
              callback_url: '#/components/schemas/CallbackDelivery'
              inline: '#/components/schemas/InlineDelivery'
              put_url: '#/components/schemas/PutUrlDelivery'
        source:
          type: string
          title: Source
          description: 'Image source: a public URL (https://...) or a base64-encoded string (optionally as a data URI like data:image/png;base64,...).'
        operations:
          items:
            $ref: '#/components/schemas/PipelineOperation'
          type: array
          title: Operations
          description: Ordered list of operations to apply sequentially. Each operation receives the output of the previous one. Max 10.
      type: object
      required:
      - source
      - operations
      title: PipelineRequest
    CallbackDelivery:
      properties:
        mode:
          type: string
          const: callback_url
          title: Mode
        callback_url:
          type: string
          maxLength: 2083
          minLength: 1
          format: uri
          title: Callback Url
          description: Customer endpoint where the optimized bytes will be POSTed. Must be https://. For async/large jobs. We send an X-Pig-Sha256 header of the body so the receiver can verify integrity. No credentials are stored on our side; secure the endpoint with a token in the URL itself.
        headers:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Headers
          description: Optional headers to include on the POST call (Content-Type, Cache-Control, x-amz-*, etc.). Whitelisted at SSRF layer.
        secret:
          anyOf:
          - type: string
          - type: 'null'
          title: Secret
          description: 'Optional HMAC secret. When set, we sign the POST body with HMAC-SHA256 and send ''X-Pig-Signature: sha256=<hex>''. Used per request and never stored. Recompute the HMAC on your endpoint to authenticate the callback (constant-time compare).'
      additionalProperties: false
      type: object
      required:
      - mode
      - callback_url
      title: CallbackDelivery
    PipelineOperation:
      properties:
        type:
          type: string
          title: Type
          description: 'Operation type: resize, compress, convert, or crop.'
        params:
          additionalProperties:
            type: string
          type: object
          title: Params
          description: 'Operation parameters as key-value string pairs. E.g. {"scale": "0.5"} for resize, {"format": "webp"} for convert.'
          default: {}
      type: object
      required:
      - type
      title: PipelineOperation