> ## Documentation Index > Fetch the complete documentation index at: https://docs.vocily.ai/llms.txt > Use this file to discover all available pages before exploring further. # Take an agent off air > Stop an agent answering, without deleting it. The reverse of [make live](/developers/agents/make-live), and gated the same way, because it is just as visible to callers: the agent stops answering and releases the numbers it was answering on. Nothing is deleted. Every version survives, and making one live again brings the agent straight back. ## OpenAPI ````yaml developers/openapi.json DELETE /v1/agents/{agent_id}/live openapi: 3.1.0 info: title: Vocily API description: >- Public REST API for Vocily. Build and configure an agent, publish a version and put it live, place outbound calls, and read back calls, chats and what the agent remembered. Authenticate with a workspace API key as a Bearer token. Some things stay in the dashboard, by design: creating an API key, buying or connecting a phone number, setting an agent's webhook URL, connecting WhatsApp and its templates, building HTTP tools, and running batch campaigns. version: v1 servers: - url: https://api.vocily.ai description: Production security: [] paths: /v1/agents/{agent_id}/live: delete: tags: - agent-versions summary: Take Agent Off Air description: >- Stop this agent answering, and release the numbers it answered on. Afterwards inbound calls and WhatsApp no longer reach it, new outbound calls and batches are refused, and its numbers are free for another agent to claim. Returns the version it was taken off, so you can name it. operationId: take_agent_off_air_v1_agents__agent_id__live_delete parameters: - name: agent_id in: path required: true schema: type: string title: Agent Id description: The agent's id, as `GET /v1/agents` returns it. responses: '200': description: >- The version the agent was taken off. It still exists — nothing is deleted. content: application/json: schema: $ref: '#/components/schemas/PublicVersionSummary' example: version: 0 version_id: 00000006-0000-4000-8000-000000000006 is_published: true is_live: false label: Renamed notes: null base_version: null document_revision: 2 blocked_reasons: [] inbound_phone: null inbound_whatsapp: null created_at: '2026-09-16T19:38:03.767024Z' published_at: '2026-09-16T19:38:03.999783Z' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: detail: Invalid API key code: UNAUTHORIZED '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: Rate limit exceeded — honor `Retry-After`. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: code: rate_limited security: - bearerAuth: [] components: schemas: PublicVersionSummary: additionalProperties: false description: >- One version in an agent's history. Versions are identified by NUMBER: it is what every version read returns and what `?version=` and `/versions/{n}` take. properties: version: description: This version's number — what you pass in `/versions/{n}`. title: Version type: integer version_id: description: >- This version's uuid. Published because `POST /v1/calls` pins a call with `agent_version_id`, which takes a uuid rather than a number. title: Version Id type: string is_published: description: >- True once frozen. Configuration can never be edited again; `label` and `notes` still can. title: Is Published type: boolean is_live: description: True if this is the version answering calls right now. title: Is Live type: boolean label: anyOf: - type: string - type: 'null' default: null description: Short name for this version. title: Label notes: anyOf: - type: string - type: 'null' default: null description: Longer free text about this version. title: Notes base_version: anyOf: - type: integer - type: 'null' default: null description: >- Which version this one was branched from, by NUMBER — `null` for the agent's first. title: Base Version document_revision: description: >- This version's edit counter. Send it as `If-Match` to make a write conditional. title: Document Revision type: integer blocked_reasons: description: >- Why this version cannot be made live, if it cannot — e.g. it pins a retired model. Check it before offering a deploy button, so the button never fails on click. items: type: string title: Blocked Reasons type: array inbound_phone: anyOf: - type: string - type: 'null' default: null description: >- The phone number this version will answer on once it is made live. Inert until then. title: Inbound Phone inbound_whatsapp: anyOf: - type: string - type: 'null' default: null description: >- The WhatsApp number this version will answer on once it is made live. Inert until then. title: Inbound Whatsapp created_at: description: When this version was created (UTC, ISO 8601). format: date-time title: Created At type: string published_at: anyOf: - type: string format: date-time - type: 'null' default: null description: When it was frozen. `null` while it is still a draft. title: Published At required: - version - version_id - is_published - is_live - document_revision - created_at title: PublicVersionSummary type: object ApiError: type: object description: >- Error envelope. `code` is derived from the HTTP status, so branch on it for the CLASS of failure; the specific reason is `detail.code`. Every public refusal carries both. properties: detail: type: object description: >- The reason. `code` is the domain reason (e.g. `call_not_found`) and `message` is a sentence safe to log. On a `422` it also carries `errors[]`, one entry per rejected field — see `HTTPValidationError`. properties: code: type: string example: call_not_found message: type: string example: Call not found required: - code - message code: type: string description: Derived from the HTTP status, not the domain reason. example: NOT_FOUND HTTPValidationError: type: object title: HTTPValidationError description: >- A request the API could not read: a field of the wrong type, out of range, missing, or one we do not accept. Same envelope as every other error. properties: detail: type: object description: >- What was wrong, as `code`, a one-line `message`, and every offending field in `errors`. required: - code - message - errors properties: code: type: string enum: - validation_error message: type: string description: >- The first problem in one line, with a count of the rest — e.g. `model.temperature: Input should be less than or equal to 2 (and 1 more)`. errors: type: array items: $ref: '#/components/schemas/ValidationError' description: >- One entry per offending field. **Every problem is reported at once**, not just the first, so a malformed body needs one round trip to fix rather than one per field. code: type: string enum: - VALIDATION_ERROR description: Derived from the HTTP status, as on every error. ValidationError: type: object title: ValidationError required: - field - message - type properties: field: type: string description: >- The offending field as a path from the root of your request — `voice.speed`, `variables[0].key`, or `query.limit` for a query parameter. **This is the field to read.** message: type: string description: What is wrong with it, in plain language. type: type: string description: >- A stable machine code for the kind of failure, e.g. `extra_forbidden` for a field we do not accept, `missing` for a required one, or `less_than_equal` for a number out of range. Switch on this rather than on `message`, which may be reworded. securitySchemes: bearerAuth: type: http scheme: bearer description: 'Your API key as a Bearer token, e.g. `Authorization: Bearer vk_…`.' ````