# Drain a room

Source: https://docs.vlayers.ai/reference/hosting/drain-room

`POST /v1/rooms/{id}/drain` · scope `workspace:write`

Stops a room taking new work: calls it already holds finish, then the room ends. A replacement starts first when the version still needs the room, so a drain does not leave the agent without one. Draining a room that is already draining or over changes nothing and succeeds with `changed: false`.

Requires an API key with the `workspace:write` scope.

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | The room id. Example: `"room_0192f5d4-8b9c-7dae-8f3a-4b5c6d7e8f90"` |

## Request

cURL:

```bash
curl -X POST "https://api.vlayers.ai/v1/rooms/$ROOM_ID/drain" \
  -H "Authorization: Bearer $VOICELAYER_API_KEY"
```

TypeScript:

```ts
import { VoiceLayer } from '@voicelayer/api';

const voicelayer = new VoiceLayer();

const { room } = await voicelayer.hosting.drainRoom('<room-id>');
console.log(room.state);
```

Python:

```python
from voicelayer import VoiceLayer

vl = VoiceLayer()

result = vl.hosting.drain_room("<room-id>")
print(result.room.state)
```

## Response `200`

```json
{
  "room": {
    "id": "room_0192f5d4-8b9c-7dae-8f3a-4b5c6d7e8f90",
    "workspaceId": "0192f5a1-5e6f-7a7b-8c8d-9e0f1a2b3c45",
    "environment": "prd",
    "agentId": "0192f5c2-6f7a-7b9c-8d1e-2f3a4b5c6d78",
    "versionId": "0192f5d5-9cad-7ebf-9a4b-5c6d7e8f9012",
    "manifestHash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "imageDigest": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "replica": 0,
    "sizeClass": "small",
    "purpose": "warm",
    "state": "draining",
    "runtimeClass": "kata-clh-4-2",
    "shimVersion": "1.0.0",
    "replacementOf": null,
    "createdAt": "2026-10-20T15:04:05.000Z",
    "endedAt": null
  },
  "changed": true
}
```
