Drain a room

POST
/v1/rooms/{id}/drain

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.

Authorization

apiKey
headerAuthorizationBearer <token>

A secret API key from the dashboard (Developers → API keys): vl_live_…, or vl_test_… for test mode. Each operation says which scope the key needs.

Path Parameters

id*string

The room id.

Response Body

The room, and whether this call changed it

application/json
  1. response
room*
changed*boolean
Example Request
curl -X POST "https://api.vlayers.ai/v1/rooms/$ROOM_ID/drain" \  -H "Authorization: Bearer $VOICELAYER_API_KEY"
Example Response
{  "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}