openapi: 3.0.3
info:
  title: VideoDB Server API
  description: |
    VideoDB Server API for video, audio, and image processing with AI capabilities.
    This API provides comprehensive video management, search, indexing, and AI-powered features.
  version: 1.0.0
  contact:
    name: VideoDB Support
    url: https://videodb.io
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.videodb.io
    description: Production server
  - url: https://staging-api.videodb.io
    description: Staging server

security:
  - ApiKeyAuth: []

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-access-token
      description: API key for authentication (sk-xxx format)

  schemas:
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: "Error message"
        error_code:
          type: string
          example: "ERROR_CODE"

    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: "Operation successful"

    AsyncResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        status:
          type: string
          enum: [processing, done, failed]
          example: "processing"
        data:
          type: object
          properties:
            id:
              type: string
              example: "job-123"
            output_url:
              type: string
              example: "https://api.videodb.io/async-response/job-123"

    Sandbox:
      type: object
      properties:
        sandbox_id:
          type: string
          example: "bx-123abc"
        name:
          type: string
          example: "my-sandbox"
        tier:
          type: string
          enum: [small, medium]
          example: "small"
        status:
          type: string
          enum: [provisioning, active, alert, stopping, stopped, failed]
          example: "active"
        models:
          type: array
          items:
            type: string
          example: ["rtdetr-v2-r50vd"]
        model_categories:
          type: array
          items:
            type: string
          example: ["object_detection"]
        region:
          type: string
          example: "aws-us-east-1"
        expires_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        started_at:
          type: string
          format: date-time
        stopped_at:
          type: string
          format: date-time

    SandboxResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          $ref: '#/components/schemas/Sandbox'

    SandboxListResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            sandboxes:
              type: array
              items:
                $ref: '#/components/schemas/Sandbox'
            page:
              type: integer
              example: 1
            page_size:
              type: integer
              example: 20
            total:
              type: integer
              example: 1

    User:
      type: object
      properties:
        user_id:
          type: string
          example: "u-12345"
        user_name:
          type: string
          example: "John Doe"
        user_email:
          type: string
          example: "john@example.com"
        collections:
          type: array
          items:
            type: string
          example: ["default", "c-67890"]
        default_collection:
          type: string
          example: "default"

    Collection:
      type: object
      properties:
        id:
          type: string
          example: "default"
        name:
          type: string
          example: "My Collection"
        description:
          type: string
          example: "Collection description"
        is_public:
          type: boolean
          example: false
        owner:
          type: string
          example: "u-12345"
        created_at:
          type: string
          format: date-time

    Video:
      type: object
      properties:
        id:
          type: string
          example: "m-12345"
        name:
          type: string
          example: "video.mp4"
        description:
          type: string
          example: "Video description"
        collection_id:
          type: string
          example: "default"
        length:
          type: number
          example: 120.5
        size:
          type: number
          example: 1048576
        stream_url:
          type: string
          example: "https://stream.videodb.io/v/12345"
        player_url:
          type: string
          example: "https://console.videodb.io/player/12345"
        thumbnail_url:
          type: string
          example: "https://assets.videodb.io/thumb/12345.jpg"
        created_at:
          type: string
          format: date-time

    Audio:
      type: object
      properties:
        id:
          type: string
          example: "a-12345"
        name:
          type: string
          example: "audio.mp3"
        collection_id:
          type: string
          example: "default"
        length:
          type: number
          example: 60.0
        size:
          type: number
          example: 524288
        created_at:
          type: string
          format: date-time

    Image:
      type: object
      properties:
        id:
          type: string
          example: "img-12345"
        name:
          type: string
          example: "image.jpg"
        collection_id:
          type: string
          example: "default"
        width:
          type: number
          example: 1920
        height:
          type: number
          example: 1080
        size:
          type: number
          example: 262144
        url:
          type: string
          example: "https://assets.videodb.io/img/12345.jpg"
        created_at:
          type: string
          format: date-time

    SearchResult:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            query:
              type: string
              example: "search query"
            results:
              type: array
              items:
                type: object
                properties:
                  video_id:
                    type: string
                    example: "m-12345"
                  start:
                    type: number
                    example: 10.5
                  end:
                    type: number
                    example: 20.3
                  text:
                    type: string
                    example: "matched content"
                  score:
                    type: number
                    example: 0.95

    Timeline:
      type: object
      properties:
        video_id:
          type: string
          example: "m-12345"
        clips:
          type: array
          items:
            type: object
            properties:
              start:
                type: number
                example: 0
              end:
                type: number
                example: 30
              volume:
                type: number
                example: 1.0

    BillingUsage:
      type: object
      properties:
        credit_balance:
          type: number
          example: 100.50
        usage_this_month:
          type: number
          example: 25.75
        breakdown:
          type: object
          additionalProperties:
            type: number

    RTStream:
      type: object
      properties:
        id:
          type: string
          example: "rts-12345"
        name:
          type: string
          example: "My Stream"
        status:
          type: string
          enum: [connected, stopped]
          example: "connected"
        sample_rate:
          type: integer
          example: 30
        media_types:
          type: array
          items:
            type: string
            enum: [video, audio]
          example: ["video", "audio"]
        collection_id:
          type: string
          example: "default"
        store:
          type: boolean
          example: false
        created_at:
          type: string
          format: date-time

    CaptureSession:
      type: object
      properties:
        session_id:
          type: string
          example: "capture-12345"
        end_user_id:
          type: string
          example: "user-123"
        status:
          type: string
          enum: [created, starting, active, stopped, failed]
          example: "created"
        collection_id:
          type: string
          example: "default"
        ws_connection_id:
          type: string
          example: "conn-123"
        metadata:
          type: object
        created_at:
          type: string
          format: date-time

