API reference

Who this credential is

GET /v1/me

Needs: identify (every token has it)

The person or bot, the orgs it may act in (with roles) and its scopes. Needs no scope.

Your local date and time context

GET /v1/me/context

Needs: identify (every token has it)

People only. Uses the last remembered browser zone from flash-card or portal reminder preferences; no saved zone means null local fields, not a guessed UTC zone. time_zone may supply a zone the person gave, without saving it. Week start comes from the selected workspace's scheduling settings (Monday when unset); without an org and with several reachable orgs it is the Monday default. Responses are not cached.

Your activity line

GET /v1/me/activity

Needs: identify (every token has it)

The opt-in status line next to your name ("Playing …", "Live on …"; INTEGRATIONS_PLAN §4.15). Null when none is set or it expired. Bots have none (403).

Set your activity line

POST /v1/me/activity

Needs: presence:write

Replaces the line. It lapses after ttl_seconds (default five minutes), so a desktop app posts again while the game runs and deletes it when it stops. Shown to others only while Settings → Connections → "Share my activity" is on; the answer's visible says whether it is. Rate limit: 60 a minute.

Request body (application/json, required): ActivityInput.

Clear your activity line

DELETE /v1/me/activity

Needs: presence:write

Orgs this credential may act in

GET /v1/orgs

Needs: identify (every token has it)

One org

GET /v1/orgs/{orgId}

Needs: identify (every token has it)

Change the word filter

PATCH /v1/orgs/{orgId}/word-filter

Needs: admin:write

Owners only, as Org Settings → Word filter: add or take off blocked words and allowed words (each up to 40 characters, up to 200 a list), or switch the profanity list. The lists are never read back — the answer is counts. The platform list always applies. Listed in the person's Activity with Undo while nobody has changed it since. People only.

Request body (application/json, required): object.

Hand a category to someone for a while

POST /v1/orgs/{orgId}/handoffs

Needs: admin:write

The app's category hand-off: whoever manages the category gives someone a role they may grant, until ends_at (within 90 days; default 14). Both are told. The note passes the word filter. Listed in the person's Activity with Undo (the hand-off ends). People only.

Request body (application/json, required): object.

Categories shared with other workspaces

GET /v1/orgs/{orgId}/category-shares

Needs: admin:read

Owners and Admins: the shares this workspace hosts or takes part in (pending, active, paused) — which side, the other workspace's name, the channels that cross and a waiting request's check words. Never a person or an email address. People only.

Ask to share a category with another workspace

POST /v1/orgs/{orgId}/category-shares

Needs: invites:write

Owners and Admins, where the plan includes synced categories. With the outward scope a personal token creates the invitation directly (201), unless the Owner enabled assistant ask-first (202, password confirmation in Missived). The partner Admin must still accept with step-up. Supply partner_name (full name) and company_name (workspace display name) exactly as the person provided them; these recorded labels form the Activity notice and result summary. Never guessed or resolved through an account directory. Undo cancels a pending invitation or ends an accepted share through the normal step-up/reason flow. By email, or code: true for a one-time code returned directly (ask-first: shown only on the confirm screen). People only.

Request body (application/json, required): object.

What became of a request that waited

GET /v1/pending-actions/{id}

Needs: invites:write

A request answered with pending_confirmation: pending, confirmed, declined, expired or failed. The credential's own person's requests only. There is no way to confirm one over the API. People only.

What the workspace has on

GET /v1/orgs/{orgId}/features

Needs: identify (every token has it)

Each optional feature: whether the plan includes it, whether an Owner or Admin switched it off, and so whether it is on. Switching is PATCH (admin:write).

Switch features on or off

PATCH /v1/orgs/{orgId}/features

Needs: admin:write

Owners and Admins, as Org Settings → Features: switching off hides, nothing is deleted. Unknown keys are refused. Made with a personal token or a person's connection, it is listed in the person's Activity with Undo. People only.

Request body (application/json, required): object.

Channels visible to this credential

GET /v1/orgs/{orgId}/channels

Needs: channels:read

Everything the person can see in the app (DMs and group chats only for a session, or a personal token with “Include my direct messages”). An app sees the org's public text channels plus any its token names. Returned in one page (next_cursor is null).

Create a text channel

POST /v1/orgs/{orgId}/channels

Needs: channels:write

The same rules as the app's create card: Owners and admins (or a member of a workspace category that lets its members create channels), a person's session or personal token. The name and topic pass the workspace's word filter; kind makes a prayer, flash-card, Table, forum, looking-for-group or Bible study channel when the plan includes it and the workspace hasn't switched it off. Apps can't create channels yet.

Request body (application/json, required): NewChannel.

One channel

GET /v1/channels/{channelId}

Needs: channels:read

Rename a channel or set its topic

