> ## 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. # Set a number's agent > Points the number's one AI agent step at another agent. Only when it is unambiguous: the number plays an IVR menu with exactly one AI agent step that no other number shares. Otherwise `409 number_routing_complex` with `details.reason` (`no_menu`, `menu_without_ai_agent`, `menu_with_several_ai_agents`, `menu_shared`); change those in the dashboard's IVR builder. The agent must be on and answer calls (`inbound` or `both`). Scope: `agents:manage`. ## OpenAPI ````yaml /api-reference/openapi.json put /numbers/{id}/agent 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: /numbers/{id}/agent: put: tags: - Agents summary: Set a number's agent description: >- Points the number's one AI agent step at another agent. Only when it is unambiguous: the number plays an IVR menu with exactly one AI agent step that no other number shares. Otherwise `409 number_routing_complex` with `details.reason` (`no_menu`, `menu_without_ai_agent`, `menu_with_several_ai_agents`, `menu_shared`); change those in the dashboard's IVR builder. The agent must be on and answer calls (`inbound` or `both`). Scope: `agents:manage`. operationId: setNumberAgent parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentRef' example: agent_id: 17ea33d2-5b6c-4c1e-9a1f-2d4e6f8a9b0c responses: '200': description: The number with its new agent. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Number' '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 '404': description: No such number or agent in your account. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: number_not_found: value: error: code: number_not_found message: No number pn_9 in this account. request_id: req_8f2c1a7e agent_not_found: value: error: code: agent_not_found message: No agent 17ea… in this account. request_id: req_8f2c1a7e '409': description: The switch is not possible through the API. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: number_routing_complex: value: error: code: number_routing_complex message: >- This number's menu has 2 AI agent steps (one per menu option)… request_id: req_8f2c1a7e number_not_inbound_capable: value: error: code: number_not_inbound_capable message: >- Calls to this number are not answered by an AI agent on its provider (EXOTEL)… request_id: req_8f2c1a7e agent_disabled: value: error: code: agent_disabled message: Agent 17ea… is turned off. request_id: req_8f2c1a7e agent_outbound_only: value: error: code: agent_outbound_only message: Agent 17ea… only places calls… request_id: req_8f2c1a7e number_routing_changed: value: error: code: number_routing_changed message: The number's menu changed while this request ran… 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: AgentRef: type: object required: - agent_id properties: agent_id: type: string Number: type: object properties: id: type: string object: type: string const: number phone_number: type: string example: '+918045001234' label: type: - string - 'null' provider: type: string example: plivo description: Only Vacademy Voice (`plivo`) numbers answer with an AI agent. enabled: type: boolean agent: type: - object - 'null' properties: id: type: string object: type: string name: type: string enabled: type: boolean direction: type: string deleted: type: boolean description: The step points at an agent that no longer exists. routing: type: object properties: type: type: string enum: - ai_agent - menu_with_ai_agent - menu_with_several_ai_agents - menu_without_ai_agent - no_menu description: type: string menu_id: type: string menu_name: type: string ai_agent_steps: type: integer shared_with: type: array items: type: string description: Other numbers that play the same menu. agents: type: array items: type: - object - 'null' properties: id: type: string object: type: string name: type: string enabled: type: boolean direction: type: string deleted: type: boolean description: The step points at an agent that no longer exists. 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. 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.