{ "openapi": "3.1.0", "info": { "title": "Beyond Presence API", "summary": "Create, configure, and run interactive real-time avatars.", "description": "The Beyond Presence API lets you build lifelike, real-time avatars.\n\n## Starting a conversation with a Managed Agent\n\nThere are two ways to put a user in front of one of your agents, and most\nintegrations only need the first:\n\n1. **Open the agent's managed room** at `https://bey.chat/`. This\n needs no API call at all and is available on every plan. Use the\n `Agent Conversations` endpoints afterwards to read status and transcripts.\n2. **Drive the media session yourself** from a LiveKit client SDK, using\n `POST /v1/livekit-rooms` in the `Agent Integration` group to mint room\n credentials. This requires the Growth plan or above.\n\n## Authentication\n\nAuthenticate every request with your API key in the `x-api-key` header:\n\n```\nx-api-key: \n```\n\nYou can create and manage API keys in the dashboard, and verify a key with\n`GET /v1/auth/verify`.\n\n## Pagination\n\nList endpoints are cursor-paginated. Pass `limit` (1-50, default 10) to control\nthe page size and `cursor` to fetch the next page. Each response includes a\n`next_cursor` when more results are available.\n\n## Errors\n\nErrors return the appropriate HTTP status code with a JSON body containing a\n`detail` message with more information.\n\n## Rate limits\n\nUsage and concurrency limits are tied to your plan. Exhausting the usage limit\nreturns HTTP `402`, and reaching the concurrency limit returns HTTP `429`.\n", "version": "0.3.0" }, "servers": [ { "url": "https://api.bey.dev" } ], "paths": { "/v1/avatars": { "get": { "tags": [ "Avatars" ], "summary": "List Avatars", "description": "List available avatars.\n\nReturns a cursor-paginated list of the avatars you can use in agents:\nboth your own trained avatars and public stock avatars.", "operationId": "list_avatars_v1_avatars_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "exclusiveMinimum": 0, "description": "Maximum number of objects to return.", "default": 10, "title": "Limit" }, "description": "Maximum number of objects to return." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for pagination.", "title": "Cursor" }, "description": "Cursor for pagination." } ], "responses": { "200": { "description": "Paginated List of Avatars", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_AvatarResponse_" } } } }, "401": { "description": "Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.", "content": { "application/json": { "examples": { "missing": { "summary": "Missing API key", "value": { "detail": "API key is required." } }, "invalid": { "summary": "Invalid API key", "value": { "detail": "Invalid API key." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "The plan's usage limit has been reached, or the requested feature requires a plan upgrade.", "content": { "application/json": { "examples": { "usage": { "summary": "Usage limit reached", "value": { "detail": "You have reached your usage limit. Please upgrade your plan or enable usage-based billing." } }, "plan": { "summary": "Plan upgrade required", "value": { "detail": "This feature is not available on your current plan. Please upgrade your plan." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key is valid but not permitted to perform this action, because the resource belongs to someone else.", "content": { "application/json": { "example": { "detail": "You do not have permission to access this resource." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist or is not accessible with this API key.", "content": { "application/json": { "example": { "detail": "The requested resource was not found." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is malformed. `detail` lists each field that failed validation, where it was located, and why.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "body", "name" ], "msg": "Field required", "type": "missing" } ] } } } }, "429": { "description": "The plan's limit on the number of concurrent sessions has been reached.", "content": { "application/json": { "example": { "detail": "You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/avatars/{id}": { "get": { "tags": [ "Avatars" ], "summary": "Retrieve Avatar", "description": "Retrieve a single avatar by ID.", "operationId": "get_avatar_v1_avatars__id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Avatar ID.", "title": "Id" }, "description": "Avatar ID." } ], "responses": { "200": { "description": "Requested Avatar", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvatarResponse" } } } }, "401": { "description": "Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.", "content": { "application/json": { "examples": { "missing": { "summary": "Missing API key", "value": { "detail": "API key is required." } }, "invalid": { "summary": "Invalid API key", "value": { "detail": "Invalid API key." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "The plan's usage limit has been reached, or the requested feature requires a plan upgrade.", "content": { "application/json": { "examples": { "usage": { "summary": "Usage limit reached", "value": { "detail": "You have reached your usage limit. Please upgrade your plan or enable usage-based billing." } }, "plan": { "summary": "Plan upgrade required", "value": { "detail": "This feature is not available on your current plan. Please upgrade your plan." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key is valid but not permitted to perform this action, because the resource belongs to someone else.", "content": { "application/json": { "example": { "detail": "You do not have permission to access this resource." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist or is not accessible with this API key.", "content": { "application/json": { "example": { "detail": "The requested resource was not found." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is malformed. `detail` lists each field that failed validation, where it was located, and why.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "body", "name" ], "msg": "Field required", "type": "missing" } ] } } } }, "429": { "description": "The plan's limit on the number of concurrent sessions has been reached.", "content": { "application/json": { "example": { "detail": "You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agents": { "post": { "tags": [ "Agents" ], "summary": "Create Agent", "description": "Create a new agent.", "operationId": "create_agent_v1_agents_post", "security": [ { "APIKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentRequest" } } } }, "responses": { "201": { "description": "Created Agent with ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "401": { "description": "Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.", "content": { "application/json": { "examples": { "missing": { "summary": "Missing API key", "value": { "detail": "API key is required." } }, "invalid": { "summary": "Invalid API key", "value": { "detail": "Invalid API key." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "The plan's usage limit has been reached, or the requested feature requires a plan upgrade.", "content": { "application/json": { "examples": { "usage": { "summary": "Usage limit reached", "value": { "detail": "You have reached your usage limit. Please upgrade your plan or enable usage-based billing." } }, "plan": { "summary": "Plan upgrade required", "value": { "detail": "This feature is not available on your current plan. Please upgrade your plan." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key is valid but not permitted to perform this action, because the resource belongs to someone else.", "content": { "application/json": { "example": { "detail": "You do not have permission to access this resource." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist or is not accessible with this API key.", "content": { "application/json": { "example": { "detail": "The requested resource was not found." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is malformed. `detail` lists each field that failed validation, where it was located, and why.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "body", "name" ], "msg": "Field required", "type": "missing" } ] } } } }, "429": { "description": "The plan's limit on the number of concurrent sessions has been reached.", "content": { "application/json": { "example": { "detail": "You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "tags": [ "Agents" ], "summary": "List Agents", "description": "List your agents.\n\nReturns a cursor-paginated list of the agents you own, most recent first.", "operationId": "list_agents_v1_agents_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "exclusiveMinimum": 0, "description": "Maximum number of objects to return.", "default": 10, "title": "Limit" }, "description": "Maximum number of objects to return." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for pagination.", "title": "Cursor" }, "description": "Cursor for pagination." } ], "responses": { "200": { "description": "Paginated List of Agents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_AgentResponse_" } } } }, "401": { "description": "Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.", "content": { "application/json": { "examples": { "missing": { "summary": "Missing API key", "value": { "detail": "API key is required." } }, "invalid": { "summary": "Invalid API key", "value": { "detail": "Invalid API key." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "The plan's usage limit has been reached, or the requested feature requires a plan upgrade.", "content": { "application/json": { "examples": { "usage": { "summary": "Usage limit reached", "value": { "detail": "You have reached your usage limit. Please upgrade your plan or enable usage-based billing." } }, "plan": { "summary": "Plan upgrade required", "value": { "detail": "This feature is not available on your current plan. Please upgrade your plan." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key is valid but not permitted to perform this action, because the resource belongs to someone else.", "content": { "application/json": { "example": { "detail": "You do not have permission to access this resource." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist or is not accessible with this API key.", "content": { "application/json": { "example": { "detail": "The requested resource was not found." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is malformed. `detail` lists each field that failed validation, where it was located, and why.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "body", "name" ], "msg": "Field required", "type": "missing" } ] } } } }, "429": { "description": "The plan's limit on the number of concurrent sessions has been reached.", "content": { "application/json": { "example": { "detail": "You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agents/{id}": { "patch": { "tags": [ "Agents" ], "summary": "Update Agent", "description": "Update an existing agent.\n\nOnly the fields present in the request body are changed; omitted fields keep\ntheir current values.", "operationId": "update_agent_v1_agents__id__patch", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Agent ID.", "title": "Id" }, "description": "Agent ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentRequest" } } } }, "responses": { "204": { "description": "Successful Update" }, "401": { "description": "Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.", "content": { "application/json": { "examples": { "missing": { "summary": "Missing API key", "value": { "detail": "API key is required." } }, "invalid": { "summary": "Invalid API key", "value": { "detail": "Invalid API key." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "The plan's usage limit has been reached, or the requested feature requires a plan upgrade.", "content": { "application/json": { "examples": { "usage": { "summary": "Usage limit reached", "value": { "detail": "You have reached your usage limit. Please upgrade your plan or enable usage-based billing." } }, "plan": { "summary": "Plan upgrade required", "value": { "detail": "This feature is not available on your current plan. Please upgrade your plan." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key is valid but not permitted to perform this action, because the resource belongs to someone else.", "content": { "application/json": { "example": { "detail": "You do not have permission to access this resource." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist or is not accessible with this API key.", "content": { "application/json": { "example": { "detail": "The requested resource was not found." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is malformed. `detail` lists each field that failed validation, where it was located, and why.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "body", "name" ], "msg": "Field required", "type": "missing" } ] } } } }, "429": { "description": "The plan's limit on the number of concurrent sessions has been reached.", "content": { "application/json": { "example": { "detail": "You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "tags": [ "Agents" ], "summary": "Retrieve Agent", "description": "Retrieve a single agent by ID.", "operationId": "get_agent_v1_agents__id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Agent ID.", "title": "Id" }, "description": "Agent ID." } ], "responses": { "200": { "description": "Requested Agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "401": { "description": "Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.", "content": { "application/json": { "examples": { "missing": { "summary": "Missing API key", "value": { "detail": "API key is required." } }, "invalid": { "summary": "Invalid API key", "value": { "detail": "Invalid API key." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "The plan's usage limit has been reached, or the requested feature requires a plan upgrade.", "content": { "application/json": { "examples": { "usage": { "summary": "Usage limit reached", "value": { "detail": "You have reached your usage limit. Please upgrade your plan or enable usage-based billing." } }, "plan": { "summary": "Plan upgrade required", "value": { "detail": "This feature is not available on your current plan. Please upgrade your plan." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key is valid but not permitted to perform this action, because the resource belongs to someone else.", "content": { "application/json": { "example": { "detail": "You do not have permission to access this resource." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist or is not accessible with this API key.", "content": { "application/json": { "example": { "detail": "The requested resource was not found." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is malformed. `detail` lists each field that failed validation, where it was located, and why.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "body", "name" ], "msg": "Field required", "type": "missing" } ] } } } }, "429": { "description": "The plan's limit on the number of concurrent sessions has been reached.", "content": { "application/json": { "example": { "detail": "You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Agents" ], "summary": "Delete Agent", "description": "Delete an agent.\n\nPermanently removes the agent. Calls that already ran are unaffected.", "operationId": "delete_agent_v1_agents__id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Agent ID.", "title": "Id" }, "description": "Agent ID." } ], "responses": { "204": { "description": "Successful Deletion" }, "401": { "description": "Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.", "content": { "application/json": { "examples": { "missing": { "summary": "Missing API key", "value": { "detail": "API key is required." } }, "invalid": { "summary": "Invalid API key", "value": { "detail": "Invalid API key." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "The plan's usage limit has been reached, or the requested feature requires a plan upgrade.", "content": { "application/json": { "examples": { "usage": { "summary": "Usage limit reached", "value": { "detail": "You have reached your usage limit. Please upgrade your plan or enable usage-based billing." } }, "plan": { "summary": "Plan upgrade required", "value": { "detail": "This feature is not available on your current plan. Please upgrade your plan." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key is valid but not permitted to perform this action, because the resource belongs to someone else.", "content": { "application/json": { "example": { "detail": "You do not have permission to access this resource." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist or is not accessible with this API key.", "content": { "application/json": { "example": { "detail": "The requested resource was not found." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is malformed. `detail` lists each field that failed validation, where it was located, and why.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "body", "name" ], "msg": "Field required", "type": "missing" } ] } } } }, "429": { "description": "The plan's limit on the number of concurrent sessions has been reached.", "content": { "application/json": { "example": { "detail": "You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/conversations": { "get": { "tags": [ "Agent Conversations" ], "summary": "List Conversations", "description": "List conversations managed by your agents.\n\nReturns a cursor-paginated list of conversations across all of your\nagents, most recent first.", "operationId": "list_conversations_v1_conversations_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "exclusiveMinimum": 0, "description": "Maximum number of objects to return.", "default": 10, "title": "Limit" }, "description": "Maximum number of objects to return." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for pagination.", "title": "Cursor" }, "description": "Cursor for pagination." } ], "responses": { "200": { "description": "Paginated List of Conversations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_ConversationResponse_" } } } }, "401": { "description": "Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.", "content": { "application/json": { "examples": { "missing": { "summary": "Missing API key", "value": { "detail": "API key is required." } }, "invalid": { "summary": "Invalid API key", "value": { "detail": "Invalid API key." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "The plan's usage limit has been reached, or the requested feature requires a plan upgrade.", "content": { "application/json": { "examples": { "usage": { "summary": "Usage limit reached", "value": { "detail": "You have reached your usage limit. Please upgrade your plan or enable usage-based billing." } }, "plan": { "summary": "Plan upgrade required", "value": { "detail": "This feature is not available on your current plan. Please upgrade your plan." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key is valid but not permitted to perform this action, because the resource belongs to someone else.", "content": { "application/json": { "example": { "detail": "You do not have permission to access this resource." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist or is not accessible with this API key.", "content": { "application/json": { "example": { "detail": "The requested resource was not found." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is malformed. `detail` lists each field that failed validation, where it was located, and why.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "body", "name" ], "msg": "Field required", "type": "missing" } ] } } } }, "429": { "description": "The plan's limit on the number of concurrent sessions has been reached.", "content": { "application/json": { "example": { "detail": "You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/conversations/{id}": { "get": { "tags": [ "Agent Conversations" ], "summary": "Retrieve Conversation", "description": "Retrieve a single conversation by ID, including its status and participants.", "operationId": "get_conversation_v1_conversations__id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Conversation ID.", "title": "Id" }, "description": "Conversation ID." } ], "responses": { "200": { "description": "Requested Conversation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationResponse" } } } }, "401": { "description": "Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.", "content": { "application/json": { "examples": { "missing": { "summary": "Missing API key", "value": { "detail": "API key is required." } }, "invalid": { "summary": "Invalid API key", "value": { "detail": "Invalid API key." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "The plan's usage limit has been reached, or the requested feature requires a plan upgrade.", "content": { "application/json": { "examples": { "usage": { "summary": "Usage limit reached", "value": { "detail": "You have reached your usage limit. Please upgrade your plan or enable usage-based billing." } }, "plan": { "summary": "Plan upgrade required", "value": { "detail": "This feature is not available on your current plan. Please upgrade your plan." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key is valid but not permitted to perform this action, because the resource belongs to someone else.", "content": { "application/json": { "example": { "detail": "You do not have permission to access this resource." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist or is not accessible with this API key.", "content": { "application/json": { "example": { "detail": "The requested resource was not found." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is malformed. `detail` lists each field that failed validation, where it was located, and why.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "body", "name" ], "msg": "Field required", "type": "missing" } ] } } } }, "429": { "description": "The plan's limit on the number of concurrent sessions has been reached.", "content": { "application/json": { "example": { "detail": "You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/conversations/{id}/messages": { "get": { "tags": [ "Agent Conversations" ], "summary": "List Conversation Messages", "description": "List the transcribed messages of a conversation.\n\nReturns the conversation transcript in chronological order, with each\nmessage attributed to either the agent or the user.", "operationId": "list_messages_v1_conversations__id__messages_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Conversation ID.", "title": "Id" }, "description": "Conversation ID." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationMessage" }, "title": "Response List Messages V1 Conversations Id Messages Get" } } } }, "401": { "description": "Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.", "content": { "application/json": { "examples": { "missing": { "summary": "Missing API key", "value": { "detail": "API key is required." } }, "invalid": { "summary": "Invalid API key", "value": { "detail": "Invalid API key." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "The plan's usage limit has been reached, or the requested feature requires a plan upgrade.", "content": { "application/json": { "examples": { "usage": { "summary": "Usage limit reached", "value": { "detail": "You have reached your usage limit. Please upgrade your plan or enable usage-based billing." } }, "plan": { "summary": "Plan upgrade required", "value": { "detail": "This feature is not available on your current plan. Please upgrade your plan." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key is valid but not permitted to perform this action, because the resource belongs to someone else.", "content": { "application/json": { "example": { "detail": "You do not have permission to access this resource." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist or is not accessible with this API key.", "content": { "application/json": { "example": { "detail": "The requested resource was not found." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is malformed. `detail` lists each field that failed validation, where it was located, and why.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "body", "name" ], "msg": "Field required", "type": "missing" } ] } } } }, "429": { "description": "The plan's limit on the number of concurrent sessions has been reached.", "content": { "application/json": { "example": { "detail": "You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/livekit-rooms": { "post": { "tags": [ "Agent Integration" ], "summary": "Create LiveKit Room", "description": "Create a LiveKit room for one of your agents and return the credentials a LiveKit client needs to join it.\n\nUse this only when you are embedding a conversation in your own\napplication via the LiveKit client SDK. Most integrations do not need it:\nInteracting with Managed Agents through the UI starts a conversation with no API call required.\n\nThe room is created together with its conversation, whose status and\ntranscript you can then read from `/v1/conversations/{id}`.", "operationId": "create_livekit_room_v1_livekit_rooms_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLiveKitRoomRequest" } } }, "required": true }, "responses": { "201": { "description": "Created LiveKit room with its conversation ID and connection details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveKitRoomResponse" } } } }, "401": { "description": "Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing": { "summary": "Missing API key", "value": { "detail": "API key is required." } }, "invalid": { "summary": "Invalid API key", "value": { "detail": "Invalid API key." } } } } } }, "402": { "description": "The plan's usage limit has been reached, or the requested feature requires a plan upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "usage": { "summary": "Usage limit reached", "value": { "detail": "You have reached your usage limit. Please upgrade your plan or enable usage-based billing." } }, "plan": { "summary": "Plan upgrade required", "value": { "detail": "This feature is not available on your current plan. Please upgrade your plan." } } } } } }, "403": { "description": "The API key is valid but not permitted to perform this action, because the resource belongs to someone else.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "You do not have permission to access this resource." } } } }, "404": { "description": "The requested resource does not exist or is not accessible with this API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "The requested resource was not found." } } } }, "422": { "description": "The request is malformed. `detail` lists each field that failed validation, where it was located, and why.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "body", "name" ], "msg": "Field required", "type": "missing" } ] } } } }, "429": { "description": "The plan's limit on the number of concurrent sessions has been reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions." } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/v1/knowledge-files": { "get": { "tags": [ "Agent Knowledge Files" ], "summary": "List Knowledge Files", "description": "List your knowledge files.\n\nReturns a cursor-paginated list of the knowledge files you own, along with\ntheir processing status.", "operationId": "list_knowledge_files_v1_knowledge_files_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "exclusiveMinimum": 0, "description": "Maximum number of objects to return.", "default": 10, "title": "Limit" }, "description": "Maximum number of objects to return." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for pagination.", "title": "Cursor" }, "description": "Cursor for pagination." } ], "responses": { "200": { "description": "Paginated List of Knowledge Files", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_KnowledgeFileResponse_" } } } }, "401": { "description": "Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.", "content": { "application/json": { "examples": { "missing": { "summary": "Missing API key", "value": { "detail": "API key is required." } }, "invalid": { "summary": "Invalid API key", "value": { "detail": "Invalid API key." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "The plan's usage limit has been reached, or the requested feature requires a plan upgrade.", "content": { "application/json": { "examples": { "usage": { "summary": "Usage limit reached", "value": { "detail": "You have reached your usage limit. Please upgrade your plan or enable usage-based billing." } }, "plan": { "summary": "Plan upgrade required", "value": { "detail": "This feature is not available on your current plan. Please upgrade your plan." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key is valid but not permitted to perform this action, because the resource belongs to someone else.", "content": { "application/json": { "example": { "detail": "You do not have permission to access this resource." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist or is not accessible with this API key.", "content": { "application/json": { "example": { "detail": "The requested resource was not found." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is malformed. `detail` lists each field that failed validation, where it was located, and why.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "body", "name" ], "msg": "Field required", "type": "missing" } ] } } } }, "429": { "description": "The plan's limit on the number of concurrent sessions has been reached.", "content": { "application/json": { "example": { "detail": "You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Agent Knowledge Files" ], "summary": "Create Knowledge File", "description": "Create a knowledge file and start its upload.\n\nText files are stored immediately and begin indexing, so they come back\nas `processing` and are ready to attach to an agent once they read\n`available`. PDF files begin a chunked upload: use the returned ID to\nupload each chunk via `PUT /{id}/upload`, then finalize with\n`POST /{id}/submit`.", "operationId": "create_knowledge_file_v1_knowledge_files_post", "security": [ { "APIKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKnowledgeFileRequest" } } } }, "responses": { "201": { "description": "Created Knowledge File", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeFileResponse" } } } }, "401": { "description": "Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.", "content": { "application/json": { "examples": { "missing": { "summary": "Missing API key", "value": { "detail": "API key is required." } }, "invalid": { "summary": "Invalid API key", "value": { "detail": "Invalid API key." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "The plan's usage limit has been reached, or the requested feature requires a plan upgrade.", "content": { "application/json": { "examples": { "usage": { "summary": "Usage limit reached", "value": { "detail": "You have reached your usage limit. Please upgrade your plan or enable usage-based billing." } }, "plan": { "summary": "Plan upgrade required", "value": { "detail": "This feature is not available on your current plan. Please upgrade your plan." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key is valid but not permitted to perform this action, because the resource belongs to someone else.", "content": { "application/json": { "example": { "detail": "You do not have permission to access this resource." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist or is not accessible with this API key.", "content": { "application/json": { "example": { "detail": "The requested resource was not found." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is malformed. `detail` lists each field that failed validation, where it was located, and why.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "body", "name" ], "msg": "Field required", "type": "missing" } ] } } } }, "429": { "description": "The plan's limit on the number of concurrent sessions has been reached.", "content": { "application/json": { "example": { "detail": "You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/knowledge-files/{id}": { "get": { "tags": [ "Agent Knowledge Files" ], "summary": "Retrieve Knowledge File", "description": "Retrieve a single knowledge file by ID, including its extracted text.", "operationId": "get_knowledge_file_v1_knowledge_files__id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Knowledge File ID.", "title": "Id" }, "description": "Knowledge File ID." } ], "responses": { "200": { "description": "Requested Knowledge File", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeFileResponse" } } } }, "401": { "description": "Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.", "content": { "application/json": { "examples": { "missing": { "summary": "Missing API key", "value": { "detail": "API key is required." } }, "invalid": { "summary": "Invalid API key", "value": { "detail": "Invalid API key." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "The plan's usage limit has been reached, or the requested feature requires a plan upgrade.", "content": { "application/json": { "examples": { "usage": { "summary": "Usage limit reached", "value": { "detail": "You have reached your usage limit. Please upgrade your plan or enable usage-based billing." } }, "plan": { "summary": "Plan upgrade required", "value": { "detail": "This feature is not available on your current plan. Please upgrade your plan." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key is valid but not permitted to perform this action, because the resource belongs to someone else.", "content": { "application/json": { "example": { "detail": "You do not have permission to access this resource." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist or is not accessible with this API key.", "content": { "application/json": { "example": { "detail": "The requested resource was not found." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is malformed. `detail` lists each field that failed validation, where it was located, and why.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "body", "name" ], "msg": "Field required", "type": "missing" } ] } } } }, "429": { "description": "The plan's limit on the number of concurrent sessions has been reached.", "content": { "application/json": { "example": { "detail": "You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Agent Knowledge Files" ], "summary": "Delete Knowledge File", "description": "Delete a knowledge file.\n\nFails if any of your agents still references the file; detach it from those\nagents first.", "operationId": "delete_knowledge_file_v1_knowledge_files__id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Knowledge File ID.", "title": "Id" }, "description": "Knowledge File ID." } ], "responses": { "204": { "description": "Successful Response" }, "401": { "description": "Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.", "content": { "application/json": { "examples": { "missing": { "summary": "Missing API key", "value": { "detail": "API key is required." } }, "invalid": { "summary": "Invalid API key", "value": { "detail": "Invalid API key." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "The plan's usage limit has been reached, or the requested feature requires a plan upgrade.", "content": { "application/json": { "examples": { "usage": { "summary": "Usage limit reached", "value": { "detail": "You have reached your usage limit. Please upgrade your plan or enable usage-based billing." } }, "plan": { "summary": "Plan upgrade required", "value": { "detail": "This feature is not available on your current plan. Please upgrade your plan." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key is valid but not permitted to perform this action, because the resource belongs to someone else.", "content": { "application/json": { "example": { "detail": "You do not have permission to access this resource." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist or is not accessible with this API key.", "content": { "application/json": { "example": { "detail": "The requested resource was not found." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is malformed. `detail` lists each field that failed validation, where it was located, and why.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "body", "name" ], "msg": "Field required", "type": "missing" } ] } } } }, "429": { "description": "The plan's limit on the number of concurrent sessions has been reached.", "content": { "application/json": { "example": { "detail": "You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/knowledge-files/{id}/upload": { "put": { "tags": [ "Agent Knowledge Files" ], "summary": "Upload Knowledge File Chunk", "description": "Upload a single chunk of a PDF knowledge file.\n\nSend the raw chunk bytes as the request body. Chunks are zero-indexed via\nthe `chunk_number` query parameter and can be uploaded in any order.", "operationId": "upload_knowledge_file_chunk_v1_knowledge_files__id__upload_put", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Knowledge File ID.", "title": "Id" }, "description": "Knowledge File ID." }, { "name": "chunk_number", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 0, "description": "Chunk number, starting from 0.", "title": "Chunk Number" }, "description": "Chunk number, starting from 0." } ], "responses": { "204": { "description": "Successful Response" }, "401": { "description": "Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.", "content": { "application/json": { "examples": { "missing": { "summary": "Missing API key", "value": { "detail": "API key is required." } }, "invalid": { "summary": "Invalid API key", "value": { "detail": "Invalid API key." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "The plan's usage limit has been reached, or the requested feature requires a plan upgrade.", "content": { "application/json": { "examples": { "usage": { "summary": "Usage limit reached", "value": { "detail": "You have reached your usage limit. Please upgrade your plan or enable usage-based billing." } }, "plan": { "summary": "Plan upgrade required", "value": { "detail": "This feature is not available on your current plan. Please upgrade your plan." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key is valid but not permitted to perform this action, because the resource belongs to someone else.", "content": { "application/json": { "example": { "detail": "You do not have permission to access this resource." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist or is not accessible with this API key.", "content": { "application/json": { "example": { "detail": "The requested resource was not found." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is malformed. `detail` lists each field that failed validation, where it was located, and why.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "body", "name" ], "msg": "Field required", "type": "missing" } ] } } } }, "429": { "description": "The plan's limit on the number of concurrent sessions has been reached.", "content": { "application/json": { "example": { "detail": "You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/knowledge-files/{id}/submit": { "post": { "tags": [ "Agent Knowledge Files" ], "summary": "Submit Knowledge File", "description": "Finalize a chunked knowledge file upload.\n\nAssembles the uploaded chunks and starts extracting and indexing them.\nReturns the file as `processing`; it becomes `available` once that\nfinishes, which takes minutes for a long document.", "operationId": "submit_knowledge_file_v1_knowledge_files__id__submit_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Knowledge File ID.", "title": "Id" }, "description": "Knowledge File ID." } ], "responses": { "200": { "description": "Processed Knowledge File", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeFileResponse" } } } }, "401": { "description": "Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.", "content": { "application/json": { "examples": { "missing": { "summary": "Missing API key", "value": { "detail": "API key is required." } }, "invalid": { "summary": "Invalid API key", "value": { "detail": "Invalid API key." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "The plan's usage limit has been reached, or the requested feature requires a plan upgrade.", "content": { "application/json": { "examples": { "usage": { "summary": "Usage limit reached", "value": { "detail": "You have reached your usage limit. Please upgrade your plan or enable usage-based billing." } }, "plan": { "summary": "Plan upgrade required", "value": { "detail": "This feature is not available on your current plan. Please upgrade your plan." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key is valid but not permitted to perform this action, because the resource belongs to someone else.", "content": { "application/json": { "example": { "detail": "You do not have permission to access this resource." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist or is not accessible with this API key.", "content": { "application/json": { "example": { "detail": "The requested resource was not found." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is malformed. `detail` lists each field that failed validation, where it was located, and why.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "body", "name" ], "msg": "Field required", "type": "missing" } ] } } } }, "429": { "description": "The plan's limit on the number of concurrent sessions has been reached.", "content": { "application/json": { "example": { "detail": "You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/external-apis": { "post": { "tags": [ "Agents External APIs" ], "summary": "Create External API Configuration", "description": "Create an external API configuration.\n\nSecurely stores credentials for an external service (such as an\nOpenAI-compatible LLM or your ElevenLabs account) so agents can reference\nit by ID. The secret itself is never returned in responses. Fails if the\nservice rejects the key, which is only checked for ElevenLabs so far.", "operationId": "create_external_api_v1_external_apis_post", "security": [ { "APIKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateExternalApiRequest", "description": "External API configuration data." } } } }, "responses": { "201": { "description": "Created External API Configuration with ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalApiResponse" } } } }, "401": { "description": "Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.", "content": { "application/json": { "examples": { "missing": { "summary": "Missing API key", "value": { "detail": "API key is required." } }, "invalid": { "summary": "Invalid API key", "value": { "detail": "Invalid API key." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "The plan's usage limit has been reached, or the requested feature requires a plan upgrade.", "content": { "application/json": { "examples": { "usage": { "summary": "Usage limit reached", "value": { "detail": "You have reached your usage limit. Please upgrade your plan or enable usage-based billing." } }, "plan": { "summary": "Plan upgrade required", "value": { "detail": "This feature is not available on your current plan. Please upgrade your plan." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key is valid but not permitted to perform this action, because the resource belongs to someone else.", "content": { "application/json": { "example": { "detail": "You do not have permission to access this resource." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist or is not accessible with this API key.", "content": { "application/json": { "example": { "detail": "The requested resource was not found." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is malformed. `detail` lists each field that failed validation, where it was located, and why.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "body", "name" ], "msg": "Field required", "type": "missing" } ] } } } }, "429": { "description": "The plan's limit on the number of concurrent sessions has been reached.", "content": { "application/json": { "example": { "detail": "You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "tags": [ "Agents External APIs" ], "summary": "List External API Configurations", "description": "List your external API configurations.\n\nReturns a cursor-paginated list of configurations you own. Secrets are\nnever included.", "operationId": "list_external_apis_v1_external_apis_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "exclusiveMinimum": 0, "description": "Maximum number of objects to return.", "default": 10, "title": "Limit" }, "description": "Maximum number of objects to return." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for pagination.", "title": "Cursor" }, "description": "Cursor for pagination." } ], "responses": { "200": { "description": "Paginated List of External API Configurations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_ExternalApiResponse_" } } } }, "401": { "description": "Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.", "content": { "application/json": { "examples": { "missing": { "summary": "Missing API key", "value": { "detail": "API key is required." } }, "invalid": { "summary": "Invalid API key", "value": { "detail": "Invalid API key." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "The plan's usage limit has been reached, or the requested feature requires a plan upgrade.", "content": { "application/json": { "examples": { "usage": { "summary": "Usage limit reached", "value": { "detail": "You have reached your usage limit. Please upgrade your plan or enable usage-based billing." } }, "plan": { "summary": "Plan upgrade required", "value": { "detail": "This feature is not available on your current plan. Please upgrade your plan." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key is valid but not permitted to perform this action, because the resource belongs to someone else.", "content": { "application/json": { "example": { "detail": "You do not have permission to access this resource." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist or is not accessible with this API key.", "content": { "application/json": { "example": { "detail": "The requested resource was not found." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is malformed. `detail` lists each field that failed validation, where it was located, and why.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "body", "name" ], "msg": "Field required", "type": "missing" } ] } } } }, "429": { "description": "The plan's limit on the number of concurrent sessions has been reached.", "content": { "application/json": { "example": { "detail": "You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/external-apis/{id}": { "get": { "tags": [ "Agents External APIs" ], "summary": "Retrieve External API Configuration", "description": "Retrieve a single external API configuration by ID (without its secret).", "operationId": "get_external_api_v1_external_apis__id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "External API configuration ID.", "title": "Id" }, "description": "External API configuration ID." } ], "responses": { "200": { "description": "Requested External API Configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalApiResponse" } } } }, "401": { "description": "Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.", "content": { "application/json": { "examples": { "missing": { "summary": "Missing API key", "value": { "detail": "API key is required." } }, "invalid": { "summary": "Invalid API key", "value": { "detail": "Invalid API key." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "The plan's usage limit has been reached, or the requested feature requires a plan upgrade.", "content": { "application/json": { "examples": { "usage": { "summary": "Usage limit reached", "value": { "detail": "You have reached your usage limit. Please upgrade your plan or enable usage-based billing." } }, "plan": { "summary": "Plan upgrade required", "value": { "detail": "This feature is not available on your current plan. Please upgrade your plan." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key is valid but not permitted to perform this action, because the resource belongs to someone else.", "content": { "application/json": { "example": { "detail": "You do not have permission to access this resource." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist or is not accessible with this API key.", "content": { "application/json": { "example": { "detail": "The requested resource was not found." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is malformed. `detail` lists each field that failed validation, where it was located, and why.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "body", "name" ], "msg": "Field required", "type": "missing" } ] } } } }, "429": { "description": "The plan's limit on the number of concurrent sessions has been reached.", "content": { "application/json": { "example": { "detail": "You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Agents External APIs" ], "summary": "Delete External API Configuration", "description": "Delete an external API configuration and its stored secret.\n\nFails if any of your agents still uses the configuration; change their LLM\nfirst.", "operationId": "delete_external_api_v1_external_apis__id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "External API configuration ID.", "title": "Id" }, "description": "External API configuration ID." } ], "responses": { "204": { "description": "Successful Deletion" }, "401": { "description": "Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.", "content": { "application/json": { "examples": { "missing": { "summary": "Missing API key", "value": { "detail": "API key is required." } }, "invalid": { "summary": "Invalid API key", "value": { "detail": "Invalid API key." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "The plan's usage limit has been reached, or the requested feature requires a plan upgrade.", "content": { "application/json": { "examples": { "usage": { "summary": "Usage limit reached", "value": { "detail": "You have reached your usage limit. Please upgrade your plan or enable usage-based billing." } }, "plan": { "summary": "Plan upgrade required", "value": { "detail": "This feature is not available on your current plan. Please upgrade your plan." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key is valid but not permitted to perform this action, because the resource belongs to someone else.", "content": { "application/json": { "example": { "detail": "You do not have permission to access this resource." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist or is not accessible with this API key.", "content": { "application/json": { "example": { "detail": "The requested resource was not found." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is malformed. `detail` lists each field that failed validation, where it was located, and why.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "body", "name" ], "msg": "Field required", "type": "missing" } ] } } } }, "429": { "description": "The plan's limit on the number of concurrent sessions has been reached.", "content": { "application/json": { "example": { "detail": "You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/auth/verify": { "get": { "tags": [ "Authentication" ], "summary": "Verify API Key", "description": "Check whether the `x-api-key` header contains a valid API key. Returns `204 No Content` when the key is valid and `401 Unauthorized` otherwise. Useful as a lightweight connectivity and credential check.", "operationId": "verify_v1_auth_verify_get", "responses": { "204": { "description": "Valid API Key" }, "401": { "description": "Missing or Invalid API Key" } }, "security": [ { "APIKeyHeader": [] } ] } }, "/v1/sessions": { "post": { "tags": [ "Speech-to-Video Sessions" ], "summary": "Create Speech-to-Video Session", "description": "Create a speech-to-video session.\n\nTip: do not use this directly, use the LiveKit plugin instead.\nSee .", "operationId": "create_session_v1_sessions_post", "security": [ { "APIKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionRequest" } } } }, "responses": { "201": { "description": "Created Speech-to-Video Session with ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponse" } } } }, "401": { "description": "Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.", "content": { "application/json": { "examples": { "missing": { "summary": "Missing API key", "value": { "detail": "API key is required." } }, "invalid": { "summary": "Invalid API key", "value": { "detail": "Invalid API key." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "The plan's usage limit has been reached, or the requested feature requires a plan upgrade.", "content": { "application/json": { "examples": { "usage": { "summary": "Usage limit reached", "value": { "detail": "You have reached your usage limit. Please upgrade your plan or enable usage-based billing." } }, "plan": { "summary": "Plan upgrade required", "value": { "detail": "This feature is not available on your current plan. Please upgrade your plan." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key is valid but not permitted to perform this action, because the resource belongs to someone else.", "content": { "application/json": { "example": { "detail": "You do not have permission to access this resource." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist or is not accessible with this API key.", "content": { "application/json": { "example": { "detail": "The requested resource was not found." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is malformed. `detail` lists each field that failed validation, where it was located, and why.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "body", "name" ], "msg": "Field required", "type": "missing" } ] } } } }, "429": { "description": "The plan's limit on the number of concurrent sessions has been reached.", "content": { "application/json": { "example": { "detail": "You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "tags": [ "Speech-to-Video Sessions" ], "summary": "List Speech-to-Video Sessions", "description": "List your speech-to-video sessions.\n\nReturns a cursor-paginated list of sessions, most recent first.", "operationId": "list_sessions_v1_sessions_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "exclusiveMinimum": 0, "description": "Maximum number of objects to return.", "default": 10, "title": "Limit" }, "description": "Maximum number of objects to return." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for pagination.", "title": "Cursor" }, "description": "Cursor for pagination." } ], "responses": { "200": { "description": "Paginated List of Speech-to-Video Sessions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_SessionResponse_" } } } }, "401": { "description": "Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.", "content": { "application/json": { "examples": { "missing": { "summary": "Missing API key", "value": { "detail": "API key is required." } }, "invalid": { "summary": "Invalid API key", "value": { "detail": "Invalid API key." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "The plan's usage limit has been reached, or the requested feature requires a plan upgrade.", "content": { "application/json": { "examples": { "usage": { "summary": "Usage limit reached", "value": { "detail": "You have reached your usage limit. Please upgrade your plan or enable usage-based billing." } }, "plan": { "summary": "Plan upgrade required", "value": { "detail": "This feature is not available on your current plan. Please upgrade your plan." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key is valid but not permitted to perform this action, because the resource belongs to someone else.", "content": { "application/json": { "example": { "detail": "You do not have permission to access this resource." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist or is not accessible with this API key.", "content": { "application/json": { "example": { "detail": "The requested resource was not found." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is malformed. `detail` lists each field that failed validation, where it was located, and why.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "body", "name" ], "msg": "Field required", "type": "missing" } ] } } } }, "429": { "description": "The plan's limit on the number of concurrent sessions has been reached.", "content": { "application/json": { "example": { "detail": "You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/sessions/{id}": { "get": { "tags": [ "Speech-to-Video Sessions" ], "summary": "Retrieve Speech-to-Video Session", "description": "Retrieve a single speech-to-video session by ID.", "operationId": "get_session_v1_sessions__id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Speech-to-video session ID.", "title": "Id" }, "description": "Speech-to-video session ID." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponse" } } } }, "401": { "description": "Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.", "content": { "application/json": { "examples": { "missing": { "summary": "Missing API key", "value": { "detail": "API key is required." } }, "invalid": { "summary": "Invalid API key", "value": { "detail": "Invalid API key." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "The plan's usage limit has been reached, or the requested feature requires a plan upgrade.", "content": { "application/json": { "examples": { "usage": { "summary": "Usage limit reached", "value": { "detail": "You have reached your usage limit. Please upgrade your plan or enable usage-based billing." } }, "plan": { "summary": "Plan upgrade required", "value": { "detail": "This feature is not available on your current plan. Please upgrade your plan." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key is valid but not permitted to perform this action, because the resource belongs to someone else.", "content": { "application/json": { "example": { "detail": "You do not have permission to access this resource." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist or is not accessible with this API key.", "content": { "application/json": { "example": { "detail": "The requested resource was not found." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is malformed. `detail` lists each field that failed validation, where it was located, and why.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "body", "name" ], "msg": "Field required", "type": "missing" } ] } } } }, "429": { "description": "The plan's limit on the number of concurrent sessions has been reached.", "content": { "application/json": { "example": { "detail": "You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/usage": { "get": { "tags": [ "Usage" ], "summary": "Retrieve Usage", "description": "Retrieve your organization's usage in the current billing period.\n\nAll figures are seconds as your plan counts them, and cover every workspace\nof your organization, so only an API key of the default workspace can read\nthem. Usage can take a few minutes to appear.", "operationId": "get_usage_v1_usage_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" } } } }, "401": { "description": "Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing": { "summary": "Missing API key", "value": { "detail": "API key is required." } }, "invalid": { "summary": "Invalid API key", "value": { "detail": "Invalid API key." } } } } } }, "402": { "description": "The plan's usage limit has been reached, or the requested feature requires a plan upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "usage": { "summary": "Usage limit reached", "value": { "detail": "You have reached your usage limit. Please upgrade your plan or enable usage-based billing." } }, "plan": { "summary": "Plan upgrade required", "value": { "detail": "This feature is not available on your current plan. Please upgrade your plan." } } } } } }, "403": { "description": "The API key is valid but not permitted to perform this action, because the resource belongs to someone else.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "You do not have permission to access this resource." } } } }, "404": { "description": "The requested resource does not exist or is not accessible with this API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "The requested resource was not found." } } } }, "422": { "description": "The request is malformed. `detail` lists each field that failed validation, where it was located, and why.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "body", "name" ], "msg": "Field required", "type": "missing" } ] } } } }, "429": { "description": "The plan's limit on the number of concurrent sessions has been reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions." } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/v1/usage/sessions": { "get": { "tags": [ "Usage" ], "summary": "Retrieve Speech-to-Video Session Usage", "description": "Retrieve the usage of each speech-to-video session.\n\nLists the sessions created in the range, in UTC days, that have started\nand ended.\nThe figures are seconds as your plan counts them, and cover every\nworkspace of your organization, so only an API key of the default\nworkspace can read them. Agent conversations and text-to-video are not\nincluded.\n\nThe days are UTC calendar days, so they do not line up with your billing\nperiod; Retrieve Usage gives the usage of your billing period. A range\nspans at most 366 days and 10,000 sessions; split a busier range into\nshorter ones.", "operationId": "get_session_usage_v1_usage_sessions_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "start", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "Earliest day a listed session was created, in UTC (YYYY-MM-DD).", "title": "Start" }, "description": "Earliest day a listed session was created, in UTC (YYYY-MM-DD)." }, { "name": "end", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "Latest day a listed session was created, in UTC (YYYY-MM-DD).", "title": "End" }, "description": "Latest day a listed session was created, in UTC (YYYY-MM-DD)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionUsageResponse" } } } }, "401": { "description": "Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.", "content": { "application/json": { "examples": { "missing": { "summary": "Missing API key", "value": { "detail": "API key is required." } }, "invalid": { "summary": "Invalid API key", "value": { "detail": "Invalid API key." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "The plan's usage limit has been reached, or the requested feature requires a plan upgrade.", "content": { "application/json": { "examples": { "usage": { "summary": "Usage limit reached", "value": { "detail": "You have reached your usage limit. Please upgrade your plan or enable usage-based billing." } }, "plan": { "summary": "Plan upgrade required", "value": { "detail": "This feature is not available on your current plan. Please upgrade your plan." } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key is valid but not permitted to perform this action, because the resource belongs to someone else.", "content": { "application/json": { "example": { "detail": "You do not have permission to access this resource." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist or is not accessible with this API key.", "content": { "application/json": { "example": { "detail": "The requested resource was not found." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is malformed. `detail` lists each field that failed validation, where it was located, and why.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "body", "name" ], "msg": "Field required", "type": "missing" } ] } } } }, "429": { "description": "The plan's limit on the number of concurrent sessions has been reached.", "content": { "application/json": { "example": { "detail": "You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "schemas": { "AgentCapability": { "oneOf": [ { "$ref": "#/components/schemas/WebcamVisionAgentCapability" }, { "$ref": "#/components/schemas/WakeupModeAgentCapability" } ], "discriminator": { "propertyName": "type", "mapping": { "wakeup_mode": "#/components/schemas/WakeupModeAgentCapability", "webcam_vision": "#/components/schemas/WebcamVisionAgentCapability" } } }, "AgentCapabilityList": { "items": { "$ref": "#/components/schemas/AgentCapability" }, "type": "array" }, "AgentLlm": { "oneOf": [ { "$ref": "#/components/schemas/LivekitAgentLlm" }, { "$ref": "#/components/schemas/OpenaiAgentLlm" }, { "$ref": "#/components/schemas/OpenaiCompatibleAgentLlm" }, { "$ref": "#/components/schemas/ElevenlabsAgentLlm" } ], "discriminator": { "propertyName": "type", "mapping": { "elevenlabs_agent": "#/components/schemas/ElevenlabsAgentLlm", "livekit": "#/components/schemas/LivekitAgentLlm", "openai": "#/components/schemas/OpenaiAgentLlm", "openai_compatible": "#/components/schemas/OpenaiCompatibleAgentLlm" } } }, "AgentResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier of the object in the database.", "examples": [ "01234567-89ab-cdef-0123-456789abcdef" ] }, "name": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Name", "description": "Display name to use. Also used when addressed in conversations.", "examples": [ "Jarvis", "HAL 9000" ] }, "avatar_id": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Avatar Id", "description": "ID of avatar to use.", "examples": [ "01234567-89ab-cdef-0123-456789abcdef" ] }, "system_prompt": { "type": "string", "maxLength": 10000, "minLength": 1, "title": "System Prompt", "description": "System prompt to use.", "examples": [ "You are a helpful assistant." ] }, "language": { "anyOf": [ { "$ref": "#/components/schemas/Language" }, { "type": "null" } ], "description": "Language to use.", "examples": [ "en", "en-US", "de" ] }, "greeting": { "anyOf": [ { "type": "string", "maxLength": 1000, "minLength": 1 }, { "type": "null" } ], "title": "Greeting", "description": "What to say when a call starts.", "examples": [ "Hello!" ] }, "max_session_length_minutes": { "anyOf": [ { "type": "integer", "maximum": 90.0, "exclusiveMinimum": 0.0 }, { "type": "null" } ], "title": "Max Session Length Minutes", "description": "Maximum session length in minutes.", "examples": [ 30 ] }, "capabilities": { "$ref": "#/components/schemas/AgentCapabilityList", "description": "Extra capabilities to manage calls.", "examples": [ [ { "type": "webcam_vision" }, { "triggers": [ "hey agent", "hi pal" ], "type": "wakeup_mode" } ] ] }, "llm": { "anyOf": [ { "$ref": "#/components/schemas/AgentLlm" }, { "type": "null" } ], "description": "Configuration for LLM to use.", "examples": [ { "type": "openai" }, { "api_id": "01234567-89ab-cdef-0123-456789abcdef", "model": "gpt-4o-mini", "temperature": 0.7, "type": "openai_compatible" } ] }, "tts": { "anyOf": [ { "$ref": "#/components/schemas/AgentTts" }, { "type": "null" } ], "description": "Configuration for TTS to use.", "examples": [ { "type": "elevenlabs", "voice": "21m00Tcm4TlvDq8ikWAM" } ] }, "knowledge_file_ids": { "items": { "type": "string", "minLength": 1 }, "type": "array", "uniqueItems": true, "title": "Knowledge File Ids", "description": "IDs of knowledge files to refer to." } }, "type": "object", "required": [ "id", "name", "avatar_id", "system_prompt" ], "title": "AgentResponse", "description": "Response model for an agent." }, "AgentTts": { "oneOf": [ { "$ref": "#/components/schemas/LivekitAgentTts" }, { "$ref": "#/components/schemas/CartesiaAgentTts" }, { "$ref": "#/components/schemas/ElevenlabsAgentTts" }, { "$ref": "#/components/schemas/DeepgramAgentTts" }, { "$ref": "#/components/schemas/OpenaiAgentTts" }, { "$ref": "#/components/schemas/GoogleAgentTts" } ], "discriminator": { "propertyName": "type", "mapping": { "cartesia": "#/components/schemas/CartesiaAgentTts", "deepgram": "#/components/schemas/DeepgramAgentTts", "elevenlabs": "#/components/schemas/ElevenlabsAgentTts", "google_tts": "#/components/schemas/GoogleAgentTts", "livekit": "#/components/schemas/LivekitAgentTts", "openai_tts": "#/components/schemas/OpenaiAgentTts" } } }, "AvailableKnowledgeFileResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier of the object in the database.", "examples": [ "01234567-89ab-cdef-0123-456789abcdef" ] }, "name": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Name", "examples": [ "Hitchhiker's Guide to the Galaxy" ] }, "format": { "$ref": "#/components/schemas/KnowledgeFileFormat" }, "status": { "type": "string", "const": "available", "title": "Status", "default": "available" }, "text": { "type": "string", "title": "Text", "description": "Text extracted from the file. Shortened to the start of the file when it is a large one; see `is_text_complete`." }, "is_text_complete": { "type": "boolean", "title": "Is Text Complete", "description": "Whether `text` is the whole file rather than the start of it. A large file is stored and searched in full either way; this only says how much of it this endpoint hands back." } }, "type": "object", "required": [ "id", "name", "format", "text", "is_text_complete" ], "title": "AvailableKnowledgeFileResponse", "description": "Response model for an available knowledge file." }, "AvatarResponse": { "properties": { "visibility": { "$ref": "#/components/schemas/Visibility" }, "id": { "type": "string", "title": "Id", "description": "Unique identifier of the object in the database.", "examples": [ "01234567-89ab-cdef-0123-456789abcdef" ] }, "name": { "type": "string", "title": "Name", "examples": [ "John Doe", "Jane Smith" ] }, "status": { "$ref": "#/components/schemas/AvatarStatus" } }, "type": "object", "required": [ "visibility", "id", "name", "status" ], "title": "AvatarResponse", "description": "Response model for an avatar." }, "AvatarStatus": { "type": "string", "enum": [ "to-train", "training", "available", "failed" ], "title": "AvatarStatus", "description": "Status of an avatar." }, "CartesiaAgentTts": { "properties": { "type": { "type": "string", "const": "cartesia", "title": "Type", "default": "cartesia" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" }, "voice": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice" } }, "type": "object", "title": "CartesiaAgentTts", "description": "Configuration for Cartesia TTS." }, "CompletedConversationStatus": { "properties": { "type": { "type": "string", "const": "completed", "title": "Type", "default": "completed" }, "started_at": { "type": "string", "title": "Started At", "description": "Start time in ISO 8601 format.", "examples": [ "2022-01-01T00:00:00Z" ] }, "ended_at": { "type": "string", "title": "Ended At", "description": "End time in ISO 8601 format.", "examples": [ "2022-01-01T00:00:00Z" ] } }, "type": "object", "required": [ "started_at", "ended_at" ], "title": "CompletedConversationStatus", "description": "Status for conversation that has completed." }, "ConversationMessage": { "properties": { "message": { "type": "string", "title": "Message", "description": "Text content." }, "sent_at": { "type": "string", "title": "Sent At", "description": "Sent time in ISO 8601 format." }, "sender": { "type": "string", "enum": [ "ai", "user" ], "title": "Sender", "description": "Sender, either 'ai' or 'user'." } }, "type": "object", "required": [ "message", "sent_at", "sender" ], "title": "ConversationMessage", "description": "Message in a conversation." }, "ConversationResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier of the object in the database.", "examples": [ "01234567-89ab-cdef-0123-456789abcdef" ] }, "agent_id": { "type": "string", "title": "Agent Id", "description": "ID of agent managing the conversation." }, "user_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Name", "description": "Name of the user." }, "user_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Email", "description": "Email of the user." }, "tags": { "additionalProperties": { "type": "string", "maxLength": 100, "minLength": 1 }, "propertyNames": { "maxLength": 30, "minLength": 1 }, "type": "object", "maxProperties": 10, "title": "Tags", "description": "Tags for the conversation." }, "status": { "$ref": "#/components/schemas/ConversationStatus" } }, "type": "object", "required": [ "id", "agent_id", "status" ], "title": "ConversationResponse", "description": "Response model for a conversation." }, "ConversationStatus": { "oneOf": [ { "$ref": "#/components/schemas/ToStartConversationStatus" }, { "$ref": "#/components/schemas/OngoingConversationStatus" }, { "$ref": "#/components/schemas/CompletedConversationStatus" } ], "discriminator": { "propertyName": "type", "mapping": { "completed": "#/components/schemas/CompletedConversationStatus", "ongoing": "#/components/schemas/OngoingConversationStatus", "to_start": "#/components/schemas/ToStartConversationStatus" } } }, "CreateAgentRequest": { "properties": { "name": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Name", "description": "Display name to use. Also used when addressed in conversations.", "examples": [ "Jarvis", "HAL 9000" ] }, "avatar_id": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Avatar Id", "description": "ID of avatar to use.", "examples": [ "01234567-89ab-cdef-0123-456789abcdef" ] }, "system_prompt": { "type": "string", "maxLength": 10000, "minLength": 1, "title": "System Prompt", "description": "System prompt to use.", "examples": [ "You are a helpful assistant." ] }, "language": { "anyOf": [ { "$ref": "#/components/schemas/Language" }, { "type": "null" } ], "description": "Language to use.", "examples": [ "en", "en-US", "de" ] }, "greeting": { "anyOf": [ { "type": "string", "maxLength": 1000, "minLength": 1 }, { "type": "null" } ], "title": "Greeting", "description": "What to say when a call starts.", "examples": [ "Hello!" ] }, "max_session_length_minutes": { "anyOf": [ { "type": "integer", "maximum": 90.0, "exclusiveMinimum": 0.0 }, { "type": "null" } ], "title": "Max Session Length Minutes", "description": "Maximum session length in minutes.", "examples": [ 30 ] }, "capabilities": { "$ref": "#/components/schemas/AgentCapabilityList", "description": "Extra capabilities to manage calls.", "examples": [ [ { "type": "webcam_vision" }, { "triggers": [ "hey agent", "hi pal" ], "type": "wakeup_mode" } ] ] }, "llm": { "anyOf": [ { "$ref": "#/components/schemas/AgentLlm" }, { "type": "null" } ], "description": "Configuration for LLM to use.", "examples": [ { "type": "openai" }, { "api_id": "01234567-89ab-cdef-0123-456789abcdef", "model": "gpt-4o-mini", "temperature": 0.7, "type": "openai_compatible" } ] }, "tts": { "anyOf": [ { "$ref": "#/components/schemas/AgentTts" }, { "type": "null" } ], "description": "Configuration for TTS to use.", "examples": [ { "type": "elevenlabs", "voice": "21m00Tcm4TlvDq8ikWAM" } ] }, "knowledge_file_ids": { "items": { "type": "string", "minLength": 1 }, "type": "array", "uniqueItems": true, "title": "Knowledge File Ids", "description": "IDs of knowledge files to refer to." } }, "type": "object", "required": [ "name", "avatar_id", "system_prompt" ], "title": "CreateAgentRequest", "description": "Request body to create an agent." }, "CreateElevenlabsExternalApiRequest": { "properties": { "type": { "type": "string", "const": "elevenlabs", "title": "Type", "default": "elevenlabs" }, "name": { "type": "string", "title": "Name" }, "api_key": { "type": "string", "minLength": 1, "format": "password", "title": "Api Key", "writeOnly": true } }, "type": "object", "required": [ "name", "api_key" ], "title": "CreateElevenlabsExternalApiRequest", "description": "Request body to create an ElevenLabs API configuration." }, "CreateExternalApiRequest": { "oneOf": [ { "$ref": "#/components/schemas/CreateOpenaiCompatibleLlmExternalApiRequest" }, { "$ref": "#/components/schemas/CreateElevenlabsExternalApiRequest" } ], "discriminator": { "propertyName": "type", "mapping": { "elevenlabs": "#/components/schemas/CreateElevenlabsExternalApiRequest", "openai_compatible_llm": "#/components/schemas/CreateOpenaiCompatibleLlmExternalApiRequest" } } }, "CreateKnowledgeFileRequest": { "oneOf": [ { "$ref": "#/components/schemas/CreateTextKnowledgeFileRequest" }, { "$ref": "#/components/schemas/CreatePdfKnowledgeFileRequest" } ], "discriminator": { "propertyName": "format", "mapping": { "pdf": "#/components/schemas/CreatePdfKnowledgeFileRequest", "text": "#/components/schemas/CreateTextKnowledgeFileRequest" } } }, "CreateLiveKitRoomRequest": { "properties": { "agent_id": { "type": "string", "title": "Agent Id", "description": "ID of agent managing the conversation." }, "user_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Name", "description": "Name of the user." }, "user_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Email", "description": "Email of the user." }, "tags": { "additionalProperties": { "type": "string", "maxLength": 100, "minLength": 1 }, "propertyNames": { "maxLength": 30, "minLength": 1 }, "type": "object", "maxProperties": 10, "title": "Tags", "description": "Tags for the conversation." } }, "type": "object", "required": [ "agent_id" ], "title": "CreateLiveKitRoomRequest", "description": "Request body to create a LiveKit room and its conversation." }, "CreateLivekitSessionRequest": { "properties": { "transport": { "type": "string", "const": "livekit", "title": "Transport", "default": "livekit" }, "avatar_id": { "type": "string", "title": "Avatar Id", "description": "ID of avatar to use.", "examples": [ "01234567-89ab-cdef-0123-456789abcdef" ] }, "url": { "type": "string", "title": "Url", "description": "URL of LiveKit server the avatar worker should connect to.", "examples": [ "wss://.livekit.cloud" ] }, "token": { "type": "string", "format": "password", "title": "Token", "description": "The token used to join your LiveKit room.", "writeOnly": true, "examples": [ "" ] } }, "type": "object", "required": [ "avatar_id", "url", "token" ], "title": "CreateLivekitSessionRequest", "description": "Request body to create a LiveKit speech-to-video session." }, "CreateOpenaiCompatibleLlmExternalApiRequest": { "properties": { "type": { "type": "string", "const": "openai_compatible_llm", "title": "Type", "default": "openai_compatible_llm" }, "name": { "type": "string", "title": "Name" }, "url": { "type": "string", "title": "Url" }, "api_key": { "type": "string", "format": "password", "title": "Api Key", "writeOnly": true } }, "type": "object", "required": [ "name", "url", "api_key" ], "title": "CreateOpenaiCompatibleLlmExternalApiRequest", "description": "Request body to create an OpenAI-compatible LLM API configuration." }, "CreatePdfKnowledgeFileRequest": { "properties": { "name": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Name", "examples": [ "Hitchhiker's Guide to the Galaxy" ] }, "format": { "type": "string", "const": "pdf", "title": "Format" }, "upload_num_chunks": { "type": "integer", "maximum": 1000.0, "exclusiveMinimum": 0.0, "title": "Upload Num Chunks" } }, "type": "object", "required": [ "name", "format", "upload_num_chunks" ], "title": "CreatePdfKnowledgeFileRequest", "description": "Request model for creating a PDF knowledge file." }, "CreatePipecatSessionRequest": { "properties": { "transport": { "type": "string", "const": "pipecat", "title": "Transport", "default": "pipecat" }, "avatar_id": { "type": "string", "title": "Avatar Id", "description": "ID of avatar to use.", "examples": [ "01234567-89ab-cdef-0123-456789abcdef" ] }, "url": { "type": "string", "title": "Url", "description": "URL of Daily room the video bot should connect to.", "examples": [ "wss://.pipecat.cloud" ] }, "token": { "type": "string", "format": "password", "title": "Token", "description": "The token used to join your Daily room.", "writeOnly": true, "examples": [ "" ] } }, "type": "object", "required": [ "avatar_id", "url", "token" ], "title": "CreatePipecatSessionRequest", "description": "Request body to create a Pipecat speech-to-video session." }, "CreateSessionRequest": { "anyOf": [ { "$ref": "#/components/schemas/CreateLivekitSessionRequest" }, { "$ref": "#/components/schemas/CreatePipecatSessionRequest" } ] }, "CreateTextKnowledgeFileRequest": { "properties": { "name": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Name", "examples": [ "Hitchhiker's Guide to the Galaxy" ] }, "format": { "type": "string", "const": "text", "title": "Format" }, "content": { "type": "string", "maxLength": 250000, "minLength": 1, "title": "Content" } }, "type": "object", "required": [ "name", "format", "content" ], "title": "CreateTextKnowledgeFileRequest", "description": "Request model for creating a text knowledge file." }, "DeepgramAgentTts": { "properties": { "type": { "type": "string", "const": "deepgram", "title": "Type", "default": "deepgram" }, "voice": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice" } }, "type": "object", "title": "DeepgramAgentTts", "description": "Configuration for Deepgram TTS." }, "ElevenlabsAgentLlm": { "properties": { "type": { "type": "string", "const": "elevenlabs_agent", "title": "Type", "default": "elevenlabs_agent" }, "api_id": { "type": "string", "title": "Api Id" }, "agent_id": { "type": "string", "pattern": "^[A-Za-z0-9_]+$", "title": "Agent Id" } }, "type": "object", "required": [ "api_id", "agent_id" ], "title": "ElevenlabsAgentLlm", "description": "Configuration for running your own ElevenLabs agent.\n\nElevenLabs runs the conversation with the agent's own prompt, voice,\nknowledge base and tools, so the agent cannot set a TTS or a greeting,\nnor use webcam vision, wakeup mode or dynamic avatar emotions.\n\nThe ElevenLabs agent should send the `agent_response_complete` client\nevent." }, "ElevenlabsAgentTts": { "properties": { "type": { "type": "string", "const": "elevenlabs", "title": "Type", "default": "elevenlabs" }, "voice": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice" } }, "type": "object", "title": "ElevenlabsAgentTts", "description": "Configuration for Elevenlabs TTS." }, "ElevenlabsExternalApiResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier of the object in the database.", "examples": [ "01234567-89ab-cdef-0123-456789abcdef" ] }, "type": { "type": "string", "const": "elevenlabs", "title": "Type", "default": "elevenlabs" }, "name": { "type": "string", "title": "Name" } }, "type": "object", "required": [ "id", "name" ], "title": "ElevenlabsExternalApiResponse", "description": "Response body for an ElevenLabs API configuration." }, "ErrorResponse": { "properties": { "detail": { "type": "string", "title": "Detail", "description": "Human-readable description of the error.", "examples": [ "Invalid API key." ] } }, "type": "object", "required": [ "detail" ], "title": "ErrorResponse", "description": "Standard error response body.\n\nCarries a single human-readable `detail` message describing what went\nwrong. This is the shape of every error response except validation errors\n(`422`), which instead return a list of per-field error objects." }, "ExternalApiResponse": { "oneOf": [ { "$ref": "#/components/schemas/OpenaiCompatibleLlmExternalApiResponse" }, { "$ref": "#/components/schemas/ElevenlabsExternalApiResponse" } ], "discriminator": { "propertyName": "type", "mapping": { "elevenlabs": "#/components/schemas/ElevenlabsExternalApiResponse", "openai_compatible_llm": "#/components/schemas/OpenaiCompatibleLlmExternalApiResponse" } } }, "FailedKnowledgeFileResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier of the object in the database.", "examples": [ "01234567-89ab-cdef-0123-456789abcdef" ] }, "name": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Name", "examples": [ "Hitchhiker's Guide to the Galaxy" ] }, "format": { "$ref": "#/components/schemas/KnowledgeFileFormat" }, "status": { "type": "string", "const": "failed", "title": "Status", "default": "failed" }, "reason": { "type": "string", "title": "Reason" } }, "type": "object", "required": [ "id", "name", "format", "reason" ], "title": "FailedKnowledgeFileResponse", "description": "Response model for a knowledge file that could not be processed." }, "GoogleAgentTts": { "properties": { "type": { "type": "string", "const": "google_tts", "title": "Type", "default": "google_tts" }, "voice": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice" } }, "type": "object", "title": "GoogleAgentTts", "description": "Configuration for Google TTS." }, "HasMorePage_AgentResponse_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AgentResponse" }, "type": "array", "title": "Data", "description": "List of objects." }, "has_more": { "type": "boolean", "const": true, "title": "Has More", "description": "Whether there are more objects to fetch.", "default": true }, "next_cursor": { "type": "string", "title": "Next Cursor", "description": "The cursor for the next page of objects." } }, "type": "object", "required": [ "data", "next_cursor" ], "title": "HasMorePage[AgentResponse]" }, "HasMorePage_AvatarResponse_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AvatarResponse" }, "type": "array", "title": "Data", "description": "List of objects." }, "has_more": { "type": "boolean", "const": true, "title": "Has More", "description": "Whether there are more objects to fetch.", "default": true }, "next_cursor": { "type": "string", "title": "Next Cursor", "description": "The cursor for the next page of objects." } }, "type": "object", "required": [ "data", "next_cursor" ], "title": "HasMorePage[AvatarResponse]" }, "HasMorePage_ConversationResponse_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ConversationResponse" }, "type": "array", "title": "Data", "description": "List of objects." }, "has_more": { "type": "boolean", "const": true, "title": "Has More", "description": "Whether there are more objects to fetch.", "default": true }, "next_cursor": { "type": "string", "title": "Next Cursor", "description": "The cursor for the next page of objects." } }, "type": "object", "required": [ "data", "next_cursor" ], "title": "HasMorePage[ConversationResponse]" }, "HasMorePage_ExternalApiResponse_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ExternalApiResponse" }, "type": "array", "title": "Data", "description": "List of objects." }, "has_more": { "type": "boolean", "const": true, "title": "Has More", "description": "Whether there are more objects to fetch.", "default": true }, "next_cursor": { "type": "string", "title": "Next Cursor", "description": "The cursor for the next page of objects." } }, "type": "object", "required": [ "data", "next_cursor" ], "title": "HasMorePage[ExternalApiResponse]" }, "HasMorePage_KnowledgeFileResponse_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/KnowledgeFileResponse" }, "type": "array", "title": "Data", "description": "List of objects." }, "has_more": { "type": "boolean", "const": true, "title": "Has More", "description": "Whether there are more objects to fetch.", "default": true }, "next_cursor": { "type": "string", "title": "Next Cursor", "description": "The cursor for the next page of objects." } }, "type": "object", "required": [ "data", "next_cursor" ], "title": "HasMorePage[KnowledgeFileResponse]" }, "HasMorePage_SessionResponse_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/SessionResponse" }, "type": "array", "title": "Data", "description": "List of objects." }, "has_more": { "type": "boolean", "const": true, "title": "Has More", "description": "Whether there are more objects to fetch.", "default": true }, "next_cursor": { "type": "string", "title": "Next Cursor", "description": "The cursor for the next page of objects." } }, "type": "object", "required": [ "data", "next_cursor" ], "title": "HasMorePage[SessionResponse]" }, "KnowledgeFileFormat": { "type": "string", "enum": [ "text", "pdf" ], "title": "KnowledgeFileFormat", "description": "Format of the knowledge file." }, "KnowledgeFileResponse": { "oneOf": [ { "$ref": "#/components/schemas/ToUploadKnowledgeFileResponse" }, { "$ref": "#/components/schemas/ProcessingKnowledgeFileResponse" }, { "$ref": "#/components/schemas/AvailableKnowledgeFileResponse" }, { "$ref": "#/components/schemas/FailedKnowledgeFileResponse" } ], "discriminator": { "propertyName": "status", "mapping": { "available": "#/components/schemas/AvailableKnowledgeFileResponse", "failed": "#/components/schemas/FailedKnowledgeFileResponse", "processing": "#/components/schemas/ProcessingKnowledgeFileResponse", "to-upload": "#/components/schemas/ToUploadKnowledgeFileResponse" } } }, "Language": { "type": "string", "enum": [ "ar", "ar-SA", "bn", "bg", "zh", "cs", "da", "nl", "en", "en-AU", "en-GB", "en-US", "fi", "fr", "fr-CA", "fr-FR", "de", "el", "hi", "hu", "id", "it", "ja", "kk", "ko", "ms", "no", "pl", "pt", "pt-BR", "pt-PT", "ro", "ru", "sk", "es", "sv", "tr", "uk", "ur", "vi" ], "title": "Language", "description": "Language for communication." }, "LiveKitRoomResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier of the object in the database.", "examples": [ "01234567-89ab-cdef-0123-456789abcdef" ] }, "agent_id": { "type": "string", "title": "Agent Id", "description": "ID of agent managing the conversation." }, "user_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Name", "description": "Name of the user." }, "user_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Email", "description": "Email of the user." }, "tags": { "additionalProperties": { "type": "string", "maxLength": 100, "minLength": 1 }, "propertyNames": { "maxLength": 30, "minLength": 1 }, "type": "object", "maxProperties": 10, "title": "Tags", "description": "Tags for the conversation." }, "status": { "$ref": "#/components/schemas/ConversationStatus" }, "livekit_url": { "type": "string", "title": "Livekit Url", "description": "LiveKit server URL to connect to." }, "livekit_token": { "type": "string", "title": "Livekit Token", "description": "JWT for joining the LiveKit room." } }, "type": "object", "required": [ "id", "agent_id", "status", "livekit_url", "livekit_token" ], "title": "LiveKitRoomResponse", "description": "Response model for a conversation including LiveKit connection details." }, "LivekitAgentLlm": { "properties": { "type": { "type": "string", "const": "livekit", "title": "Type", "default": "livekit" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" }, "reasoning_effort": { "anyOf": [ { "type": "string", "enum": [ "low", "medium", "high", "xhigh" ] }, { "type": "null" } ], "title": "Reasoning Effort" } }, "type": "object", "title": "LivekitAgentLlm", "description": "Configuration for LLMs supported via LiveKit Inference." }, "LivekitAgentTts": { "properties": { "type": { "type": "string", "const": "livekit", "title": "Type", "default": "livekit" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" }, "voice": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice" } }, "type": "object", "title": "LivekitAgentTts", "description": "Configuration for TTS supported via LiveKit Inference." }, "LivekitSessionResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier of the object in the database.", "examples": [ "01234567-89ab-cdef-0123-456789abcdef" ] }, "transport": { "type": "string", "const": "livekit", "title": "Transport", "default": "livekit" }, "avatar_id": { "type": "string", "title": "Avatar Id", "description": "ID of avatar to use.", "examples": [ "01234567-89ab-cdef-0123-456789abcdef" ] }, "status": { "$ref": "#/components/schemas/SessionStatus" }, "url": { "type": "string", "title": "Url", "description": "URL of LiveKit server the avatar worker should connect to.", "examples": [ "wss://.livekit.cloud" ] } }, "type": "object", "required": [ "id", "avatar_id", "status", "url" ], "title": "LivekitSessionResponse", "description": "Response body for a LiveKit speech-to-video session." }, "NoMorePage_AgentResponse_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AgentResponse" }, "type": "array", "title": "Data", "description": "List of objects." }, "has_more": { "type": "boolean", "const": false, "title": "Has More", "description": "Whether there are more objects to fetch.", "default": false } }, "type": "object", "required": [ "data" ], "title": "NoMorePage[AgentResponse]" }, "NoMorePage_AvatarResponse_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AvatarResponse" }, "type": "array", "title": "Data", "description": "List of objects." }, "has_more": { "type": "boolean", "const": false, "title": "Has More", "description": "Whether there are more objects to fetch.", "default": false } }, "type": "object", "required": [ "data" ], "title": "NoMorePage[AvatarResponse]" }, "NoMorePage_ConversationResponse_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ConversationResponse" }, "type": "array", "title": "Data", "description": "List of objects." }, "has_more": { "type": "boolean", "const": false, "title": "Has More", "description": "Whether there are more objects to fetch.", "default": false } }, "type": "object", "required": [ "data" ], "title": "NoMorePage[ConversationResponse]" }, "NoMorePage_ExternalApiResponse_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ExternalApiResponse" }, "type": "array", "title": "Data", "description": "List of objects." }, "has_more": { "type": "boolean", "const": false, "title": "Has More", "description": "Whether there are more objects to fetch.", "default": false } }, "type": "object", "required": [ "data" ], "title": "NoMorePage[ExternalApiResponse]" }, "NoMorePage_KnowledgeFileResponse_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/KnowledgeFileResponse" }, "type": "array", "title": "Data", "description": "List of objects." }, "has_more": { "type": "boolean", "const": false, "title": "Has More", "description": "Whether there are more objects to fetch.", "default": false } }, "type": "object", "required": [ "data" ], "title": "NoMorePage[KnowledgeFileResponse]" }, "NoMorePage_SessionResponse_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/SessionResponse" }, "type": "array", "title": "Data", "description": "List of objects." }, "has_more": { "type": "boolean", "const": false, "title": "Has More", "description": "Whether there are more objects to fetch.", "default": false } }, "type": "object", "required": [ "data" ], "title": "NoMorePage[SessionResponse]" }, "OngoingConversationStatus": { "properties": { "type": { "type": "string", "const": "ongoing", "title": "Type", "default": "ongoing" }, "started_at": { "type": "string", "title": "Started At", "description": "Start time in ISO 8601 format.", "examples": [ "2022-01-01T00:00:00Z" ] } }, "type": "object", "required": [ "started_at" ], "title": "OngoingConversationStatus", "description": "Status for conversation that is currently ongoing." }, "OpenaiAgentLlm": { "properties": { "type": { "type": "string", "const": "openai", "title": "Type", "default": "openai" }, "model": { "anyOf": [ { "type": "string", "enum": [ "gpt-5.4-mini", "gpt-4.1-mini", "gpt-4.1" ] }, { "type": "null" } ], "title": "Model", "description": "Name of model to use. Defaults to GPT 5.4 mini." } }, "type": "object", "title": "OpenaiAgentLlm", "description": "Configuration for OpenAI LLM." }, "OpenaiAgentTts": { "properties": { "type": { "type": "string", "const": "openai_tts", "title": "Type", "default": "openai_tts" }, "voice": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice" } }, "type": "object", "title": "OpenaiAgentTts", "description": "Configuration for OpenAI TTS." }, "OpenaiCompatibleAgentLlm": { "properties": { "type": { "type": "string", "const": "openai_compatible", "title": "Type", "default": "openai_compatible" }, "api_id": { "type": "string", "title": "Api Id" }, "model": { "type": "string", "title": "Model" }, "temperature": { "type": "number", "title": "Temperature" }, "headers": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Headers" } }, "type": "object", "required": [ "api_id", "model", "temperature" ], "title": "OpenaiCompatibleAgentLlm", "description": "Configuration for an LLM provided by an OpenAI-compatible API.\n\nThe notion of \"OpenAI-compatible API\" is somewhat fuzzy, there is no\nagreed upon standard for what it means.\nIn practice, we care if the API is compatible with how LiveKit's openai\nplugin interacts with it, i.e. a subset of OpenAI's API specification that\nprovides chat completions:\nhttps://platform.openai.com/docs/api-reference/completions" }, "OpenaiCompatibleLlmExternalApiResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier of the object in the database.", "examples": [ "01234567-89ab-cdef-0123-456789abcdef" ] }, "type": { "type": "string", "const": "openai_compatible_llm", "title": "Type", "default": "openai_compatible_llm" }, "name": { "type": "string", "title": "Name" }, "url": { "type": "string", "title": "Url" } }, "type": "object", "required": [ "id", "name", "url" ], "title": "OpenaiCompatibleLlmExternalApiResponse", "description": "Response body for an OpenAI-compatible LLM API configuration." }, "Page_AgentResponse_": { "anyOf": [ { "$ref": "#/components/schemas/HasMorePage_AgentResponse_" }, { "$ref": "#/components/schemas/NoMorePage_AgentResponse_" } ] }, "Page_AvatarResponse_": { "anyOf": [ { "$ref": "#/components/schemas/HasMorePage_AvatarResponse_" }, { "$ref": "#/components/schemas/NoMorePage_AvatarResponse_" } ] }, "Page_ConversationResponse_": { "anyOf": [ { "$ref": "#/components/schemas/HasMorePage_ConversationResponse_" }, { "$ref": "#/components/schemas/NoMorePage_ConversationResponse_" } ] }, "Page_ExternalApiResponse_": { "anyOf": [ { "$ref": "#/components/schemas/HasMorePage_ExternalApiResponse_" }, { "$ref": "#/components/schemas/NoMorePage_ExternalApiResponse_" } ] }, "Page_KnowledgeFileResponse_": { "anyOf": [ { "$ref": "#/components/schemas/HasMorePage_KnowledgeFileResponse_" }, { "$ref": "#/components/schemas/NoMorePage_KnowledgeFileResponse_" } ] }, "Page_SessionResponse_": { "anyOf": [ { "$ref": "#/components/schemas/HasMorePage_SessionResponse_" }, { "$ref": "#/components/schemas/NoMorePage_SessionResponse_" } ] }, "PipecatSessionResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier of the object in the database.", "examples": [ "01234567-89ab-cdef-0123-456789abcdef" ] }, "transport": { "type": "string", "const": "pipecat", "title": "Transport", "default": "pipecat" }, "avatar_id": { "type": "string", "title": "Avatar Id", "description": "ID of avatar to use.", "examples": [ "01234567-89ab-cdef-0123-456789abcdef" ] }, "status": { "$ref": "#/components/schemas/SessionStatus" }, "url": { "type": "string", "title": "Url", "description": "URL of Daily room the video bot should connect to.", "examples": [ "wss://.pipecat.cloud" ] } }, "type": "object", "required": [ "id", "avatar_id", "status", "url" ], "title": "PipecatSessionResponse", "description": "Response body for a Pipecat speech-to-video session." }, "ProcessingKnowledgeFileResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier of the object in the database.", "examples": [ "01234567-89ab-cdef-0123-456789abcdef" ] }, "name": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Name", "examples": [ "Hitchhiker's Guide to the Galaxy" ] }, "format": { "$ref": "#/components/schemas/KnowledgeFileFormat" }, "status": { "type": "string", "const": "processing", "title": "Status", "default": "processing" } }, "type": "object", "required": [ "id", "name", "format" ], "title": "ProcessingKnowledgeFileResponse", "description": "Response model for a knowledge file that is still being processed." }, "SessionResponse": { "oneOf": [ { "$ref": "#/components/schemas/LivekitSessionResponse" }, { "$ref": "#/components/schemas/PipecatSessionResponse" } ], "discriminator": { "propertyName": "transport", "mapping": { "livekit": "#/components/schemas/LivekitSessionResponse", "pipecat": "#/components/schemas/PipecatSessionResponse" } } }, "SessionStatus": { "oneOf": [ { "$ref": "#/components/schemas/SessionStatusToStart" }, { "$ref": "#/components/schemas/SessionStatusOngoing" }, { "$ref": "#/components/schemas/SessionStatusCompleted" } ], "discriminator": { "propertyName": "type", "mapping": { "completed": "#/components/schemas/SessionStatusCompleted", "ongoing": "#/components/schemas/SessionStatusOngoing", "to_start": "#/components/schemas/SessionStatusToStart" } } }, "SessionStatusCompleted": { "properties": { "type": { "type": "string", "const": "completed", "title": "Type", "default": "completed" }, "started_at": { "type": "string", "title": "Started At", "description": "Start time in ISO 8601 format.", "examples": [ "2022-01-01T00:00:00Z" ] }, "ended_at": { "type": "string", "title": "Ended At", "description": "End time in ISO 8601 format.", "examples": [ "2022-01-01T00:00:00Z" ] } }, "type": "object", "required": [ "started_at", "ended_at" ], "title": "SessionStatusCompleted", "description": "Session that has completed." }, "SessionStatusOngoing": { "properties": { "type": { "type": "string", "const": "ongoing", "title": "Type", "default": "ongoing" }, "started_at": { "type": "string", "title": "Started At", "description": "Start time in ISO 8601 format.", "examples": [ "2022-01-01T00:00:00Z" ] } }, "type": "object", "required": [ "started_at" ], "title": "SessionStatusOngoing", "description": "Session that is currently ongoing." }, "SessionStatusToStart": { "properties": { "type": { "type": "string", "const": "to_start", "title": "Type", "default": "to_start" } }, "type": "object", "title": "SessionStatusToStart", "description": "Session that has not yet started." }, "SessionUsage": { "properties": { "id": { "type": "string", "title": "Id", "description": "ID of the session.", "examples": [ "01234567-89ab-cdef-0123-456789abcdef" ] }, "avatar_id": { "type": "string", "title": "Avatar Id", "description": "ID of the avatar of the session.", "examples": [ "01234567-89ab-cdef-0123-456789abcdef" ] }, "started_at": { "type": "string", "title": "Started At", "description": "Time the avatar started in the room in ISO 8601 format.", "examples": [ "2026-10-01T09:00:00+00:00" ] }, "ended_at": { "type": "string", "title": "Ended At", "description": "Time the session ended in ISO 8601 format.", "examples": [ "2026-10-01T09:30:30+00:00" ] }, "used_seconds": { "type": "integer", "title": "Used Seconds", "description": "Usage billed for the session: from the time the avatar started in the room until it last spoke.", "examples": [ 1830 ] } }, "type": "object", "required": [ "id", "avatar_id", "started_at", "ended_at", "used_seconds" ], "title": "SessionUsage", "description": "Usage of one speech-to-video session." }, "SessionUsageResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/SessionUsage" }, "type": "array", "title": "Data", "description": "Every ended session of the requested range, newest first." } }, "type": "object", "required": [ "data" ], "title": "SessionUsageResponse", "description": "Speech-to-video usage per session." }, "ToStartConversationStatus": { "properties": { "type": { "type": "string", "const": "to_start", "title": "Type", "default": "to_start" } }, "type": "object", "title": "ToStartConversationStatus", "description": "Status for conversation that has not yet started." }, "ToUploadKnowledgeFileResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier of the object in the database.", "examples": [ "01234567-89ab-cdef-0123-456789abcdef" ] }, "name": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Name", "examples": [ "Hitchhiker's Guide to the Galaxy" ] }, "format": { "$ref": "#/components/schemas/KnowledgeFileFormat" }, "status": { "type": "string", "const": "to-upload", "title": "Status", "default": "to-upload" } }, "type": "object", "required": [ "id", "name", "format" ], "title": "ToUploadKnowledgeFileResponse", "description": "Response model for a knowledge file that is to be uploaded." }, "UpdateAgentRequest": { "properties": { "name": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Name", "description": "Display name to use. Also used when addressed in conversations.", "examples": [ "Jarvis", "HAL 9000" ] }, "avatar_id": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Avatar Id", "description": "ID of avatar to use.", "examples": [ "01234567-89ab-cdef-0123-456789abcdef" ] }, "system_prompt": { "type": "string", "maxLength": 10000, "minLength": 1, "title": "System Prompt", "description": "System prompt to use.", "examples": [ "You are a helpful assistant." ] }, "language": { "anyOf": [ { "$ref": "#/components/schemas/Language" }, { "type": "null" } ], "description": "Language to use.", "examples": [ "en", "en-US", "de" ] }, "greeting": { "anyOf": [ { "type": "string", "maxLength": 1000, "minLength": 1 }, { "type": "null" } ], "title": "Greeting", "description": "What to say when a call starts.", "examples": [ "Hello!" ] }, "max_session_length_minutes": { "anyOf": [ { "type": "integer", "maximum": 90.0, "exclusiveMinimum": 0.0 }, { "type": "null" } ], "title": "Max Session Length Minutes", "description": "Maximum session length in minutes.", "examples": [ 30 ] }, "capabilities": { "$ref": "#/components/schemas/AgentCapabilityList", "description": "Extra capabilities to manage calls.", "examples": [ [ { "type": "webcam_vision" }, { "triggers": [ "hey agent", "hi pal" ], "type": "wakeup_mode" } ] ] }, "llm": { "anyOf": [ { "$ref": "#/components/schemas/AgentLlm" }, { "type": "null" } ], "description": "Configuration for LLM to use.", "examples": [ { "type": "openai" }, { "api_id": "01234567-89ab-cdef-0123-456789abcdef", "model": "gpt-4o-mini", "temperature": 0.7, "type": "openai_compatible" } ] }, "tts": { "anyOf": [ { "$ref": "#/components/schemas/AgentTts" }, { "type": "null" } ], "description": "Configuration for TTS to use.", "examples": [ { "type": "elevenlabs", "voice": "21m00Tcm4TlvDq8ikWAM" } ] }, "knowledge_file_ids": { "items": { "type": "string", "minLength": 1 }, "type": "array", "uniqueItems": true, "title": "Knowledge File Ids", "description": "IDs of knowledge files to refer to." } }, "type": "object", "title": "UpdateAgentRequest", "description": "Request body to update an agent. Omitted fields are unchanged." }, "UsageResponse": { "properties": { "period_start": { "type": "string", "title": "Period Start", "description": "Start of the billing period in ISO 8601 format.", "examples": [ "2026-10-01T00:00:00+00:00" ] }, "period_end": { "type": "string", "title": "Period End", "description": "End of the billing period in ISO 8601 format, exclusive.", "examples": [ "2027-01-01T00:00:00+00:00" ] }, "included_seconds": { "type": "integer", "title": "Included Seconds", "description": "Usage your plan includes in the billing period.", "examples": [ 540000 ] }, "used_seconds": { "type": "integer", "title": "Used Seconds", "description": "Usage billed in the billing period, including overage.", "examples": [ 432000 ] }, "remaining_seconds": { "type": "integer", "title": "Remaining Seconds", "description": "Usage your plan includes that is not used yet.", "examples": [ 108000 ] }, "overage_seconds": { "type": "integer", "title": "Overage Seconds", "description": "Usage billed past what your plan includes. It only grows when usage-based billing is enabled.", "examples": [ 0 ] } }, "type": "object", "required": [ "period_start", "period_end", "included_seconds", "used_seconds", "remaining_seconds", "overage_seconds" ], "title": "UsageResponse", "description": "Usage of the current billing period." }, "Visibility": { "type": "string", "enum": [ "public", "private" ], "title": "Visibility", "description": "Visibility of the resource." }, "WakeupModeAgentCapability": { "properties": { "type": { "type": "string", "const": "wakeup_mode", "title": "Type", "default": "wakeup_mode" }, "triggers": { "items": { "type": "string", "pattern": "[^\\W_]" }, "type": "array", "title": "Triggers" } }, "type": "object", "required": [ "triggers" ], "title": "WakeupModeAgentCapability", "description": "Agent capability to wake up only on specific keywords." }, "WebcamVisionAgentCapability": { "properties": { "type": { "type": "string", "const": "webcam_vision", "title": "Type", "default": "webcam_vision" } }, "type": "object", "title": "WebcamVisionAgentCapability", "description": "Agent capability to see user camera feed." } }, "securitySchemes": { "APIKeyHeader": { "type": "apiKey", "description": "Your Beyond Presence API Key.", "in": "header", "name": "x-api-key" } } }, "tags": [ { "name": "Avatars", "description": "Retrieve information about the avatars available to your account." }, { "name": "Agents", "description": "Create and configure Managed Agents." }, { "name": "Agent Conversations", "description": "Retrieve information about the conversations your Managed Agents have had, including their status, participants, and transcripts." }, { "name": "Agent Integration", "description": "Primitives for embedding a Managed Agent in your own application with advanced cusotmization. **Most integrations do not need these.**" }, { "name": "Agent Knowledge Files", "description": "Manage the knowledge base documents your Managed Agents can draw on during a conversation." }, { "name": "Agents External APIs", "description": "Store credentials for external services, such as an OpenAI-compatible LLM, so Managed Agents can reference them by ID." }, { "name": "Authentication", "description": "Verify your API key." }, { "name": "Speech-to-Video Sessions", "description": "Attach an avatar to a voice agent you build and run yourself. Prefer using the [LiveKit Plugin](https://docs.bey.dev/integrations/voice-agents/livekit) over calling these endpoints directly." }, { "name": "Usage", "description": "Retrieve how much of your plan your organization has used." } ] }