PATCH /v1/channels/{channelId}

Needs: channels:write

The app's rules (lib/channels/update.ts): a rename by the channel's creator, its managers or the org's admins (lowercase letters, numbers, hyphens); the topic by owners and admins (empty or null clears it). Both pass the word filter. Never a DM, group chat or personal channel. People only.

Request body (application/json, required): object.

Delete a channel

DELETE /v1/channels/{channelId}

Needs: admin:write

The app's delete (lib/channels/delete.ts): its creator, an Owner / Admin or Manage channel; never a DM, group chat, personal channel or #general (400), never a shared channel (409 shared_channel). Messages, threads and files go; everyone who wrote there is told. Fires channel.deleted. Not reversible. Made with a personal token or a person's connection, it is listed in the person's Activity. People only.

Who can see a channel

GET /v1/channels/{channelId}/members

Needs: members:read

The sidebar's categories and groups

GET /v1/orgs/{orgId}/categories

Needs: channels:read

The categories this person sees (a category whose every channel is hidden from them is left out; a Guest sees only their own workspace categories), each with the ids of its channels they see. People only.

Create a category

POST /v1/orgs/{orgId}/categories

Needs: channels:write

At the end of the sidebar. Owners and admins; the name passes the word filter. People only.

Request body (application/json, required): object.

Delete a category

DELETE /v1/orgs/{orgId}/categories/{categoryId}

Needs: admin:write

Its creator or an Owner / Admin. Its channels stay, uncategorised; its Guests lose it and are told. Never a client portal's (409 portal_category) or a shared one (409 shared_category). Made with a personal token or a person's connection, it is listed in the person's Activity. People only.

Group categories in the sidebar

POST /v1/orgs/{orgId}/category-groups

Needs: channels:write

Owners, admins and people with Manage channels. A category moves out of any group it was in. People only.

Request body (application/json, required): object.

The org's installed apps

GET /v1/orgs/{orgId}/apps

Needs: identify (every token has it)

A person sees every installed app; an app token sees only its own install. Needs no scope.

One installed app

GET /v1/orgs/{orgId}/apps/{installId}

Needs: identify (every token has it)

The channels an app was added to

GET /v1/orgs/{orgId}/apps/{installId}/channels

Needs: channels:read

Only the ones this credential may view.

Add an app to a channel

PUT /v1/channels/{channelId}/apps/{installId}

Needs: channels:write

Owner decision D4: an app reads message content only in channels it was added to. A person who manages the channel (or the org's integrations) adds it; an app token can't. Never a DM, group chat, personal channel or meal train (D3). 201 when added, 200 when it was already there.

Remove an app from a channel

DELETE /v1/channels/{channelId}/apps/{installId}

Needs: channels:write

A person who manages the channel, or the app itself leaving. Its token stops reading the channel at once; its event subscriptions no longer receive the channel's events.

The slash commands apps registered in an org

GET /v1/orgs/{orgId}/commands

Needs: identify (every token has it)

An app token sees its own; a person sees every installed app's. People run them from the composer's / picker in channels the app is in (D4), subject to each command's permission.

Register a slash command

POST /v1/orgs/{orgId}/commands

Needs: commands:write

App tokens only (commands:write). At most 50 per app. 409 when the app already has that name in that scope.

Request body (application/json, required): CommandDraft.

Replace all of the app's commands

PUT /v1/orgs/{orgId}/commands

Needs: commands:write

Bulk overwrite, as Discord's: the list becomes the app's whole set (rows with the same name and scope are updated in place, the rest deleted, new ones created). App tokens only. Changes take effect at once; the web refreshes its picker.

Request body (application/json, required): array of CommandDraft.

One command

GET /v1/orgs/{orgId}/commands/{commandId}

Needs: identify (every token has it)

Change a command

PATCH /v1/orgs/{orgId}/commands/{commandId}

Needs: commands:write

Fields left out keep their value; the version bumps. App tokens only.

Request body (application/json, optional): CommandDraft.

Remove a command

DELETE /v1/orgs/{orgId}/commands/{commandId}

Needs: commands:write

Send a follow-up message

POST /v1/interactions/{token}/messages

Needs: No bearer token

Posted in the channel as the app's bot, within 15 minutes of the interaction (at most 20). With flags: 64 it is a private reply only the invoker sees (an EphemeralMessage, delivered to their screens and kept 15 minutes, never in search or events). Send Idempotency-Key to deduplicate retries. Authenticated by the token in the path; exempt from the app's chat budget.

Request body (application/json, required): InteractionReply.

Edit the original reply

PATCH /v1/interactions/{token}/messages/@original

Needs: No bearer token

Replaces the app's reply — after a deferred answer (type: 5) the “thinking…” placeholder, after a component update (type: 6 / 7) the message the component is on, after a private reply that reply — with this content, embeds and/or components (a field left out keeps its value).

Request body (application/json, required): InteractionReply.

Delete the original reply

DELETE /v1/interactions/{token}/messages/@original

Needs: No bearer token

Upload a file to attach to a message

POST /v1/orgs/{orgId}/files

Needs: files:write

multipart/form-data with one part named file (its filename and Content-Type are kept). The file is stored encrypted at rest and counts against the org's storage; it is pending until you post it with attachment_ids, and only this credential can attach it. At most 25 MB through the API; the composer's file types only.

Request body (multipart/form-data, required): object.

Download an attachment

GET /v1/attachments/{attachmentId}/content

Needs: messages:read

The bytes, decrypted, as Content-Disposition: attachment. An attached file is readable by whoever may read its channel's messages (apps: channels they were added to, or messages:read:all; never DMs); a pending upload only by its uploader. Anything else is 404.

A channel's messages

GET /v1/channels/{channelId}/messages

Needs: messages:read

Newest first by default. To follow a channel, use order=oldest: every non-empty page returns a next_cursor to resume from later. Apps read only channels their token names, unless they hold messages:read:all.

Post a message

POST /v1/channels/{channelId}/messages

Needs: messages:write

Posts as the person (their permissions, slow mode and AutoMod apply) or as the app's bot user (marked BOT; @mentions inert unless allowed_mentions allows them; may send embeds). Spends the chat budget: 20 posts per 10 seconds per person or bot.

Request body (application/json, required): NewMessage.

One message

GET /v1/channels/{channelId}/messages/{messageId}

Needs: messages:read

Edit your own message

PATCH /v1/channels/{channelId}/messages/{messageId}

Needs: messages:write

Only the author edits. An app may replace its embeds and components ([] removes them; a field left out keeps its value); link previews follow the new links.

Request body (application/json, required): MessageEdit.

Delete a message

DELETE /v1/channels/{channelId}/messages/{messageId}

Needs: messages:write

Your own, or — for a person with Manage messages there — anyone's (they're told). An app deletes only its own. Made with a personal token or a person's connection, it is listed in the person's Activity.

