Teams & Applications

Endpoints for building bots. A team owns applications, and an application can have one bot user and slash command manifests, and receives interactions. The objects are described in Team & Application Resources.

Notes

Team, application and bot endpoints are human-only. Except for the team invite endpoints (/api/users/@me/team-invites), they also need a verified email: otherwise they answer 403 with {"error": "email must be verified to access developer features"}.
A team has one admin, the user who created it (role 0). Invited users join as members (role 1). Members can list the team’s members, applications and commands; the rest needs the admin. Renaming or deleting the team also needs its owner.
In paths with a {teamId}, the API answers 403 with not a team member or not a team admin when you lack the role, and 404 with application not found when the application isn’t in that team.
Bots authenticate with Authorization: Bot <token>, and send the same token in the gateway identify. The token is only shown when the bot is created or its token is reset.
The command endpoints and Get Next Interaction also accept the application’s own bot, and don’t need a verified email.

Teams

Create Team

POST /api/users/@me/teams

Create a team. You become its owner and its admin.

JSON Body

Field	Type	Description
`name`	`string`	Team name

Returns: 201 Created with a Team object.

List Teams

GET /api/users/@me/teams

List the teams you belong to, newest first.

Returns: Array of Team objects.

Update Team

PATCH /api/users/@me/teams/{teamId}

Rename a team. Only its owner can.

JSON Body

Field	Type	Description
`name`	`string`	New team name

Returns: Team object.

Delete Team

DELETE /api/users/@me/teams/{teamId}

Delete a team. Only its owner can. Its applications go too, with their bots and command manifests, and so do its members and pending invites.

Returns: 204 No Content

List Team Members

GET /api/users/@me/teams/{teamId}/members

List a team's members. Any member can.

Returns: Array of Team Member objects.

Invite to Team

POST /api/users/@me/teams/{teamId}/invites

Invite a user to the team by email. Admin only. The invited user receives a TEAM_INVITE_CREATE event. Answers 404 when no account has that email, and 400 for a bot account.

JSON Body

Field	Type	Description
`email`	`string`	Email of the user to invite

Returns: 201 Created with a Team Invite object.

Remove Team Member

DELETE /api/users/@me/teams/{teamId}/members/{userId}

Remove a member from the team. Admin only; you can't remove yourself (400) or the team's owner (403). A removed member can join again with a new invite.

Returns: 204 No Content

Team Invites

These don’t need a verified email.

List My Team Invites

GET /api/users/@me/team-invites

List the team invites you've received, newest first.

Returns: Array of Pending Team Invite objects.

Accept Team Invite

POST /api/users/@me/team-invites/{inviteId}/accept

Accept an invite and join the team as a member. Answers 404 with team invite not found when the invite doesn't exist or isn't yours.

Returns: 204 No Content

Decline Team Invite

POST /api/users/@me/team-invites/{inviteId}/decline

Decline and delete an invite. Answers 404 with team invite not found when the invite doesn't exist or isn't yours.

Returns: 204 No Content

Applications

Create Application

POST /api/users/@me/teams/{teamId}/applications

Create an application in the team. Admin only.

JSON Body

Field	Type	Description
`name`	`string`	Application name
`description` ?	`string?`	Application description

Returns: 201 Created with an Application object.

List Applications

GET /api/users/@me/teams/{teamId}/applications

List the team's applications. Any member can.

Returns: Array of Application objects.

Update Application

PATCH /api/users/@me/teams/{teamId}/applications/{appId}

Update an application. Admin only. Fields you omit or send as null keep their value, so the description and the icon can't be cleared.

JSON Body

Field	Type	Description
`name` ?	`string`	Application name
`description` ?	`string`	Application description
`icon` ?	`string`	Icon, stored as given
`public` ?	`boolean`	Whether anyone with ManageBots can add the bot to their space

Returns: Application object.

Delete Application

DELETE /api/users/@me/teams/{teamId}/applications/{appId}

Delete an application. Admin only. Its bot is deleted too, as in Delete Bot, and so are its command manifests.

Returns: 204 No Content

Bot

All bot endpoints are admin only. Except for Create Bot, they answer 404 with application has no bot when the application has none.

Create Bot

POST /api/users/@me/teams/{teamId}/applications/{appId}/bot

Create the application's bot user. Its username is the application name with spaces replaced by -, cut to 32 characters. Answers 409 when the application already has a bot.

Returns: 201 Created with an object containing the bot token (string). The token is only shown here and when it's reset.

{ "token": "3f9c1a..." }

Update Bot

