> ## 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. # Turn off an agent > Turns the agent off and cancels every call still waiting for it, from any source (API, workflows, bulk, manual), with a reason on each; `waiting_calls_canceled` says how many. Warnings flag when it is the default agent or answers an inbound number. Scope: `agents:manage`. ## OpenAPI ````yaml /api-reference/openapi.json post /agents/{id}/disable 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/{id}/disable: post: tags: - Agents summary: Turn off an agent description: >- Turns the agent off and cancels every call still waiting for it, from any source (API, workflows, bulk, manual), with a reason on each; `waiting_calls_canceled` says how many. Warnings flag when it is the default agent or answers an inbound number. Scope: `agents:manage`. operationId: disableAgent parameters: - name: id in: path required: true schema: type: string responses: '200': description: The agent. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/AgentDetail' '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 agent with this id in your account. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: agent_not_found: value: error: code: agent_not_found message: >- No agent 17ea… in this account. List your agents with GET /v1/agents. 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: headers: RequestId: schema: type: string description: Unique id of this request. Quote it to support. schemas: 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. 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.