Rooms API

21 endpoints. All under /v1/rooms/.

Listing and discovery#

Method	Path	Purpose
`GET`	`/v1/directory/rooms`	All rooms the caller can see in the current tenant.
`GET`	`/v1/rooms/{room_id}`	One room with metadata + members count.
`GET`	`/v1/rooms/archived`	Your archived rooms (recoverable).
`GET`	`/v1/rooms/{room_id}/members`	Members of a room.

Creation#

POST /v1/rooms#

Create a group, public, or incognito room.

bash
curl -X POST "$BASE/v1/rooms" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "room_type": "group",
    "name": "engineering",
    "topic": "All things eng",
    "is_public": false,
    "workspace_id": "<optional; defaults to your personal workspace>",
    "scope_kind": null
  }'

Body fields:

room_type (group / public / incognito).
name (required for group/public; null/auto for DMs).
topic (optional).
is_public (bool).
workspace_id (optional; defaults to creator's personal workspace).
scope_kind (null / "incognito").

Returns {data: {id, room_alias, …}}.

POST /v1/rooms/dm#

Create or fetch a 1:1 DM with another participant.

bash
curl -X POST "$BASE/v1/rooms/dm" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"participant_id": "<other-id>"}'

Idempotent — returns the existing DM if one is open.

Lifecycle#

Method	Path	Purpose
`POST`	`/v1/rooms/{room_id}/join`	Join a public/invite room.
`POST`	`/v1/rooms/{room_id}/leave`	Leave a room.
`POST`	`/v1/rooms/{room_id}/close`	Close (admin).
`POST`	`/v1/rooms/{room_id}/archive`	Archive (recoverable).
`POST`	`/v1/rooms/{room_id}/rejoin`	Restore from archive.
`POST`	`/v1/rooms/{room_id}/invite`	Invite a participant.
`POST`	`/v1/rooms/{room_id}/kick`	Kick (`power_level ≥ 50`).
`POST`	`/v1/rooms/{room_id}/ban`	Ban (`power_level ≥ 50`).

close_room requires creator_id == caller or power_level >= 100.

Metadata edits#

Method	Path	Purpose
`PUT`	`/v1/rooms/{room_id}/name`	Rename.
`PUT`	`/v1/rooms/{room_id}/topic`	Set topic.
`PUT`	`/v1/rooms/{room_id}/workspace`	Move to a different workspace.
`PUT`	`/v1/rooms/{room_id}/notification-mode`	Per-room mode for the caller.
`PUT`	`/v1/rooms/{room_id}/mute`	Mute with expiry.

Export / import#

Method	Path	Purpose
`GET`	`/v1/rooms/{room_id}/export`	Stream a ZIP bundle (manifest.json + media/<sha>).
`POST`	`/v1/rooms/import`	Multipart upload of a previously-exported bundle.

See Export and import rooms.

Federation toggles#

Method	Path	Purpose
`PUT`	`/v1/admin/rooms/{room_id}/federate`	Enable / disable federation for this room.
`POST`	`/v1/admin/rooms/{room_id}/federation/invite`	Invite a foreign participant.
`POST`	`/v1/admin/rooms/{room_id}/federation/backfill`	Pull historical events from peer.

See Federation.

Read marker#

Method	Path	Purpose
`PUT`	`/v1/rooms/{room_id}/read`	Advance the caller's read marker to the given event id.

Common error codes#

SW_ROOM_NOT_FOUND — room id doesn't exist (or you can't see it).
SW_ROOM_FORBIDDEN — caller isn't a member or lacks power.
SW_ROOM_FROZEN — room is closed or archived.
SW_ROOM_CAPACITY — tenant max_participants reached.
SW_ROOM_TYPE_INVARIANT — operation invalid for this room_type (e.g. inviting a third member to a DM).