openapi: 3.1.0
info:
  title: Convai Live API
  version: "1.0-beta"
  description: |
    Beta Live API for ultra-low-latency, fully duplex character sessions over
    WebRTC. The /connect endpoint establishes a session and returns SDP/peer
    configuration; subsequent audio and event messages flow over WebRTC data
    channels (RTVI message format) and media tracks. Supports metrics and
    server-side audio data channels.
servers:
- url: https://live.convai.com
security:
- LiveApiKey: []
paths:
  /connect:
    post:
      summary: Connect Live Session
      operationId: connectLiveSession
      tags: [Live]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [character_id]
              properties:
                character_id: { type: string }
                session_id: { type: string }
                debug:
                  type: boolean
                  description: Enable metrics events on the data channel
                  default: false
                audio_config:
                  type: object
                  properties:
                    output:
                      type: object
                      properties:
                        audio_routing:
                          type: string
                          enum: [media, data-channel]
      responses:
        '200':
          description: Connection params (SDP, ICE servers, room info)
          content:
            application/json:
              schema:
                type: object
                properties:
                  room_url: { type: string, format: uri }
                  token: { type: string }
                  sdp: { type: string }
components:
  securitySchemes:
    LiveApiKey:
      type: apiKey
      in: header
      name: X-API-Key