> ## Documentation Index > Fetch the complete documentation index at: https://docs.colloqui.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create Agent > Create a new agent ## OpenAPI ````yaml POST /api/v1/agents openapi: 3.0.3 info: title: Colloqui API Documentation description: API documentation for Colloqui application version: 1.0.0 servers: - url: https://colloqui-web-develop-btoadh.laravel.cloud security: - default: [] tags: - name: Authentication description: |- APIs for retrieving a token and invalidating the current token. - name: API Keys description: |- APIs for managing API keys. - name: Agent description: |- APIs for agents - name: Agent Versions description: |- APIs for retrieving version history of an agent. - name: Call History description: |- APIs for managing call histories. - name: Knowledge Base description: |- APIs for knowledge base management. - name: Number description: |- APIs for managing numbers. - name: Subscription description: |- APIs to subscribe an agent to a subscription. - name: User description: |- APIs for managing users. - name: Webhook description: |- APIs for managing webhooks. - name: Workspace description: |- APIs for managing workspaces. - name: Workspace User description: |- APIs for managing users within workspaces. paths: /api/v1/agents: post: tags: - Agent summary: Create Agent description: Create a new agent operationId: createAgent parameters: [] requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: Must not be greater than 255 characters. example: b call_config: type: object description: '' properties: max_call_duration_ms: type: integer description: >- Maximum call duration in milliseconds. Must be at least 60000. Must not be greater than 7200000. example: 3600000 ring_duration_ms: type: integer description: >- Ring duration in milliseconds before call is considered unanswered. Must be at least 5000. Must not be greater than 300000. example: 30000 knowledge_base_config: type: object description: '' properties: chunks_to_retrieve: type: integer description: >- Number of knowledge base chunks to retrieve (1-10). Must be at least 1. Must not be greater than 10. example: 5 similarity_threshold: type: number description: >- Similarity threshold for knowledge base retrieval (0.30-0.95). Must be at least 0.30. Must not be greater than 0.95. example: 0.75 nullable: true llm_config: type: object description: '' properties: provider: type: string description: '' example: internal enum: - internal - azure - mistral - bedrock_claude - groq model: type: string description: >- The model name to use according to the llm_config.provider. example: gpt-4o-mini temperature: type: number description: >- Controls creativity or randomness in the model's responses. This field is required when `llm_config.provider` is `bedrock_claude`. This field is required when `llm_config.provider` is `internal`. Must be at least 0. Must not be greater than 1. example: 1 deployment: type: string description: >- The name of the deployment you created in Azure. This field is required when `llm_config.provider` is `azure`. example: 01h8xyz123abc456def789ghi endpoint: type: string description: >- The full endpoint URL of your Azure resource. This field is required when `llm_config.provider` is `azure`. Must be a valid URL. example: https://my-resource-name.openai.azure.com/ api_version: type: string description: >- The Azure OpenAI API version to use. This field is required when `llm_config.provider` is `azure`. example: 2024-02-15-preview base_url: type: string description: >- This field is required when `llm_config.provider` is `internal`. example: >- http://www.example.com/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html api_key: type: string description: '' example: example nullable: true region: type: string description: >- The AWS region where the Bedrock service is hosted. This field is required when `llm_config.provider` is `bedrock_claude`. example: us-east-1 max_tokens: type: integer description: >- The maximum number of tokens (words/pieces of words) that the model can generate in its response. This field is required when `llm_config.provider` is `bedrock_claude`. example: 16 knowledge_base_ids: type: array description: >- The `id` of an existing record in the knowledge_bases table. example: - architecto items: type: string tools: type: array description: Array of tool configurations. example: [] items: type: object nullable: true properties: name: type: string description: >- Must match the regex /^[a-zA-Z_-][a-zA-Z0-9_-]*$/. Must not be greater than 255 characters. example: i description: type: string description: Must not be greater than 1024 characters. example: Example text. nullable: true type: type: string description: '' example: press_ivr enum: - end_call - transfer_call - press_ivr - send_sms - extract_dynamic_variable - custom_function announcement_type: type: string description: '' example: static enum: - static - prompt nullable: true announcement_message: type: string description: '' example: example nullable: true announcement_prompt: type: string description: '' example: example nullable: true transfer_declined_message: type: string description: '' example: example nullable: true hold_audio: type: string description: Must not be greater than 50 characters. example: 'n' nullable: true custom_sip_headers: type: object description: >- Custom SIP headers for this tool as key-value pairs, where keys are header names (e.g., "X-Foo") and values are header values. example: X-Foo: Foo X-Bar: Bar properties: {} voicemail_detection: type: boolean description: '' example: false nullable: true voicemail_response_action_type: type: string description: '' example: prompt enum: - prompt - hangup - message nullable: true voicemail_response_text: type: string description: '' example: example nullable: true phone_directory: type: array description: >- This field is required when `llm_config.tools.*.type` is `transfer_call`. example: [] items: type: object properties: name: type: string description: '' example: example phone_number: type: string description: '' example: example description: type: string description: '' example: example transfer_type: type: string description: '' example: warm enum: - warm - cold required: - name - phone_number - description - transfer_type pause_detection_delay_ms: type: integer description: >- Must be at least 1000. Must not be greater than 6000. example: 22 nullable: true content_type: type: string description: >- This field is required when `llm_config.tools.*.type` is `send_sms`. example: prompt enum: - prompt - static content: type: string description: >- This field is required when `llm_config.tools.*.type` is `send_sms`. example: example http_method: type: string description: >- This field is required when `llm_config.tools.*.http_method` is `custom_function`. example: PUT enum: - GET - POST - PUT - PATCH - DELETE api_endpoint: type: string description: >- This field is required when `llm_config.tools.*.api_endpoint` is `custom_function`. Must be a valid URL. example: http://example.com/ timeout: type: integer description: Must be at least 0. example: 77 nullable: true custom_function_headers: type: array description: '' example: - architecto items: type: string custom_function_query: type: array description: '' example: - architecto items: type: string custom_function_parameters: type: string description: '' example: example nullable: true custom_function_variables: type: array description: '' example: - architecto items: type: string speak_during_execution: type: boolean description: '' example: false nullable: true speak_during_execution_options: type: array description: '' example: - architecto items: type: string speak_after_execution: type: boolean description: '' example: false nullable: true variables: type: array description: >- This field is required when `llm_config.tools.*.type` is `extract_dynamic_variable`. example: [] items: type: object properties: type: type: string description: '' example: string enum: - string - number - boolean - enum name: type: string description: >- Must match the regex /^[a-zA-Z_-][a-zA-Z0-9_-]*$/. example: lm0y5pX description: type: string description: '' example: Eius et animi quos velit et. choices: type: array description: '' example: - architecto items: type: string required: - type - name - description required: - name - type required: - provider prompt_config: type: object description: '' properties: prompt: type: string description: >- General prompt appended to system prompt no matter what state the agent is in. example: example first_speaker: type: string description: The speaker who starts the conversation. example: ai enum: - ai - user ai_speak_after_silence: type: boolean description: Allow the AI to speak first when the user is silent. example: true ai_speak_wait_time: type: number description: >- How long the AI will wait until speaking. This field is required when `prompt_config.ai_speak_after_silence` is `true`. Must be at least 0. Must not be greater than 5. example: 2 welcome_message_type: type: string description: >- Where the AI will get the message to greet the user. When set to `dynamic`, the message will be derived from the `prompt`. When `static`, the `welcome_message` must be set. example: static enum: - static - dynamic welcome_message: type: string description: >- The welcome message the AI will use when the `welcome_message_type` is `statis`. This field is required when `prompt_config.welcome_message_type` is `static`. example: example required: - prompt - first_speaker - welcome_message_type stt_config: type: object description: '' properties: provider: type: string description: The STT provider to use. example: deepgram enum: - deepgram - assemblyai model: type: string description: The STT model to use for the given provider. example: nova-3 required: - provider tts_config: type: object description: '' properties: provider: type: string description: '' example: elevenlabs enum: - elevenlabs - cartesia - rime model: type: string description: >- The model name to use according to the tts_config.provider. example: 01h8xyz123abc456def789ghi voice_id: type: string description: >- This field is required when `tts_config.provider` is `elevenlabs` or `cartesia`. example: 01h8xyz123abc456def789ghi nullable: true speaker: type: string description: >- (Rime only) The speaker voice identifier to use for Rime TTS. Required when provider is `rime` instead of `voice_id`. This field is required when `tts_config.provider` is `rime`. example: 01h8xyz123abc456def789ghi nullable: true streaming_latency: type: integer description: >- (Elevenlabs only) Optimize for streaming latency, defaults to 0 - disabled. 4 for max latency optimizations. This field is required when `tts_config.provider` is `elevenlabs` or `rime`. Must be at least 0. Must not be greater than 4. example: 4 speed: type: string description: (Cartesia only) Voice control - Speed. example: normal enum: - fastest - fast - normal - slow - slowest nullable: true emotion: type: string description: (Cartesia only) Voice control - Emotion. example: positivity enum: - anger:lowest - anger:low - anger - anger:high - anger:highest - positivity:lowest - positivity:low - positivity - positivity:high - positivity:highest - surprise:lowest - surprise:low - surprise - surprise:high - surprise:highest - sadness:lowest - sadness:low - sadness - sadness:high - sadness:highest - curiosity:lowest - curiosity:low - curiosity - curiosity:high - curiosity:highest nullable: true speed_alpha: type: number description: >- (Rime only) Adjusts the speed of speech. Lower than `1.0` results in slower speech; higher than `1.0` results in faster speech. Must be at least 0. Must not be greater than 2. example: 1 nullable: true ambient_sound: type: string description: >- When turned on, the call includes background environment audio to enhance realism. example: office_ambience enum: - office_ambience - keyboard_typing - keyboard_typing2 nullable: true ambient_sound_volume: type: number description: Control the ambient sound volume. example: 4326.41688 nullable: true responsiveness: type: number description: >- Controls how responsive the agent is. Must be at least 0. Must not be greater than 1. example: 1 nullable: true interruption_sensitivity: type: number description: >- Controls how sensitive the agent is to interruptions. Must be at least 0. Must not be greater than 1. example: 1 nullable: true enable_backchannel: type: boolean description: >- Specifies whether the agent interjects with backchannel phrases (e.g., "yeah", "uh-huh") to show attentiveness. example: true nullable: true backchannel_frequency: type: number description: Frequency of backchannel responses. example: 0.8 nullable: true backchannel_words: type: array description: Must not be greater than 255 characters. example: - m items: type: string reminder_trigger_ms: type: integer description: >- How much time until the agent triggers a reminder. Must be at least 1000. Must not be greater than 60000. example: 10000 nullable: true required: - provider required: - name responses: '201': description: '' content: application/json: schema: type: object example: data: version: null numbers: [] id: 01kqh44e4g7ec2h7z372qvz92k name: My Agent status: draft call_config: max_call_duration_ms: 2108804 ring_duration_ms: 35396 llm_config: provider: mistral model: mistral-tiny knowledge_base_ids: [] tools: [] prompt_config: prompt: >- You are a helpful assistant for Acme Co. Greet the caller, identify their need, and assist them politely. first_speaker: ai ai_speak_after_silence: false ai_speak_wait_time: 4.1 welcome_message_type: dynamic welcome_message: null stt_config: model: universal-streaming-english provider: assemblyai tts_config: voice_id: 5601c8f4-9fee-3c15-b93d-e34b88b648fd streaming_latency: 3 speed_alpha: null provider: elevenlabs model: eleven_monolingual_v1 ambient_sound_volume: 1 responsiveness: 1 interruption_sensitivity: 1 enable_backchannel: true backchannel_frequency: 0.8 reminder_trigger_ms: 10000 workspace_id: 01kqh44e41j0whyxxxjhtvythz created_at: '2026-05-01T06:38:03+00:00' updated_at: '2026-05-01T06:38:03+00:00' published_at: null properties: data: type: object properties: version: type: string example: null nullable: true numbers: type: array example: [] id: type: string example: 01kqh44e4g7ec2h7z372qvz92k name: type: string example: My Agent status: type: string example: draft call_config: type: object properties: max_call_duration_ms: type: integer example: 2108804 ring_duration_ms: type: integer example: 35396 llm_config: type: object properties: provider: type: string example: mistral model: type: string example: mistral-tiny knowledge_base_ids: type: array example: [] tools: type: array example: [] prompt_config: type: object properties: prompt: type: string example: Example text. first_speaker: type: string example: ai ai_speak_after_silence: type: boolean example: false ai_speak_wait_time: type: number example: 4.1 welcome_message_type: type: string example: dynamic welcome_message: type: string example: null nullable: true stt_config: type: object properties: model: type: string example: universal-streaming-english provider: type: string example: assemblyai tts_config: type: object properties: voice_id: type: string example: 5601c8f4-9fee-3c15-b93d-e34b88b648fd streaming_latency: type: integer example: 3 speed_alpha: type: string example: null nullable: true provider: type: string example: elevenlabs model: type: string example: eleven_monolingual_v1 ambient_sound_volume: type: integer example: 1 responsiveness: type: integer example: 1 interruption_sensitivity: type: integer example: 1 enable_backchannel: type: boolean example: true backchannel_frequency: type: number example: 0.8 reminder_trigger_ms: type: integer example: 10000 workspace_id: type: string example: 01kqh44e41j0whyxxxjhtvythz created_at: type: string example: '2026-05-01T06:38:03+00:00' updated_at: type: string example: '2026-05-01T06:38:03+00:00' published_at: type: string example: null nullable: true components: securitySchemes: default: type: http scheme: bearer description: Bearer token authentication ````