paths:
  /:
    get:
      summary: Get service information
      description: Returns basic service information
      responses:
        '200':
          description: Service information
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      service:
                        type: string
                        example: "VideoDB Server"

  /user:
    get:
      summary: Get user information
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: User information
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/User'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /user/api_key:
    get:
      summary: Get user API keys
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: List of API keys
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                          example: "sk-xxx"
                        created_at:
                          type: string
                          format: date-time

    post:
      summary: Create new API key
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: API key created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      api_key:
                        type: string
                        example: "sk-xxx"

  /user/api_key/{api_key}:
    delete:
      summary: Delete API key
      security:
        - ApiKeyAuth: []
      parameters:
        - name: api_key
          in: path
          required: true
          schema:
            type: string
            example: "sk-xxx"
      responses:
        '200':
          description: API key deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /collection:
    get:
      summary: Get user collections
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: List of collections
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      collections:
                        type: array
                        items:
                          $ref: '#/components/schemas/Collection'
                      default_collection:
                        type: string
                        example: "default"

    post:
      summary: Create new collection
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: "My New Collection"
                description:
                  type: string
                  example: "Collection for my videos"
                is_public:
                  type: boolean
                  example: false
      responses:
        '200':
          description: Collection created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Collection'

  /collection/{collection_id}:
    get:
      summary: Get collection details
      security:
        - ApiKeyAuth: []
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
            example: "default"
      responses:
        '200':
          description: Collection details
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Collection'

    patch:
      summary: Update collection
      security:
        - ApiKeyAuth: []
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
            example: "default"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: "Updated Collection Name"
                description:
                  type: string
                  example: "Updated description"
                is_public:
                  type: boolean
                  example: true
      responses:
        '200':
          description: Collection updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Collection'

    delete:
      summary: Delete collection
      security:
        - ApiKeyAuth: []
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
            example: "default"
      responses:
        '200':
          description: Collection deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /collection/{collection_id}/upload:
    post:
      summary: Upload media to collection
      security:
        - ApiKeyAuth: []
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
            example: "default"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url
              properties:
                url:
                  type: string
                  example: "https://example.com/video.mp4"
                name:
                  type: string
                  example: "My Video"
                media_type:
                  type: string
                  enum: [video, audio, image]
                  example: "video"
                callback_url:
                  type: string
                  example: "https://webhook.example.com/callback"
      responses:
        '200':
          description: Upload initiated
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/AsyncResponse'
                  - type: object
                    properties:
                      success:
                        type: boolean
                        example: true
                      data:
                        $ref: '#/components/schemas/Video'

  /collection/{collection_id}/search/:
    post:
      summary: Search within collection
      security:
        - ApiKeyAuth: []
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
            example: "default"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                  example: "search query"
                index_type:
                  type: string
                  enum: [spoken_word, scene]
                  example: "spoken_word"
                search_type:
                  type: string
                  enum: [semantic, custom]
                  example: "semantic"
                score_threshold:
                  type: number
                  example: 0.2
                result_threshold:
                  type: integer
                  example: 10
                stitch:
                  type: boolean
                  example: true
                rerank:
                  type: boolean
                  example: false
                filter:
                  type: array
                  items:
                    type: object
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResult'

  /video/:
    get:
      summary: List videos
      security:
        - ApiKeyAuth: []
      parameters:
        - name: collection_id
          in: query
          schema:
            type: string
            example: "default"
        - name: page_index
          in: query
          schema:
            type: integer
            example: 0
        - name: count
          in: query
          schema:
            type: integer
            maximum: 5000
            example: 50
      responses:
        '200':
          description: List of videos
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      videos:
                        type: array
                        items:
                          $ref: '#/components/schemas/Video'

  /video/{video_id}:
    get:
      summary: Get video details
      security:
        - ApiKeyAuth: []
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^m-"
            example: "m-12345"
        - name: collection_id
          in: query
          schema:
            type: string
            example: "default"
      responses:
        '200':
          description: Video details
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Video'

    patch:
      summary: Update video
      tags:
        - Videos
      security:
        - ApiKeyAuth: []
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^m-"
            example: "m-12345"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: "Updated Video Name"
      responses:
        '200':
          description: Video updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Video'

    delete:
      summary: Delete video
      security:
        - ApiKeyAuth: []
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^m-"
            example: "m-12345"
      responses:
        '200':
          description: Video deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /video/{video_id}/storage/:
    delete:
      summary: Delete video storage
      security:
        - ApiKeyAuth: []
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^m-"
            example: "m-12345"
      responses:
        '200':
          description: Video storage deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /video/{video_id}/stream/:
    post:
      summary: Create video stream
      security:
        - ApiKeyAuth: []
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^m-"
            example: "m-12345"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                format:
                  type: string
                  enum: [mp4, webm, hls]
                  example: "mp4"
                quality:
                  type: string
                  enum: [low, medium, high]
                  example: "high"
      responses:
        '200':
          description: Stream created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      stream_url:
                        type: string
                        example: "https://stream.videodb.io/v/12345"

  /video/{video_id}/thumbnail/:
    get:
      summary: Get video thumbnail
      security:
        - ApiKeyAuth: []
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^m-"
            example: "m-12345"
        - name: timestamp
          in: query
          schema:
            type: number
            example: 10.5
      responses:
        '200':
          description: Thumbnail URL
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      thumbnail_url:
                        type: string
                        example: "https://assets.videodb.io/thumb/12345.jpg"

    post:
      summary: Generate custom thumbnail
      security:
        - ApiKeyAuth: []
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^m-"
            example: "m-12345"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                timestamp:
                  type: number
                  example: 10.5
                width:
                  type: integer
                  example: 320
                height:
                  type: integer
                  example: 180
      responses:
        '200':
          description: Thumbnail generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncResponse'

  /video/{video_id}/thumbnails/:
    get:
      summary: Get all video thumbnails
      security:
        - ApiKeyAuth: []
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^m-"
            example: "m-12345"
      responses:
        '200':
          description: List of thumbnails
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        timestamp:
                          type: number
                          example: 10.5
                        url:
                          type: string
                          example: "https://assets.videodb.io/thumb/12345_10.jpg"

  /video/{video_id}/transcription/:
    get:
      summary: Get video transcription
      security:
        - ApiKeyAuth: []
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^m-"
            example: "m-12345"
        - name: engine
          in: query
          schema:
            type: string
            default: "default"
            example: "default"
        - name: start
          in: query
          schema:
            type: number
            default: 0
            example: 10.5
        - name: end
          in: query
          schema:
            type: number
            default: -1
            example: 60.0
        - name: segmenter
          in: query
          schema:
            type: string
            default: "word"
            example: "word"
        - name: length
          in: query
          schema:
            type: integer
            default: 1
            example: 1
      responses:
        '200':
          description: Transcription data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  status:
                    type: string
                    enum: [completed, processing, failed]
                    example: "completed"
                  data:
                    type: object
                    properties:
                      transcript:
                        type: array
                        items:
                          type: object
                          properties:
                            text:
                              type: string
                              example: "Hello world"
                            start:
                              type: number
                              example: 1.5
                            end:
                              type: number
                              example: 3.2

    post:
      summary: Generate video transcription
      security:
        - ApiKeyAuth: []
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^m-"
            example: "m-12345"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                engine:
                  type: string
                  default: "default"
                  example: "default"
                force:
                  type: boolean
                  example: false
                language_code:
                  type: string
                  example: "en-US"
                callback_url:
                  type: string
                  example: "https://webhook.example.com/callback"
                callback_data:
                  type: object
      responses:
        '200':
          description: Transcription job started
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/AsyncResponse'
                  - type: object
                    properties:
                      success:
                        type: boolean
                        example: true
                      message:
                        type: string
                        example: "transcription already exists"

  /video/{video_id}/index/:
    get:
      summary: Get video index status
      security:
        - ApiKeyAuth: []
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^m-"
            example: "m-12345"
        - name: index_type
          in: query
          required: true
          schema:
            type: string
            enum: [spoken_word, scene]
            example: "spoken_word"
        - name: engine
          in: query
          schema:
            type: string
            default: "default"
            example: "default"
      responses:
        '200':
          description: Index status
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  status:
                    type: string
                    enum: [done, processing, failed]
                    example: "done"
                  message:
                    type: string
                    example: "Index is available"

    post:
      summary: Create video index
      security:
        - ApiKeyAuth: []
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^m-"
            example: "m-12345"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                index_type:
                  type: string
                  enum: [spoken_word, scene]
                  default: "spoken_word"
                  example: "spoken_word"
                engine:
                  type: string
                  default: "default"
                  example: "default"
                force:
                  type: boolean
                  example: false
                language_code:
                  type: string
                  example: "en-US"
                segmentation_type:
                  type: string
                  default: "sentence"
                  example: "sentence"
                callback_url:
                  type: string
                  example: "https://webhook.example.com/callback"
      responses:
        '200':
          description: Index job started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncResponse'

  /video/{video_id}/search/:
    post:
      summary: Search within video
      security:
        - ApiKeyAuth: []
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^m-"
            example: "m-12345"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                  example: "search query"
                index_type:
                  type: string
                  enum: [spoken_word, scene]
                  example: "spoken_word"
                search_type:
                  type: string
                  enum: [semantic, keyword]
                  example: "semantic"
                score_threshold:
                  type: number
                  example: 0.2
                result_threshold:
                  type: integer
                  example: 10
                stitch:
                  type: boolean
                  example: true
                scene_index_id:
                  type: string
                  example: "idx-12345"
                filter:
                  type: array
                  items:
                    type: object
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResult'

  /video/{video_id}/scenes/:
    get:
      summary: Get video scenes
      security:
        - ApiKeyAuth: []
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^m-"
            example: "m-12345"
      responses:
        '200':
          description: List of scenes
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        scene_id:
                          type: string
                          example: "scene-123"
                        start_time:
                          type: number
                          example: 10.5
                        end_time:
                          type: number
                          example: 25.3
                        description:
                          type: string
                          example: "Scene description"
                        thumbnail_url:
                          type: string
                          example: "https://assets.videodb.io/scene/123.jpg"

    post:
      summary: Create video scenes
      security:
        - ApiKeyAuth: []
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^m-"
            example: "m-12345"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                scene_type:
                  type: string
                  enum: [shot, time_based]
                  example: "shot"
                callback_url:
                  type: string
                  example: "https://webhook.example.com/callback"
      responses:
        '200':
          description: Scene creation started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncResponse'

  /video/{video_id}/scene/{scene_id}/describe/:
    post:
      summary: Describe video scene
      security:
        - ApiKeyAuth: []
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^m-"
            example: "m-12345"
        - name: scene_id
          in: path
          required: true
          schema:
            type: string
            example: "scene-123"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                prompt:
                  type: string
                  example: "Describe what happens in this scene"
                model_name:
                  type: string
                  example: "gpt-4"
      responses:
        '200':
          description: Scene description generated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      description:
                        type: string
                        example: "Scene description text"

  /video/{video_id}/frame/{frame_id}/describe/:
    post:
      summary: Describe video frame
      security:
        - ApiKeyAuth: []
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^m-"
            example: "m-12345"
        - name: frame_id
          in: path
          required: true
          schema:
            type: string
            example: "frame-123"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                prompt:
                  type: string
                  example: "Describe this frame"
                model_name:
                  type: string
                  example: "gpt-4-vision"
      responses:
        '200':
          description: Frame description generated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      description:
                        type: string
                        example: "Frame description text"

  /video/{video_id}/clip:
    post:
      summary: Generate video clip
      security:
        - ApiKeyAuth: []
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^m-"
            example: "m-12345"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - prompt
              properties:
                prompt:
                  type: string
                  example: "Create a clip about the introduction"
                content_type:
                  type: string
                  default: "spoken"
                  example: "spoken"
                model_name:
                  type: string
                  default: "basic"
                  example: "basic"
                scene_index_id:
                  type: string
                  example: "idx-12345"
                callback_url:
                  type: string
                  example: "https://webhook.example.com/callback"
      responses:
        '200':
          description: Clip generation started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncResponse'

  /video/{video_id}/workflow/:
    post:
      summary: Execute video workflow
      security:
        - ApiKeyAuth: []
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^m-"
            example: "m-12345"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - workflow_type
              properties:
                workflow_type:
                  type: string
                  enum: [transcribe, index, analyze]
                  example: "transcribe"
                config:
                  type: object
                  properties:
                    language:
                      type: string
                      example: "en"
                    model:
                      type: string
                      example: "gpt-4"
      responses:
        '200':
          description: Workflow started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncResponse'

  /audio/:
    get:
      summary: List audios
      security:
        - ApiKeyAuth: []
      parameters:
        - name: collection_id
          in: query
          schema:
            type: string
            example: "default"
      responses:
        '200':
          description: List of audios
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      audios:
                        type: array
                        items:
                          $ref: '#/components/schemas/Audio'

  /audio/{audio_id}:
    get:
      summary: Get audio details
      security:
        - ApiKeyAuth: []
      parameters:
        - name: audio_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^a-"
            example: "a-12345"
        - name: collection_id
          in: query
          schema:
            type: string
            example: "default"
      responses:
        '200':
          description: Audio details
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Audio'

    patch:
      summary: Update audio
      tags:
        - Audio
      security:
        - ApiKeyAuth: []
      parameters:
        - name: audio_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^a-"
            example: "a-12345"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: "Updated Audio Name"
      responses:
        '200':
          description: Audio updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Audio'

    delete:
      summary: Delete audio
      security:
        - ApiKeyAuth: []
      parameters:
        - name: audio_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^a-"
            example: "a-12345"
      responses:
        '200':
          description: Audio deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /audio/{audio_id}/generate_url:
    post:
      summary: Generate audio stream URL
      security:
        - ApiKeyAuth: []
      parameters:
        - name: audio_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^a-"
            example: "a-12345"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                format:
                  type: string
                  enum: [mp3, wav, flac]
                  example: "mp3"
                quality:
                  type: string
                  enum: [low, medium, high]
                  example: "high"
      responses:
        '200':
          description: Stream URL generated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      stream_url:
                        type: string
                        example: "https://stream.videodb.io/a/12345"

  /image/:
    get:
      summary: List images
      security:
        - ApiKeyAuth: []
      parameters:
        - name: collection_id
          in: query
          schema:
            type: string
            example: "default"
      responses:
        '200':
          description: List of images
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      images:
                        type: array
                        items:
                          $ref: '#/components/schemas/Image'

  /image/{image_id}:
    get:
      summary: Get image details
      security:
        - ApiKeyAuth: []
      parameters:
        - name: image_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^img-"
            example: "img-12345"
        - name: collection_id
          in: query
          schema:
            type: string
            example: "default"
      responses:
        '200':
          description: Image details
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Image'

    patch:
      summary: Update image
      tags:
        - Images
      security:
        - ApiKeyAuth: []
      parameters:
        - name: image_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^img-"
            example: "img-12345"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: "Updated Image Name"
      responses:
        '200':
          description: Image updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Image'

    delete:
      summary: Delete image
      security:
        - ApiKeyAuth: []
      parameters:
        - name: image_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^img-"
            example: "img-12345"
      responses:
        '200':
          description: Image deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /image/{image_id}/generate_url:
    post:
      summary: Generate image URL
      security:
        - ApiKeyAuth: []
      parameters:
        - name: image_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^img-"
            example: "img-12345"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                format:
                  type: string
                  enum: [jpg, png, webp]
                  example: "jpg"
                quality:
                  type: integer
                  minimum: 1
                  maximum: 100
                  example: 90
                width:
                  type: integer
                  example: 1024
                height:
                  type: integer
                  example: 768
      responses:
        '200':
          description: Image URL generated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      image_url:
                        type: string
                        example: "https://assets.videodb.io/img/12345.jpg"

  /collection/{collection_id}/generate/image/:
    post:
      summary: Generate image using AI
      security:
        - ApiKeyAuth: []
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
            example: "default"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - prompt
              properties:
                prompt:
                  type: string
                  example: "A beautiful sunset over mountains"
                aspect_ratio:
                  type: string
                  example: "16:9"
                model_name:
                  type: string
                  description: Model used for image generation.
                  example: "black-forest-labs/FLUX.1-dev"
                config:
                  type: object
                  description: Model configuration. For FLUX supports size, num_inference_steps, guidance_scale, negative_prompt, and seed.
                  additionalProperties: true
                sandbox_id:
                  type: string
                  description: Sandbox ID used for self-hosted image generation.
                  example: "bx-123abc"
                callback_url:
                  type: string
                  example: "https://webhook.example.com/callback"
      responses:
        '200':
          description: Image generation started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncResponse'

  /collection/{collection_id}/generate/video/:
    post:
      summary: Generate video using AI
      security:
        - ApiKeyAuth: []
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
            example: "default"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - prompt
              properties:
                prompt:
                  type: string
                  example: "A cat playing with a ball"
                duration:
                  type: number
                  example: 5
                callback_url:
                  type: string
                  example: "https://webhook.example.com/callback"
      responses:
        '200':
          description: Video generation started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncResponse'

  /collection/{collection_id}/generate/audio/:
    post:
      summary: Generate audio using AI
      security:
        - ApiKeyAuth: []
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
            example: "default"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - audio_type
              properties:
                prompt:
                  type: string
                  description: Prompt for music or sound effect generation.
                  example: "Generate upbeat background music"
                text:
                  type: string
                  description: Text to convert to speech when `audio_type` is `voice`.
                  example: "Hello, welcome to VideoDB."
                audio_type:
                  type: string
                  enum: [voice, sound_effect, music]
                  example: "voice"
                voice_name:
                  type: string
                  description: Voice name for hosted text-to-speech.
                  example: "Default"
                model_name:
                  type: string
                  description: Model used for text-to-speech.
                  example: "k2-fsa/OmniVoice"
                config:
                  type: object
                  description: Voice configuration. For OmniVoice supports instructions, ref_audio, ref_text, response_format, speed, language, and max_new_tokens.
                  additionalProperties: true
                sandbox_id:
                  type: string
                  description: Sandbox ID used for self-hosted text-to-speech.
                  example: "bx-123abc"
                voice_clone_id:
                  type: string
                  description: Reusable VideoDB voice clone ID.
                  example: "vc-123abc"
                callback_url:
                  type: string
                  example: "https://webhook.example.com/callback"
      responses:
        '200':
          description: Audio generation started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncResponse'

  /sandbox:
    post:
      summary: Create a Sandbox Compute pool
      tags:
        - Sandbox
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tier:
                  type: string
                  enum: [small, medium]
                  example: "small"
                name:
                  type: string
                  example: "my-sandbox"
                callback_url:
                  type: string
                  format: uri
                models:
                  type: array
                  items:
                    type: string
                  example: ["rtdetr-v2-r50vd"]
                model_categories:
                  type: array
                  items:
                    type: string
                  example: ["object_detection"]
              anyOf:
                - required: [models]
                - required: [model_categories]
      responses:
        '200':
          description: Sandbox accepted for provisioning
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxResponse'
    get:
      summary: List Sandbox Compute pools
      tags:
        - Sandbox
      security:
        - ApiKeyAuth: []
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [provisioning, active, alert, stopping, stopped, failed]
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: page_size
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Sandbox list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxListResponse'

  /sandbox/{sandbox_id}:
    get:
      summary: Get a Sandbox Compute pool
      tags:
        - Sandbox
      security:
        - ApiKeyAuth: []
      parameters:
        - name: sandbox_id
          in: path
          required: true
          schema:
            type: string
            example: "bx-123abc"
      responses:
        '200':
          description: Current Sandbox state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxResponse'

  /sandbox/{sandbox_id}/stop:
    post:
      summary: Stop a Sandbox Compute pool
      tags:
        - Sandbox
      security:
        - ApiKeyAuth: []
      parameters:
        - name: sandbox_id
          in: path
          required: true
          schema:
            type: string
            example: "bx-123abc"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                grace:
                  type: boolean
                  default: true
      responses:
        '200':
          description: Sandbox stopping
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxResponse'

  /job/{job_id}:
    get:
      summary: Get self-inference generation job status
      security:
        - ApiKeyAuth: []
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
            example: "550e8400-e29b-41d4-a716-446655440000"
      responses:
        '200':
          description: Generation job status or final generated asset
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  status:
                    type: string
                    enum: [processing, done, failed]
                  data:
                    type: object
                    additionalProperties: true
                  message:
                    type: string
        '404':
          description: Job not found

  /collection/{collection_id}/generate/text/:
    post:
      summary: Generate text using AI
      security:
        - ApiKeyAuth: []
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
            example: "default"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Provide either `prompt` for inline text or `prompt_url` for a previously uploaded prompt file.
              properties:
                prompt:
                  type: string
                  description: Inline prompt text. Use for smaller prompts.
                  example: "Summarize the content of this video"
                prompt_url:
                  type: string
                  description: URL to a previously uploaded plain-text prompt file. Use for larger prompts.
                  example: "https://storage.googleapis.com/.../generate_text_prompt_123abc.txt"
                video_id:
                  type: string
                  example: "m-12345"
                model_name:
                  type: string
                  description: Hosted tier (`mini`, `basic`, `pro`, `ultra`) or self-hosted sandbox model name.
                  example: "Qwen/Qwen3.5-27B"
                sandbox_id:
                  type: string
                  description: Sandbox ID to use when `model_name` is a self-hosted model.
                  example: "bx-123abc"
                max_tokens:
                  type: integer
                  example: 500
                temperature:
                  type: number
                  example: 0.7
                model_config:
                  type: object
                  description: Additional self-hosted model configuration.
                  additionalProperties: true
                callback_url:
                  type: string
                  example: "https://webhook.example.com/callback"
              oneOf:
                - required:
                    - prompt
                - required:
                    - prompt_url
      responses:
        '200':
          description: Text generation started or completed
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/AsyncResponse'
                  - type: object
                    properties:
                      success:
                        type: boolean
                        example: true
                      data:
                        type: object
                        properties:
                          output:
                            type: string
                            example: "Generated text content"

  /timeline:
    post:
      summary: Compile timeline
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - request_type
                - timeline
              properties:
                request_type:
                  type: string
                  enum: [compile]
                  example: "compile"
                timeline:
                  type: array
                  items:
                    $ref: '#/components/schemas/Timeline'
      responses:
        '200':
          description: Timeline compilation result
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      stream_url:
                        type: string
                        example: "https://stream.videodb.io/compiled/12345"

  /billing/usage:
    get:
      summary: Get billing usage information
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Billing usage data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/BillingUsage'

  /billing/checkout:
    post:
      summary: Create billing checkout session
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mode:
                  type: string
                  enum: [payment, subscription]
                  example: "payment"
                plan_id:
                  type: string
                  example: "plan-basic"
                amount:
                  type: number
                  example: 100
      responses:
        '200':
          description: Checkout URL
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      url:
                        type: string
                        example: "https://checkout.stripe.com/pay/xxx"

  /billing/checkouts:
    get:
      summary: Get billing checkout history
      security:
        - ApiKeyAuth: []
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            example: 10
        - name: offset
          in: query
          schema:
            type: integer
            example: 0
      responses:
        '200':
          description: Checkout history
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: "cs_test_xxx"
                        amount:
                          type: number
                          example: 100
                        currency:
                          type: string
                          example: "usd"
                        status:
                          type: string
                          example: "completed"
                        created_at:
                          type: string
                          format: date-time

  /billing/invoices:
    get:
      summary: Get billing invoices
      security:
        - ApiKeyAuth: []
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            example: 10
        - name: offset
          in: query
          schema:
            type: integer
            example: 0
      responses:
        '200':
          description: Invoice list
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: "in_xxx"
                        amount:
                          type: number
                          example: 100
                        currency:
                          type: string
                          example: "usd"
                        status:
                          type: string
                          example: "paid"
                        pdf_url:
                          type: string
                          example: "https://invoice.stripe.com/pdf/xxx"
                        created_at:
                          type: string
                          format: date-time

  /billing/topup:
    post:
      summary: Create topup payment
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - amount
              properties:
                amount:
                  type: number
                  example: 50
                currency:
                  type: string
                  example: "usd"
      responses:
        '200':
          description: Topup checkout URL
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      url:
                        type: string
                        example: "https://checkout.stripe.com/pay/xxx"

  /billing/auto_recharge:
    get:
      summary: Get auto recharge settings
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Auto recharge settings
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      enabled:
                        type: boolean
                        example: true
                      threshold:
                        type: number
                        example: 10
                      amount:
                        type: number
                        example: 50

    post:
      summary: Update auto recharge settings
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                enabled:
                  type: boolean
                  example: true
                threshold:
                  type: number
                  example: 10
                amount:
                  type: number
                  example: 50
      responses:
        '200':
          description: Auto recharge updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Auto recharge settings updated"

  /async-response/{response_id}:
    get:
      summary: Get async operation result
      parameters:
        - name: response_id
          in: path
          required: true
          schema:
            type: string
            example: "job-12345"
      responses:
        '200':
          description: Operation result
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  status:
                    type: string
                    enum: [processing, done, failed]
                    example: "done"
                  data:
                    type: object
                    description: "Result data varies by operation type"
        '404':
          description: Response not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /download:
    get:
      summary: List download entries
      security:
        - ApiKeyAuth: []
      parameters:
        - name: page_index
          in: query
          schema:
            type: integer
            example: 0
        - name: count
          in: query
          schema:
            type: integer
            maximum: 5000
            example: 50
      responses:
        '200':
          description: List of downloads
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      downloads:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              example: "download-12345"
                            name:
                              type: string
                              example: "video_download.mp4"
                            status:
                              type: string
                              enum: [processing, done, error]
                              example: "done"
                            created_at:
                              type: string
                              format: date-time
                            download_url:
                              type: string
                              example: "https://example.com/download/video.mp4"

    post:
      summary: Create download request
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - stream_link
              properties:
                stream_link:
                  type: string
                  example: "https://stream.videodb.io/v/12345"
                name:
                  type: string
                  example: "my_download.mp4"
      responses:
        '200':
          description: Download initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncResponse'

    delete:
      summary: Delete download entry
      security:
        - ApiKeyAuth: []
      parameters:
        - name: download_id
          in: query
          required: true
          schema:
            type: string
            example: "download-12345"
      responses:
        '200':
          description: Download deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /download/{download_id}:
    get:
      summary: Get download status/details
      security:
        - ApiKeyAuth: []
      parameters:
        - name: download_id
          in: path
          required: true
          schema:
            type: string
            example: "download-12345"
      responses:
        '200':
          description: Download status
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/AsyncResponse'
                  - type: object
                    properties:
                      success:
                        type: boolean
                        example: true
                      data:
                        type: object
                        properties:
                          id:
                            type: string
                            example: "download-12345"
                          name:
                            type: string
                            example: "video_download.mp4"
                          status:
                            type: string
                            enum: [processing, done, error]
                            example: "done"
                          download_url:
                            type: string
                            example: "https://example.com/download/video.mp4"
                          created_at:
                            type: string
                            format: date-time

    post:
      summary: Retry download
      security:
        - ApiKeyAuth: []
      parameters:
        - name: download_id
          in: path
          required: true
          schema:
            type: string
            example: "download-12345"
      responses:
        '200':
          description: Download retry initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncResponse'

  /chat/completions:
    post:
      summary: OpenAI-compatible chat completions proxy
      description: Proxy endpoint for OpenAI chat completions API with VideoDB billing
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - messages
              properties:
                model:
                  type: string
                  enum: [gpt-4o-2024-11-20]
                  example: "gpt-4o-2024-11-20"
                messages:
                  type: array
                  items:
                    type: object
                    properties:
                      role:
                        type: string
                        enum: [system, user, assistant]
                        example: "user"
                      content:
                        type: string
                        example: "Hello, how are you?"
                max_tokens:
                  type: integer
                  example: 100
                temperature:
                  type: number
                  example: 0.7
                stream:
                  type: boolean
                  example: false
      responses:
        '200':
          description: Chat completion response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: "chatcmpl-123"
                  object:
                    type: string
                    example: "chat.completion"
                  created:
                    type: integer
                    example: 1677652288
                  model:
                    type: string
                    example: "gpt-4o-2024-11-20"
                  choices:
                    type: array
                    items:
                      type: object
                      properties:
                        index:
                          type: integer
                          example: 0
                        message:
                          type: object
                          properties:
                            role:
                              type: string
                              example: "assistant"
                            content:
                              type: string
                              example: "Hello! I'm doing well, thank you for asking."
                        finish_reason:
                          type: string
                          example: "stop"
                  usage:
                    type: object
                    properties:
                      prompt_tokens:
                        type: integer
                        example: 10
                      completion_tokens:
                        type: integer
                        example: 15
                      total_tokens:
                        type: integer
                        example: 25

  /timeline_v2:
    post:
      summary: Compile timeline (v2)
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - request_type
                - timeline
              properties:
                request_type:
                  type: string
                  enum: [compile]
                  example: "compile"
                timeline:
                  type: array
                  items:
                    $ref: '#/components/schemas/Timeline'
                output_format:
                  type: string
                  enum: [mp4, webm, hls]
                  example: "mp4"
                quality:
                  type: string
                  enum: [low, medium, high]
                  example: "high"
      responses:
        '200':
          description: Timeline compilation result
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      stream_url:
                        type: string
                        example: "https://stream.videodb.io/compiled/12345"
                      duration:
                        type: number
                        example: 120.5
                      format:
                        type: string
                        example: "mp4"

  /timeline_v2/download:
    post:
      summary: Download compiled timeline
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - timeline_id
              properties:
                timeline_id:
                  type: string
                  example: "timeline-12345"
                format:
                  type: string
                  enum: [mp4, webm, avi]
                  example: "mp4"
                quality:
                  type: string
                  enum: [low, medium, high]
                  example: "high"
      responses:
        '200':
          description: Download initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncResponse'

  /compile/:
    post:
      summary: Compile media content
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - inputs
              properties:
                inputs:
                  type: array
                  items:
                    type: object
                    properties:
                      media_id:
                        type: string
                        example: "m-12345"
                      start_time:
                        type: number
                        example: 10.0
                      end_time:
                        type: number
                        example: 30.0
                output_format:
                  type: string
                  enum: [mp4, webm, hls]
                  example: "mp4"
                callback_url:
                  type: string
                  example: "https://webhook.example.com/callback"
      responses:
        '200':
          description: Compilation started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncResponse'

  /video/{video_id}/index/scene/:
    get:
      summary: Get video scene index status
      security:
        - ApiKeyAuth: []
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^m-"
            example: "m-12345"
      responses:
        '200':
          description: Scene index status
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  status:
                    type: string
                    enum: [done, processing, failed]
                    example: "done"
                  data:
                    type: object
                    properties:
                      scene_count:
                        type: integer
                        example: 25
                      total_duration:
                        type: number
                        example: 120.5
                      last_updated:
                        type: string
                        format: date-time

    post:
      summary: Create video scene index
      security:
        - ApiKeyAuth: []
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^m-"
            example: "m-12345"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                scene_type:
                  type: string
                  enum: [shot, time_based]
                  example: "shot"
                segmentation_threshold:
                  type: number
                  example: 0.8
                callback_url:
                  type: string
                  example: "https://webhook.example.com/callback"
      responses:
        '200':
          description: Scene index creation started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncResponse'

  /video/{video_id}/index/scene/{scene_index_id}:
    get:
      summary: Get scene index details
      security:
        - ApiKeyAuth: []
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^m-"
            example: "m-12345"
        - name: scene_index_id
          in: path
          required: true
          schema:
            type: string
            example: "scene-idx-12345"
      responses:
        '200':
          description: Scene index details
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: "scene-idx-12345"
                      video_id:
                        type: string
                        example: "m-12345"
                      scene_type:
                        type: string
                        example: "shot"
                      status:
                        type: string
                        enum: [done, processing, failed]
                        example: "done"
                      scenes:
                        type: array
                        items:
                          type: object
                          properties:
                            start_time:
                              type: number
                              example: 10.5
                            end_time:
                              type: number
                              example: 25.3
                            confidence:
                              type: number
                              example: 0.85

    delete:
      summary: Delete scene index
      security:
        - ApiKeyAuth: []
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^m-"
            example: "m-12345"
        - name: scene_index_id
          in: path
          required: true
          schema:
            type: string
            example: "scene-idx-12345"
      responses:
        '200':
          description: Scene index deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /audio/{audio_id}/transcription/:
    get:
      summary: Get audio transcription
      tags:
        - Audio
      security:
        - ApiKeyAuth: []
      parameters:
        - name: audio_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^a-"
            example: "a-12345"
        - name: engine
          in: query
          schema:
            type: string
            example: "default"
        - name: start
          in: query
          schema:
            type: number
            default: 0
            example: 0
        - name: end
          in: query
          schema:
            type: number
            default: -1
            example: 60.0
      responses:
        '200':
          description: Audio transcription data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  status:
                    type: string
                    enum: [completed, processing, failed]
                    example: "completed"
                  data:
                    type: object
                    properties:
                      transcript:
                        type: array
                        items:
                          type: object
                          properties:
                            text:
                              type: string
                              example: "Hello world"
                            start:
                              type: number
                              example: 1.5
                            end:
                              type: number
                              example: 3.2
        '404':
          description: Transcription not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    post:
      summary: Generate audio transcription
      tags:
        - Audio
      security:
        - ApiKeyAuth: []
      parameters:
        - name: audio_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^a-"
            example: "a-12345"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                engine:
                  type: string
                  default: "default"
                  example: "default"
                language_code:
                  type: string
                  default: "en"
                  example: "en"
                force:
                  type: boolean
                  default: false
                  example: false
                callback_url:
                  type: string
                  example: "https://webhook.example.com/callback"
                callback_data:
                  type: object
      responses:
        '200':
          description: Transcription job started
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/AsyncResponse'
                  - type: object
                    properties:
                      success:
                        type: boolean
                        example: true
                      message:
                        type: string
                        example: "transcription already exists"

  /collection/{collection_id}/upload_url:
    get:
      summary: Get presigned upload URL
      tags:
        - Collections
      security:
        - ApiKeyAuth: []
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
            example: "default"
        - name: name
          in: query
          schema:
            type: string
            example: "my_video.mp4"
      responses:
        '200':
          description: Upload URL generated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      upload_url:
                        type: string
                        example: "https://s3.amazonaws.com/..."
                      video_id:
                        type: string
                        example: "m-12345"

  /collection/{collection_id}/websocket:
    get:
      summary: Get WebSocket connection URL
      tags:
        - Collections
      security:
        - ApiKeyAuth: []
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
            example: "default"
      responses:
        '200':
          description: WebSocket URL
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      websocket_url:
                        type: string
                        example: "wss://ws.videodb.io/..."

  /collection/{collection_id}/search/title/:
    post:
      summary: Search by title within collection
      tags:
        - Search
      security:
        - ApiKeyAuth: []
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
            example: "default"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                  example: "search query"
                search_type:
                  type: string
                  default: "llm"
                  example: "llm"
      responses:
        '200':
          description: Title search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object

  /collection/{collection_id}/search/web/:
    post:
      summary: Web search within collection
      tags:
        - Search
      security:
        - ApiKeyAuth: []
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
            example: "default"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                  example: "search query"
      responses:
        '200':
          description: Web search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object

  /collection/{collection_id}/generate/video/dub:
    post:
      summary: Dub video with AI-generated audio
      tags:
        - AI Generation
      security:
        - ApiKeyAuth: []
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
            example: "default"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                video_id:
                  type: string
                  example: "m-12345"
                target_language:
                  type: string
                  example: "es"
                callback_url:
                  type: string
                  example: "https://webhook.example.com/callback"
                callback_data:
                  type: object
      responses:
        '200':
          description: Dubbing job started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncResponse'

  /collection/{collection_id}/video/{video_id}/translate:
    post:
      summary: Translate video content
      tags:
        - AI Generation
      security:
        - ApiKeyAuth: []
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
            example: "default"
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^m-"
            example: "m-12345"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                target_language:
                  type: string
                  example: "es"
                callback_url:
                  type: string
                  example: "https://webhook.example.com/callback"
                callback_data:
                  type: object
      responses:
        '200':
          description: Translation job started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncResponse'

  /video/{video_id}/scenes/{scene_collection_id}/:
    get:
      summary: Get scene collection details
      tags:
        - Videos
      security:
        - ApiKeyAuth: []
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^m-"
            example: "m-12345"
        - name: scene_collection_id
          in: path
          required: true
          schema:
            type: string
            example: "sc-12345"
        - name: offset
          in: query
          schema:
            type: integer
            example: 0
        - name: limit
          in: query
          schema:
            type: integer
            example: 100
      responses:
        '200':
          description: Scene collection details
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: "sc-12345"
                      scenes:
                        type: array
                        items:
                          type: object
                          properties:
                            scene_id:
                              type: string
                            start:
                              type: number
                            end:
                              type: number
                            description:
                              type: string

    patch:
      summary: Update scene collection
      tags:
        - Videos
      security:
        - ApiKeyAuth: []
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^m-"
            example: "m-12345"
        - name: scene_collection_id
          in: path
          required: true
          schema:
            type: string
            example: "sc-12345"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - scenes
              properties:
                scenes:
                  type: array
                  items:
                    type: object
      responses:
        '200':
          description: Scene collection updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

    delete:
      summary: Delete scene collection
      tags:
        - Videos
      security:
        - ApiKeyAuth: []
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^m-"
            example: "m-12345"
        - name: scene_collection_id
          in: path
          required: true
          schema:
            type: string
            example: "sc-12345"
      responses:
        '200':
          description: Scene collection deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncResponse'

  /video/{video_id}/index/delete:
    post:
      summary: Delete video index
      tags:
        - Videos
      security:
        - ApiKeyAuth: []
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^m-"
            example: "m-12345"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                index_type:
                  type: string
                  enum: [spoken_word, scene, all]
                  default: "all"
                  example: "all"
                model_name:
                  type: string
                  default: "gpt4-v"
                  example: "gpt4-v"
      responses:
        '200':
          description: Index deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /video/{video_id}/reframe:
    post:
      summary: Reframe video to different aspect ratio
      tags:
        - Videos
      security:
        - ApiKeyAuth: []
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^m-"
            example: "m-12345"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - target
                - mode
              properties:
                target:
                  type: string
                  example: "9:16"
                mode:
                  type: string
                  example: "auto"
                start:
                  type: number
                  default: 0
                  example: 0
                end:
                  type: number
                  example: 30
                callback_url:
                  type: string
                  example: "https://webhook.example.com/callback"
                callback_data:
                  type: object
      responses:
        '200':
          description: Reframe job started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncResponse'

  /video/{video_id}/reframe/{reframe_id}:
    get:
      summary: Get reframe job status
      tags:
        - Videos
      security:
        - ApiKeyAuth: []
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^m-"
            example: "m-12345"
        - name: reframe_id
          in: path
          required: true
          schema:
            type: string
            example: "reframe-12345"
      responses:
        '200':
          description: Reframe job status
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  status:
                    type: string
                    enum: [processing, done, failed]
                    example: "done"
                  data:
                    type: object
        '404':
          description: Reframe job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /assets:
    get:
      summary: List all assets across collections
      tags:
        - Assets
      security:
        - ApiKeyAuth: []
      parameters:
        - name: collection_id
          in: query
          schema:
            type: string
            example: "default"
        - name: asset_type
          in: query
          description: Comma-separated asset types
          schema:
            type: string
            example: "video,audio,image"
        - name: sort_by
          in: query
          schema:
            type: string
            enum: [name, duration, size, created_at]
            default: "created_at"
            example: "created_at"
        - name: sort_order
          in: query
          schema:
            type: string
            enum: [asc, desc]
            default: "desc"
            example: "desc"
        - name: min_duration
          in: query
          schema:
            type: number
            example: 10
        - name: max_duration
          in: query
          schema:
            type: number
            example: 300
        - name: min_size
          in: query
          schema:
            type: number
            example: 1024
        - name: max_size
          in: query
          schema:
            type: number
            example: 104857600
        - name: name_pattern
          in: query
          description: Regex pattern for name filter
          schema:
            type: string
            example: ".*intro.*"
        - name: page
          in: query
          schema:
            type: integer
            default: 1
            example: 1
        - name: page_size
          in: query
          schema:
            type: integer
            default: 50000
            maximum: 50000
            example: 100
      responses:
        '200':
          description: List of assets
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object

  /user/api-key-collections:
    put:
      summary: Set API key collection scoping
      tags:
        - Authentication
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - api_key
                - collection_ids
              properties:
                api_key:
                  type: string
                  example: "sk-xxx"
                collection_ids:
                  type: array
                  items:
                    type: string
                  example: ["default", "c-12345"]
      responses:
        '200':
          description: API key collections updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Pro-only feature
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /editor:
    post:
      summary: Compile editor timeline
      tags:
        - Editor
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Timeline compilation payload with tracks and clips
      responses:
        '200':
          description: Timeline compilation started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncResponse'

  /editor/download:
    post:
      summary: Download compiled editor timeline
      tags:
        - Editor
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - stream_url
              properties:
                stream_url:
                  type: string
                  example: "https://stream.videodb.io/compiled/12345"
      responses:
        '200':
          description: Download URL generated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      download_url:
                        type: string
                        example: "https://download.videodb.io/..."

  /transcode:
    post:
      summary: Start transcode job
      tags:
        - Transcode
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - source
              properties:
                source:
                  type: string
                  description: Source video ID
                  example: "m-12345"
      responses:
        '200':
          description: Transcode job started
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      job_id:
                        type: string
                        example: "job-12345"
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /transcode/{job_id}:
    get:
      summary: Get transcode job status
      tags:
        - Transcode
      security:
        - ApiKeyAuth: []
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
            example: "job-12345"
      responses:
        '200':
          description: Transcode job details
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object

  /collection/{collection_id}/meeting/record:
    post:
      summary: Record a meeting
      tags:
        - Meeting
      security:
        - ApiKeyAuth: []
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
            example: "default"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - meeting_url
              properties:
                meeting_url:
                  type: string
                  example: "https://meet.google.com/abc-def-ghi"
                bot_name:
                  type: string
                  default: "VideoDB Assistant"
                  example: "VideoDB Assistant"
                meeting_title:
                  type: string
                  example: "Weekly standup"
                time_zone:
                  type: string
                  default: "UTC"
                  example: "UTC"
                bot_image_url:
                  type: string
                  example: "https://example.com/bot-avatar.png"
                realtime_stream:
                  type: boolean
                  default: false
                  example: false
                callback_url:
                  type: string
                  example: "https://webhook.example.com/callback"
                callback_data:
                  type: object
      responses:
        '200':
          description: Meeting recording started
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      bot_id:
                        type: string
                        example: "bot-12345"
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /collection/{collection_id}/meeting/{bot_id}:
    get:
      summary: Get meeting recording information
      tags:
        - Meeting
      security:
        - ApiKeyAuth: []
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
            example: "default"
        - name: bot_id
          in: path
          required: true
          schema:
            type: string
            example: "bot-12345"
      responses:
        '200':
          description: Meeting information
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      bot_id:
                        type: string
                        example: "bot-12345"
                      status:
                        type: string
                        example: "recording"
                      video_url:
                        type: string
                        example: "https://stream.videodb.io/v/12345"
        '400':
          description: Invalid meeting ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /video/{video_id}/meeting:
    get:
      summary: Get meeting by video
      tags:
        - Meeting
      security:
        - ApiKeyAuth: []
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^m-"
            example: "m-12345"
      responses:
        '200':
          description: Meeting information for video
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object

  /collection/{collection_id}/capture/session:
    post:
      summary: Create capture session
      tags:
        - Capture
      security:
        - ApiKeyAuth: []
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
            example: "default"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - end_user_id
              properties:
                end_user_id:
                  type: string
                  example: "user-123"
                callback_url:
                  type: string
                  example: "https://webhook.example.com/callback"
                ws_connection_id:
                  type: string
                  example: "conn-123"
                metadata:
                  type: object
      responses:
        '200':
          description: Capture session created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/CaptureSession'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    get:
      summary: List capture sessions
      tags:
        - Capture
      security:
        - ApiKeyAuth: []
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
            example: "default"
        - name: status
          in: query
          schema:
            type: string
            enum: [created, starting, active, stopped, failed]
            example: "active"
      responses:
        '200':
          description: List of capture sessions
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      sessions:
                        type: array
                        items:
                          $ref: '#/components/schemas/CaptureSession'
                      next_page:
                        type: string
                        nullable: true

  /collection/{collection_id}/capture/session/{session_id}:
    get:
      summary: Get capture session details
      tags:
        - Capture
      security:
        - ApiKeyAuth: []
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
            example: "default"
        - name: session_id
          in: path
          required: true
          schema:
            type: string
            example: "capture-12345"
      responses:
        '200':
          description: Capture session details
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/CaptureSession'
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /capture/session/token:
    post:
      summary: Create capture session token
      tags:
        - Capture
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: string
                  description: End user identifier for partner tracking
                  example: "user-123"
                expires_in:
                  type: integer
                  description: Token validity in seconds
                  default: 86400
                  example: 86400
      responses:
        '200':
          description: Session token created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      token:
                        type: string
                        example: "st-xxx"
                      expires_at:
                        type: number
                        example: 1700000000
                      expires_in:
                        type: integer
                        example: 86400

  /capture/session/start:
    post:
      summary: Start capture session
      tags:
        - Capture
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - session_id
                - channels
              properties:
                session_id:
                  type: string
                  example: "capture-12345"
                channels:
                  type: array
                  items:
                    type: object
                    required:
                      - channel_id
                    properties:
                      channel_id:
                        type: string
                        example: "mic"
                      channel_name:
                        type: string
                        example: "Microphone"
                      type:
                        type: string
                        enum: [audio, video]
                        default: "audio"
                        example: "audio"
                      store:
                        type: boolean
                        default: true
                        example: true
                ws_connection_id:
                  type: string
                  example: "conn-123"
                callback_url:
                  type: string
                  example: "https://webhook.example.com/callback"
      responses:
        '200':
          description: Capture session started
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      session_id:
                        type: string
                        example: "capture-12345"
                      status:
                        type: string
                        example: "starting"
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Insufficient credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /capture/session/{streaming_session_id}:
    get:
      summary: Get capture session with RTSP URLs
      tags:
        - Capture
      security:
        - ApiKeyAuth: []
      parameters:
        - name: streaming_session_id
          in: path
          required: true
          schema:
            type: string
            example: "capture-12345"
      responses:
        '200':
          description: Session details with RTSP URLs
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      session_id:
                        type: string
                        example: "capture-12345"
                      status:
                        type: string
                        example: "active"
                      channels:
                        type: array
                        items:
                          type: object
                          properties:
                            channel_id:
                              type: string
                            rtsp_url:
                              type: string
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /capture/session/{streaming_session_id}/stop:
    post:
      summary: Stop capture session
      tags:
        - Capture
      security:
        - ApiKeyAuth: []
      parameters:
        - name: streaming_session_id
          in: path
          required: true
          schema:
            type: string
            example: "capture-12345"
      responses:
        '200':
          description: Session stopped
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /rtstream/:
    get:
      summary: List RTStreams
      tags:
        - RTStream
      security:
        - ApiKeyAuth: []
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
            example: 10
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
            example: 0
        - name: status
          in: query
          schema:
            type: string
            enum: [connected, stopped]
            example: "connected"
        - name: name
          in: query
          description: Filter by name substring
          schema:
            type: string
            example: "my stream"
        - name: ordering
          in: query
          description: Sort field (prefix with - for descending)
          schema:
            type: string
            example: "-created_at"
      responses:
        '200':
          description: List of RTStreams
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      results:
                        type: array
                        items:
                          $ref: '#/components/schemas/RTStream'
                      count:
                        type: integer
                        example: 25
                      next:
                        type: string
                        nullable: true
                        example: "/rtstream/?limit=10&offset=10"
                      previous:
                        type: string
                        nullable: true
                        example: null

    post:
      summary: Create RTStream
      tags:
        - RTStream
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url
              properties:
                url:
                  type: string
                  description: RTSP or YouTube stream URL
                  example: "rtsp://example.com:8554/stream"
                name:
                  type: string
                  example: "My Stream"
                collection_id:
                  type: string
                  default: "default"
                  example: "default"
                sample_rate:
                  type: integer
                  default: 30
                  example: 30
                media_types:
                  type: array
                  items:
                    type: string
                    enum: [video, audio]
                  example: ["video", "audio"]
                store:
                  type: boolean
                  default: false
                  example: false
                enable_transcript:
                  type: boolean
                  default: true
                  example: true
                ws_connection_id:
                  type: string
                  example: "conn-123"
      responses:
        '201':
          description: RTStream created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/RTStream'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Insufficient credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /rtstream/{stream_id}/:
    get:
      summary: Get RTStream details
      tags:
        - RTStream
      security:
        - ApiKeyAuth: []
      parameters:
        - name: stream_id
          in: path
          required: true
          schema:
            type: string
            example: "rts-12345"
      responses:
        '200':
          description: RTStream details
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/RTStream'
        '404':
          description: Stream not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    patch:
      summary: Update RTStream
      tags:
        - RTStream
      security:
        - ApiKeyAuth: []
      parameters:
        - name: stream_id
          in: path
          required: true
          schema:
            type: string
            example: "rts-12345"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: "Updated Stream Name"
                sample_rate:
                  type: integer
                  example: 15
      responses:
        '200':
          description: RTStream updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/RTStream'
        '400':
          description: Invalid fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /rtstream/{stream_id}/status/:
    patch:
      summary: Start or stop RTStream
      tags:
        - RTStream
      security:
        - ApiKeyAuth: []
      parameters:
        - name: stream_id
          in: path
          required: true
          schema:
            type: string
            example: "rts-12345"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - action
              properties:
                action:
                  type: string
                  enum: [start, stop]
                  example: "stop"
      responses:
        '200':
          description: RTStream status updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /rtstream/{stream_id}/export:
    post:
      summary: Export RTStream recording as VideoDB asset
      tags:
        - RTStream
      security:
        - ApiKeyAuth: []
      parameters:
        - name: stream_id
          in: path
          required: true
          schema:
            type: string
            example: "rts-12345"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: "Exported Recording"
      responses:
        '200':
          description: Recording exported
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      video_id:
                        type: string
                        example: "m-12345"
                      name:
                        type: string
                        example: "Exported Recording"
                      stream_url:
                        type: string
                        example: "https://stream.videodb.io/v/12345"
                      player_url:
                        type: string
                        example: "https://console.videodb.io/player/12345"
                      duration:
                        type: number
                        example: 123.45
        '400':
          description: No recordings available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /rtstream/{stream_id}/index/scene:
    post:
      summary: Create RTStream scene index
      tags:
        - RTStream
      security:
        - ApiKeyAuth: []
      parameters:
        - name: stream_id
          in: path
          required: true
          schema:
            type: string
            example: "rts-12345"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                extraction_type:
                  type: string
                  enum: [time, transcript]
                  default: "time"
                  example: "time"
                extraction_config:
                  type: object
                  properties:
                    time:
                      type: integer
                      example: 10
                    frame_count:
                      type: integer
                      example: 5
                prompt:
                  type: string
                  example: "Describe the scene"
                model_name:
                  type: string
                  example: "GPT4o"
                model_config:
                  type: object
                name:
                  type: string
                  example: "My Scene Index"
                ws_connection_id:
                  type: string
                  example: "conn-123"
      responses:
        '200':
          description: Scene index created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      rtstream_index_id:
                        type: string
                        example: "scene-idx-12345"
                      extraction_type:
                        type: string
                        example: "time"
                      status:
                        type: string
                        example: "running"
                      prompt:
                        type: string
                        example: "Describe the scene"
                      name:
                        type: string
                        example: "My Scene Index"

    get:
      summary: List RTStream scene indexes
      tags:
        - RTStream
      security:
        - ApiKeyAuth: []
      parameters:
        - name: stream_id
          in: path
          required: true
          schema:
            type: string
            example: "rts-12345"
      responses:
        '200':
          description: List of scene indexes
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      scene_indexes:
                        type: array
                        items:
                          type: object
                          properties:
                            rtstream_index_id:
                              type: string
                              example: "scene-idx-12345"
                            extraction_type:
                              type: string
                              example: "time"
                            status:
                              type: string
                              example: "running"
                            prompt:
                              type: string
                            name:
                              type: string

  /rtstream/{stream_id}/index/{scene_index_id}:
    get:
      summary: Get RTStream scene index details
      tags:
        - RTStream
      security:
        - ApiKeyAuth: []
      parameters:
        - name: stream_id
          in: path
          required: true
          schema:
            type: string
            example: "rts-12345"
        - name: scene_index_id
          in: path
          required: true
          schema:
            type: string
            example: "scene-idx-12345"
      responses:
        '200':
          description: Scene index details
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      rtstream_index_id:
                        type: string
                        example: "scene-idx-12345"
                      extraction_type:
                        type: string
                        example: "time"
                      extraction_config:
                        type: object
                      status:
                        type: string
                        example: "running"
                      prompt:
                        type: string
                      name:
                        type: string

  /rtstream/{stream_id}/index/scene/{scene_index_id}:
    get:
      summary: Get RTStream scene records
      tags:
        - RTStream
      security:
        - ApiKeyAuth: []
      parameters:
        - name: stream_id
          in: path
          required: true
          schema:
            type: string
            example: "rts-12345"
        - name: scene_index_id
          in: path
          required: true
          schema:
            type: string
            example: "scene-idx-12345"
        - name: page
          in: query
          schema:
            type: integer
            default: 1
            example: 1
        - name: page_size
          in: query
          schema:
            type: integer
            default: 100
            example: 100
        - name: start
          in: query
          description: Filter by start timestamp
          schema:
            type: number
            example: 1700000000
        - name: end
          in: query
          description: Filter by end timestamp
          schema:
            type: number
            example: 1700003600
      responses:
        '200':
          description: Scene records
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      scene_index_records:
                        type: array
                        items:
                          type: object
                          properties:
                            start:
                              type: number
                              example: 1700000000
                            end:
                              type: number
                              example: 1700000010
                            description:
                              type: string
                              example: "Scene description"
                      next_page:
                        type: boolean
                        example: false

    patch:
      summary: Update RTStream scene index prompt
      tags:
        - RTStream
      security:
        - ApiKeyAuth: []
      parameters:
        - name: stream_id
          in: path
          required: true
          schema:
            type: string
            example: "rts-12345"
        - name: scene_index_id
          in: path
          required: true
          schema:
            type: string
            example: "scene-idx-12345"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - prompt
              properties:
                prompt:
                  type: string
                  example: "Updated scene description prompt"
      responses:
        '200':
          description: Scene index prompt updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /rtstream/{stream_id}/index/scene/{scene_index_id}/status:
    patch:
      summary: Update RTStream scene index status
      tags:
        - RTStream
      security:
        - ApiKeyAuth: []
      parameters:
        - name: stream_id
          in: path
          required: true
          schema:
            type: string
            example: "rts-12345"
        - name: scene_index_id
          in: path
          required: true
          schema:
            type: string
            example: "scene-idx-12345"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - action
              properties:
                action:
                  type: string
                  enum: [start, stop]
                  example: "stop"
      responses:
        '200':
          description: Scene index status updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /rtstream/{stream_id}/search:
    post:
      summary: Search RTStream scene index
      tags:
        - RTStream
      security:
        - ApiKeyAuth: []
      parameters:
        - name: stream_id
          in: path
          required: true
          schema:
            type: string
            example: "rts-12345"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
                - scene_index_id
              properties:
                query:
                  type: string
                  example: "person walking"
                scene_index_id:
                  type: string
                  example: "scene-idx-12345"
                result_threshold:
                  type: integer
                  default: 10
                  example: 10
                score_threshold:
                  type: number
                  example: 0.5
                dynamic_score_percentage:
                  type: integer
                  default: 20
                  example: 20
                stitch:
                  type: boolean
                  default: true
                  example: true
                filter:
                  type: array
                  items:
                    type: object
                rerank:
                  type: boolean
                  default: false
                  example: false
                rerank_params:
                  type: object
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      results:
                        type: array
                        items:
                          type: object
                          properties:
                            start:
                              type: number
                              example: 1700000000
                            end:
                              type: number
                              example: 1700000010
                            text:
                              type: string
                              example: "matching scene text"
                            score:
                              type: number
                              example: 0.95
                            scene_index_id:
                              type: string
                              example: "scene-idx-12345"

  /rtstream/{stream_id}/stream:
    get:
      summary: Get RTStream playback URL
      tags:
        - RTStream
      security:
        - ApiKeyAuth: []
      parameters:
        - name: stream_id
          in: path
          required: true
          schema:
            type: string
            example: "rts-12345"
        - name: start
          in: query
          description: Start unix timestamp for time-based retrieval
          schema:
            type: number
            example: 1700000000
        - name: end
          in: query
          description: End unix timestamp for time-based retrieval
          schema:
            type: number
            example: 1700003600
        - name: original_frame_rate
          in: query
          schema:
            type: integer
            default: 1
            example: 1
        - name: frame_rate
          in: query
          schema:
            type: integer
            default: 1
            example: 1
      responses:
        '200':
          description: Stream URL
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      stream_url:
                        type: string
                        example: "https://stream.videodb.io/rts/12345"

  /rtstream/{stream_id}/transcription/:
    get:
      summary: Get RTStream transcription data
      tags:
        - RTStream
      security:
        - ApiKeyAuth: []
      parameters:
        - name: stream_id
          in: path
          required: true
          schema:
            type: string
            example: "rts-12345"
        - name: engine
          in: query
          schema:
            type: string
            default: "default"
            example: "default"
        - name: page
          in: query
          schema:
            type: integer
            default: 1
            example: 1
        - name: page_size
          in: query
          schema:
            type: integer
            default: 100
            maximum: 1000
            example: 100
        - name: start
          in: query
          description: Filter by start timestamp
          schema:
            type: number
            example: 1700000000
        - name: end
          in: query
          description: Filter by end timestamp
          schema:
            type: number
            example: 1700003600
        - name: since
          in: query
          description: Get only entries newer than this timestamp (for polling)
          schema:
            type: number
            example: 1700000000
      responses:
        '200':
          description: Transcription data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      transcription_records:
                        type: array
                        items:
                          type: object
                          properties:
                            start:
                              type: number
                              example: 1700000000
                            end:
                              type: number
                              example: 1700000005
                            text:
                              type: string
                              example: "transcribed text"
                            word_timestamps:
                              type: array
                              items:
                                type: object
                      next_page:
                        type: boolean
                        example: false
                      total_count:
                        type: integer
                        example: 50
                      page:
                        type: integer
                        example: 1
                      page_size:
                        type: integer
                        example: 100

    post:
      summary: Start or stop RTStream transcription
      tags:
        - RTStream
      security:
        - ApiKeyAuth: []
      parameters:
        - name: stream_id
          in: path
          required: true
          schema:
            type: string
            example: "rts-12345"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - action
              properties:
                action:
                  type: string
                  enum: [start, stop]
                  example: "start"
                engine:
                  type: string
                  default: "default"
                  example: "default"
                ws_connection_id:
                  type: string
                  example: "conn-123"
      responses:
        '200':
          description: Transcription status updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      status:
                        type: string
                        enum: [running, stopped]
                        example: "running"
                      engine:
                        type: string
                        example: "default"
                      updated_at:
                        type: string
                        format: date-time

  /rtstream/{stream_id}/transcription/status:
    get:
      summary: Get RTStream transcription status
      tags:
        - RTStream
      security:
        - ApiKeyAuth: []
      parameters:
        - name: stream_id
          in: path
          required: true
          schema:
            type: string
            example: "rts-12345"
        - name: engine
          in: query
          schema:
            type: string
            default: "default"
            example: "default"
      responses:
        '200':
          description: Transcription status
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      status:
                        type: string
                        enum: [running, stopped, not_configured]
                        example: "running"
                      engine:
                        type: string
                        example: "default"
                      language:
                        type: string
                        example: "en"
                      created_at:
                        type: string
                        format: date-time
                      updated_at:
                        type: string
                        format: date-time

  /rtstream/event:
    post:
      summary: Create collection event
      tags:
        - RTStream
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - event_prompt
                - label
              properties:
                event_prompt:
                  type: string
                  example: "Detect when a person enters the room"
                label:
                  type: string
                  example: "person-entry"
      responses:
        '200':
          description: Event created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      event_id:
                        type: string
                        example: "event-12345"

    get:
      summary: List collection events
      tags:
        - RTStream
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: List of events
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      events:
                        type: array
                        items:
                          type: object
                          properties:
                            event_id:
                              type: string
                              example: "event-12345"
                            event_prompt:
                              type: string
                              example: "Detect when a person enters the room"
                            label:
                              type: string
                              example: "person-entry"

  /rtstream/{stream_id}/index/{scene_index_id}/alert:
    post:
      summary: Create RTStream alert
      tags:
        - RTStream
      security:
        - ApiKeyAuth: []
      parameters:
        - name: stream_id
          in: path
          required: true
          schema:
            type: string
            example: "rts-12345"
        - name: scene_index_id
          in: path
          required: true
          schema:
            type: string
            example: "scene-idx-12345"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - event_id
              properties:
                event_id:
                  type: string
                  example: "event-12345"
                callback_url:
                  type: string
                  example: "https://webhook.example.com/alert"
                ws_connection_id:
                  type: string
                  example: "conn-123"
      responses:
        '200':
          description: Alert created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      alert_id:
                        type: string
                        example: "alert-12345"

    get:
      summary: List RTStream alerts
      tags:
        - RTStream
      security:
        - ApiKeyAuth: []
      parameters:
        - name: stream_id
          in: path
          required: true
          schema:
            type: string
            example: "rts-12345"
        - name: scene_index_id
          in: path
          required: true
          schema:
            type: string
            example: "scene-idx-12345"
      responses:
        '200':
          description: List of alerts
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      alerts:
                        type: array
                        items:
                          type: object
                          properties:
                            alert_id:
                              type: string
                              example: "alert-12345"
                            event_id:
                              type: string
                              example: "event-12345"
                            prompt:
                              type: string
                              example: "Detect when a person enters the room"
                            label:
                              type: string
                              example: "person-entry"
                            callback_url:
                              type: string
                              example: "https://webhook.example.com/alert"
                            status:
                              type: string
                              enum: [enabled, disabled]
                              example: "enabled"

  /rtstream/{stream_id}/index/{scene_index_id}/alert/{alert_id}/status:
    patch:
      summary: Update RTStream alert status
      tags:
        - RTStream
      security:
        - ApiKeyAuth: []
      parameters:
        - name: stream_id
          in: path
          required: true
          schema:
            type: string
            example: "rts-12345"
        - name: scene_index_id
          in: path
          required: true
          schema:
            type: string
            example: "scene-idx-12345"
        - name: alert_id
          in: path
          required: true
          schema:
            type: string
            example: "alert-12345"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - status
              properties:
                status:
                  type: string
                  enum: [enabled, disabled]
                  example: "disabled"
      responses:
        '200':
          description: Alert status updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

tags:
  - name: Authentication
    description: User authentication and API key management
  - name: Collections
    description: Collection management operations
  - name: Videos
    description: Video upload, processing, and management
  - name: Audio
    description: Audio management operations
  - name: Images
    description: Image management operations
  - name: Search
    description: Content search and indexing
  - name: AI Generation
    description: AI-powered content generation
  - name: Sandbox
    description: Dedicated compute lifecycle for supported open-weight models
  - name: Billing
    description: Billing and usage management
  - name: RTStream
    description: Real-time streaming operations
  - name: Utilities
    description: Utility endpoints
  - name: Meeting
    description: Meeting recording and management
  - name: Capture
    description: Capture session management for recording streams
  - name: Editor
    description: Timeline editor operations
  - name: Transcode
    description: Media transcoding operations
  - name: Assets
    description: Cross-collection asset listing