{
  "openapi": "3.1.0",
  "info": {
    "title": "VoxAgent Public API Reference",
    "version": "1.0.5",
    "description": "Public machine-readable API reference for VoxAgent V1.0.5 outbound call integration, HMAC authentication, notification bots, custom bots, voiceType selection, call turn content query, call status query, and HTTP POST + SSE conversation protocol. Read /docs.md for the complete human-readable protocol documentation."
  },
  "servers": [
    {
      "url": "https://vox.teddymobile.cn",
      "description": "Vox runtime API"
    },
    {
      "url": "https://vox-ai.teddymobile.cn",
      "description": "VoxAgent developer portal"
    }
  ],
  "tags": [
    {
      "name": "Runtime",
      "description": "Vox V1.0.5 runtime APIs"
    },
    {
      "name": "SSE",
      "description": "Developer-hosted HTTP POST + SSE conversation contract"
    },
    {
      "name": "Portal",
      "description": "Developer portal control-plane endpoints"
    }
  ],
  "paths": {
    "/vox/v1/outbound": {
      "post": {
        "tags": [
          "Runtime"
        ],
        "summary": "Start an outbound call",
        "description": "Starts an outbound phone call. V1.0.5 supports call bots with botid, notification bots through extra.notification, custom bots through botType=custom and extra.agent_profile, TTS voice selection through extra.voiceType, plus call turn content and status query APIs.",
        "operationId": "startOutboundCall",
        "security": [
          {
            "hmacAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OutboundCallRequest"
              },
              "examples": {
                "callBot": {
                  "summary": "Call bot outbound request",
                  "value": {
                    "appId": "your_app_id",
                    "botid": "bot_10001",
                    "callee": "13800138000",
                    "requestId": "req_202605200001"
                  }
                },
                "notification": {
                  "summary": "Notification bot outbound request",
                  "value": {
                    "appId": "your_app_id",
                    "botid": "bot_10001",
                    "callee": "13800138000",
                    "requestId": "req_202605200002",
                    "extra": "{\"notification\":{\"text\":\"您好，这是一条通知\",\"times\":1},\"voiceType\":\"3\"}"
                  }
                },
                "customBot": {
                  "summary": "Custom bot outbound request",
                  "value": {
                    "appId": "your_app_id",
                    "botid": "",
                    "callee": "13800138000",
                    "requestId": "req_202605200003",
                    "botType": "custom",
                    "extra": "{\"voiceType\":\"0\",\"agent_profile\":{\"name\":\"小美\",\"gender\":\"女\",\"age\":25,\"role\":\"销售顾问\",\"communicationStyle\":[\"热情\",\"专业\"],\"background\":\"春季新品推广活动\",\"goals\":\"了解客户购买意向\",\"skills\":\"产品介绍、需求挖掘\",\"workflow\":\"问候 -> 了解需求 -> 介绍产品\",\"constraint\":\"保持礼貌，不强制推销\",\"openingPrompt\":\"您好，我是小美\"}}"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Outbound request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CommonResponse"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing HMAC authentication."
          },
          "403": {
            "description": "No API access permission."
          },
          "429": {
            "description": "Rate limit or access frequency threshold exceeded."
          }
        }
      }
    },
    "/developer-api": {
      "post": {
        "tags": [
          "SSE"
        ],
        "summary": "Developer-hosted SSE conversation endpoint",
        "description": "Vox sends each conversation turn to the developer HTTPS endpoint by HTTP POST. The developer system responds with text/event-stream chunks and must finish the turn with data: [DONE]. Replace this path with your own configured endpoint.",
        "operationId": "handleSseConversationTurn",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SseConversationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SSE stream containing message chunks and data: [DONE].",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/trial/applications": {
      "post": {
        "tags": [
          "Portal"
        ],
        "summary": "Submit trial application",
        "description": "Submits a trial application in the developer portal.",
        "operationId": "submitTrialApplication",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TrialApplicationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Trial application response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CommonResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/launch/requests": {
      "get": {
        "tags": [
          "Portal"
        ],
        "summary": "List production Bot configurations",
        "description": "Lists production Bot configurations for the authenticated organization.",
        "operationId": "listLaunchRequests",
        "responses": {
          "200": {
            "description": "Production Bot configuration list.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CommonResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Portal"
        ],
        "summary": "Create production Bot configuration",
        "description": "Creates a production Bot configuration for launch preparation in the developer portal.",
        "operationId": "createLaunchRequest",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LaunchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Production Bot configuration response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CommonResponse"
                }
              }
            }
          }
        }
      }
    },
    "/voice/v1/call/turns/query": {
      "post": {
        "tags": [
          "Runtime"
        ],
        "summary": "Query call turn content",
        "description": "Queries per-turn text content for a call by callId and appId. This is turn-level content, not a complete CDR or call detail record.",
        "operationId": "queryCallTurns",
        "security": [
          {
            "hmacAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CallQueryRequest"
              },
              "example": {
                "callId": "4e0c4ecf-1ad6-42c3-b343-e1eb90ee18c6",
                "appId": "your_app_id"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Call turn list. Empty array means no turn records.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallTurnsResponse"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing HMAC authentication."
          },
          "403": {
            "description": "No API access permission."
          }
        }
      }
    },
    "/voice/v1/call/status/query": {
      "post": {
        "tags": [
          "Runtime"
        ],
        "summary": "Query call status",
        "description": "Queries the simplified call status for a call by callId and appId. Current status values are not_found, started, and completed.",
        "operationId": "queryCallStatus",
        "security": [
          {
            "hmacAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CallQueryRequest"
              },
              "example": {
                "callId": "4e0c4ecf-1ad6-42c3-b343-e1eb90ee18c6",
                "appId": "your_app_id"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Simplified call status response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallStatusResponse"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing HMAC authentication."
          },
          "403": {
            "description": "No API access permission."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "hmacAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "HMAC-SIGNATURE",
        "description": "HMAC authentication. Also send HMAC-APPID, HMAC-DATE, HMAC-ALGORITHM, and HMAC-SIGNED-HEADERS."
      }
    },
    "schemas": {
      "OutboundCallRequest": {
        "type": "object",
        "required": [
          "appId",
          "callee",
          "requestId"
        ],
        "properties": {
          "appId": {
            "type": "string",
            "description": "Enterprise account identifier assigned by TeddyMobile."
          },
          "botid": {
            "type": "string",
            "description": "Platform-generated Bot identifier. Optional when botType is custom."
          },
          "callee": {
            "type": "string",
            "description": "Destination phone number."
          },
          "requestId": {
            "type": "string",
            "description": "Caller-generated idempotency identifier."
          },
          "botType": {
            "type": "string",
            "enum": [
              "custom"
            ],
            "description": "Bot type. V1.0.5 currently documents custom for custom Bot outbound calls."
          },
          "extra": {
            "type": "string",
            "description": "JSON string extension payload. Can contain notification, voiceType, and agent_profile."
          }
        }
      },
      "NotificationExtra": {
        "type": "object",
        "required": [
          "text"
        ],
        "properties": {
          "text": {
            "type": "string",
            "description": "Notification content to speak when notification is present."
          },
          "times": {
            "type": "integer",
            "minimum": 1,
            "description": "Playback count. Defaults to 1."
          }
        }
      },
      "AgentProfile": {
        "type": "object",
        "required": [
          "name",
          "gender",
          "age",
          "role",
          "communicationStyle",
          "background",
          "goals",
          "skills",
          "workflow",
          "constraint",
          "openingPrompt"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "gender": {
            "type": "string"
          },
          "age": {
            "type": "integer"
          },
          "role": {
            "type": "string"
          },
          "communicationStyle": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "background": {
            "type": "string"
          },
          "goals": {
            "type": "string"
          },
          "skills": {
            "type": "string"
          },
          "workflow": {
            "type": "string"
          },
          "constraint": {
            "type": "string"
          },
          "openingPrompt": {
            "type": "string"
          }
        }
      },
      "SseConversationRequest": {
        "type": "object",
        "required": [
          "turn",
          "calltype",
          "callee",
          "caller",
          "callid",
          "requestid",
          "message"
        ],
        "properties": {
          "turn": {
            "type": "integer"
          },
          "calltype": {
            "type": "string",
            "enum": [
              "inbound",
              "outbound"
            ]
          },
          "callee": {
            "type": "string"
          },
          "caller": {
            "type": "string"
          },
          "callid": {
            "type": "string"
          },
          "requestid": {
            "type": "string"
          },
          "message": {
            "type": "string",
            "description": "User input text. Empty string on the first request after call connection."
          }
        }
      },
      "TrialApplicationRequest": {
        "type": "object",
        "additionalProperties": true
      },
      "LaunchRequest": {
        "type": "object",
        "additionalProperties": true
      },
      "CommonResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": 0
          },
          "msg": {
            "type": "string"
          },
          "data": {
            "description": "Endpoint-specific response payload"
          },
          "time": {
            "type": "integer",
            "format": "int64"
          }
        },
        "additionalProperties": true
      },
      "CallQueryRequest": {
        "type": "object",
        "required": [
          "callId",
          "appId"
        ],
        "properties": {
          "callId": {
            "type": "string",
            "description": "Call identifier. The Webhook protocol uses callid for the same call identifier."
          },
          "appId": {
            "type": "string",
            "description": "Enterprise account identifier assigned by TeddyMobile."
          }
        }
      },
      "CallTurn": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "callId": {
            "type": "string"
          },
          "appId": {
            "type": "string"
          },
          "turnIndex": {
            "type": "integer"
          },
          "userText": {
            "type": "string"
          },
          "botText": {
            "type": "string"
          },
          "playbackCompletedAt": {
            "type": "string",
            "description": "Bot playback completion time in yyyy-MM-ddTHH:mm:ss format."
          }
        }
      },
      "CallTurnsResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CommonResponse"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/CallTurn"
                }
              }
            }
          }
        ]
      },
      "CallStatusData": {
        "type": "object",
        "properties": {
          "callId": {
            "type": "string"
          },
          "appId": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "not_found",
              "started",
              "completed"
            ]
          }
        }
      },
      "CallStatusResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CommonResponse"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/CallStatusData"
              }
            }
          }
        ]
      }
    }
  },
  "externalDocs": {
    "description": "Complete VoxAgent markdown API documentation",
    "url": "https://vox-ai.teddymobile.cn/docs.md"
  }
}