chat
28 endpoints
post /channels/{uuid}/attachments
Upload a file to a channel
Requires authentication
Stores a file against the channel and returns its uuid. The file carries NO message yet — send one naming the uuid in `attachmentUuids` to attach it. This two-phase shape is deliberate: it keeps a slow upload from holding the message hostage, lets the client show per-file progress before the user commits to sending, and stops a retried send from re-uploading bytes that already landed. Requires WRITE access to the channel: an attachment is a contribution to the conversation, not a read of it. An upload nobody sends is swept after two hours. Accepts the same types as task attachments (jpeg/png/gif/webp/pdf/txt), validated by extension, declared MIME type AND a magic-byte sniff of the real content.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Channel uuid |
Request body: object
| Name | Type | Required | Description |
|---|---|---|---|
| file | string (binary) | yes | File to upload |
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
- 413 Request Entity Too Large · apimodel.ErrorEnvelope
- 507 Insufficient Storage · apimodel.ErrorEnvelope
delete /channels/{uuid}/attachments/{attachmentUuid}
Remove an unsent upload
Requires authentication
Deletes a file the caller uploaded but has not sent yet — the "x" on an attachment chip in the composer. Only the UPLOADER may call it, and only while the file is unsent: once a message carries the attachment, removing it is an edit of that message. Returns 409 in that case.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Channel uuid |
| attachmentUuid | path | string | yes | Attachment uuid |
Responses
- 204 No Content
- 401 Unauthorized · apimodel.ErrorEnvelope
- 403 Forbidden · apimodel.ErrorEnvelope
- 404 Not Found · apimodel.ErrorEnvelope
- 409 Conflict · apimodel.ErrorEnvelope
get /channels/{uuid}/attachments/{attachmentUuid}/signed-url
Get a viewable URL for a chat attachment
Requires authentication
Mints a short-lived, signed URL for the attachment's bytes. Needed because an `<img src>` cannot send an Authorization header, so the capability has to travel in the URL instead. Valid for 15 minutes and re-mintable; the authorization is checked HERE, at mint time, which is the only place it can be — the view route itself has no session. Requires only READ access, unlike uploading.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Channel uuid |
| attachmentUuid | path | string | yes | Attachment uuid |
Responses
- 200 OK · object
- 401 Unauthorized · apimodel.ErrorEnvelope
- 403 Forbidden · apimodel.ErrorEnvelope
- 404 Not Found · apimodel.ErrorEnvelope
get /channels/{uuid}/messages
Read a channel's messages
Requires authentication
Returns one keyset page of the conversation. `?before=` walks BACKWARDS and returns NEWEST FIRST; `?after=` walks FORWARDS and returns OLDEST FIRST. They are mirrors over the same stream and the same cursor, and supplying both is a 400 — a page cannot walk two directions. With neither, you get the newest page. Follow `nextBefore` / `nextAfter` respectively. There is no offset paging: the cursor is the per-channel `seq`, so a page boundary cannot shift when somebody posts mid-scroll. Tombstoned messages ARE returned (with an empty body) so the cursor stays dense — which is what makes `?after=` usable as "everything I missed since seq N", including the chat.resync range the live stream names. A message whose stored body the server cannot decrypt is likewise returned, with an empty `body` and `bodyUnreadable: true`, and all of its unencrypted metadata intact — one such row does not fail the page, and the client must render it as "cannot be read" rather than as an empty message (an empty `body` alone is ordinary: an attachment-only message has one). `?topic=` narrows this SAME stream to one tab — a topic page is a subset of the unfiltered page over the same seq range, and the cursor means the same thing either way. Each message carries `topicUuid` so the client can render its topic chip even in the All tab; a message tagged with an archived topic reports "" and stays in the stream.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Channel uuid |
| before | query | integer | no | Return messages with seq strictly below this, newest first. Omit for the newest page. Mutually exclusive with after. |
| after | query | integer | no | Return messages with seq strictly above this, oldest first. Mutually exclusive with before. |
| limit | query | integer | no | Page size (default 50, max 199) |
| topic | query | string | no | Topic uuid. Filters this same stream to one tab; omit for the All tab. |
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}/messages
Send a message to a channel
Requires authentication
Appends a message to the channel. `uuid` in the body is REQUIRED and must be a client-minted UUIDv7 — it is the idempotency key, so re-sending the same uuid returns the stored message instead of creating a second one. `topicUuid` optionally TAGS the message with one of the channel's topics (the client sends the active tab; tagging is optional and an untagged message is normal). `replyToUuid` optionally quotes another message IN THE SAME CHANNEL — it is a pointer rendered as an inline quoted bubble, never a thread. Any `@BUG-241` style reference in the body creates a backlink on that task and notifies its assignees, regardless of topic or mute.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Channel uuid |
Request body: dto.SendMessageRequest
| Name | Type | Required | Description |
|---|---|---|---|
| attachmentUuids | string[] | no | AttachmentUUIDs claims files ALREADY UPLOADED to this channel, in the order they should render (migration 0056). Uuids, never file bytes: uploading is a separate, earlier request (POST /channels/:uuid/attachments) so that a slow 100MB upload does not hold the message hostage, per-file progress can be shown before the user commits to sending, and a retry of a failed send does not re-upload a file that already landed. It is the same two-phase shape Slack and Discord both settled on. A message carrying attachments may have an EMPTY body — dragging in a screenshot and pressing send without typing is the common case, not an edge one. Every uuid must be an unclaimed attachment of THIS channel. One from another conversation is reported as not-found rather than forbidden, so the answer never confirms that a file exists somewhere the caller cannot see. |
| body | string | no | Body is the message text. |
| contentType | string | no | ContentType is "text" (default) or "markdown". |
| replyToUuid | string | no | ReplyToUUID optionally quotes another message in the SAME channel. A POINTER, never a container. It renders as an inline quoted bubble in the same stream (the iMessage / Telegram / WhatsApp shape) and clicking it scrolls to the quoted message. There is no thread view, no thread panel and no "also send to channel", because there are no threads. |
| topicUuid | string | no | TopicUUID optionally TAGS the message with one of the channel's topics. The client sends the topic whose tab is currently active in its composer — typing while a topic tab is selected auto-tags the message with that topic. Empty is normal and correct: tagging is OPTIONAL, an untagged message appears in the "All" tab, and the server never infers a tag from the text or from the previous message. A topic uuid belonging to a different channel is rejected rather than accepted: a message carrying a foreign tag would be invisible in every tab while still looking tagged. |
| uuid | string | no | UUID is the client-minted UUIDv7 idempotency key. |
Responses
- 201 Created · object
- 400 Bad Request · apimodel.ErrorEnvelope
- 401 Unauthorized · apimodel.ErrorEnvelope
- 403 Forbidden · apimodel.ErrorEnvelope
- 404 Not Found · apimodel.ErrorEnvelope
post /channels/{uuid}/messages/{messageUuid}/reactions
React to a message
Requires authentication
Adds the caller's emoji to a message. IDEMPOTENT — reacting twice with the same emoji is a no-op, not an error, because the client has already drawn the pill as pressed. `emoji` is a SHORTCODE (`thumbsup`, `+1`, `shipit`), with or without surrounding colons; unicode glyphs are refused because skin-tone modifiers and variation selectors make them non-comparable, which would split one reaction into two piles. Requires write access to the channel: a reaction renders under your name, so it is a contribution rather than a read.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Channel uuid |
| messageUuid | path | string | yes | Message uuid |
Request body: dto.ReactionRequest
| Name | Type | Required | Description |
|---|---|---|---|
| emoji | string | no | Emoji is a SHORTCODE — `thumbsup`, `+1`, `shipit` — with or without the surrounding colons every emoji picker emits. Unicode glyphs are refused by domain.NormalizeEmoji; see migration 0053 for why. |
Responses
- 204 No Content
- 400 Bad Request · apimodel.ErrorEnvelope
- 401 Unauthorized · apimodel.ErrorEnvelope
- 403 Forbidden · apimodel.ErrorEnvelope
- 404 Not Found · apimodel.ErrorEnvelope
get /channels/{uuid}/messages/{messageUuid}/reactions/{emoji}
Who reacted with one emoji
Requires authentication
Lists the user uuids behind one pill, oldest first, capped. This is the TOOLTIP's data and is deliberately not included in the message page: one popular message would otherwise put hundreds of uuids into a response that fifty messages share. Requires only read access, unlike reacting itself.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Channel uuid |
| messageUuid | path | string | yes | Message uuid |
| emoji | path | string | yes | Emoji shortcode |
| limit | query | integer | no | Max names (default 50, max 200) |
Responses
- 200 OK · object
- 400 Bad Request · apimodel.ErrorEnvelope
- 401 Unauthorized · apimodel.ErrorEnvelope
- 403 Forbidden · apimodel.ErrorEnvelope
delete /channels/{uuid}/messages/{messageUuid}/reactions/{emoji}
Withdraw a reaction
Requires authentication
Removes the caller's emoji from a message. IDEMPOTENT — removing one that is not there is a no-op. Only ever removes the CALLER's own reaction; there is no way to clear someone else's.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Channel uuid |
| messageUuid | path | string | yes | Message uuid |
| emoji | path | string | yes | Emoji shortcode |
Responses
- 204 No Content
- 400 Bad Request · apimodel.ErrorEnvelope
- 401 Unauthorized · apimodel.ErrorEnvelope
- 403 Forbidden · apimodel.ErrorEnvelope
- 404 Not Found · apimodel.ErrorEnvelope
get /channels/{uuid}/presence
Presence for a channel's members
Requires authentication
Resolves presence for everyone in one channel, as of a single instant. Members with no presence row are returned as `offline` — never having connected is a real answer, not missing data, which is what keeps presence from needing one row per user per deployment.
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
get /channels/{uuid}/task-refs
Resolve @BUG-241 references in a channel
Requires authentication
Turns a batch of task references into the live chips a client renders inside message bodies: current title, current status, and everyone assigned. The unit is a PAGE OF MESSAGES, not a single reference — a client parses every reference out of the page it is about to render and asks once. Resolution is identical to the rule the send path used when it decided whether to write a backlink: scoped to this channel's project when it has one, widened to the org when it does not (a standalone channel or a DM), and an org-wide reference that matches in two projects resolves to NOTHING rather than guessing. A reference that resolves to nothing is simply ABSENT from the response — it is ordinary prose, not an error, and the client leaves the author's text alone. Authorization is the CHANNEL, so this can never be used to read a task's title through a conversation the caller cannot open.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Channel uuid |
| refs | query | string | yes | Comma-separated references, e.g. `BUG-241,FEAT-3`. A leading `@` is accepted. Case-insensitive. Maximum 100 per call — chunk a larger page. |
Responses
- 200 OK · object
- 400 Bad Request · apimodel.ErrorEnvelope
- 401 Unauthorized · apimodel.ErrorEnvelope
- 403 Forbidden · apimodel.ErrorEnvelope
- 404 Not Found · apimodel.ErrorEnvelope
get /chat-attachments/{uuid}/view
Stream a chat attachment (signed)
No authentication
Serves the bytes to a caller holding a token minted by the signed-url endpoint. No session is required or consulted — the token is the capability, and it expires in 15 minutes.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Attachment uuid |
| token | query | string | yes | Signature from the signed-url endpoint |
| exp | query | integer | yes | Expiry from the signed-url endpoint |
Responses
- 200 OK · string (binary)
- 401 Unauthorized · apimodel.ErrorEnvelope
- 404 Not Found · apimodel.ErrorEnvelope
get /chat/conversations
List the messenger inbox
Requires authentication
One row per project in the caller's org, with the project's rolled-up unread count (General + every task thread). Unread rows first, most unread first; the rest by most-recent activity.
Responses
- 200 OK · object
- 401 Unauthorized · apimodel.ErrorEnvelope
get /chat/notification-preferences
The caller's chat notification preferences
Requires authentication
Returns the account-wide default plus every per-channel override, keyed by channel uuid. `levels` names the vocabulary this build accepts so the settings UI does not carry a duplicate copy. Levels are `mentions` (notify me when someone @-mentions me here) and `none` (mute). There is deliberately no "all messages" level — nothing in this build writes a notification for a message that does not mention you, so it would be a setting that changes nothing.
Responses
- 200 OK · object
- 401 Unauthorized · apimodel.ErrorEnvelope
put /chat/notification-preferences
Set the caller's default chat notification level
Requires authentication
Sets the level applied to every conversation the caller has not overridden. `none` mutes chat wholesale — conversations opted back in individually still notify. Takes effect on the next inbox read; muting does not delete anything, so un-muting restores the history.
Request body: dto.ChatNotificationDefaultRequest
| Name | Type | Required | Description |
|---|---|---|---|
| level | string | no | Level is `mentions` or `none`. There is no `all`: nothing in this build notifies on a message that does not mention you, so an `all` level would be stored and behave identically to `mentions`. See migration 0057. |
Responses
- 200 OK · object
- 400 Bad Request · apimodel.ErrorEnvelope
- 401 Unauthorized · apimodel.ErrorEnvelope
put /chat/notification-preferences/{channelUuid}
Override one conversation's notification level
Requires authentication
Sets `mentions` or `none` for a single channel, overriding the account default. Requires read access to the channel — muting a uuid you cannot reach is refused rather than stored, so this endpoint cannot be used to test whether a private channel or DM exists.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| channelUuid | path | string | yes | Channel uuid |
Request body: dto.ChatNotificationChannelRequest
| Name | Type | Required | Description |
|---|---|---|---|
| level | string | no | Level is `mentions` or `none`. DELETE the same path to remove the override and follow the account default again. |
Responses
- 200 OK · object
- 400 Bad Request · apimodel.ErrorEnvelope
- 401 Unauthorized · apimodel.ErrorEnvelope
- 403 Forbidden · apimodel.ErrorEnvelope
- 404 Not Found · apimodel.ErrorEnvelope
delete /chat/notification-preferences/{channelUuid}
Drop one conversation's override
Requires authentication
Removes the per-channel override so the conversation follows the account default again. Idempotent — clearing an override that is not there succeeds, because the requested state already holds.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| channelUuid | 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 /chat/read
Mark a chat conversation read
Requires authentication
Clears the caller's unread notifications for a project (and optionally a specific task thread).
Request body: apimodel.ChatMarkReadRequest
| Name | Type | Required | Description |
|---|---|---|---|
| projectId | integer | no | |
| taskNumber | integer | no |
Responses
- 200 OK · object
- 400 Bad Request · apimodel.ErrorEnvelope
get /mentions
The caller's mentions
Requires authentication
One keyset page of messages that named the caller, newest first. `before` is the `id` of the oldest row on the previous page; omit it for the first page. `unread=true` narrows to what still needs attention. Only DIRECT mentions appear — `@channel` and `@here` are a property of the message rather than of every member, so they are not filed per person.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| before | query | integer | no | Keyset cursor: id of the oldest row already seen |
| limit | query | integer | no | Page size (default 30, max 100) |
| unread | query | boolean | no | Only unread mentions |
Responses
- 200 OK · object
- 401 Unauthorized · apimodel.ErrorEnvelope
post /mentions/{uuid}/read
Clear one mention
Requires authentication
Stamps a mention read. Succeeds whether or not anything changed — an already-read mention and one belonging to somebody else are deliberately indistinguishable in the response, so this endpoint cannot be used to probe whether a given uuid exists.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Mention uuid |
Responses
- 204 No Content
- 401 Unauthorized · apimodel.ErrorEnvelope
post /mentions/read-all
Clear every mention
Requires authentication
Marks all of the caller's unread mentions read, for the current organization only. Returns how many were cleared.
Responses
- 200 OK · object
- 401 Unauthorized · apimodel.ErrorEnvelope
get /mentions/unread-count
Unread mention count
Requires authentication
The sidebar badge, for the caller's current organization. Scoped per org because the badge is per workspace — one customer's unread mentions must not show up while you are looking at another's.
Responses
- 200 OK · object
- 401 Unauthorized · apimodel.ErrorEnvelope
patch /messages/{uuid}
Edit your own message
Requires authentication
Replaces the message body and stamps `editedAt`. Author-only at every role — a channel admin may delete another person's message but may never rewrite it. The message keeps its `seq`, so an edit does not move any client's cursor.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Message uuid |
Request body: dto.EditMessageRequest
| Name | Type | Required | Description |
|---|---|---|---|
| body | string | no |
Responses
- 200 OK · object
- 400 Bad Request · apimodel.ErrorEnvelope
- 401 Unauthorized · apimodel.ErrorEnvelope
- 403 Forbidden · apimodel.ErrorEnvelope
- 404 Not Found · apimodel.ErrorEnvelope
delete /messages/{uuid}
Delete a message
Requires authentication
Tombstones the message: the row and its `seq` survive so no client's cursor develops a hole, the body is withheld from every response, and the tombstone records who deleted it and why. The author may delete their own; deleting someone else's requires chat.manage on the channel. Not idempotent — deleting an already-deleted message is a 404, so a second delete cannot overwrite who moderated it first.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Message uuid |
Responses
- 200 OK · object
- 400 Bad Request · apimodel.ErrorEnvelope
- 401 Unauthorized · apimodel.ErrorEnvelope
- 403 Forbidden · apimodel.ErrorEnvelope
- 404 Not Found · apimodel.ErrorEnvelope
post /presence/heartbeat
Report that the caller is still here
Requires authentication
Stamps the caller's presence. Send roughly every 30 seconds while the client is focused; a heartbeat older than 90 seconds resolves to offline. Does NOT clear a manual status — somebody on do-not-disturb is still heartbeating, and treating that as an intention to come back would make the setting impossible to keep.
Responses
- 204 No Content
- 401 Unauthorized · apimodel.ErrorEnvelope
patch /presence/status
Set or clear a manual presence status
Requires authentication
`status` is `active`, `away` or `dnd`, or empty to clear it and fall back to inferring from the heartbeat. A stated status always wins over inference. `offline` is deliberately NOT accepted — appearing offline while connected is a separate feature with its own rules for notifications and read receipts, and quietly accepting it here would ship half of it by accident.
Request body: dto.PresenceStatusRequest
| Name | Type | Required | Description |
|---|---|---|---|
| status | string | no | Status is `active`, `away`, `dnd`, or "" to clear the manual override and fall back to inferring presence from the heartbeat. |
Responses
- 204 No Content
- 400 Bad Request · apimodel.ErrorEnvelope
- 401 Unauthorized · apimodel.ErrorEnvelope
get /projects/{id}/comments
List a project's General chat messages
Requires authentication
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | integer | yes | Project id |
Responses
- 200 OK · object
- 400 Bad Request · apimodel.ErrorEnvelope
- 403 Forbidden · apimodel.ErrorEnvelope
- 404 Not Found · apimodel.ErrorEnvelope
post /projects/{id}/comments
Post to a project's General chat
Requires authentication
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | integer | yes | Project id |
Request body: apimodel.CreateCommentRequest
| Name | Type | Required | Description |
|---|---|---|---|
| content | string | no |
Responses
- 201 Created · object
- 400 Bad Request · apimodel.ErrorEnvelope
- 403 Forbidden · apimodel.ErrorEnvelope
get /projects/{id}/conversations
List a project's conversation threads
Requires authentication
The project's General chat row plus every task thread. Unread threads first, most unread first; the rest by most-recent activity.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | integer | yes | Project id |
Responses
- 200 OK · object
- 400 Bad Request · apimodel.ErrorEnvelope
- 403 Forbidden · apimodel.ErrorEnvelope
- 404 Not Found · apimodel.ErrorEnvelope