openapi: 3.1.0
info:
  title: WaveForge Agent Door
  version: "0.1.0"
  description: |
    ChatGPT Actions preview: submit a public audio_url to queue a watermarked
    720p WaveForge preview (max 60 seconds, trimmed if longer). No credit charge.
    Authenticate with Authorization: Bearer <AGENT_DOOR_API_KEY>.
    Caps are per Action key + ChatGPT conversation id (not IP).
servers:
  - url: https://waveforge.net
paths:
  /api/agent/v1/preview:
    post:
      operationId: createAgentPreview
      summary: Queue a watermarked 720p preview from audio_url
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [audio_url, rights_attested]
              properties:
                audio_url:
                  type: string
                  format: uri
                  description: Public https URL of the audio file (SSRF-checked).
                image_url:
                  type: string
                  format: uri
                  description: Optional public cover image URL.
                title:
                  type: string
                  maxLength: 120
                rights_attested:
                  type: boolean
                  description: Must be true — you affirm you have rights to the media.
      responses:
        "200":
          description: Queued (desktop worker online)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PreviewAccepted"
        "202":
          description: Queued while desktop worker is offline
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PreviewAccepted"
        "400":
          description: Validation / SSRF / rights
        "401":
          description: Missing or invalid API key
        "404":
          description: Feature flag off
        "429":
          description: Caller or global daily cap
  /api/agent/v1/status/{id}:
    get:
      operationId: getAgentPreviewStatus
      summary: Poll opaque preview status
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            pattern: '^ado_'
      responses:
        "200":
          description: Status payload (no raw job id)
        "401":
          description: Missing or invalid API key
        "404":
          description: Unknown id or flag off
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    PreviewAccepted:
      type: object
      properties:
        id: { type: string }
        status: { type: string }
        status_url: { type: string }
        queue_position: { type: integer }
        worker_online: { type: boolean }
        message: { type: string }
        audio_trimmed_to_60s: { type: boolean }
        tos: { type: string }
        takedown_contact:
          type: ["string", "null"]
        note: { type: string }