Skip to content

All resources

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

NameInTypeRequiredDescription
uuidpathstringyesChannel uuid

Request body: object

NameTypeRequiredDescription
filestring (binary)yesFile 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

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

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

NameInTypeRequiredDescription
uuidpathstringyesChannel uuid
beforequeryintegernoReturn messages with seq strictly below this, newest first. Omit for the newest page. Mutually exclusive with after.
afterqueryintegernoReturn messages with seq strictly above this, oldest first. Mutually exclusive with before.
limitqueryintegernoPage size (default 50, max 199)
topicquerystringnoTopic 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

NameInTypeRequiredDescription
uuidpathstringyesChannel uuid

Request body: dto.SendMessageRequest

NameTypeRequiredDescription
attachmentUuidsstring[]noAttachmentUUIDs 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.
bodystringnoBody is the message text.
contentTypestringnoContentType is "text" (default) or "markdown".
replyToUuidstringnoReplyToUUID 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.
topicUuidstringnoTopicUUID 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.
uuidstringnoUUID 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

NameInTypeRequiredDescription
uuidpathstringyesChannel uuid
messageUuidpathstringyesMessage uuid

Request body: dto.ReactionRequest

NameTypeRequiredDescription
emojistringnoEmoji 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

NameInTypeRequiredDescription
uuidpathstringyesChannel uuid
messageUuidpathstringyesMessage uuid
emojipathstringyesEmoji shortcode
limitqueryintegernoMax 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

NameInTypeRequiredDescription
uuidpathstringyesChannel uuid
messageUuidpathstringyesMessage uuid
emojipathstringyesEmoji 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

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

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

NameInTypeRequiredDescription
uuidpathstringyesAttachment uuid
tokenquerystringyesSignature from the signed-url endpoint
expqueryintegeryesExpiry 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

NameTypeRequiredDescription
levelstringnoLevel 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

NameInTypeRequiredDescription
channelUuidpathstringyesChannel uuid

Request body: dto.ChatNotificationChannelRequest

NameTypeRequiredDescription
levelstringnoLevel 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

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

NameTypeRequiredDescription
projectIdintegerno
taskNumberintegerno

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

NameInTypeRequiredDescription
beforequeryintegernoKeyset cursor: id of the oldest row already seen
limitqueryintegernoPage size (default 30, max 100)
unreadquerybooleannoOnly 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

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

NameInTypeRequiredDescription
uuidpathstringyesMessage uuid

Request body: dto.EditMessageRequest

NameTypeRequiredDescription
bodystringno

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

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

NameTypeRequiredDescription
statusstringnoStatus 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

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

NameInTypeRequiredDescription
idpathintegeryesProject id

Request body: apimodel.CreateCommentRequest

NameTypeRequiredDescription
contentstringno

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

NameInTypeRequiredDescription
idpathintegeryesProject id

Responses

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