API pipeline: Create and manage your own room

Index: API pipelines — index

Goal: create your own room and run it: invite projects, see members, set roles, remove or ban, change settings, open threads, rename, set visibility.

Rooms speak as projects: you need at least one project. Messaging in a room: API pipeline: Read and answer your conversations

Steps

1. Create.

POST /v0/my/rooms
Idempotency-Key: room-8a1f…
{"title": "Wedding partners", "visibility": "Private"}
→ {"nonce": "470000000000000310", "card_type": "room", "talk": {"kind": "native", …}, "role": "owner", …}

• Only title is required; visibility defaults to Private. Public: anyone may join and read the history; Private: by invitation.
• You speak in it as your first project.

2. Invite a project. POST /v0/my/rooms/470000000000000310/talk/invite {"project": "470000000000000002"} → 204.

3. Members.

GET …/talk/members
→ {"members": [{"mxid": "<member id>", "role": "owner"}, {"mxid": "<member id>", "role": "member"}], "banned": []}

Member ids from this list are what the next calls take.

4. Roles and removal.

POST …/talk/role   {"mxid": "<member id>", "role": "admin"}       owner | admin | member | guest
POST …/talk/kick   {"mxid": "<member id>", "reason": "spam"}
POST …/talk/ban    {"mxid": "<member id>", "reason": "spam"}
POST …/talk/unban  {"mxid": "<member id>"}

All → 204.

5. Settings. GET …/talk/settings → current. POST …/talk/settings {"threads": true, "slow_mode_secs": 30} → 204; slow_mode_secs: 0 turns slow mode off.

6. Threads. With threads on: POST …/talk/threads {"name": "Pricing"} → {"event_id": "<thread root id>"}; send into it with thread_id, read it with GET …/talk?thread_id=<thread root id>.

7. Rename, visibility, card fields.

• POST …/rename {"name": "Wedding partners 2027"} → 204.
• POST …/visibility {"visibility": "Public"} → 204 (owner only).
• PATCH /v0/my/rooms/{ident} (owner only) takes the common card fields: title, content, handle, project, rubrics, location, visibility, publicity, permissions, translate_mode, translate_langs (machine translation of the room card's title and description, not of messages). Same rules as articles: API pipeline: Write articles and posts

Behind

• Nothing runs later: every call takes effect when it answers.

Rules

• 400: title is required; create a project first — rooms speak as a project; name must not be empty; role must be owner|admin|member|guest.
• 400: no permission to add members (same for kick, ban, unban, change roles, change settings, pin, rename); threads are disabled in this room; not a participant of this room.
• 404: a room you are not in; visibility or PATCH by someone other than the owner.
• Your permissions on GET /v0/my/rooms/{ident} show in advance what you may do (add_members, kick, ban, pin, change_settings, change_roles).

API surface