topics
6 endpoints
get /channels/{uuid}/topics
List a channel's topic tabs
Requires authentication
Returns the channel's tab bar: its live topics in explicit `position` order, each with the caller's own read watermark and mute state. The "All" tab is NOT in this list — it is the absence of a filter rather than a topic row, so the client renders it itself. Requires read access to the channel; there is no per-topic permission, because a topic is a lane and not an access boundary.
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
post /channels/{uuid}/topics
Create a topic in a channel
Requires authentication
Adds a lane to the channel's tab bar. Requires channel-MANAGE authority, because the tab bar is shared surface that every member then sees — unlike mute and read, which are private. A channel may hold at most 12 live topics; the 13th is refused with 409 and the caller's remedy is to archive one. Names are unique per channel, case-insensitively, and the new topic is placed at the end of the bar. Topics are never created automatically — not per task, not per bug, not per release.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Channel UUID |
Request body: dto.CreateTopicRequest
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | no | Name is required, trimmed, at most 48 characters, and unique within the channel case-insensitively. A channel may hold at most 12 live topics — enforced by trg_topics_cap in migration 0044, not by this endpoint. |
Responses
- 201 Created · object
- 400 Bad Request · apimodel.ErrorEnvelope
- 401 Unauthorized · apimodel.ErrorEnvelope
- 403 Forbidden · apimodel.ErrorEnvelope
- 404 Not Found · apimodel.ErrorEnvelope
- 409 Conflict · apimodel.ErrorEnvelope
patch /topics/{uuid}
Rename or reorder a topic
Requires authentication
Partially updates a topic. Requires channel-manage authority. `position` is the explicit tab order — human-set rather than derived, because sorting by name would reshuffle the bar on a rename and sorting by activity would move it under the cursor. Re-tagging existing messages is NOT part of a rename: a topic is a label, and its messages keep pointing at it.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Topic UUID |
Request body: dto.UpdateTopicRequest
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | no | |
| position | integer | no | Position is the explicit tab order. Human-set rather than derived: sorting by name would reshuffle the bar the moment somebody renames a lane, and sorting by activity would make the bar move under the cursor. |
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
delete /topics/{uuid}
Archive a topic
Requires authentication
Removes a lane from the tab bar. IT DOES NOT DELETE, HIDE OR RE-TAG ITS MESSAGES — they stay in the channel, keep their `seq`, keep appearing in the All tab, and simply report no topic from then on. That is the whole point of a topic being a filter rather than a room: tidying up a tab can never cost anyone a conversation. Requires channel-manage authority.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Topic UUID |
Responses
- 200 OK · object
- 400 Bad Request · apimodel.ErrorEnvelope
- 401 Unauthorized · apimodel.ErrorEnvelope
- 403 Forbidden · apimodel.ErrorEnvelope
- 404 Not Found · apimodel.ErrorEnvelope
post /topics/{uuid}/mute
Mute or unmute a topic for the caller
Requires authentication
Sets the caller's own mute for one lane — the main attention control in the product, and invisible to everyone else. Muting suppresses the channel's `topicsMoved` badge for this topic and NOTHING else: the lane still receives messages and still shows them in the All tab. The one thing mute cannot suppress is a task mention — an `@BUG-241` reference notifies the task's assignees regardless of topic or mute. Requires only read access.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Topic UUID |
Request body: dto.MuteTopicRequest
| Name | Type | Required | Description |
|---|---|---|---|
| muted | 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 /topics/{uuid}/read
Advance the caller's read watermark for a topic
Requires authentication
Moves the caller's cursor for this lane to `seq` — the PER-CHANNEL message sequence, because a topic filters the channel's one stream and giving topics their own numbering would create a second cursor space to keep in step. The advance is monotonic: a sequence at or below the stored one is accepted and changes nothing, because two of the caller's devices race by design and the slower one must not un-read what the faster one read. Requires only read access.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Topic UUID |
Request body: dto.MarkTopicReadRequest
| 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