> ## Documentation Index > Fetch the complete documentation index at: https://docs.bey.dev/llms.txt > Use this file to discover all available pages before exploring further. # Update Agent > Update an existing agent. Only the fields present in the request body are changed; omitted fields keep their current values. ## OpenAPI ````yaml /openapi.json patch /v1/agents/{id} 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. ## Starting a conversation with a Managed Agent There are two ways to put a user in front of one of your agents, and most integrations only need the first: 1. **Open the agent's managed room** at `https://bey.chat/`. This needs no API call at all and is available on every plan. Use the `Agent Conversations` endpoints afterwards to read status and transcripts. 2. **Drive the media session yourself** from a LiveKit client SDK, using `POST /v1/livekit-rooms` in the `Agent Integration` group to mint room credentials. This requires the Growth plan or above. ## Authentication Authenticate every request with your API key in the `x-api-key` header: ``` x-api-key: ``` You can create and manage API keys in the dashboard, and verify a key with `GET /v1/auth/verify`. ## Pagination List endpoints are cursor-paginated. Pass `limit` (1-50, default 10) to control the page size and `cursor` to fetch the next page. Each response includes a `next_cursor` when more results are available. ## Errors Errors return the appropriate HTTP status code with a JSON body containing a `detail` message with more information. ## Rate limits Usage and concurrency limits are tied to your plan and surfaced as HTTP `429` responses. version: 0.3.0 servers: - url: https://api.bey.dev security: [] 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. paths: /v1/agents/{id}: patch: tags: - Agents summary: Update Agent description: >- Update an existing agent. Only the fields present in the request body are changed; omitted fields keep their current values. operationId: update_agent_v1_agents__id__patch 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' '403': description: >- The API key is valid but not permitted to perform this action, either because the resource belongs to someone else or because the requested feature requires a plan upgrade. content: application/json: examples: permission: summary: Not permitted value: detail: You do not have permission to access this resource. 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' '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: >- A plan limit has been exceeded, either the usage limit or the number of concurrent sessions. content: application/json: examples: usage: summary: Usage limit exceeded value: detail: Usage limit exceeded. Please upgrade your plan. concurrency: summary: Concurrency limit exceeded value: detail: >- You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions. schema: $ref: '#/components/schemas/ErrorResponse' security: - APIKeyHeader: [] components: schemas: 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 exclusiveMinimum: 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. 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. Carries a single human-readable `detail` message describing what went wrong. This is the shape of every error response except validation errors (`422`), which instead return a list of per-field error objects. 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. 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' 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' AgentCapability: oneOf: - $ref: '#/components/schemas/WebcamVisionAgentCapability' - $ref: '#/components/schemas/WakeupModeAgentCapability' discriminator: propertyName: type mapping: wakeup_mode: '#/components/schemas/WakeupModeAgentCapability' webcam_vision: '#/components/schemas/WebcamVisionAgentCapability' 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. 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. 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. The notion of "OpenAI-compatible API" is somewhat fuzzy, there is no agreed upon standard for what it means. In practice, we care if the API is compatible with how LiveKit's openai plugin interacts with it, i.e. a subset of OpenAI's API specification that provides chat completions: https://platform.openai.com/docs/api-reference/completions ElevenlabsAgentLlm: properties: type: type: string const: elevenlabs_agent title: Type default: elevenlabs_agent api_id: type: string title: Api Id agent_id: type: string minLength: 1 title: Agent Id type: object required: - api_id - agent_id title: ElevenlabsAgentLlm description: |- Configuration for running your own ElevenLabs agent. ElevenLabs runs the conversation with the agent's own prompt, voice, knowledge base and tools, so the agent cannot set a TTS or a greeting, nor use webcam vision, wakeup mode or dynamic avatar emotions. The ElevenLabs agent must use a PCM format (e.g. `pcm_16000`) for both user input and agent output audio, and should send the `agent_response_complete` client event. 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. 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. 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. 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. 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. 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. 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. WakeupModeAgentCapability: properties: type: type: string const: wakeup_mode title: Type default: wakeup_mode triggers: items: type: string type: array title: Triggers type: object required: - triggers title: WakeupModeAgentCapability description: Agent capability to wake up only on specific keywords. securitySchemes: APIKeyHeader: type: apiKey description: Your Beyond Presence API Key. in: header name: x-api-key ```` ## Related topics - [Changelog](/learn/changelog.md) - [Beyond Presence REST API](/concepts/api/index.md) - [Delete Agent](/api-reference/agents/delete-agent.md) - [List Agents](/api-reference/agents/list-agents.md) - [Create Agent](/api-reference/agents/create-agent.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.