# Chat

Team chat rooms, members, and messages. Workspace-scoped in Phase 0; portal and cross-workspace rooms in later phases.

**Base URL:** `https://api.trustpager.com/functions/v1/api/v1`

## Endpoints

### POST /chat/rooms/:room_id/members

Add a workspace user to a chat room. In Phase 0 the user must belong to this workspace; cross-workspace adds (which need a consent handshake) come later.

**Scopes:** `chat:write` — [full detail](./chat/post-chat-rooms-room-id-members.md)

### POST /chat/rooms

Create a chat room. The API key owner joins as owner; pass member_user_ids to add teammates (they must belong to this workspace). Use room_type "dm" for 1:1, "group" for a named group, "self" for a private notes-to-self room, "workspace" for a team-wide channel.

**Scopes:** `chat:write` — [full detail](./chat/post-chat-rooms.md)

### DELETE /chat/rooms/:room_id/messages/:message_id

Soft-delete one of your own chat messages (sets deleted_at; history preserved). Only the original sender can delete.

**Scopes:** `chat:write` — [full detail](./chat/delete-chat-rooms-room-id-messages-message-id.md)

### PATCH /chat/rooms/:room_id/messages/:message_id

Edit one of your own chat messages (sets edited_at). Only the original sender can edit. Pass the new `body` and/or `content`.

**Scopes:** `chat:write` — [full detail](./chat/patch-chat-rooms-room-id-messages-message-id.md)

### GET /chat/rooms/:room_id

Fetch a single chat room by UUID.

**Scopes:** `chat:read` — [full detail](./chat/get-chat-rooms-room-id.md)

### POST /chat/rooms/:room_id/invite

Invite someone to a chat room by email — the cross-workspace path. Existing TrustPager users are added immediately; a new email is provisioned an account and added so they land in the room when they accept. Optionally set member_role "host" so they can invite their own people.

**Scopes:** `chat:write` — [full detail](./chat/post-chat-rooms-room-id-invite.md)

### GET /chat/rooms/:room_id/messages

List messages in a chat room, newest first, paginated. Soft-deleted messages are excluded.

**Scopes:** `chat:read` — [full detail](./chat/get-chat-rooms-room-id-messages.md)

### GET /chat/rooms/:room_id/members

List the members of a chat room, with each member's user profile (name, email, avatar).

**Scopes:** `chat:read` — [full detail](./chat/get-chat-rooms-room-id-members.md)

### GET /chat/rooms

List chat rooms in the workspace. A room is a set of participants (a DM, a group, a self-note, or a workspace channel). Filter by room_type or is_archived. Newest activity first.

**Scopes:** `chat:read` — [full detail](./chat/get-chat-rooms.md)

### POST /chat/rooms/:room_id/read

Mark a chat room as read up to now for the API key owner, updating their last_read_at. You can only mark your own read state.

**Scopes:** `chat:write` — [full detail](./chat/post-chat-rooms-room-id-read.md)

### DELETE /chat/rooms/:room_id/members/:user_id

Remove a member from a chat room (marks them removed; message history is preserved).

**Scopes:** `chat:write` — [full detail](./chat/delete-chat-rooms-room-id-members-user-id.md)

### POST /chat/rooms/:room_id/messages

Post a message to a chat room. When sent via API/MCP the message is attributed as an AI actor on the workspace's behalf (actor_type defaults to "ai"); pass actor_type "human" only when relaying a real person. Provide `body` text and/or structured `content`.

**Scopes:** `chat:write` — [full detail](./chat/post-chat-rooms-room-id-messages.md)

### PATCH /chat/rooms/:room_id

Update a chat room title or archive it. Pass only the fields to change.

**Scopes:** `chat:write` — [full detail](./chat/patch-chat-rooms-room-id.md)