List your rooms

GET
/v1/rooms

Lists the rooms your hosted agents run in: one per warm copy of a version, with its state (starting, ready, draining, and the ones that ended). Use it to see what is running, which version each room serves and why one is not ready. By default only rooms that are not over are listed; scope=all adds the ones that ended, were lost or failed in the last week.

Requires an API key with the workspace:read 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.

Query Parameters

agentId?string

Only the rooms of this agent.

Formatuuid
environment?string

Only the rooms of one environment: dev, stg or prd.

Value in"dev""stg""prd"
scope?string

live (the default) lists rooms that are not over; all adds the ended, lost and failed ones from the last week.

Default"live"
Value in"live""all"
limit?integer

How many items to return, 1–200. Default 100.

Range1 <= value <= 200
Default100

Response Body

The workspace's rooms and their states

application/json
  1. response
rooms*array<>
Example Request
curl "https://api.vlayers.ai/v1/rooms?scope=live&limit=20" \  -H "Authorization: Bearer $VOICELAYER_API_KEY"
Example Response
{  "rooms": [    {      "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": "ready",      "runtimeClass": "kata-clh-4-2",      "shimVersion": "1.0.0",      "replacementOf": null,      "createdAt": "2026-10-20T15:04:05.000Z",      "endedAt": null    }  ]}