channels
11 endpoints
get /channels
List the caller's conversations
Requires authentication
Returns the caller's channel dock: standalone channels, project channels and direct messages, each with the caller's own unread and pin state and its `topicsMoved` badge — a count of TOPICS whose head is ahead of the caller's per-topic watermark ("2 topics", never "47"), with muted topics excluded. Archived channels are omitted. Ordered pinned-first, then by most recent activity.
Responses
- 200 OK · object
- 401 Unauthorized · apimodel.ErrorEnvelope
- 403 Forbidden · apimodel.ErrorEnvelope
post /channels
Create a standalone channel
Requires authentication
Creates a named, org-wide channel and makes the caller its admin. `visibility` is "public" (reachable by every non-guest org member) or "private" (explicit members only); it defaults to public — those are the only two values. Names are unique per organization, case-insensitively. Guests may not create channels.
Request body: dto.CreateChannelRequest
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | no | Name is required. A leading '#' is stripped; names are unique per org, case-insensitively. |
| topic | string | no | Topic is the optional one-line description shown in the channel header. |
| visibility | string | no | Visibility is "public" (every non-guest org member can reach it) or "private" (explicit members only). Defaults to public when omitted. "unlisted" is rejected — it is reserved for task conversations. |
Responses
- 201 Created · object
- 400 Bad Request · apimodel.ErrorEnvelope
- 401 Unauthorized · apimodel.ErrorEnvelope
- 403 Forbidden · apimodel.ErrorEnvelope
- 409 Conflict · apimodel.ErrorEnvelope
get /channels/{uuid}
Get one channel
Requires authentication
Returns a single conversation with the caller's access, unread and pin state, AND its topic tabs in `topics` — the tab bar the client renders across the top, with "All" implied rather than listed. A channel that exists in the caller's organization but that they cannot reach answers 403; one that does not exist answers 404. Archived channels are readable here even though they are absent from the list.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Channel UUID |
Responses
- 200 OK · object
- 400 Bad Request · apimodel.ErrorEnvelope
- 401 Unauthorized · apimodel.ErrorEnvelope
- 403 Forbidden · apimodel.ErrorEnvelope
- 404 Not Found · apimodel.ErrorEnvelope
patch /channels/{uuid}
Rename, re-topic or archive a channel
Requires authentication
Partially updates a channel. Requires channel-manage authority. `name` and `topic` are accepted only on standalone channels — a project conversation takes its identity from its project, and a DM from its participants. `archived` is accepted on every kind.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Channel UUID |
Request body: dto.UpdateChannelRequest
| Name | Type | Required | Description |
|---|---|---|---|
| archived | boolean | no | Archived ends (or reopens) the conversation. Unlike name and topic it is accepted on every kind — a task conversation cannot be renamed, but it can certainly be finished. |
| name | string | no | |
| topic | string | no |
Responses
- 200 OK · object
- 400 Bad Request · apimodel.ErrorEnvelope
- 401 Unauthorized · apimodel.ErrorEnvelope
- 403 Forbidden · apimodel.ErrorEnvelope
- 404 Not Found · apimodel.ErrorEnvelope
- 409 Conflict · apimodel.ErrorEnvelope
get /channels/{uuid}/members
List a channel's members
Requires authentication
Returns WHO is in this conversation. People and agents come back in ONE list, in the same shape, distinguished only by `kind` — an agent in a channel is a member of it, not a different sort of thing that sits beside the members. Requires read access, because attributing a bubble and knowing which agent can be mentioned here are both part of reading the conversation.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Channel UUID |
Responses
- 200 OK · object
- 401 Unauthorized · apimodel.ErrorEnvelope
- 403 Forbidden · apimodel.ErrorEnvelope
- 404 Not Found · apimodel.ErrorEnvelope
post /channels/{uuid}/members
Add a member to a channel
Requires authentication
Adds a human or an agent — the same endpoint for both, because an agent is a users row with kind='agent' and the capability flags are properties of the membership rather than of the actor. Requires channel-manage authority. The target must be a live member of the caller's organization. On a private channel a `historyFrom` floor is stamped, so joining does not expose what was said before. Direct-message membership is immutable and is rejected here.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Channel UUID |
Request body: dto.AddChannelMemberRequest
| Name | Type | Required | Description |
|---|---|---|---|
| canExecute | boolean | no | CanExecute allows an agent member to act on this channel's context. Default true. |
| canMention | boolean | no | CanMention allows the member to be @-mentioned here. Default true. |
| canWriteMemory | boolean | no | CanWriteMemory allows an agent member to record what it reads here into project memory. Default true. Set false for a channel that should be answered in but never remembered. |
| role | string | no | Role is "admin", "member" or "viewer". Defaults to "member". |
| userUuid | string | no | UserUUID names the member. Must be a live member of the caller's org. |
Responses
- 201 Created · object
- 400 Bad Request · apimodel.ErrorEnvelope
- 401 Unauthorized · apimodel.ErrorEnvelope
- 403 Forbidden · apimodel.ErrorEnvelope
- 404 Not Found · apimodel.ErrorEnvelope
delete /channels/{uuid}/members/{userUuid}
Remove a member from a channel
Requires authentication
Revokes a membership. Requires channel-manage authority. The row is tombstoned rather than deleted, so a re-add keeps the member's history floor and "who was in this channel in March" stays answerable. Direct-message membership is immutable and is rejected here.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Channel UUID |
| userUuid | path | string | yes | Member's user UUID |
Responses
- 200 OK · object
- 400 Bad Request · apimodel.ErrorEnvelope
- 401 Unauthorized · apimodel.ErrorEnvelope
- 403 Forbidden · apimodel.ErrorEnvelope
- 404 Not Found · apimodel.ErrorEnvelope
get /channels/{uuid}/members/available
List the actors that can be added to a channel
Requires authentication
The org's live actors — people and agents, one list — who are not already members. Requires channel-manage authority: enumerating an organization's addresses is not something being in a conversation entitles you to, and the only reason to read this list is to add somebody from it. A direct message returns an empty list, because its membership is its identity and nobody can be added to it.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Channel UUID |
Responses
- 200 OK · object
- 401 Unauthorized · apimodel.ErrorEnvelope
- 403 Forbidden · apimodel.ErrorEnvelope
- 404 Not Found · apimodel.ErrorEnvelope
post /channels/{uuid}/pin
Pin or unpin a channel for the caller
Requires authentication
Sets the caller's own pin, which floats the channel to the top of the dock. Invisible to everyone else. Requires only read access.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Channel UUID |
Request body: dto.PinChannelRequest
| Name | Type | Required | Description |
|---|---|---|---|
| pinned | boolean | no |
Responses
- 200 OK · object
- 400 Bad Request · apimodel.ErrorEnvelope
- 401 Unauthorized · apimodel.ErrorEnvelope
- 403 Forbidden · apimodel.ErrorEnvelope
- 404 Not Found · apimodel.ErrorEnvelope
post /channels/{uuid}/read
Advance the caller's read watermark
Requires authentication
Moves the caller's cursor for this channel to `seq` — the per-channel message sequence, not a timestamp or a message id. The advance is monotonic: a sequence at or below the stored one is accepted and changes nothing, because two of the caller's devices reading the same channel race by design and the slower one must not un-read what the faster one read. A genuine advance clears the channel's mention badge. Requires only read access.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Channel UUID |
Request body: dto.MarkChannelReadRequest
| Name | Type | Required | Description |
|---|---|---|---|
| seq | integer | no |
Responses
- 200 OK · object
- 400 Bad Request · apimodel.ErrorEnvelope
- 401 Unauthorized · apimodel.ErrorEnvelope
- 403 Forbidden · apimodel.ErrorEnvelope
- 404 Not Found · apimodel.ErrorEnvelope
post /dms
Open or return a direct message
Requires authentication
Returns the conversation for a participant SET, creating it on first use. The caller is always a participant; `participantUuids` lists the others and may safely repeat the caller. Order does not matter and duplicates are collapsed — the same set of people always resolves to the same conversation, so this endpoint is idempotent. Between 2 and 9 participants including the caller. Membership is immutable: to add someone, open a new conversation with the larger set.
Request body: dto.OpenDMRequest
| Name | Type | Required | Description |
|---|---|---|---|
| participantUuids | string[] | no |
Responses
- 200 OK · object
- 400 Bad Request · apimodel.ErrorEnvelope
- 401 Unauthorized · apimodel.ErrorEnvelope
- 403 Forbidden · apimodel.ErrorEnvelope
- 404 Not Found · apimodel.ErrorEnvelope