Discord API
Discord channels that follow a workspace, and the routes the Discord bot calls for them.
All paths are relative to the API origin. Send Authorization: Bearer <token> unless a route says otherwise; see the API overview for tokens and errors.
GET /v1/workspaces/:slug/discord
Members; the Discord channels that follow this workspace
Response
| Field | Type | Required | Notes |
|---|---|---|---|
channels | object[] | yes | |
spaces | object[] | no |
PUT /v1/workspaces/:slug/discord/:channelId
Admin+; changes what the channel follows in this workspace
Body
| Field | Type | Required | Notes |
|---|---|---|---|
spaceIds | string[] | null | yes |
Response: 204, no body
DELETE /v1/workspaces/:slug/discord/:channelId
Admin+; the channel stops following this workspace
Response: 204, no body
GET /v1/discord/connects/:userCode
Clerk session only; a /cloudtifact request from a Discord channel, and your workspaces to share with it
Response
| Field | Type | Required | Notes |
|---|---|---|---|
userCode | string | yes | |
status | "pending" | "approved" | "denied" | "expired" | yes | |
expiresAt | number | yes | |
guildName | string | yes | |
channelName | string | yes | |
askedBy | string | yes | |
workspaces | object[] | yes | |
others | object[] | yes |
POST /v1/discord/connects/:userCode/decide
Clerk session only; approving sets what the channel follows in the workspaces you administer
Body
| Field | Type | Required | Notes |
|---|---|---|---|
approve | boolean | yes | |
workspaces | object[] | no (default []) |
Response: 204, no body
POST /v1/discord/connects
Bot only (DISCORD_BOT_HEADER; 404 without it)
Body
| Field | Type | Required | Notes |
|---|---|---|---|
guildId | string | yes | |
guildName | string | yes | |
channelId | string | yes | |
channelName | string | yes | |
user | object | yes |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
userCode | string | yes | |
url | string | yes | |
expiresIn | integer | yes |
GET /v1/discord/channels/:channelId
Bot only
Response
| Field | Type | Required | Notes |
|---|---|---|---|
connected | boolean | yes | |
workspaces | object[] | yes |
DELETE /v1/discord/channels/:channelId
Bot only; disconnects the channel from everything
Body
| Field | Type | Required | Notes |
|---|---|---|---|
user | object | yes |
Response: 204, no body
GET /v1/discord/channels/:channelId/spaces
Bot only; the spaces the channel follows, newest version first
Query
| Field | Type | Required | Notes |
|---|---|---|---|
q | string | no | |
limit | integer | no (default 25) |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
spaces | object[] | yes |
GET /v1/discord/channels/:channelId/spaces/:id/threads
Bot only; a followed space's open threads, and its home
Response
| Field | Type | Required | Notes |
|---|---|---|---|
space | object | yes | |
linked | string[] | yes | |
home | object | null | yes | |
threads | object[] | yes |
POST /v1/discord/channels/:channelId/spaces/:id/home
Bot only; the followed space's news goes to this channel only
Body
| Field | Type | Required | Notes |
|---|---|---|---|
user | object | yes |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
space | object | yes | |
previous | object | null | yes |
POST /v1/discord/channels/:channelId/main
Bot only; the main channel of every workspace it follows: spaces without a home post here
Body
| Field | Type | Required | Notes |
|---|---|---|---|
user | object | yes |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
workspaces | string[] | yes |
GET /v1/discord/channels/:channelId/info
Bot only; the spaces linked to a thread, the spaces that post in this channel, and how many post elsewhere
Query
| Field | Type | Required | Notes |
|---|---|---|---|
threadId | string | no |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
thread | object[] | yes | |
here | object[] | yes | |
hereTotal | integer | yes | |
main | integer | yes | |
elsewhere | integer | yes |
POST /v1/discord/channels/:channelId/comments
Bot only; a comment written in Discord, as a guest named after the Discord user, via "discord"
Body
| Field | Type | Required | Notes |
|---|---|---|---|
spaceId | string | yes | |
parentId | string | no | |
body | string | yes | |
author | object | yes |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | |
threadId | string | yes | |
spaceId | string | yes |
POST /v1/discord/channels/:channelId/comments/:id/resolve
Bot only; resolves a thread on a followed space
Body
| Field | Type | Required | Notes |
|---|---|---|---|
user | object | yes |
Response: 204, no body
POST /v1/discord/channels/:channelId/links
Bot only; links a thread (or the channel) to a followed space and makes it the space's home
Body
| Field | Type | Required | Notes |
|---|---|---|---|
spaceId | string | yes | |
threadId | string | yes | |
threadName | string | yes | |
user | object | yes |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
space | object | yes | |
previous | object | null | yes |
POST /v1/discord/channels/:channelId/spaces
Bot only; makes an empty members-only space in the channel's first workspace, with the thread linked as its home (20 a day per channel). A thread that already has a space gets that one back, with existing: true
Body
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | yes | |
threadId | string | yes | |
threadName | string | yes | |
user | object | yes |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
space | object | yes | |
existing | boolean | yes |
DELETE /v1/discord/channels/:channelId/links
Bot only; unlinks it; if it was the space's home, the space posts in the main channel again
Body
| Field | Type | Required | Notes |
|---|---|---|---|
spaceId | string | yes | |
threadId | string | yes | |
threadName | string | yes | |
user | object | yes |
Response: 204, no body
GET /v1/spaces/:id/discord
Push access; the Discord threads linked to this space
Response
| Field | Type | Required | Notes |
|---|---|---|---|
links | object[] | yes |
GET /v1/spaces/:id/discord/:threadId
Push access; the linked thread's messages, read from Discord now and not stored; + liveUrl
Query
| Field | Type | Required | Notes |
|---|---|---|---|
all | "1" | "true" | no |
Response
| Field | Type | Required | Notes |
|---|---|---|---|
link | object | yes | |
messages | object[] | yes | |
more | boolean | yes | |
liveUrl | string | no |
DELETE /v1/spaces/:id/discord/:threadId
Push access; unlinks the thread; if it was the space's home, the space posts in the main channel again
Response: 204, no body