HTTP endpoints
HTTP: rooms
All 34 rooms endpoints, with request fields and access notes.
On this page
- GET /v1/rooms
- POST /v1/rooms
- DELETE /v1/rooms/{id}
- GET /v1/rooms/{id}
- PATCH /v1/rooms/{id}
- GET /v1/rooms/{id}/activity
- GET /v1/rooms/{id}/agent-control
- POST /v1/rooms/{id}/agent-control
- GET /v1/rooms/{id}/agent-memberships
- POST /v1/rooms/{id}/agent-memberships
- DELETE /v1/rooms/{id}/agent-memberships/{membership_id}
- PATCH /v1/rooms/{id}/agent-memberships/{membership_id}
- POST /v1/rooms/{id}/agent-memberships/{membership_id}/writer-transfer
- GET /v1/rooms/{id}/agent-routes
- POST /v1/rooms/{id}/agents
- PATCH /v1/rooms/{id}/agents/{membership_id}/source
- POST /v1/rooms/{id}/done-when
- GET /v1/rooms/{id}/events
- POST /v1/rooms/{id}/friction-digest
- GET /v1/rooms/{id}/preview-targets
- POST /v1/rooms/{id}/preview-targets
- DELETE /v1/rooms/{id}/preview-targets/{name}
- POST /v1/rooms/{id}/preview-targets/{name}
- GET /v1/rooms/{id}/preview-targets/{name}/logs
- PATCH /v1/rooms/{id}/state
- POST /v1/rooms/{id}/state/override
- GET /v1/rooms/{id}/status
- GET /v1/rooms/{id}/workspace/files
- GET /v1/rooms/{id}/workspaces
- POST /v1/rooms/{id}/workspaces
- DELETE /v1/rooms/{id}/workspaces/{agent_id}
- GET /v1/rooms/{id}/workspaces/{agent_id}
- GET /v1/rooms/{id}/workspaces/{agent_id}/diff
- GET /v2/rooms/{id}/events
HTTP directory · Transport guide
Request fields and access notes below are partial. Additional constraints and permissions may apply. Prefer the corresponding MCP tool and schema where available.
GET /v1/rooms
List rooms.
Query field names (types and requiredness not specified here): include_archived, project_id.
POST /v1/rooms
Create room.
Access: LAN writes require an active session token. Local loopback requests are exempt from this requirement by default; other permissions still apply.
Request body fields (partial)
| Field | Type | Required | Constraints |
|---|---|---|---|
project_id | string | yes | See operation notes. |
name | string | yes | See operation notes. |
topic | string | no | See operation notes. |
purpose | string | no | See operation notes. |
roles | array | no | See operation notes. |
metadata | object | no | See operation notes. |
force | boolean | no | See operation notes. |
force_reason | string | no | See operation notes. |
Other constraints may apply, including for fields marked optional.
DELETE /v1/rooms/{id}
Delete room.
Path parameters: id.
Access: This action may require confirmation. Follow the confirmation details returned for your request. LAN writes require an active session token. Local loopback requests are exempt from this requirement by default; other permissions still apply.
This directory does not provide a request schema for this endpoint. Use the corresponding supported tool or client where available.
GET /v1/rooms/{id}
Get room.
Path parameters: id.
This directory does not provide a request schema for this endpoint. Use the corresponding supported tool or client where available.
PATCH /v1/rooms/{id}
Patch room.
Path parameters: id.
Access: LAN writes require an active session token. Local loopback requests are exempt from this requirement by default; other permissions still apply.
Request body fields (partial)
| Field | Type | Required | Constraints |
|---|---|---|---|
name | string | no | See operation notes. |
topic | string | no | See operation notes. |
purpose | string | no | See operation notes. |
roles | array | no | See operation notes. |
archived | boolean | no | See operation notes. |
metadata | object | no | See operation notes. |
replacement_room_id | string | no | See operation notes. |
Other constraints may apply, including for fields marked optional.
GET /v1/rooms/{id}/activity
Read the operator-only merged room activity record, including third-party direct messages.
Path parameters: id.
Access: Requires an authenticated operator credential or session; an agent_id alone is insufficient.
Query field names (types and requiredness not specified here): before, lanes, limit.
GET /v1/rooms/{id}/agent-control
Read room agent control.
Path parameters: id.
This directory does not provide a request schema for this endpoint. Use the corresponding supported tool or client where available.
POST /v1/rooms/{id}/agent-control
Set room agent control.
Path parameters: id.
Access: LAN writes require an active session token. Local loopback requests are exempt from this requirement by default; other permissions still apply.
This directory does not provide a request schema for this endpoint. Use the corresponding supported tool or client where available.
GET /v1/rooms/{id}/agent-memberships
Read room agent memberships.
Path parameters: id.
Query field names (types and requiredness not specified here): all_rooms, include_disabled.
POST /v1/rooms/{id}/agent-memberships
Create room agent membership.
Path parameters: id.
Access: LAN writes require an active session token. Local loopback requests are exempt from this requirement by default; other permissions still apply. Managed-seat operations require authority for the targeted seat.
This directory does not provide a request schema for this endpoint. Use the corresponding supported tool or client where available.
DELETE /v1/rooms/{id}/agent-memberships/{membership_id}
Disable room agent membership.
Path parameters: id, membership_id.
Access: LAN writes require an active session token. Local loopback requests are exempt from this requirement by default; other permissions still apply. Managed-seat operations require authority for the targeted seat.
This directory does not provide a request schema for this endpoint. Use the corresponding supported tool or client where available.
PATCH /v1/rooms/{id}/agent-memberships/{membership_id}
Patch room agent membership.
Path parameters: id, membership_id.
Access: LAN writes require an active session token. Local loopback requests are exempt from this requirement by default; other permissions still apply. Managed-seat operations require authority for the targeted seat.
This directory does not provide a request schema for this endpoint. Use the corresponding supported tool or client where available.
POST /v1/rooms/{id}/agent-memberships/{membership_id}/writer-transfer
Transfer room agent writer.
Path parameters: id, membership_id.
Access: LAN writes require an active session token. Local loopback requests are exempt from this requirement by default; other permissions still apply. Managed-seat operations require authority for the targeted seat.
This directory does not provide a request schema for this endpoint. Use the corresponding supported tool or client where available.
GET /v1/rooms/{id}/agent-routes
Read recent room agent routes.
Path parameters: id.
Query field names (types and requiredness not specified here): limit.
POST /v1/rooms/{id}/agents
Add room agents from source.
Path parameters: id.
Access: LAN writes require an active session token. Local loopback requests are exempt from this requirement by default; other permissions still apply.
This directory does not provide a request schema for this endpoint. Use the corresponding supported tool or client where available.
PATCH /v1/rooms/{id}/agents/{membership_id}/source
Change room agent source.
Path parameters: id, membership_id.
Access: LAN writes require an active session token. Local loopback requests are exempt from this requirement by default; other permissions still apply.
This directory does not provide a request schema for this endpoint. Use the corresponding supported tool or client where available.
POST /v1/rooms/{id}/done-when
Room done when.
Path parameters: id.
Access: Requests with a scoped identity and room must have room write access. Additional permissions may apply. LAN writes require an active session token. Local loopback requests are exempt from this requirement by default; other permissions still apply.
Request body fields (partial)
| Field | Type | Required | Constraints |
|---|---|---|---|
clauses | array | no | See operation notes. |
membership_id | string | no | See operation notes. |
inherit | boolean | no | See operation notes. |
expected_version | integer | yes | See operation notes. |
by_agent_id | string | no | See operation notes. |
session_id | string | no | See operation notes. |
Other constraints may apply, including for fields marked optional.
Additional body field names (types and requiredness not specified here): room_id.
GET /v1/rooms/{id}/events
Long-poll the v1 room coordination-event feed using a since_id cursor.
Path parameters: id.
Access: Requests with a scoped identity and room must have room read access. Additional permissions may apply.
Query field names (types and requiredness not specified here): limit, since_id, timeout, type.
POST /v1/rooms/{id}/friction-digest
Create friction digest.
Path parameters: id.
Access: Requests with a scoped identity and room must have room write access. Additional permissions may apply. LAN writes require an active session token. Local loopback requests are exempt from this requirement by default; other permissions still apply.
Request body fields (partial)
| Field | Type | Required | Constraints |
|---|---|---|---|
days | integer | no | See operation notes. |
by_agent_id | string | no | See operation notes. |
Other constraints may apply, including for fields marked optional.
GET /v1/rooms/{id}/preview-targets
List or register daemon-supervised preview server targets for a room.
Path parameters: id.
Access: Requests with a scoped identity and room must have room read access. Additional permissions may apply.
This directory does not provide a request schema for this endpoint. Use the corresponding supported tool or client where available.
POST /v1/rooms/{id}/preview-targets
List or register daemon-supervised preview server targets for a room.
Path parameters: id.
Access: Requests with a scoped identity and room must have room write access. Additional permissions may apply. LAN writes require an active session token. Local loopback requests are exempt from this requirement by default; other permissions still apply. Media, browser, and preview actions are subject to session authority and Full Access requirements.
This directory does not provide a request schema for this endpoint. Use the corresponding supported tool or client where available.
DELETE /v1/rooms/{id}/preview-targets/{name}
Start or stop a registered preview server target.
Path parameters: id, name.
Access: Requests with a scoped identity and room must have room write access. Additional permissions may apply. LAN writes require an active session token. Local loopback requests are exempt from this requirement by default; other permissions still apply. Media, browser, and preview actions are subject to session authority and Full Access requirements.
This directory does not provide a request schema for this endpoint. Use the corresponding supported tool or client where available.
POST /v1/rooms/{id}/preview-targets/{name}
Start or stop a registered preview server target.
Path parameters: id, name.
Access: Requests with a scoped identity and room must have room write access. Additional permissions may apply. LAN writes require an active session token. Local loopback requests are exempt from this requirement by default; other permissions still apply. Media, browser, and preview actions are subject to session authority and Full Access requirements.
This directory does not provide a request schema for this endpoint. Use the corresponding supported tool or client where available.
GET /v1/rooms/{id}/preview-targets/{name}/logs
Read bounded logs from a supervised preview server.
Path parameters: id, name.
Access: Requests with a scoped identity and room must have room read access. Additional permissions may apply. Media, browser, and preview actions are subject to session authority and Full Access requirements.
Query field names (types and requiredness not specified here): tail.
PATCH /v1/rooms/{id}/state
Read shared room state or apply a version-checked patch.
Path parameters: id.
Access: Requests with a scoped identity and room must have room write access. Additional permissions may apply. LAN writes require an active session token. Local loopback requests are exempt from this requirement by default; other permissions still apply.
Request body fields (partial)
| Field | Type | Required | Constraints |
|---|---|---|---|
patch | object | yes | See operation notes. |
reason | string | yes | See operation notes. |
by_agent_id | string | no | See operation notes. |
expected_version | integer | yes | See operation notes. |
Other constraints may apply, including for fields marked optional.
POST /v1/rooms/{id}/state/override
Override shared room state with a recorded reason.
Path parameters: id.
Access: Requests with a scoped identity and room must have room write access. Additional permissions may apply. LAN writes require an active session token. Local loopback requests are exempt from this requirement by default; other permissions still apply.
Request body fields (partial)
| Field | Type | Required | Constraints |
|---|---|---|---|
patch | object | yes | See operation notes. |
reason | string | yes | See operation notes. |
by_agent_id | string | no | See operation notes. |
Other constraints may apply, including for fields marked optional.
GET /v1/rooms/{id}/status
Get the current room contract, roster, coordination state and attention summary.
Path parameters: id.
Query field names (types and requiredness not specified here): agent_id, max_chars.
GET /v1/rooms/{id}/workspace/files
Read workspace files.
Path parameters: id.
Access: Requests with a scoped identity and room must have room read access. Additional permissions may apply. Available only to loopback callers.
This directory does not provide a request schema for this endpoint. Use the corresponding supported tool or client where available.
GET /v1/rooms/{id}/workspaces
List workspaces.
Path parameters: id.
Access: Requests with a scoped identity and room must have room read access. Additional permissions may apply.
This directory does not provide a request schema for this endpoint. Use the corresponding supported tool or client where available.
POST /v1/rooms/{id}/workspaces
Provision workspace.
Path parameters: id.
Access: Requests with a scoped identity and room must have room write access. Additional permissions may apply. LAN writes require an active session token. Local loopback requests are exempt from this requirement by default; other permissions still apply.
Request body fields (partial)
| Field | Type | Required | Constraints |
|---|---|---|---|
agent_id | string | yes | See operation notes. |
Other constraints may apply, including for fields marked optional.
DELETE /v1/rooms/{id}/workspaces/{agent_id}
Remove workspace.
Path parameters: id, agent_id.
Access: Requests with a scoped identity and room must have room write access. Additional permissions may apply. LAN writes require an active session token. Local loopback requests are exempt from this requirement by default; other permissions still apply.
Query field names (types and requiredness not specified here): force.
GET /v1/rooms/{id}/workspaces/{agent_id}
Get workspace.
Path parameters: id, agent_id.
Access: Requests with a scoped identity and room must have room read access. Additional permissions may apply.
This directory does not provide a request schema for this endpoint. Use the corresponding supported tool or client where available.
GET /v1/rooms/{id}/workspaces/{agent_id}/diff
Read workspace diff.
Path parameters: id, agent_id.
Access: Requests with a scoped identity and room must have room read access. Additional permissions may apply.
Query field names (types and requiredness not specified here): scope.
GET /v2/rooms/{id}/events
Read the canonical per-room coordination feed with sequence, epoch and gap detection.
Path parameters: id.
Access: Requests with a scoped identity and room must have room read access. Additional permissions may apply.
Query field names (types and requiredness not specified here): after_seq, feed_epoch, limit, since_id, timeout, type.