Skip to content

All resources

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

NameTypeRequiredDescription
namestringnoName is required. A leading '#' is stripped; names are unique per org, case-insensitively.
topicstringnoTopic is the optional one-line description shown in the channel header.
visibilitystringnoVisibility 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

NameInTypeRequiredDescription
uuidpathstringyesChannel 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

NameInTypeRequiredDescription
uuidpathstringyesChannel UUID

Request body: dto.UpdateChannelRequest

NameTypeRequiredDescription
archivedbooleannoArchived 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.
namestringno
topicstringno

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

NameInTypeRequiredDescription
uuidpathstringyesChannel 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

NameInTypeRequiredDescription
uuidpathstringyesChannel UUID

Request body: dto.AddChannelMemberRequest

NameTypeRequiredDescription
canExecutebooleannoCanExecute allows an agent member to act on this channel's context. Default true.
canMentionbooleannoCanMention allows the member to be @-mentioned here. Default true.
canWriteMemorybooleannoCanWriteMemory 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.
rolestringnoRole is "admin", "member" or "viewer". Defaults to "member".
userUuidstringnoUserUUID 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

NameInTypeRequiredDescription
uuidpathstringyesChannel UUID
userUuidpathstringyesMember'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

NameInTypeRequiredDescription
uuidpathstringyesChannel 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

NameInTypeRequiredDescription
uuidpathstringyesChannel UUID

Request body: dto.PinChannelRequest

NameTypeRequiredDescription
pinnedbooleanno

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

NameInTypeRequiredDescription
uuidpathstringyesChannel UUID

Request body: dto.MarkChannelReadRequest

NameTypeRequiredDescription
seqintegerno

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

NameTypeRequiredDescription
participantUuidsstring[]no

Responses

  • 200 OK · object
  • 400 Bad Request · apimodel.ErrorEnvelope
  • 401 Unauthorized · apimodel.ErrorEnvelope
  • 403 Forbidden · apimodel.ErrorEnvelope
  • 404 Not Found · apimodel.ErrorEnvelope