> ## Documentation Index > Fetch the complete documentation index at: https://docs.kejue.co/llms.txt > Use this file to discover all available pages before exploring further. # Create Voice Config > Add a voice configuration to an agent. ## OpenAPI ````yaml /openapi.json post /agents/{agent_id}/voice-configs openapi: 3.1.0 info: title: Kejue Public API description: >- The Kejue Public API lets you programmatically create calls, manage campaigns, and retrieve call results. ## Authentication All requests require an API key passed in the `X-API-Key` header: ``` X-API-Key: kej_live_... ``` API keys are scoped to a workspace. Create and manage keys from the Kejue dashboard under **Settings → API Keys**. ## Base URL ``` https://api.kejue.co/api/v1 ``` ## Rate Limits API requests are rate-limited per workspace. If you exceed the limit you'll receive a `429 Too Many Requests` response. ## Errors All error responses follow a consistent format: ```json { "error": "Human-readable message", "code": "ERROR_CODE", "details": {} } ``` version: 1.0.0 servers: - url: https://api.kejue.co/api/v1 description: Production security: - ApiKeyAuth: [] tags: - name: Agents description: >- Create and manage AI agents (personas). Each agent has a name, prompt, voice configuration, and optional tools. Agents are the core building block — attach voice configs, tools, and use them to make calls. - name: Calls description: >- Create outbound calls, retrieve call details and transcripts, and list calls with filtering. Each call is associated with a contact and optionally an agent and campaign. - name: Persona Calls description: >- Create calls with the full agent configuration pre-loaded. Applies the complete settings hierarchy (workspace → agent → campaign → overrides) with all agent tools, tags, scoring, and webhooks inherited automatically. - name: Contacts description: >- Create and manage contacts. Contacts represent the people your agents call. Each contact has a phone number, name, and optional metadata. Supports single creation, bulk import, and CSV upload. - name: Campaigns description: >- Create and manage calling campaigns. Campaigns let you batch-call a list of contacts with shared settings, scheduling, and retry logic. - name: Tools description: >- Create and manage custom HTTP tools that agents can invoke during calls. Tools let agents fetch data, trigger actions, or integrate with external systems mid-conversation. Each tool supports three parameter types: - **Dynamic parameters** — filled by the AI at runtime (visible to the AI) - **Static parameters** — fixed values sent with every invocation (hidden from the AI) - **System parameters** — values injected from the execution context at runtime, such as `call_id`, `contact_id`, or `workspace_id` (hidden from the AI) - name: Voices description: List available voices for use in agent voice configurations. - name: Phone Numbers description: List phone numbers available in your workspace for making outbound calls. - name: Webhooks description: >- Create and manage webhook subscriptions. Receive real-time notifications for call events (started, ended, etc.) at your specified URL. - name: Models description: List available AI models for use in agent voice configurations. paths: /agents/{agent_id}/voice-configs: post: tags: - Agents summary: Create Voice Config description: Add a voice configuration to an agent. operationId: create_voice_config_agents__agent_id__voice_configs_post parameters: - name: agent_id in: path required: true schema: type: string title: Agent Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VoiceConfigInput' responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/VoiceConfigResponse' '401': description: >- Missing or invalid API key. Pass a workspace API key in the `X-API-Key` header. content: application/json: example: error: Invalid or missing API key code: UNAUTHORIZED details: {} schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Agent not found in this workspace. content: application/json: example: error: Agent not found code: NOT_FOUND details: agent_id: non_existent_id schema: $ref: '#/components/schemas/ErrorResponse' '409': description: A voice config for this language locale already exists on the agent. content: application/json: example: error: Voice config for locale 'en-US' already exists code: CONFLICT details: {} schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Request body or query parameters failed validation. content: application/json: example: error: Validation failed code: VALIDATION_ERROR details: errors: - field: body.name message: Field required type: missing schema: $ref: '#/components/schemas/ErrorResponse' security: - ApiKeyAuth: [] components: schemas: VoiceConfigInput: properties: language_locale: type: string title: Language Locale description: BCP-47 locale, e.g. 'en-US', 'ar-AE' name: type: string title: Name description: Agent display name for this locale prompt: type: string title: Prompt description: System prompt / instructions for the agent first_speaker: $ref: '#/components/schemas/FirstSpeaker' description: Who speaks first default: agent first_message: anyOf: - type: string - type: 'null' title: First Message description: Agent's opening message first_message_uninterruptible: type: boolean title: First Message Uninterruptible description: Prevent user from interrupting the first message default: false first_message_delay_ms: anyOf: - type: integer minimum: 0 - type: 'null' title: First Message Delay Ms description: Delay before first message in ms voice_id: anyOf: - type: string - type: 'null' title: Voice Id description: Voice ID (from GET /voices) model: anyOf: - $ref: '#/components/schemas/Model' - type: 'null' description: Voice AI model override temperature: anyOf: - type: number maximum: 2 minimum: 0 - type: 'null' title: Temperature description: Model temperature recording_enabled: type: boolean title: Recording Enabled description: Record the call default: true inactivity_messages: anyOf: - items: $ref: '#/components/schemas/InactivityMessage' type: array - type: 'null' title: Inactivity Messages description: Messages the agent sends after periods of user silence silence_timeout: anyOf: - type: integer maximum: 120 minimum: 5 - type: 'null' title: Silence Timeout description: Silence timeout in seconds max_duration: anyOf: - type: integer maximum: 7200 minimum: 30 - type: 'null' title: Max Duration description: Max call duration in seconds is_default: type: boolean title: Is Default description: Set as the default voice config for this agent default: false config: anyOf: - additionalProperties: true type: object - type: 'null' title: Config exclude_from_public: true type: object required: - language_locale - name - prompt title: VoiceConfigInput description: Voice configuration for an agent. VoiceConfigResponse: properties: id: type: string title: Id name: type: string title: Name language_locale: type: string title: Language Locale prompt: type: string title: Prompt first_speaker: type: string title: First Speaker first_message: anyOf: - type: string - type: 'null' title: First Message first_message_uninterruptible: type: boolean title: First Message Uninterruptible default: false first_message_delay_ms: anyOf: - type: integer - type: 'null' title: First Message Delay Ms voice_id: anyOf: - type: string - type: 'null' title: Voice Id voice_name: anyOf: - type: string - type: 'null' title: Voice Name model: anyOf: - type: string - type: 'null' title: Model temperature: anyOf: - type: number - type: 'null' title: Temperature recording_enabled: type: boolean title: Recording Enabled inactivity_messages: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' title: Inactivity Messages silence_timeout: type: integer title: Silence Timeout max_duration: type: integer title: Max Duration corpus_id: anyOf: - type: string - type: 'null' title: Corpus Id is_default: type: boolean title: Is Default is_active: type: boolean title: Is Active created_at: anyOf: - type: string - type: 'null' title: Created At updated_at: anyOf: - type: string - type: 'null' title: Updated At type: object required: - id - name - language_locale - prompt - first_speaker - recording_enabled - silence_timeout - max_duration - is_default - is_active title: VoiceConfigResponse description: Voice configuration in API responses (public-safe). ErrorResponse: properties: error: type: string title: Error code: type: string title: Code details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details type: object required: - error - code title: ErrorResponse description: Standard error response. example: code: NOT_FOUND details: contact_id: '123' error: Contact not found FirstSpeaker: type: string enum: - agent - user title: FirstSpeaker description: Who speaks first in the call. Model: type: string enum: - KJUE-v0 - KJUE-v0-mini - KJUE-v0-large - KJUE-v1.0 title: Model description: Available voice AI models. InactivityMessage: properties: message: type: string title: Message description: Text the agent will speak after the delay delay_seconds: type: integer maximum: 120 minimum: 1 title: Delay Seconds description: Seconds of silence before sending this message end_behavior: anyOf: - type: string - type: 'null' title: End Behavior description: >- What to do after speaking this message. One of END_BEHAVIOR_UNSPECIFIED, END_BEHAVIOR_HANG_UP_SOFT, END_BEHAVIOR_HANG_UP_STRICT. Maps to Ultravox endBehavior. type: object required: - message - delay_seconds title: InactivityMessage description: A message the agent sends after a period of silence from the user. example: delay_seconds: 15 end_behavior: END_BEHAVIOR_UNSPECIFIED message: Are you still there? securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: Workspace API key (e.g. `kej_live_...`) ````