Search messages

GET /v1/orgs/{orgId}/messages/search

Needs: messages:read

Full-text search over the messages this credential may read in the org (the same rules as reading each channel: D3 for DMs, D4 for apps), best matches first. Sealed messages are matched through the workspace's encrypted index (every word, the last also as a prefix; no exact phrases). Pages by cursor up to 1,000 results deep.

A message's thread replies

GET /v1/channels/{channelId}/messages/{messageId}/replies

Needs: messages:read

Oldest first by default.

React to a message

PUT /v1/channels/{channelId}/messages/{messageId}/reactions/{emoji}

Needs: reactions:write

201 when added, 200 when you had already reacted with it.

Remove your reaction

DELETE /v1/channels/{channelId}/messages/{messageId}/reactions/{emoji}

Needs: reactions:write

An org's members

GET /v1/orgs/{orgId}/members

Needs: members:read

In joining order.

One member

GET /v1/orgs/{orgId}/members/{userId}

Needs: members:read

Make a member an Admin or a Member

PATCH /v1/orgs/{orgId}/members/{userId}

Needs: admin:write

The app's role change: Owners only; never ownership, never the Owner's own role, and Guest is set in the app. Made with a personal token or a person's connection, it is listed in the person's Activity with Undo. Fires member.role_changed. People only.

Request body (application/json, required): object.

Remove someone from the org

DELETE /v1/orgs/{orgId}/members/{userId}

Needs: admin:write

The app's removal: Owners and Admins (an Admin never an Owner or another Admin; the only Owner can't be removed). Access ends at once; their messages and files stay. Fires member.left. To bring them back, invite them again. Made with a personal token or a person's connection, it is listed in the person's Activity. People only.

Email someone an invitation

POST /v1/orgs/{orgId}/invites

Needs: invites:write

The app's email invite: Owners and Admins invite Members (Owners also Admins); a Guest is invited into one workspace category by an Owner, an Admin or the category's creator with Publish views, within the plan's guest seats. Single use, three days. The link goes only to the invitee by email and is never in the answer. Made with a personal token or a person's connection, it is listed in the person's Activity with Undo. Where the workspace's Owner asked, it waits for the person instead (202). People only.

Request body (application/json, required): object.

Give a member a custom role

PUT /v1/orgs/{orgId}/members/{userId}/roles/{roleId}

Needs: roles:write

Custom roles only — never the org role (Owner, Admin, Member, Guest). A person must be an Owner or Admin of the org. An app needs roles:write granted by an Owner or Admin, works only while the person who set it up is still one, and can't give a role that manages integrations. Giving a role the member already has changes nothing (200). Fires member.role_assigned.

