> ## Documentation Index > Fetch the complete documentation index at: https://docs.telleo.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create an agent > Creates an AI agent. Every value is checked: an unknown engine, voice or language is refused with the valid options instead of being replaced. Scope: `agents:manage`. ## OpenAPI ````yaml /api-reference/openapi.json post /agents openapi: 3.1.0 info: title: Telleo API version: 1.3.0 description: >- Start AI phone calls, or connect your counsellors to contacts, from your own systems and get each call's outcome back. Manage your counsellors and AI agents from the same API. servers: - url: https://api.telleo.ai/v1 security: - ApiKey: [] tags: - name: Calls - name: Batches - name: Agents - name: Human calls - name: Counsellors - name: Credits - name: Webhook paths: /agents: post: tags: - Agents summary: Create an agent description: >- Creates an AI agent. Every value is checked: an unknown engine, voice or language is refused with the valid options instead of being replaced. Scope: `agents:manage`. operationId: createAgent parameters: - name: Idempotency-Key in: header required: false schema: type: string maxLength: 255 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAgent' example: name: Riya – admissions language: hinglish tts_model: google voice: hi-IN-Chirp3-HD-Kore opening_line: >- Hi {{name}}, this is Riya from Shiksha Academy. Is this a good time? system_prompt: You are Riya, an admissions counsellor… responses: '200': description: Replay of this `Idempotency-Key`. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/AgentDetail' '201': description: The agent was created. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/AgentDetail' example: id: 17ea33d2-5b6c-4c1e-9a1f-2d4e6f8a9b0c object: agent name: Riya – admissions enabled: true direction: outbound is_default: true language: hinglish tts_model: google voice: hi-IN-Chirp3-HD-Kore opening_line: >- Hi {{name}}, this is Riya from Shiksha Academy. Is this a good time? system_prompt: You are Riya, an admissions counsellor at Shiksha Academy… extraction_questions: - Which course are you interested in? dispositions: [] handoff_numbers: - '+919800000001' max_call_minutes: 8 pace: null temperature: null voice_modulation: null speech_cache_mode: 'off' booking_page_id: null send_rules: [] uses_contact_name: true variables: - course created_at: '2026-10-13T09:00:00Z' updated_at: '2026-10-19T10:15:00Z' '400': description: The request is not valid. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: error: code: invalid_request message: system_prompt is required. request_id: req_8f2c1a7e '401': description: The key is missing, unknown, revoked or expired. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: missing_api_key: value: error: code: missing_api_key message: Send your API key in the X-API-Key header. request_id: req_8f2c1a7e invalid_api_key: value: error: code: invalid_api_key message: This API key is not valid. request_id: req_8f2c1a7e '403': description: >- The key lacks the agents:manage scope. Keys only have it when created with it. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: insufficient_scope: value: error: code: insufficient_scope message: This API key does not have the agents:manage scope. request_id: req_8f2c1a7e '409': description: The name is taken. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: agent_name_taken: value: error: code: agent_name_taken message: >- An agent named Riya already exists in this account (names are unique, ignoring case). request_id: req_8f2c1a7e idempotency_key_reused: value: error: code: idempotency_key_reused message: >- This Idempotency-Key was already used for a different request. request_id: req_8f2c1a7e '422': description: A value is not one the platform supports. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_voice: value: error: code: invalid_voice message: >- Voice priya is not a google voice. Pick one of valid_voices (GET /v1/voices). request_id: req_8f2c1a7e unsupported_tts_model: value: error: code: unsupported_tts_model message: >- tts_model must be one of the engines listed by GET /v1/voices. request_id: req_8f2c1a7e unsupported_language: value: error: code: unsupported_language message: language klingon is not supported. request_id: req_8f2c1a7e voice_language_mismatch: value: error: code: voice_language_mismatch message: The deepgram engine speaks English only… request_id: req_8f2c1a7e booking_page_not_found: value: error: code: booking_page_not_found message: No booking page bp-9 in this account (booking_page_id). request_id: req_8f2c1a7e invalid_agent: value: error: code: invalid_agent message: >- Action rule "Brochure": choose an approved WhatsApp template… request_id: req_8f2c1a7e '429': description: Too many requests for this key. headers: Retry-After: schema: type: integer description: Seconds to wait before retrying. X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: rate_limited: value: error: code: rate_limited message: Too many requests. Retry after 12 seconds. request_id: req_8f2c1a7e components: schemas: CreateAgent: type: object required: - name - system_prompt - opening_line properties: name: type: string maxLength: 128 description: Unique in your account, ignoring case. enabled: type: boolean default: true direction: type: string enum: - outbound - inbound - both default: outbound description: >- `outbound` places calls, `inbound` answers your numbers, `both` does both. language: type: - string - 'null' description: >- hinglish, hindi, english, punjabi, marathi, gujarati, bengali, tamil, telugu, kannada, malayalam, odia, a code (`hi`) or a tag (`hi-IN`). `null` = Hindi or Hinglish. example: hinglish tts_model: type: string description: >- Voice engine id from `GET /voices`. Default for a new agent: `google`. voice: type: string description: >- A voice of `tts_model` (`GET /voices`). Changing `tts_model` needs a voice of the new engine. opening_line: type: string maxLength: 2000 description: >- The first thing the agent says. `{{placeholders}}` are filled per call. system_prompt: type: string maxLength: 60000 description: The agent's script and instructions. extraction_questions: type: array maxItems: 50 items: type: string maxLength: 500 description: Questions whose answers come back in `outcome.answers`. dispositions: type: array maxItems: 50 items: type: string maxLength: 64 description: Labels the agent may give a call. Empty = your account's defaults. handoff_numbers: type: array maxItems: 10 items: type: string description: E.164 numbers the agent can transfer a caller to. max_call_minutes: type: - integer - 'null' minimum: 1 maximum: 30 description: '`null` = 10 minutes.' pace: type: - number - 'null' minimum: 0.5 maximum: 2 description: Speaking rate; `null` = default. temperature: type: - number - 'null' minimum: 0.01 maximum: 2 description: Voice expressiveness; `null` = engine default. voice_modulation: type: - number - 'null' minimum: 1 maximum: 2.5 description: Pitch-range expansion; `null` = off. booking_page_id: type: - string - 'null' description: A booking page of your account the agent books on. send_rules: type: array items: type: object additionalProperties: true description: >- A post-call or mid-call action (send a WhatsApp template or an email, or book a meeting) and when it fires. Same rules as the dashboard's agent editor, snake_case (`action_type`, `message_body`, `booking_page_id`, `when.meeting_requested` …). Not used on API calls. AgentDetail: type: object properties: id: type: string object: type: string const: agent name: type: string maxLength: 128 description: Unique in your account, ignoring case. enabled: type: boolean default: true direction: type: string enum: - outbound - inbound - both default: outbound description: >- `outbound` places calls, `inbound` answers your numbers, `both` does both. language: type: - string - 'null' description: >- hinglish, hindi, english, punjabi, marathi, gujarati, bengali, tamil, telugu, kannada, malayalam, odia, a code (`hi`) or a tag (`hi-IN`). `null` = Hindi or Hinglish. example: hinglish tts_model: type: string description: >- Voice engine id from `GET /voices`. Default for a new agent: `google`. voice: type: string description: >- A voice of `tts_model` (`GET /voices`). Changing `tts_model` needs a voice of the new engine. opening_line: type: string maxLength: 2000 description: >- The first thing the agent says. `{{placeholders}}` are filled per call. system_prompt: type: string maxLength: 60000 description: The agent's script and instructions. extraction_questions: type: array maxItems: 50 items: type: string maxLength: 500 description: Questions whose answers come back in `outcome.answers`. dispositions: type: array maxItems: 50 items: type: string maxLength: 64 description: Labels the agent may give a call. Empty = your account's defaults. handoff_numbers: type: array maxItems: 10 items: type: string description: E.164 numbers the agent can transfer a caller to. max_call_minutes: type: - integer - 'null' minimum: 1 maximum: 30 description: '`null` = 10 minutes.' pace: type: - number - 'null' minimum: 0.5 maximum: 2 description: Speaking rate; `null` = default. temperature: type: - number - 'null' minimum: 0.01 maximum: 2 description: Voice expressiveness; `null` = engine default. voice_modulation: type: - number - 'null' minimum: 1 maximum: 2.5 description: Pitch-range expansion; `null` = off. booking_page_id: type: - string - 'null' description: A booking page of your account the agent books on. send_rules: type: array items: type: object additionalProperties: true description: >- A post-call or mid-call action (send a WhatsApp template or an email, or book a meeting) and when it fires. Same rules as the dashboard's agent editor, snake_case (`action_type`, `message_body`, `booking_page_id`, `when.meeting_requested` …). Not used on API calls. is_default: type: boolean description: >- This is your account's default agent (`GET /settings/default-agent`). speech_cache_mode: type: string enum: - 'off' - fixed - full description: Read-only; set by support. configuration: type: string enum: - full - summary description: >- `summary` for a key without `agents:manage`: `system_prompt`, `handoff_numbers`, `send_rules` and `booking_page_id` are left out. uses_contact_name: type: boolean variables: type: array items: type: string created_at: type: - string - 'null' format: date-time updated_at: type: - string - 'null' format: date-time waiting_calls_canceled: type: integer description: >- On disable (and a PATCH of `enabled`): calls that were waiting for this agent and were canceled. warnings: type: array items: $ref: '#/components/schemas/Warning' description: >- Non-fatal notes about what was (not) done, e.g. `mobile_number_missing`. idempotent_replay: type: boolean Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: Machine-readable code. Branch on this, not on the message. example: invalid_request message: type: string description: A sentence you can log or show to an operator. request_id: type: string description: Quote this when you contact support. details: type: object additionalProperties: true description: >- Extra context, e.g. `errors: [{field, message}]` for validation errors or `call_id` for conflicts. Warning: type: object description: >- Something in the request that was accepted but may not do what you expect. properties: field: type: string example: variables.date code: type: string enum: - reserved_variable message: type: string example: >- {{date}} in the agent's script is always filled with the current date and time; this value does not replace it. The agent receives it only as information about the contact. headers: RequestId: schema: type: string description: Unique id of this request. Quote it to support. securitySchemes: ApiKey: type: apiKey in: header name: X-API-Key description: >- Your AI calling API key (`vak_call_…`). `Authorization: Bearer ` also works. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.