PATCH /api/users/@me/teams/{teamId}/applications/{appId}/bot

Update the bot's profile. Uploaded images are stored in your active storage bucket: uploading one without a bucket answers 403.

Multipart Body

Field	Type	Description
`username` ?	`string`	New username; longer values are cut to 32 characters
`alias` ?	`string`	New display name; an empty value removes it
`avatar` ?	`file`	Avatar image, up to 10 MB
`banner` ?	`file`	Banner image, up to 10 MB
`remove_avatar` ?	`string`	Set to "true" to remove the avatar
`remove_banner` ?	`string`	Set to "true" to remove the banner

Returns: The bot's User object.

Errors: 409 with that username is taken when another account has the username; 413 for an image over 10 MB or over your upload limit.

Reset Bot Token

POST /api/users/@me/teams/{teamId}/applications/{appId}/bot/reset-token

Replace the bot's token. The old one stops working right away, and the bot's open gateway connections are closed with code 4004.

Returns: Object containing the new token (string).

{ "token": "8b2e7d..." }

Delete Bot

DELETE /api/users/@me/teams/{teamId}/applications/{appId}/bot

Delete the bot user. It leaves every space (each one gets a SPACE_MEMBER_REMOVE event) and its gateway connections are closed with code 4004.

Returns: 204 No Content

Application Commands

Slash command manifests. Team members and the application’s bot can read them; creating, updating and deleting them needs the team admin or the bot.

List Commands

GET /api/users/@me/teams/{teamId}/applications/{appId}/commands

List the application's command manifests, newest first.

Returns: Array of Application Command objects.

Create Command

POST /api/users/@me/teams/{teamId}/applications/{appId}/commands

Create a command manifest.

JSON Body

Field	Type	Description
`name`	`string`	Manifest name, not blank and unique within the application
`description` ?	`string`	Manifest description
`commands`	SlashCommandData[]	The slash commands (may be empty)

Returns: 201 Created with an Application Command object.

Errors: 400 with invalid command name for a blank name; 409 with the application already has a command manifest with that name.

Get Command

GET /api/users/@me/teams/{teamId}/applications/{appId}/commands/{commandId}

Get a command manifest. Answers 404 when the application doesn't have it.

Returns: Application Command object.

Update Command

PATCH /api/users/@me/teams/{teamId}/applications/{appId}/commands/{commandId}

Update a command manifest. Fields you omit keep their value. A null description removes it, and null commands empty the list; the name can't be null.

JSON Body

Field	Type	Description
`name` ?	`string`	Manifest name
`description` ?	`string?`	Manifest description
`commands` ?	SlashCommandData[]?	Replaces the whole list

Returns: Application Command object, with a new version.

Errors: 400 with invalid command name for a blank name; 404 when the application doesn't have the manifest; 409 with the application already has a command manifest with that name.

Delete Command

DELETE /api/users/@me/teams/{teamId}/applications/{appId}/commands/{commandId}

Delete a command manifest.

Returns: 204 No Content

Interactions

A user’s client creates an interaction, and the application’s bot (or a member of its team) picks it up with Get Next Interaction. Queued interactions expire 5 minutes after the last one was queued for that application.

Create Interaction

POST /api/interactions

Send an interaction to an application. Human-only.

JSON Body

Field	Type	Description
`application_id`	`string`	The application that should receive it
`type`	`integer`	0 = command, 1 = input from a component
`context`	`integer`	0 = space, 1 = private chat with the bot, 2 = private room
`slash_command` ?	SlashCommandData	The invoked command, for type 0
`input_data` ?	InteractionInputData	The component input, for type 1
`space_id` ?	`string`	The space it happened in. Required for context 0. You must be a member, and the application's bot must be in the space
`room_id` ?	`string`	The room it happened in. Needs space_id; the room must be in that space and visible to you

Errors

400 for an invalid body, a missing space_id for context 0, a room_id without space_id, or a bot that isn't in the space. 403 when you aren't a member of the space or can't view the room. 404 when the application or the room doesn't exist.

Returns: 202 Accepted with the queued Interaction object. With a space_id, it includes your member and the space, and the room when you send one.

Get Next Interaction

GET /api/applications/{appId}/interactions/next

Wait for the application's next interaction. Callable by the application's bot or a member of its team. Answers as soon as one is queued, or after 20 seconds without one (3 seconds with ?wait=short). Limited to 600 requests per minute instead of the per-route limit.

Query Parameters

Field	Type	Description
`wait` ?	`string`	"short" to wait 3 seconds instead of 20

Returns: An Interaction object, or 204 No Content when none arrived in time.