{
  "openapi": "3.1.0",
  "info": {
    "title": "Voice Runtime Proxy & Recording API",
    "description": "API for voice runtime WebSocket proxying, call recordings, CDR ingestion, and static UI serving.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "http://localhost:9511/"
    }
  ],
  "tags": [
    { "name": "Voice Runtime" },
    { "name": "Recordings" },
    { "name": "CDR" },
    { "name": "Static" }
  ],
  "paths": {
    "/v1/conversation": {
      "get": {
        "tags": ["Voice Runtime"],
        "summary": "Voice Runtime WebSocket Proxy",
        "description": "WebSocket proxy endpoint for browser ↔ voice runtime audio and control messages.",
        "parameters": [
          { "name": "agent_id", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "environment_id", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "access_token", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "thread_id", "in": "query", "required": false, "schema": { "type": "string" } },
          { "name": "target_url", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" } }
        ],
        "responses": {
          "101": {
            "description": "WebSocket connection established"
          }
        },
        "x-websocket": {
          "messageTypes": [
            "start",
            "dtmf",
            "binary_audio_pcm16_16khz"
          ]
        }
      }
    },

    "/record": {
      "get": {
        "tags": ["Recordings"],
        "summary": "Call Recording WebSocket",
        "description": "WebSocket endpoint used by the voice runtime to stream call recordings.",
        "responses": {
          "101": {
            "description": "WebSocket connection established"
          }
        },
        "x-websocket": {
          "messageTypes": [
            "start",
            "audio_frame",
            "stop"
          ]
        }
      }
    },

    "/api/recordings": {
      "get": {
        "tags": ["Recordings"],
        "summary": "List all recordings",
        "responses": {
          "200": {
            "description": "List of available recordings",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecordingList"
                }
              }
            }
          }
        }
      }
    },

    "/api/recordings/{recording_id}": {
      "get": {
        "tags": ["Recordings"],
        "summary": "Get files in a recording",
        "parameters": [
          { "name": "recording_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Recording file list",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/RecordingFiles" }
              }
            }
          }
        }
      },
      "delete": {
        "tags": ["Recordings"],
        "summary": "Delete a recording",
        "parameters": [
          { "name": "recording_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Recording deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": { "type": "string" },
                    "recording_id": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },

    "/api/recordings/{recording_id}/metadata": {
      "get": {
        "tags": ["Recordings"],
        "summary": "Get recording metadata",
        "parameters": [
          { "name": "recording_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Recording metadata",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/RecordingMetadata" }
              }
            }
          }
        }
      }
    },

    "/api/recordings/{recording_id}/audio/{role}": {
      "get": {
        "tags": ["Recordings"],
        "summary": "Download role audio",
        "parameters": [
          { "name": "recording_id", "in": "path", "required": true, "schema": { "type": "string" } },
          {
            "name": "role",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "enum": ["user", "agent"] }
          }
        ],
        "responses": {
          "200": {
            "description": "Raw mono PCM audio",
            "headers": {
              "X-Sample-Rate": { "schema": { "type": "integer" }, "example": 16000 },
              "X-Channels": { "schema": { "type": "integer" }, "example": 1 },
              "X-Bit-Depth": { "schema": { "type": "integer" }, "example": 16 }
            },
            "content": {
              "application/octet-stream": {
                "schema": { "type": "string", "format": "binary" }
              }
            }
          }
        }
      }
    },

    "/api/recordings/{recording_id}/audio/interleaved": {
      "get": {
        "tags": ["Recordings"],
        "summary": "Download interleaved stereo audio",
        "parameters": [
          { "name": "recording_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Raw interleaved stereo PCM audio (16kHz, 16-bit)",
            "headers": {
              "X-Sample-Rate": { "schema": { "type": "integer" }, "example": 16000 },
              "X-Channels": { "schema": { "type": "integer" }, "example": 2 },
              "X-Bit-Depth": { "schema": { "type": "integer" }, "example": 16 },
              "X-Channel-Layout": { "schema": { "type": "string" }, "example": "stereo" }
            },
            "content": {
              "application/octet-stream": {
                "schema": { "type": "string", "format": "binary" }
              }
            }
          }
        }
      }
    },

    "/cdr-webhook": {
      "post": {
        "tags": ["CDR"],
        "summary": "Receive CDR webhook",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CdrWebhookRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook processed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string" },
                    "id": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },

    "/api/cdr/reports": {
      "get": {
        "tags": ["CDR"],
        "summary": "List CDR reports",
        "responses": {
          "200": {
            "description": "CDR report summaries",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/CdrReportSummary" }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": ["CDR"],
        "summary": "Clear CDR reports",
        "responses": {
          "200": {
            "description": "Reports cleared",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    }
  },

  "components": {
    "schemas": {
      "RecordingList": {
        "type": "object",
        "properties": {
          "recordings": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/RecordingSummary" }
          },
          "count": { "type": "integer" }
        }
      },
      "RecordingSummary": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "metadata": { "$ref": "#/components/schemas/RecordingMetadata" }
        }
      },
      "RecordingFiles": {
        "type": "object",
        "properties": {
          "recording_id": { "type": "string" },
          "files": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": { "type": "string" },
                "size": { "type": "integer" },
                "type": { "type": "string" }
              }
            }
          }
        }
      },
      "RecordingMetadata": {
        "type": "object",
        "properties": {
          "transaction_id": { "type": "string", "format": "uuid" },
          "duration_ms": { "type": "integer" },
          "start_time": { "type": "string", "format": "date-time" },
          "user_frames": { "type": "integer" },
          "agent_frames": { "type": "integer" }
        }
      },
      "CdrWebhookRequest": {
        "type": "object",
        "properties": {
          "cdr": { "$ref": "#/components/schemas/CdrReport" },
          "message": { "type": "string" }
        }
      },
      "CdrReportSummary": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "received_at": { "type": "string", "format": "date-time" },
          "transaction_id": { "type": "string" },
          "agent_id": { "type": "string" },
          "environment_id": { "type": "string" },
          "end_reason": { "type": "string" },
          "milliseconds_elapsed": { "type": "integer" },
          "turn_count": { "type": "integer" },
          "failure_occurred": { "type": "boolean" },
          "system_error": { "type": "boolean" },
          "message": { "type": "string" }
        }
      },
      "CdrReport": {
        "type": "object",
        "properties": {
          "transaction_id": { "type": "string" },
          "thread_id": { "type": "string" },
          "agent_id": { "type": "string" },
          "environment_id": { "type": "string" },
          "call": {
            "type": "object",
            "properties": {
              "start_timestamp": { "type": "string", "format": "date-time" },
              "end_reason": { "type": "string" },
              "milliseconds_elapsed": { "type": "integer" }
            }
          },
          "turns": {
            "type": "array",
            "items": { "type": "object" }
          },
          "failure_occurred": { "type": "boolean" },
          "system_error": { "type": "boolean" }
        }
      }
    }
  }
}