---
title: "Switch a BotInstance on or off (v2)"
method: POST
path: "/v2/bot-instances/{id}/status"
tags: ["Agents"]
---

# Switch a BotInstance on or off (v2)

`POST /v2/bot-instances/{id}/status`

## Request

- Base URL: `https://api.chat.ethora.com`
- URL: `https://api.chat.ethora.com/v2/bot-instances/{id}/status`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Sets the BotInstance's `status`. Allowed for the agent's owner,
whoever manages the bot's App (its creator, an admin with
`appSettings.update`, a B2B Server JWT for it) and
`isSuperAdmin.write`; anyone else gets 403. An `off` bot stays in its rooms but
does not answer. The AI service is told straight away (best-effort).
Supports `User JWT` and `B2B Server JWT`.

## Path parameters

- `id` string, required

## Request body

- object
  - `status` 'on' | 'off', required

## Response `200`

```
{ ok: true, botInstance: { id, agentId, appId, userId, xmppUsername, status, joinedRooms, lastActiveAt, createdAt, updatedAt } }
```

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: ``` { error: 'BotInstance not found', code: 'BOT_INSTANCE_NOT_FOUND' } ```
- `422`: ``` { error: string, code: 'VALIDATION_ERROR' } ```
- `500`: Internal Server Error

---

[API](https://skmtc.dev/ethora/apis/platform-api.md) · [All operations](https://skmtc.dev/ethora/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ethora/apis/platform-api/revisions/01b6e64378ee?raw)