Collab Rooms

A Collab Room is a shared space for paired sessions with another Malleable user. Spin one up, share the short code, and stream messages and files between machines or between two people. Rooms are lightweight: they sit alongside buckets and projects rather than replacing them.

Every room has a unique short code (the join handle), a name, an optional description, and exactly one owner: the user who created it. Other participants join as members and can leave at any time. The owner's membership is permanent for the lifetime of the room.

The web index lives at /collab and is reachable from the Collab entry on the command rail. Rooms are also fully addressable over the V1 REST API under /api/v1/collab.

From the web, open /collab, click Create room, and provide a name (max 100 characters) and an optional description (max 200 characters). On submit, Malleable returns the new room with a short code and redirects you to /collab/<code>. You are inserted as the owner participant automatically.

Over the API

curl -X POST https://malleable.cloud/api/v1/collab/rooms \
  -H "Authorization: Bearer mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Project X", "description": "Pairing on the launch checklist" }'

# → { room: { name: "Project X", code: "ABC123", ... } }

The V1 endpoint /api/v1/collab/rooms takes your API key and requires the collab:rooms scope. The web flow uses the session-auth wrapper at /api/collab/rooms, which is backed by the same tables and Row Level Security policies.

On /collab, type the room code into the Join by code field and submit. The code is case-insensitive, the form upper-cases it for you. On success you are redirected to the room page.

Over the API

curl -X POST https://malleable.cloud/api/v1/collab/rooms/ABC123/join \
  -H "Authorization: Bearer mk_live_..."

# → joined Project X (ABC123)

Both flows POST to /api/collab/rooms/<code>/join (web) or /api/v1/collab/rooms/<code>/join (API), which inserts you as a participant. After joining, the room shows up on the web index alongside any rooms you own and in your room listing from the API.

The room list shows each room's name, code, member count, and an owner badge on rooms you created. Member counts come from active participants, users who have joined and not yet left.

Live-now ping

When a room has had a message in the last 30 seconds, an emerald live pulse appears next to its name. The list re-renders every 5 seconds so the indicator decays naturally without a real-time channel: once the most recent message is older than 30 seconds, the pulse disappears on the next tick.

The threshold is hard-coded to last_message_at < 30s and is computed against the most recent row in collab_room_messages per room.

The full room surface is available over the V1 REST API, so you can drive rooms from scripts or your own integration. All endpoints require an API key with the collab:rooms scope; the message and heartbeat endpoints also require collab:sync.

GET    /api/v1/collab/rooms                 # list your rooms
POST   /api/v1/collab/rooms                 # create a room { name, description? }
POST   /api/v1/collab/rooms/<code>/join     # join by code
GET    /api/v1/collab/rooms/<code>          # room header, participants, files
GET    /api/v1/collab/rooms/<code>/messages # recent messages (?limit=, max 100)
POST   /api/v1/collab/rooms/<code>/leave    # leave a room

The room detail endpoint returns the room header, participants (with an owner flag), attached files, and recent messages. The messages endpoint accepts a limit query param (up to 100); poll it on an interval to follow a room from your own tooling. There is also a /heartbeat endpoint to mark presence in a room.

Members (non-owners) can leave a room at any time. From the web, click Leave on any row in the room list and confirm the prompt, the room is removed from your list and you stop appearing in its participant roster.

Over the API

curl -X POST https://malleable.cloud/api/v1/collab/rooms/ABC123/leave \
  -H "Authorization: Bearer mk_live_..."

# → left room ABC123

Owners do not see a Leave button on their own rooms. The room continues to exist for the remaining participants until the owner archives it through other tooling.