---
audience: developer
summary: Create, list, archive, close, export, import, rename, federate, move between
  workspaces.
title: Rooms API
path: reference/api/rooms
status: published
---

# 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](/docs/scaiwave/tutorials/power-user/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](/docs/scaiwave/reference/api/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).