Rooms

Rooms enable multi-agent voice conversations. Create a room, add characters as participants, and connect via WebRTC. Characters speak to each other and to your users in real time.

The Room object

{
  "id": "room_AbCdEfGh12345678",
  "createdAt": "2026-04-20T12:00:00Z",
  "projectId": "project_abc123",
  "name": "Town Square",
  "mode": "freeform",
  "scenePrompt": null,
  "endedAt": null,
  "participants": []
}

Field	Type	Description
id	string	Unique identifier
name	string	Room name
mode	string	"freeform" or "scripted"
scenePrompt	string | null	Scene description for scripted mode (max 5000 chars)
endedAt	string | null	When the room ended, or null if active
participants	array	Characters in the room

The Participant object

{
  "id": "participant_abc123",
  "createdAt": "2026-04-20T12:00:01Z",
  "roomId": "room_AbCdEfGh12345678",
  "characterId": "character_PuTlWmWuynYZu8sP",
  "conversationId": "conv_xyz789",
  "livekitIdentity": "agent-character_PuTlWmWuynYZu8sP",
  "leftAt": null
}

Create a room

POST /v1/rooms

Request body

Field	Type	Required	Default	Description
name	string	Yes	—	Room name (max 200 chars)
mode	string	No	"freeform"	"freeform" or "scripted"
scenePrompt	string	No	—	Scene description for scripted mode

curl

curl -X POST https://api.mindforge.ai/v1/rooms \
  -H "Authorization: Bearer $MINDFORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Town Square",
    "mode": "freeform"
  }'

List rooms

GET /v1/rooms

Returns active rooms with their participants.

Get a room

GET /v1/rooms/{roomId}

Add a participant

POST /v1/rooms/{roomId}/participants

Field	Type	Required	Description
characterId	string	Yes	Character to add to the room

curl -X POST https://api.mindforge.ai/v1/rooms/room_AbCdEfGh12345678/participants \
  -H "Authorization: Bearer $MINDFORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "characterId": "character_PuTlWmWuynYZu8sP" }'

Remove a participant

DELETE /v1/rooms/{roomId}/participants/{characterId}

Get room transcript

GET /v1/rooms/{roomId}/transcript

Returns all messages spoken in the room.

[
  {
    "id": "entry_abc123",
    "createdAt": "2026-04-20T12:01:00Z",
    "roomId": "room_AbCdEfGh12345678",
    "speakerType": "agent",
    "characterId": "character_PuTlWmWuynYZu8sP",
    "content": "Welcome to the town square!"
  }
]

Field	Type	Description
speakerType	string	"user" or "agent"
characterId	string | null	Character ID (null for user messages)
content	string	What was said

Get a join token

GET /v1/rooms/{roomId}/token

Returns a LiveKit token for connecting to the room via WebRTC.

{
  "token": "eyJ...",
  "url": "wss://livekit.example.com"
}

Start the room

POST /v1/rooms/{roomId}/start

Starts the voice agent pipelines for all participants. The room must have at least one participant.

{ "started": true }