Chat

Knobs Chat has public channels, private channels, and DMs/group DMs, with threads, reactions, pins, mentions, attachments, and per-user read state. The REST API covers all of it; live updates stream to the apps over the realtime layer, so a polling client should re-list on an interval instead.

All routes are workspace-scoped and accept a session JWT or API key. Private-channel and DM content is roster-gated: non-members get 404.

Channels & DMs

Endpoint	Description
`GET /v1/workspaces/{wid}/chat/channels`	Channels you can see (public + your private/DM roster) with read state
`POST /v1/workspaces/{wid}/chat/channels`	Create `{name, topic?, kind: ""\|"channel"\|"private", memberUids?}`
`GET /v1/workspaces/{wid}/chat/channels/{cid}`	Channel detail incl. roster + pins
`PATCH /v1/workspaces/{wid}/chat/channels/{cid}`	Rename / edit topic `{name?, topic?}`
`POST /v1/workspaces/{wid}/chat/channels/{cid}/archive`	Archive
`POST /v1/workspaces/{wid}/chat/channels/{cid}/unarchive`	Unarchive
`POST /v1/workspaces/{wid}/chat/channels/{cid}/members`	Add members `{memberUids}` (private channels)
`DELETE /v1/workspaces/{wid}/chat/channels/{cid}/members/{uid}`	Remove a member, or leave (your own uid). Not on DMs — DM rosters are immutable
`POST /v1/workspaces/{wid}/chat/dms`	Open (get-or-create) the DM/group DM for `{memberUids}` — deterministic id, so it’s idempotent

Messages

Endpoint	Description
`GET /v1/workspaces/{wid}/chat/channels/{cid}/messages`	Windowed history, oldest first; `?limit=`, `?before=<messageId>` cursor, `?threadId=` for a thread panel
`POST /v1/workspaces/{wid}/chat/channels/{cid}/messages`	Send a message
`GET /v1/workspaces/{wid}/chat/messages/{mid}`	Resolve one message by id (includes its `channelId`)
`PATCH /v1/workspaces/{wid}/chat/channels/{cid}/messages/{mid}`	Edit `{text, mentions?}` (author only)
`DELETE /v1/workspaces/{wid}/chat/channels/{cid}/messages/{mid}`	Tombstone-delete

Send a message

curl -X POST https://api.knobs.io/v1/workspaces/{wid}/chat/channels/{cid}/messages \
  -H "Authorization: Bearer knak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Build is green @sam",
    "clientMutationId": "7be1e0a2-9d3a-4a5e-a6cf-2f24c5f81b30",
    "mentions": [{"uid": "u_5ac2…", "start": 15, "length": 4}],
    "threadId": "",
    "attachments": ["n_77aa…"]
  }'

Returns 201 with the message. clientMutationId is required — retries with the same id return the original message instead of duplicating. threadId posts into a thread (set alsoSendToChannel: true to mirror it to the channel); attachments are Drive node ids.

Reactions & pins

Reaction add/remove are idempotent — never a toggle.

Endpoint	Description
`POST /v1/workspaces/{wid}/chat/channels/{cid}/messages/{mid}/reactions`	Add `{emoji}` (shortcode, e.g. `"+1"`)
`DELETE /v1/workspaces/{wid}/chat/channels/{cid}/messages/{mid}/reactions/{emoji}`	Remove your reaction
`GET /v1/workspaces/{wid}/chat/channels/{cid}/messages/{mid}/reactions`	List who reacted
`POST /v1/workspaces/{wid}/chat/channels/{cid}/messages/{mid}/pin`	Pin in the channel
`POST /v1/workspaces/{wid}/chat/channels/{cid}/messages/{mid}/unpin`	Unpin

Read state

Endpoint	Description
`POST /v1/workspaces/{wid}/chat/channels/{cid}/mark-read`	`{lastReadMessageId}` — advance your read marker, zero the mention badge
`GET /v1/workspaces/{wid}/chat/read-state`	Your read markers across all channels

Attachments

Attachment access rides the channel ACL (if you can read the message, you can fetch its attachments):

Endpoint	Description
`GET /v1/workspaces/{wid}/chat/channels/{cid}/messages/{mid}/attachments/{nid}/download`	`302` redirect to a signed download URL
`GET /v1/workspaces/{wid}/chat/channels/{cid}/messages/{mid}/attachments/{nid}/preview`	`302` redirect to a signed preview (thumbnail) URL

Use curl -L to follow the redirect.

@Web runs

@Web performs a grounded, cited web search and stores the run. Runs invoked inside a private channel inherit that channel’s ACL.

Endpoint	Description
`POST /v1/workspaces/{wid}/web-runs`	Invoke workspace-level `{query}` → `201` with the run
`POST /v1/workspaces/{wid}/chat/channels/{cid}/web-runs`	Invoke in a channel context
`GET /v1/workspaces/{wid}/chat/web-runs`	List runs you can see
`GET /v1/workspaces/{wid}/chat/web-runs/{rid}`	One run — answer + citations
`POST /v1/workspaces/{wid}/chat/web-runs/{rid}/rerun`	Re-execute the same query → a new run

curl -X POST https://api.knobs.io/v1/workspaces/{wid}/web-runs \
  -H "Authorization: Bearer knak_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "latest Go release notes"}'

Slash commands & bots

Members invoke slash commands with POST /v1/workspaces/{wid}/chat/channels/{cid}/commands; bots post via the token-authed bot API. Both are documented on Integrations & webhooks.