REST: Bots
Managing bot accounts, roles and tokens (Owner or Manage bots). Generated from mnema-talk v3.3.13 (cca4f0fdb723).
List bots
GET /api/admin/bots
Owner or Manage bots. Bots the caller outranks or not alike are all listed; changing one needs a higher role than the bot's.
Authentication: Session cookie
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Bots, oldest first. | Bot[] |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage bots permission. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Create a bot
POST /api/admin/bots
Owner or Manage bots. The bot starts with no role, no intents and no token: it can do nothing until an admin gives it roles and a token. At most 50 bots.
Authentication: Session cookie
Request body (application/json, required): CreateRequest
| Field | Type | Description |
|---|---|---|
allowed_intents | integer | AllowedIntents defaults to none. |
name (required) | string |
Responses
| Status | Meaning | Body |
|---|---|---|
| 201 | Created. | Bot |
| 400 | Invalid input (INVALID_INPUT). | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage bots permission, or cross-origin request rejected. | ErrorResponse |
| 409 | CONFLICT: the bot limit is reached. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Bot
| Field | Type | Description |
|---|---|---|
allowed_intents (required) | integer | AllowedIntents are the gateway intents the bot may ask for. |
avatar_url | string | AvatarURL is the API URL of the avatar; omitted when none. |
created_at (required) | string (date-time) | |
created_by | string (uuid) | |
description | string | Description and Homepage come from the manifest the bot was added from; omitted for a bot created by hand. |
disabled (required) | boolean | Disabled bots cannot use any token or gateway connection. |
homepage | string | |
id (required) | string (uuid) | |
last_active_at | string (date-time) | |
name (required) | string | |
role_ids (required) | string (uuid)[] | RoleIDs are the bot's roles, highest first; its permissions come from them and from channel overwrites, never from @everyone. |
user_id (required) | string (uuid) |
Add a bot from a manifest
POST /api/admin/bots/install
Owner or Manage bots. In one transaction under the permission lock: creates the bot with the manifest's name, description and homepage and the kept intents, allows the kept permissions to the bot's own role in each listed channel (nothing server-wide), or, with access "all", gives them to the bot's own role server-wide, so the bot works in every channel plain members can see (a channel they cannot see stays hidden from it unless it is listed), registers the manifest's commands and issues a token named after the bot, whose secret is in the answer and shown only once. The kept permissions and intents must be the manifest's; in each channel the installer must hold every kept permission (the Owner holds all), and with access "all" the installer must hold them in every channel the bot reaches. Anything refused creates nothing. Logged as bot.installed.
Authentication: Session cookie
Request body (application/json, required): InstallRequest
| Field | Type | Description |
|---|---|---|
access | string | Access is "channels" (the default: the kept permissions only in the listed channels) or "all" (the kept permissions in every channel, held server-wide by the bot's own role; a channel plain members cannot see stays hidden unless it is listed). |
channel_ids (required) | string (uuid)[] | ChannelIDs are the channels the bot may work in (none: it sees nothing yet); with access "all" the private channels it may also see. Each must be a channel the installer can view. |
intents (required) | string[] | Intents are names from the manifest's intents; none means none. |
manifest (required) | Manifest | |
permissions (required) | string[] | Permissions are keys from the manifest's permissions; none means none. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 201 | Added; the token's secret is shown once. | InstallResponse |
| 400 | INVALID_INPUT: the manifest is invalid, or a kept permission or intent is not in it; the message names it. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage bots permission, a kept permission the installer lacks in a listed channel (the message names both), or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: a listed channel does not exist, is not a channel, or the installer cannot view it. | ErrorResponse |
| 409 | CONFLICT: the bot limit is reached, or a listed channel is a temporary Talk. | ErrorResponse |
| 413 | PAYLOAD_TOO_LARGE: the body exceeds 1 MiB. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
InstallResponse
| Field | Type | Description |
|---|---|---|
bot (required) | Bot | |
token (required) | NewTokenResponse |
Check a bot manifest
POST /api/admin/bots/manifests/check
Owner or Manage bots. Validates a manifest and answers it normalised: cleaned text, its intents with their bits and its permissions with their names, in a fixed order, without duplicates. Unknown fields are ignored; the avatar is not part of the answer. Nothing is stored.
Authentication: Session cookie
Request body (application/json, required): Manifest
| Field | Type | Description |
|---|---|---|
avatar | string | Avatar is a data: URL the web app uploads through the avatar route. The server ignores it and never fetches anything. |
commands | CommandInput[] | Commands are registered as by PUT /api/bot/v1/commands; at most 50. |
description | string | |
homepage | string | Homepage is an https URL, shown as a link. |
intents | string[] | Intents are names: GUILDS, GUILD_MEMBERS, GUILD_MESSAGES, GUILD_MESSAGE_REACTIONS. |
manifest_version (required) | integer | |
name (required) | string | |
permissions | string[] | Permissions are permission keys, channel permissions only: view_channel, send_messages, attach_files, add_reactions, manage_messages, mention_everyone. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The manifest as the server understands it. | CheckedManifest |
| 400 | INVALID_INPUT: the manifest is invalid or asks for a permission a manifest cannot ask for; the message names it. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage bots permission, or cross-origin request rejected. | ErrorResponse |
| 413 | PAYLOAD_TOO_LARGE: the body exceeds 1 MiB. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
CheckedManifest
| Field | Type | Description |
|---|---|---|
commands (required) | CommandInput[] | |
description (required) | string | |
homepage (required) | string | |
intents (required) | ManifestIntent[] | |
manifest_version (required) | integer | |
name (required) | string | |
permissions (required) | ManifestPermission[] |
Delete a bot
DELETE /api/admin/bots/{id}
Its tokens stop working and its gateway connections close at once, and its own managed role is deleted. Messages it posted stay, with its name.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Bot ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Deleted. | |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage bots permission, or the bot's highest role is not below yours, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: no such bot. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Get a bot
GET /api/admin/bots/{id}
One bot account with its owner, status and roles. Needs Manage bots (or the Owner); secrets and tokens are never part of the answer.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Bot ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The bot. | Bot |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage bots permission, or the bot's highest role is not below yours. | ErrorResponse |
| 404 | NOT_FOUND: no such bot. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Bot
| Field | Type | Description |
|---|---|---|
allowed_intents (required) | integer | AllowedIntents are the gateway intents the bot may ask for. |
avatar_url | string | AvatarURL is the API URL of the avatar; omitted when none. |
created_at (required) | string (date-time) | |
created_by | string (uuid) | |
description | string | Description and Homepage come from the manifest the bot was added from; omitted for a bot created by hand. |
disabled (required) | boolean | Disabled bots cannot use any token or gateway connection. |
homepage | string | |
id (required) | string (uuid) | |
last_active_at | string (date-time) | |
name (required) | string | |
role_ids (required) | string (uuid)[] | RoleIDs are the bot's roles, highest first; its permissions come from them and from channel overwrites, never from @everyone. |
user_id (required) | string (uuid) |
Change a bot
PATCH /api/admin/bots/{id}
Name (the bot's own managed role is renamed with it), allowed gateway intents, or disabled. Disabling closes its gateway connections at once and refuses all its tokens.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Bot ID. |
Request body (application/json, required): UpdateRequest
| Field | Type | Description |
|---|---|---|
allowed_intents | integer | |
disabled | boolean | |
name | string |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Updated. | Bot |
| 400 | Invalid input (INVALID_INPUT). | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage bots permission, or the bot's highest role is not below yours, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: no such bot. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Bot
| Field | Type | Description |
|---|---|---|
allowed_intents (required) | integer | AllowedIntents are the gateway intents the bot may ask for. |
avatar_url | string | AvatarURL is the API URL of the avatar; omitted when none. |
created_at (required) | string (date-time) | |
created_by | string (uuid) | |
description | string | Description and Homepage come from the manifest the bot was added from; omitted for a bot created by hand. |
disabled (required) | boolean | Disabled bots cannot use any token or gateway connection. |
homepage | string | |
id (required) | string (uuid) | |
last_active_at | string (date-time) | |
name (required) | string | |
role_ids (required) | string (uuid)[] | RoleIDs are the bot's roles, highest first; its permissions come from them and from channel overwrites, never from @everyone. |
user_id (required) | string (uuid) |
Show what a bot can reach
GET /api/admin/bots/{id}/access
The effective result of the bot's roles and the channel overwrites: its server-wide permissions and, per channel it can view, what it may do there.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Bot ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Effective access. | Access |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage bots permission, or the bot's highest role is not below yours. | ErrorResponse |
| 404 | NOT_FOUND: no such bot. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Access
| Field | Type | Description |
|---|---|---|
channels (required) | ChannelAccess[] | |
elevated (required) | boolean | Elevated is true when the bot holds Administrator or opens any part of the admin area: the interface warns about it. |
granted | integer | Granted is the set the choice grants (a bit set of channel permissions); in mode "channels" what every one of SelectedChannelIDs allows. |
mixed | boolean | Mixed is true in mode "channels" when the selected channels allow different sets (set by hand): saving the choice applies one set to all. |
mode | string | Mode is the bot's access choice: "all" (its own role holds its channel permissions server-wide) or "channels" (only overwrites of its own role in the listed channels). |
permissions (required) | integer | Permissions are the server-wide permissions (a bit set). |
private_reach | boolean | PrivateReach is true in mode "channels" when the bot can view a channel that plain members cannot see (@everyone cannot view it) without having an overwrite of its own role there. |
selected_channel_ids | string (uuid)[] | SelectedChannelIDs are the channels the caller can view where the bot's own role has an overwrite: its channels in mode "channels", the private channels it may also see in mode "all". |
Choose which channels a bot works in
PUT /api/admin/bots/{id}/access
Owner or Manage bots. Sets the bot's access: "channels" gives the listed permissions to the bot's own role in exactly the listed channels (its other server-wide channel grants and overwrites go), "all" gives them to the bot's own role server-wide, so the bot works in every channel plain members can see; a channel where @everyone is denied View channels stays hidden from it unless it is listed. Only these channel permissions can be given: view, send, attach, react, manage messages, mention everyone; never Administrator or the admin area. A permission that is both given and listed lifts a deny of the bot's own role in that channel. Overwrites of the bot's own role in channels the caller cannot view stay. "all" needs view_channel. The usual bot invariant applies: nobody but the Owner gives a bot anything elevated, and nobody gives a bot a permission they lack in a channel it reaches. A bot that reaches a channel the caller cannot view cannot be changed by the caller either. Logged as bot.access.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Bot ID. |
Request body (application/json, required): AccessRequest
| Field | Type | Description |
|---|---|---|
access (required) | string | Access is "channels" (the permissions only in the listed channels) or "all" (the permissions in every channel, held server-wide by the bot's own role; a channel plain members cannot see stays hidden unless it is listed). |
channel_ids (required) | string (uuid)[] | ChannelIDs are the channels of the bot's own overwrites (with access "all": the private channels it may also see). Overwrites in channels the caller cannot view are left as they are. |
permissions (required) | string[] | Permissions are permission keys, at most the channel permissions a manifest may ask for: view_channel, send_messages, attach_files, add_reactions, manage_messages, mention_everyone. They replace what the choice granted before. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The access now. | Access |
| 400 | INVALID_INPUT: an unknown access or permission key. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage bots permission, the bot's highest role is not below yours, a permission you lack, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: no such bot, or a listed channel does not exist or you cannot view it. | ErrorResponse |
| 409 | CONFLICT: a listed channel is a temporary Talk. | ErrorResponse |
| 413 | PAYLOAD_TOO_LARGE: the body exceeds 1 MiB. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Access
| Field | Type | Description |
|---|---|---|
channels (required) | ChannelAccess[] | |
elevated (required) | boolean | Elevated is true when the bot holds Administrator or opens any part of the admin area: the interface warns about it. |
granted | integer | Granted is the set the choice grants (a bit set of channel permissions); in mode "channels" what every one of SelectedChannelIDs allows. |
mixed | boolean | Mixed is true in mode "channels" when the selected channels allow different sets (set by hand): saving the choice applies one set to all. |
mode | string | Mode is the bot's access choice: "all" (its own role holds its channel permissions server-wide) or "channels" (only overwrites of its own role in the listed channels). |
permissions (required) | integer | Permissions are the server-wide permissions (a bit set). |
private_reach | boolean | PrivateReach is true in mode "channels" when the bot can view a channel that plain members cannot see (@everyone cannot view it) without having an overwrite of its own role there. |
selected_channel_ids | string (uuid)[] | SelectedChannelIDs are the channels the caller can view where the bot's own role has an overwrite: its channels in mode "channels", the private channels it may also see in mode "all". |
Set a bot's avatar
POST /api/admin/bots/{id}/avatar
multipart/form-data with an image in field 'avatar' (max 5 MB).
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Bot ID. |
Request body (multipart/form-data, required): object
| Field | Type | Description |
|---|---|---|
avatar (required) | string (binary) | Image file, at most 5 MB. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Updated. | Bot |
| 400 | Invalid input (INVALID_INPUT). | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage bots permission, or the bot's highest role is not below yours, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: no such bot. | ErrorResponse |
| 413 | PAYLOAD_TOO_LARGE: file exceeds the limit. | ErrorResponse |
| 415 | UNSUPPORTED_MEDIA_TYPE: the file type is not allowed. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
| 503 | UNAVAILABLE: file storage is not available. | ErrorResponse |
Bot
| Field | Type | Description |
|---|---|---|
allowed_intents (required) | integer | AllowedIntents are the gateway intents the bot may ask for. |
avatar_url | string | AvatarURL is the API URL of the avatar; omitted when none. |
created_at (required) | string (date-time) | |
created_by | string (uuid) | |
description | string | Description and Homepage come from the manifest the bot was added from; omitted for a bot created by hand. |
disabled (required) | boolean | Disabled bots cannot use any token or gateway connection. |
homepage | string | |
id (required) | string (uuid) | |
last_active_at | string (date-time) | |
name (required) | string | |
role_ids (required) | string (uuid)[] | RoleIDs are the bot's roles, highest first; its permissions come from them and from channel overwrites, never from @everyone. |
user_id (required) | string (uuid) |
List a bot's commands
GET /api/admin/bots/{id}/commands
All of them, including the disabled ones.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Bot ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Commands by name. | Command[] |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage bots permission, or the bot's highest role is not below yours. | ErrorResponse |
| 404 | NOT_FOUND: no such bot. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Delete a command
DELETE /api/admin/bots/{id}/commands/{commandID}
The bot can register it again; disable it instead to keep it off.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Bot ID. |
commandID | path | string (uuid) | yes | Command ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Deleted. | |
| 400 | Invalid input (INVALID_INPUT). | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage bots permission, or the bot's highest role is not below yours, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: no such bot or command. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Enable or disable a command
PATCH /api/admin/bots/{id}/commands/{commandID}
A disabled command is hidden from members and refuses invocations. The bot cannot switch it back on, not even by registering the command again.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Bot ID. |
commandID | path | string (uuid) | yes | Command ID. |
Request body (application/json, required): CommandPatch
| Field | Type | Description |
|---|---|---|
disabled (required) | boolean |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Updated. | Command |
| 400 | Invalid input (INVALID_INPUT). | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage bots permission, or the bot's highest role is not below yours, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: no such bot or command. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Command
| Field | Type | Description |
|---|---|---|
bot_id (required) | string (uuid) | |
created_at (required) | string (date-time) | |
default_member_permissions | string | null | |
description (required) | string | |
disabled (required) | boolean | Disabled commands are hidden from members and refuse invocations; only an admin can set it, a bot registering the command again keeps it. |
id (required) | string (uuid) | |
name (required) | string | |
options (required) | Option[] |
Set a bot's roles
PUT /api/admin/bots/{id}/roles
Replaces the bot's roles. The usual hierarchy applies: only roles below the caller's highest role, and no permission the caller lacks. A role with Administrator or any admin-area permission can only be given by the Owner. The bot never inherits @everyone, always keeps the shared Bot role and its own managed role, and another bot's own role is refused.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Bot ID. |
Request body (application/json, required): RolesRequest
| Field | Type | Description |
|---|---|---|
role_ids (required) | string (uuid)[] |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Updated. | Bot |
| 400 | Invalid input (INVALID_INPUT). | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage bots permission, a role is not below your highest role, or it holds a permission you lack (roles with Administrator or admin-area permissions: Owner only), or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: no such bot. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Bot
| Field | Type | Description |
|---|---|---|
allowed_intents (required) | integer | AllowedIntents are the gateway intents the bot may ask for. |
avatar_url | string | AvatarURL is the API URL of the avatar; omitted when none. |
created_at (required) | string (date-time) | |
created_by | string (uuid) | |
description | string | Description and Homepage come from the manifest the bot was added from; omitted for a bot created by hand. |
disabled (required) | boolean | Disabled bots cannot use any token or gateway connection. |
homepage | string | |
id (required) | string (uuid) | |
last_active_at | string (date-time) | |
name (required) | string | |
role_ids (required) | string (uuid)[] | RoleIDs are the bot's roles, highest first; its permissions come from them and from channel overwrites, never from @everyone. |
user_id (required) | string (uuid) |
List a bot's tokens
GET /api/admin/bots/{id}/tokens
Never contains the secrets: name, last characters, state, expiry and last use.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Bot ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Tokens, newest first. | Token[] |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage bots permission, or the bot's highest role is not below yours. | ErrorResponse |
| 404 | NOT_FOUND: no such bot. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Issue a token
POST /api/admin/bots/{id}/tokens
The secret is in the answer and shown only once; only a SHA-256 hash is stored. Optional expiry. At most 10 active tokens per bot.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Bot ID. |
Request body (application/json): TokenRequest
| Field | Type | Description |
|---|---|---|
expires_at | string (date-time) | ExpiresAt is optional; without it the token never expires. |
name | string |
Responses
| Status | Meaning | Body |
|---|---|---|
| 201 | Issued. | NewTokenResponse |
| 400 | Invalid input (INVALID_INPUT). | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage bots permission, or the bot's highest role is not below yours, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: no such bot. | ErrorResponse |
| 409 | CONFLICT: too many active tokens. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
NewTokenResponse
| Field | Type | Description |
|---|---|---|
created_at (required) | string (date-time) | |
expires_at | string (date-time) | ExpiresAt is empty for a token that never expires. |
hint (required) | string | |
id (required) | string (uuid) | |
issuer_binding | string | IssuerBinding is only set for a token issued before 1.0, which has no recorded issuer: "unbound" until it is first used after the upgrade, then "inferred" (bound to the bot's creator or the Owner, whoever qualified; regenerate it to bind it to its real issuer). Absent for a token whose issuer was recorded when it was issued. |
last_used_at | string (date-time) | |
name (required) | string | |
secret (required) | string | Secret is the API token. It is shown only now; only its hash is kept. |
state (required) | string |
Revoke a token
DELETE /api/admin/bots/{id}/tokens/{tokenID}
Takes effect at once; open gateway connections that used the token close.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Bot ID. |
tokenID | path | string (uuid) | yes | Token ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Revoked. | |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage bots permission, or the bot's highest role is not below yours, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: no such bot or token. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Regenerate a token
POST /api/admin/bots/{id}/tokens/{tokenID}/regenerate
Issues a new token with the same name and expiry and revokes the old one at once (its gateway connections close), in one step. Only an active token can be regenerated.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Bot ID. |
tokenID | path | string (uuid) | yes | Token ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 201 | Issued; the secret is shown once. | NewTokenResponse |
| 400 | INVALID_INPUT: the token is expired or revoked. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage bots permission, or the bot's highest role is not below yours, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: no such bot or token. | ErrorResponse |
| 409 | CONFLICT: too many active tokens. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
NewTokenResponse
| Field | Type | Description |
|---|---|---|
created_at (required) | string (date-time) | |
expires_at | string (date-time) | ExpiresAt is empty for a token that never expires. |
hint (required) | string | |
id (required) | string (uuid) | |
issuer_binding | string | IssuerBinding is only set for a token issued before 1.0, which has no recorded issuer: "unbound" until it is first used after the upgrade, then "inferred" (bound to the bot's creator or the Owner, whoever qualified; regenerate it to bind it to its real issuer). Absent for a token whose issuer was recorded when it was issued. |
last_used_at | string (date-time) | |
name (required) | string | |
secret (required) | string | Secret is the API token. It is shown only now; only its hash is kept. |
state (required) | string |