Take a custom role away

DELETE /v1/orgs/{orgId}/members/{userId}/roles/{roleId}

Needs: roles:write

The same rules as giving it. A role the member doesn't have changes nothing (200). Fires member.role_removed. A linked-role rule may give it back on its next check.

An org's custom roles

GET /v1/orgs/{orgId}/roles

Needs: members:read

A person who shares an org with this credential

GET /v1/users/{userId}

Needs: members:read

Your meetings in an org

GET /v1/orgs/{orgId}/meetings

Needs: meetings:read

Meetings you organise, are invited to or approve. Upcoming ones soonest first; past ones latest first. Empty for an app.

Schedule a meeting

POST /v1/orgs/{orgId}/meetings

Needs: meetings:write

As the person the credential belongs to, who becomes its organiser (apps have no calendar: 403). The same rules as the app: invites go out by email with an .ics unless send_invites is false, outside guests only where the org allows them (external_not_allowed, 403), and meeting.scheduled fires. Errors carry the meeting's own codes: invalid_time, invalid_settings, too_many_invitees, invalid_request.

Request body (application/json, required): NewMeeting.

One of your meetings

GET /v1/meetings/{meetingId}

Needs: meetings:read

Change or reschedule a meeting

PATCH /v1/meetings/{meetingId}

Needs: meetings:write

Its organiser only (a personal token or a person's connection; 403 for apps and for anyone else who can see it). Fields left out keep their value. Moving it is allowed only before it starts. Invitees get an update email unless notify is false. Errors carry the meeting's own codes: invalid_time, invalid_settings, invalid_request.

Request body (application/json, optional): MeetingPatch.

Set who is invited

PUT /v1/meetings/{meetingId}/invitees

Needs: meetings:write

Its organiser only. The list replaces the current one: new people are invited (by email, with an .ics), people left out are sent a cancellation, and a changed role is applied. Outside guests need the org's permission (external_not_allowed, 403).

Request body (application/json, required): MeetingInviteesReplace.

Cancel a meeting

POST /v1/meetings/{meetingId}/cancel

Needs: meetings:write

Its organiser only, before it starts (409 once it is live: end it in the app). Invitees get a cancellation unless notify is false; meeting.cancelled fires.

Request body (application/json, optional): MeetingCancel.

Your published shifts

GET /v1/orgs/{orgId}/schedule/shifts

Needs: shifts:read

Overlapping the window, earliest first. Empty for an app.

The org's published events

GET /v1/orgs/{orgId}/schedule/events

Needs: shifts:read

Overlapping the window, earliest first.

Add a task to your list

POST /v1/me/tasks

Needs: tasks:write

A personal task, with an optional reminder the app delivers. Personal tokens and sessions only.

Request body (application/json, required): NewTask.

The org's audit log (OCSF)

GET /v1/orgs/{orgId}/audit-events

Needs: admin:read

Owners and admins: a session, or a personal token with admin:read. Newest first. Errors here are { "error": "…" }.

The audit log's action names

GET /v1/audit-events/actions

Needs: Any credential

The audit event shape

GET /v1/audit-events/schemas

Needs: Any credential

Audit-log destinations

GET /v1/orgs/{orgId}/log-destinations

Needs: A signed-in session (not a token)

Org Settings → Integrations uses this route. It takes a signed-in session of someone who may manage the org's integrations (Owner, Admin, or a custom role with Manage integrations); API tokens are not accepted yet.

Add an audit-log destination

POST /v1/orgs/{orgId}/log-destinations

Needs: A signed-in session (not a token)

Org Settings → Integrations uses this route. It takes a signed-in session of someone who may manage the org's integrations (Owner, Admin, or a custom role with Manage integrations); API tokens are not accepted yet.

Request body (application/json, optional): a JSON object, as the description says.

One audit-log destination

GET /v1/orgs/{orgId}/log-destinations/{id}

Needs: A signed-in session (not a token)

Org Settings → Integrations uses this route. It takes a signed-in session of someone who may manage the org's integrations (Owner, Admin, or a custom role with Manage integrations); API tokens are not accepted yet.

Change an audit-log destination

PATCH /v1/orgs/{orgId}/log-destinations/{id}

Needs: A signed-in session (not a token)

Org Settings → Integrations uses this route. It takes a signed-in session of someone who may manage the org's integrations (Owner, Admin, or a custom role with Manage integrations); API tokens are not accepted yet.

Request body (application/json, optional): a JSON object, as the description says.

Remove an audit-log destination

DELETE /v1/orgs/{orgId}/log-destinations/{id}

Needs: A signed-in session (not a token)

Org Settings → Integrations uses this route. It takes a signed-in session of someone who may manage the org's integrations (Owner, Admin, or a custom role with Manage integrations); API tokens are not accepted yet.