Bot Platform API

Build bots, slash commands, and interactive workflows for CloakShell communities.

https://api.cloakshell.com/api/v1

Getting Started

The CloakShell Bot Platform lets you build automated tools and integrations for CloakShell communities. Create moderation bots, custom slash commands, external service integrations, activity feeds, and more. Bots run as dedicated accounts within communities, interacting through a structured API with scoped permissions. Building and deploying bots requires an active CloakShell+ subscription ($4.99/month).

curl -H "Authorization: Bot YOUR_BOT_TOKEN" \
  https://api.cloakshell.com/api/v1/bots/@me

Response

200 OK

{
  "data": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "My Bot",
    "description": "A helpful bot",
    "created_at": "2026-04-01T00:00:00Z"
  }
}

Base URL

https://api.cloakshell.com/api/v1

Authentication

The API supports three authentication methods depending on the context. Bot tokens are used for automated actions, OAuth2 for user-authorized access, and JWTs for developer management endpoints.

Bot Token

Header: Authorization: Bot <token>

Used for all `/bot-api/*` endpoints and the `/bot-gateway` WebSocket connection. Tokens are generated via `POST /bots/{botID}/tokens`. The plaintext token is returned only once at creation time. Store it securely; it cannot be retrieved again. Each token carries scoped permissions. The effective permissions for any action are the intersection of the token scopes and the installation scopes.

OAuth2 (PKCE)

Header: Authorization: Bearer <access_token>

Used for user-authorized actions on behalf of a community. PKCE (S256) is required for all flows. **Authorization flow:** 1. Redirect the user to the authorization URL with your client ID, redirect URI, and a PKCE code challenge. 2. The user reviews and approves the requested scopes. 3. CloakShell redirects back to your redirect URI with an authorization code. 4. Exchange the code via `POST /oauth2/token` with your client secret and PKCE code verifier. The response includes the `installation_id`, `community_id`, and granted `scopes`.

JWT (Session Token)

Header: Authorization: Bearer <jwt>

Used for `/api/v1/bots/*` management endpoints (creating bots, managing commands, viewing installations). Developers interact with these endpoints through the CloakShell developer portal.

curl -X GET https://api.cloakshell.com/api/v1/bot-api/channels/{channelID}/messages \
  -H "Authorization: Bot YOUR_BOT_TOKEN" \
  -H "Content-Type: application/json"

curl -X POST https://api.cloakshell.com/api/v1/oauth2/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "AUTH_CODE",
    "redirect_uri": "https://yourapp.com/callback",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "code_verifier": "YOUR_CODE_VERIFIER"
  }'

curl -X GET https://api.cloakshell.com/api/v1/bots \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Core Concepts

Response Format

All API responses use a consistent JSON envelope. Successful responses wrap data in a `data` field. Paginated responses include a `cursor` object with pagination state.

Error Response Format

Errors return a structured object with a machine-readable `code` and a human-readable `message`. Use the `code` field for programmatic error handling.

{
  "data": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "My Bot",
    "created_at": "2026-04-01T00:00:00Z"
  }
}

{
  "data": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "Bot One"
    },
    {
      "id": "0fedcba9-8765-4321-0fed-cba987654321",
      "name": "Bot Two"
    }
  ],
  "cursor": {
    "next": "0fedcba9-8765-4321-0fed-cba987654321",
    "has_more": true
  }
}

{
  "error": {
    "code": "BOT_NOT_FOUND",
    "message": "Bot not found"
  }
}

Rate Limits

The API enforces per-endpoint rate limits organized into three tiers: Standard, Moderate, and Restricted. When a rate limit is exceeded, the API returns HTTP 429 with a `Retry-After` header indicating when you can retry. Each endpoint lists its rate limit tier.

Scope	Limit	Description
`Standard`	Higher allowance	Read operations, data retrieval, and general queries
`Moderate`	Reduced allowance	Write operations, content modifications, and mutations
`Restricted`	Lowest allowance	Sensitive operations including token exchange, gateway connections, and verification

Error Codes

Code	Status	Message
`BOT_NOT_FOUND`	404	Bot not found
`BOT_LIMIT_REACHED`	400	Bot limit reached
`INSTALLATION_LIMIT_REACHED`	400	Maximum number of bot installations reached for this community
`BOT_ALREADY_INSTALLED`	409	This bot is already installed in this community
`INVALID_CHANNEL`	400	One or more channels do not belong to this community
`INSTALLATION_NOT_FOUND`	404	Bot installation not found
`COMMAND_NOT_FOUND`	404	Command not found
`COMMAND_LIMIT_REACHED`	400	Maximum number of commands reached for this scope
`COMMAND_NAME_CONFLICT`	409	A command with this name already exists in this scope
`INVALID_CALLBACK_URL`	400	Callback URL must use HTTPS
`INTERACTION_TOKEN_EXPIRED`	404	Interaction token has expired or does not exist
`INTERACTION_CALLBACK_FAILED`	502	Bot callback failed or timed out
`SUBSCRIPTION_NOT_FOUND`	404	Event subscription not found
`SUBSCRIPTION_LIMIT_REACHED`	400	Maximum number of event subscriptions reached for this installation
`OAUTH2_CLIENT_NOT_FOUND`	404	OAuth2 client not found
`OAUTH2_CLIENT_EXISTS`	409	This bot already has an OAuth2 client
`OAUTH2_INVALID_REDIRECT`	400	Invalid redirect URI
`OAUTH2_INVALID_GRANT`	400	Invalid authorization code
`OAUTH2_INVALID_CLIENT`	401	Invalid client credentials
`OAUTH2_PKCE_FAILED`	400	PKCE code verifier does not match challenge
`OAUTH2_PKCE_REQUIRED`	400	PKCE code verifier is required
`INVALID_CATEGORY`	400	Invalid bot category
`VERIFICATION_NOT_ALLOWED`	400	Verification can only be submitted when status is unverified or rejected
`BOT_NOT_PENDING`	409	Bot is not in pending verification status
`ENDPOINT_REQUIRED`	400	Bot must have an interaction endpoint URL configured
`ERROR_LOG_NOT_FOUND`	404	Error log not found

Token Scopes

Bot tokens and installations each carry a set of scopes. The effective permissions for any bot action are the intersection of the token scopes and the installation scopes. Combine scope values with bitwise OR to request multiple scopes. For example, to request both `READ_MESSAGES` and `SEND_MESSAGES`, pass `scopes: 3` (1 + 2).

Name	Value	Description
`READ_MESSAGES`	1	Read message content and history
`SEND_MESSAGES`	2	Send messages to channels
`MANAGE_OWN_MESSAGES`	4	Edit and delete own messages
`READ_MEMBERS`	8	Read community member list
`ADD_REACTIONS`	16	Add and remove emoji reactions

Bot Management

Endpoints for creating and managing bot accounts. All endpoints require JWT authentication and an active CloakShell+ subscription. Bot creation is limited per developer account.

POST /api/v1/bots

Create Bot

Creates a new bot account. The number of bots per developer account is limited. The category must be one of the valid bot directory categories or an empty string.

JWT Moderate

Body Parameters

name string body required

Bot display name. Maximum 80 characters. Names containing inappropriate content will be rejected.

description string body optional

Bot description. Maximum 2000 characters. HTML tags are not supported.

public boolean body required

Whether the bot appears in the public directory and can be installed by anyone.

category string body optional

Bot directory category. Valid values: moderation, utility, fun, social, developer_tools, productivity, gaming, or empty string. (Default: "")

curl -X POST https://api.cloakshell.com/api/v1/bots \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Moderation Helper",
    "description": "Automated moderation for your community",
    "public": true,
    "category": "moderation"
  }'

Response

{
  "data": {
    "id": "01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012",
    "creator_id": "01965c8a-0a1b-7c2d-8e3f-4a5b6c7d8e9f",
    "name": "Moderation Helper",
    "description": "Automated moderation for your community",
    "public": true,
    "category": "moderation",
    "install_count": 0,
    "verification_status": "unverified",
    "created_at": "2026-04-01T12:00:00Z",
    "updated_at": "2026-04-01T12:00:00Z"
  }
}

GET /api/v1/bots

List Your Bots

Returns all bots created by the authenticated user. No pagination; returns the full list.

JWT Standard

curl -X GET https://api.cloakshell.com/api/v1/bots \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

{
  "data": [
    {
      "id": "01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012",
      "creator_id": "01965c8a-0a1b-7c2d-8e3f-4a5b6c7d8e9f",
      "name": "Moderation Helper",
      "description": "Automated moderation for your community",
      "public": true,
      "category": "moderation",
      "install_count": 3,
      "verification_status": "unverified",
      "created_at": "2026-04-01T12:00:00Z",
      "updated_at": "2026-04-01T12:00:00Z"
    }
  ]
}

GET /api/v1/bots/{botID}

Get Bot

Returns details for a specific bot owned by the authenticated user. Returns 404 if the bot does not exist or is not owned by the caller.

JWT Standard

Path Parameters

botID string (UUID) path required

The bot account ID.

curl -X GET https://api.cloakshell.com/api/v1/bots/01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

{
  "data": {
    "id": "01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012",
    "creator_id": "01965c8a-0a1b-7c2d-8e3f-4a5b6c7d8e9f",
    "name": "Moderation Helper",
    "description": "Automated moderation for your community",
    "public": true,
    "interaction_endpoint_url": "https://mybot.example.com/interactions",
    "category": "moderation",
    "install_count": 3,
    "verification_status": "unverified",
    "created_at": "2026-04-01T12:00:00Z",
    "updated_at": "2026-04-01T12:00:00Z"
  }
}

PATCH /api/v1/bots/{botID}

Update Bot

Updates one or more fields on a bot you own. Only provided fields are updated; omitted fields remain unchanged. The interaction_endpoint_url must use HTTPS. Set it to an empty string to clear.

JWT Moderate

Path Parameters

botID string (UUID) path required

The bot account ID.

Body Parameters

name string body optional

New bot name. Maximum 80 characters.

description string body optional

New description. Maximum 2000 characters. Pass empty string to clear.

public boolean body optional

Whether the bot is publicly listed in the directory.

interaction_endpoint_url string body optional

HTTPS URL for receiving interaction callbacks. Pass empty string to clear.

category string body optional

Bot directory category. Valid values: moderation, utility, fun, social, developer_tools, productivity, gaming, or empty string.

curl -X PATCH https://api.cloakshell.com/api/v1/bots/01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Moderation Helper v2",
    "interaction_endpoint_url": "https://mybot.example.com/interactions"
  }'

Response

{
  "data": {
    "id": "01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012",
    "creator_id": "01965c8a-0a1b-7c2d-8e3f-4a5b6c7d8e9f",
    "name": "Moderation Helper v2",
    "description": "Enhanced moderation for your community",
    "public": true,
    "interaction_endpoint_url": "https://mybot.example.com/interactions",
    "category": "moderation",
    "install_count": 3,
    "verification_status": "unverified",
    "created_at": "2026-04-01T12:00:00Z",
    "updated_at": "2026-04-02T08:30:00Z"
  }
}

DELETE /api/v1/bots/{botID}

Delete Bot

Deletes a bot you own. All existing installations, tokens, and commands are invalidated. Returns 204 No Content on success.

JWT Moderate

Path Parameters

botID string (UUID) path required

The bot account ID.

curl -X DELETE https://api.cloakshell.com/api/v1/bots/01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

(empty body, 204 No Content)

POST /api/v1/bots/{botID}/tokens

Create Token

Generates a new authentication token for a bot you own. The plaintext token is returned exactly once in the response. After this, only the token prefix is accessible. Store the token securely; it cannot be retrieved again. Scopes are an integer representing the permissions granted to this token.

JWT Moderate

Path Parameters

botID string (UUID) path required

The bot account ID.

Body Parameters

scopes integer body required

Bitfield of permissions. Combine with bitwise OR: READ_MESSAGES (1), SEND_MESSAGES (2), MANAGE_OWN_MESSAGES (4), READ_MEMBERS (8), ADD_REACTIONS (16). For example, 3 grants READ_MESSAGES + SEND_MESSAGES.

curl -X POST https://api.cloakshell.com/api/v1/bots/01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012/tokens \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"scopes": 3}'

Response

{
  "data": {
    "id": "01965c8a-2c3d-7e4f-9a5b-6c7d8e9f0a1b",
    "token": "csbot_a1b2c3d4e5f6...full_plaintext_token",
    "prefix": "csbot_a1b2c3d4",
    "scopes": 3,
    "created_at": "2026-04-01T12:05:00Z"
  }
}

GET /api/v1/bots/{botID}/tokens

List Tokens

Returns all active tokens for a bot you own. The full token value is never included; only the prefix is returned for identification purposes.

JWT Standard

Path Parameters

botID string (UUID) path required

The bot account ID.

curl -X GET https://api.cloakshell.com/api/v1/bots/01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012/tokens \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

{
  "data": [
    {
      "id": "01965c8a-2c3d-7e4f-9a5b-6c7d8e9f0a1b",
      "bot_id": "01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012",
      "prefix": "csbot_a1b2c3d4",
      "scopes": 3,
      "last_used_at": "2026-04-02T10:30:00Z",
      "created_at": "2026-04-01T12:05:00Z"
    }
  ]
}

POST /api/v1/bots/{botID}/tokens/{tokenID}/regenerate

Regenerate Token

Regenerates a token, creating a new token with the same scopes. The old token is invalidated. The new plaintext token is returned exactly once in the response.

JWT Moderate

Path Parameters

botID string (UUID) path required

The bot account ID.

tokenID string (UUID) path required

The token ID to regenerate.

curl -X POST https://api.cloakshell.com/api/v1/bots/01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012/tokens/01965c8a-2c3d-7e4f-9a5b-6c7d8e9f0a1b/regenerate \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

{
  "data": {
    "id": "01965c8a-3d4e-7f5a-9b6c-7d8e9f0a1b2c",
    "token": "csbot_b2c3d4e5f6a7...new_plaintext_token",
    "prefix": "csbot_b2c3d4e5",
    "scopes": 3,
    "created_at": "2026-04-02T14:00:00Z"
  }
}

DELETE /api/v1/bots/{botID}/tokens/{tokenID}

Revoke Token

Immediately revokes a token. The token becomes invalid for all future requests. Returns 204 No Content on success.

JWT Moderate

Path Parameters

botID string (UUID) path required

The bot account ID.

tokenID string (UUID) path required

The token ID to revoke.

curl -X DELETE https://api.cloakshell.com/api/v1/bots/01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012/tokens/01965c8a-2c3d-7e4f-9a5b-6c7d8e9f0a1b \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

(empty body, 204 No Content)

POST /api/v1/bots/{botID}/avatar

Upload Avatar

Uploads a new avatar image for a bot you own. Accepts multipart/form-data with a single file field named "file". Maximum file size is 5 MB. The image is validated and processed before storage. Uploads that fail validation are rejected. If the bot already has an avatar, the previous image is replaced.

JWT Moderate

Path Parameters

botID string (UUID) path required

The bot account ID.

Body Parameters

file file (multipart/form-data) body required

The avatar image file. Maximum 5 MB. SVG files are rejected.

curl -X POST https://api.cloakshell.com/api/v1/bots/01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012/avatar \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "file=@avatar.png"

Response

{
  "data": {
    "avatar_url": "https://cdn.cloakshell.com/uploads/bot-avatar/01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012.webp"
  }
}

DELETE /api/v1/bots/{botID}/avatar

Delete Avatar

Removes the avatar from a bot you own. Returns 204 No Content on success.

JWT Moderate

Path Parameters

botID string (UUID) path required

The bot account ID.

curl -X DELETE https://api.cloakshell.com/api/v1/bots/01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012/avatar \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

(empty body, 204 No Content)

Bot Directory

Endpoints for discovering and browsing public bots. Directory listing and detail routes are public and align with the rest of the SEO-facing API surface under /api/v1/public.

GET /api/v1/bots/search

Search Bots

Searches public bots by name. Requires a query string of at least 2 characters and no more than 100 characters. Returns up to 25 matching results. Only public bots appear in search results.

JWT Standard

Query Parameters

q string query required

Search query. Must be between 2 and 100 characters.

curl -X GET "https://api.cloakshell.com/api/v1/bots/search?q=moderation" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

{
  "data": [
    {
      "id": "01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012",
      "name": "Moderation Helper",
      "avatar_url": "https://cdn.cloakshell.com/uploads/bot-avatar/01965c8a-1b2e-7d3f.webp",
      "description": "Automated moderation for your community",
      "created_at": "2026-04-01T12:00:00Z"
    }
  ]
}

GET /api/v1/public/bots/directory

Browse Directory

Lists public bots in the directory with cursor-based pagination. Supports filtering by category and searching by name. Results are sorted by install count (descending). Returns up to 25 bots per page.

None Standard

Query Parameters

q string query optional

Optional search query. Must be between 2 and 100 characters if provided.

category string query optional

Filter by category. Valid values: moderation, utility, fun, social, developer_tools, productivity, gaming.

cursor string query optional

Pagination cursor from a previous response.

curl -X GET "https://api.cloakshell.com/api/v1/public/bots/directory?category=moderation"

Response

200 OK

{
  "data": [
    {
      "id": "01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012",
      "name": "Moderation Helper",
      "avatar_url": "https://cdn.cloakshell.com/uploads/bot-avatar/01965c8a-1b2e-7d3f.webp",
      "description": "Automated moderation for your community",
      "category": "moderation",
      "install_count": 42,
      "created_at": "2026-04-01T12:00:00Z"
    }
  ],
  "cursor": {
    "next": "eyJpIjoiMDE5NjVjOGEtMWIyZS03ZDNmLThhNGItNWM2ZDdlOGY5MDEyIn0",
    "has_more": true
  }
}

GET /api/v1/public/bots/directory/{botID}

Get Directory Bot

Returns detailed information for a public bot in the directory. Includes the creator username (if available), whether the bot has OAuth2 configured, and the OAuth2 client ID. Only returns bots that are public and not deleted.

None Standard

Path Parameters

botID string (UUID) path required

The bot account ID.

curl -X GET https://api.cloakshell.com/api/v1/public/bots/directory/01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012

Response

{
  "data": {
    "id": "01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012",
    "name": "Moderation Helper",
    "avatar_url": "https://cdn.cloakshell.com/uploads/bot-avatar/01965c8a-1b2e-7d3f.webp",
    "description": "Automated moderation for your community",
    "category": "moderation",
    "install_count": 42,
    "created_at": "2026-04-01T12:00:00Z",
    "creator_username": "example-developer",
    "has_oauth2": true,
    "oauth2_client_id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6a7b8c9d0e1f2a3b4c5d6a7b8c9d0e1f2",
    "interaction_endpoint_url": "https://mybot.example.com/interactions"
  }
}

Community Installation

Endpoints for installing and managing bots within a community. All endpoints require JWT authentication and the Manage Bots permission in the target community. Installing bots requires the community owner to have an active CloakShell+ subscription. Communities have a limit on the number of installed bots.

POST /api/v1/communities/{communityID}/bots

Install Bot

Installs a bot in a community. The bot must be public or owned by the requesting user. Requires the community owner to have CloakShell+. Communities have a limit on installed bots. Duplicate installations of the same bot are not allowed. You can restrict the bot to specific channels by providing channel_ids.

JWT Moderate

Path Parameters

communityID string (UUID) path required

The community ID.

Body Parameters

bot_id string (UUID) body required

The bot account ID to install.

scopes integer body required

Bitfield of permissions granted to the bot in this community. Combined with bitwise OR: READ_MESSAGES (1), SEND_MESSAGES (2), MANAGE_OWN_MESSAGES (4), READ_MEMBERS (8), ADD_REACTIONS (16).

channel_ids string[] body optional

List of channel IDs the bot is restricted to. If empty, the bot has access to all channels. Each channel ID must belong to this community.

historical_access boolean body optional

Whether the bot can access messages sent before it was installed. (Default: false)

curl -X POST https://api.cloakshell.com/api/v1/communities/01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e/bots \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": "01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012",
    "scopes": 3,
    "channel_ids": [],
    "historical_access": false
  }'

Response

{
  "data": {
    "id": "01965c8a-4e5f-7a6b-9c7d-8e9f0a1b2c3d",
    "bot_id": "01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012",
    "bot_name": "Moderation Helper",
    "bot_avatar_url": "https://cdn.cloakshell.com/uploads/bot-avatar/01965c8a-1b2e-7d3f.webp",
    "bot_description": "Automated moderation for your community",
    "community_id": "01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
    "installed_by_id": "01965c8a-0a1b-7c2d-8e3f-4a5b6c7d8e9f",
    "scopes": 3,
    "historical_access": false,
    "channel_ids": [],
    "created_at": "2026-04-01T15:00:00Z"
  }
}

GET /api/v1/communities/{communityID}/bots

List Installations

Returns all bot installations in a community. Each installation includes the bot name, avatar, description, granted scopes, and restricted channel IDs.

JWT Standard

Path Parameters

communityID string (UUID) path required

The community ID.

curl -X GET https://api.cloakshell.com/api/v1/communities/01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e/bots \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

{
  "data": [
    {
      "id": "01965c8a-4e5f-7a6b-9c7d-8e9f0a1b2c3d",
      "bot_id": "01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012",
      "bot_name": "Moderation Helper",
      "bot_avatar_url": "https://cdn.cloakshell.com/uploads/bot-avatar/01965c8a-1b2e-7d3f.webp",
      "bot_description": "Automated moderation for your community",
      "community_id": "01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
      "installed_by_id": "01965c8a-0a1b-7c2d-8e3f-4a5b6c7d8e9f",
      "scopes": 3,
      "historical_access": false,
      "channel_ids": [],
      "created_at": "2026-04-01T15:00:00Z"
    }
  ]
}

PATCH /api/v1/communities/{communityID}/bots/{installationID}

Update Installation

Updates an existing bot installation. You can change the granted scopes, the list of allowed channels, and the historical access setting. Only provided fields are updated. When channel_ids is provided, the existing channel list is replaced entirely.

JWT Moderate

Path Parameters

communityID string (UUID) path required

The community ID.

installationID string (UUID) path required

The installation ID.

Body Parameters

scopes integer body optional

New scopes value. Must contain only valid scope values.

channel_ids string[] body optional

New list of channel IDs the bot is restricted to. Replaces the existing list entirely. Pass an empty array to allow all channels.

historical_access boolean body optional

Whether the bot can access messages sent before installation.

curl -X PATCH https://api.cloakshell.com/api/v1/communities/01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e/bots/01965c8a-4e5f-7a6b-9c7d-8e9f0a1b2c3d \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": 7,
    "channel_ids": ["01965c8a-6a7b-7c8d-9e0f-1a2b3c4d5e6f"],
    "historical_access": true
  }'

Response

{
  "data": {
    "id": "01965c8a-4e5f-7a6b-9c7d-8e9f0a1b2c3d",
    "bot_id": "01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012",
    "bot_name": "Moderation Helper",
    "bot_avatar_url": "https://cdn.cloakshell.com/uploads/bot-avatar/01965c8a-1b2e-7d3f.webp",
    "bot_description": "Automated moderation for your community",
    "community_id": "01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
    "installed_by_id": "01965c8a-0a1b-7c2d-8e3f-4a5b6c7d8e9f",
    "scopes": 7,
    "historical_access": true,
    "channel_ids": ["01965c8a-6a7b-7c8d-9e0f-1a2b3c4d5e6f"],
    "created_at": "2026-04-01T15:00:00Z"
  }
}

DELETE /api/v1/communities/{communityID}/bots/{installationID}

Uninstall Bot

Removes a bot installation from a community. Commands scoped to this installation are also removed. Returns 204 No Content on success.

JWT Moderate

Path Parameters

communityID string (UUID) path required

The community ID.

installationID string (UUID) path required

The installation ID.

curl -X DELETE https://api.cloakshell.com/api/v1/communities/01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e/bots/01965c8a-4e5f-7a6b-9c7d-8e9f0a1b2c3d \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

(empty body, 204 No Content)

GET /api/v1/communities/{communityID}/bots/{installationID}/activity

Bot Activity

Returns the activity log for a bot installation in a community. Uses cursor-based pagination. Each entry shows an action the bot has performed (messages sent, reactions added, etc.).

JWT Standard

Path Parameters

communityID string (UUID) path required

The community ID.

installationID string (UUID) path required

The installation ID.

Query Parameters

limit integer query optional

Number of entries to return. Maximum 100. (Default: 25)

before string (UUID) query optional

Cursor for pagination. Returns entries before this ID.

curl -X GET "https://api.cloakshell.com/api/v1/communities/01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e/bots/01965c8a-4e5f-7a6b-9c7d-8e9f0a1b2c3d/activity?limit=25" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

{
  "data": [
    {
      "id": "01965c8a-7b8c-7d9e-0f1a-2b3c4d5e6f7a",
      "actor_id": "01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012",
      "community_id": "01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
      "action": "message.send",
      "target_type": "message",
      "target_id": "01965c8a-8c9d-7e0f-1a2b-3c4d5e6f7a8b",
      "details": {"channel_id": "01965c8a-6a7b-7c8d-9e0f-1a2b3c4d5e6f"},
      "created_at": "2026-04-02T10:30:00Z"
    }
  ],
  "cursor": {
    "next": "01965c8a-7b8c-7d9e-0f1a-2b3c4d5e6f7a",
    "has_more": true
  }
}

GET /api/v1/communities/{communityID}/commands

List Community Commands

Returns all slash commands available in a community from installed bots. Includes both global commands (registered by the bot developer) and community-scoped commands (registered for a specific installation). Each command includes the bot name and avatar for display. Requires community membership.

JWT Standard

Path Parameters

communityID string (UUID) path required

The community ID.

curl -X GET https://api.cloakshell.com/api/v1/communities/01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e/commands \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

{
  "data": [
    {
      "id": "01965c8a-9d0e-7f1a-2b3c-4d5e6f7a8b9c",
      "bot_id": "01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012",
      "bot_name": "Moderation Helper",
      "bot_avatar_url": "https://cdn.cloakshell.com/uploads/bot-avatar/01965c8a-1b2e-7d3f.webp",
      "name": "warn",
      "description": "Issue a warning to a community member",
      "options": [
        {
          "name": "user",
          "description": "The user to warn",
          "type": "user",
          "required": true
        },
        {
          "name": "reason",
          "description": "Reason for the warning",
          "type": "string",
          "required": false
        }
      ],
      "created_at": "2026-04-01T13:00:00Z",
      "updated_at": "2026-04-01T13:00:00Z"
    }
  ]
}

Bot Commands

Endpoints for registering and managing slash commands. Commands can be registered at two scopes: global (available in every community the bot is installed in) and community-scoped (available only in a specific installation). The number of commands per scope is limited. All endpoints require JWT authentication and bot ownership.

POST /api/v1/bots/{botID}/commands

Register Global Command

Registers a new global slash command for a bot you own. Global commands are available in every community where the bot is installed. Command names must be 1 to 32 lowercase alphanumeric characters or hyphens, with no leading or trailing hyphens. Each command can have up to 25 options. Commands per scope are limited.

JWT Moderate

Path Parameters

botID string (UUID) path required

The bot account ID.

Body Parameters

name string body required

Command name. 1 to 32 lowercase alphanumeric characters or hyphens. No leading or trailing hyphens.

description string body required

Human-readable description shown in the command palette. 1 to 100 characters.

options CommandOption[] body optional

Array of command options (parameters). Maximum 25 options. Each option has name (1-32 chars, same format as command name), description (1-100 chars), type (string, integer, boolean, user, channel, or role), and required (boolean).

curl -X POST https://api.cloakshell.com/api/v1/bots/01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012/commands \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "warn",
    "description": "Issue a warning to a community member",
    "options": [
      {"name": "user", "description": "The user to warn", "type": "user", "required": true},
      {"name": "reason", "description": "Reason for the warning", "type": "string", "required": false}
    ]
  }'

Response

{
  "data": {
    "id": "01965c8a-9d0e-7f1a-2b3c-4d5e6f7a8b9c",
    "bot_id": "01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012",
    "name": "warn",
    "description": "Issue a warning to a community member",
    "options": [
      {
        "name": "user",
        "description": "The user to warn",
        "type": "user",
        "required": true
      },
      {
        "name": "reason",
        "description": "Reason for the warning",
        "type": "string",
        "required": false
      }
    ],
    "created_at": "2026-04-01T13:00:00Z",
    "updated_at": "2026-04-01T13:00:00Z"
  }
}

GET /api/v1/bots/{botID}/commands

List Commands

Returns all commands registered for a bot you own, including both global and community-scoped commands. Community-scoped commands include an installation_id field.

JWT Standard

Path Parameters

botID string (UUID) path required

The bot account ID.

curl -X GET https://api.cloakshell.com/api/v1/bots/01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012/commands \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

{
  "data": [
    {
      "id": "01965c8a-9d0e-7f1a-2b3c-4d5e6f7a8b9c",
      "bot_id": "01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012",
      "name": "warn",
      "description": "Issue a warning to a community member",
      "options": [
        {
          "name": "user",
          "description": "The user to warn",
          "type": "user",
          "required": true
        }
      ],
      "created_at": "2026-04-01T13:00:00Z",
      "updated_at": "2026-04-01T13:00:00Z"
    },
    {
      "id": "01965c8a-ae1f-7b2c-3d4e-5f6a7b8c9d0e",
      "bot_id": "01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012",
      "installation_id": "01965c8a-4e5f-7a6b-9c7d-8e9f0a1b2c3d",
      "name": "server-stats",
      "description": "Show community statistics",
      "created_at": "2026-04-01T14:00:00Z",
      "updated_at": "2026-04-01T14:00:00Z"
    }
  ]
}

DELETE /api/v1/bots/{botID}/commands/{commandID}

Delete Command

Deletes a command registered for a bot you own. The command must belong to the specified bot. Returns 204 No Content on success.

JWT Moderate

Path Parameters

botID string (UUID) path required

The bot account ID.

commandID string (UUID) path required

The command ID to delete.

curl -X DELETE https://api.cloakshell.com/api/v1/bots/01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012/commands/01965c8a-9d0e-7f1a-2b3c-4d5e6f7a8b9c \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

(empty body, 204 No Content)

POST /api/v1/communities/{communityID}/bots/{installationID}/commands

Register Community Command

Registers a slash command scoped to a specific community installation. Community commands are only available in the community where the installation lives. The requesting user must own the bot associated with the installation. The same naming rules and option limits apply as for global commands. Commands per scope are limited.

JWT Moderate

Path Parameters

communityID string (UUID) path required

The community ID.

installationID string (UUID) path required

The installation ID.

Body Parameters

name string body required

Command name. 1 to 32 lowercase alphanumeric characters or hyphens. No leading or trailing hyphens.

description string body required

Human-readable description. 1 to 100 characters.

options CommandOption[] body optional

Array of command options. Maximum 25 options per command. Each option: name (1-32 chars), description (1-100 chars), type, and required flag.

curl -X POST https://api.cloakshell.com/api/v1/communities/01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e/bots/01965c8a-4e5f-7a6b-9c7d-8e9f0a1b2c3d/commands \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "server-stats",
    "description": "Show community statistics"
  }'

Response

{
  "data": {
    "id": "01965c8a-bf2a-7c3d-4e5f-6a7b8c9d0e1f",
    "bot_id": "01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012",
    "installation_id": "01965c8a-4e5f-7a6b-9c7d-8e9f0a1b2c3d",
    "name": "server-stats",
    "description": "Show community statistics",
    "created_at": "2026-04-01T14:00:00Z",
    "updated_at": "2026-04-01T14:00:00Z"
  }
}

Event Subscriptions

Endpoints for managing HTTP callback subscriptions to community events. Event subscriptions allow your bot to receive real-time notifications when events occur in a community where it is installed. All endpoints require JWT authentication, bot ownership, and an active CloakShell+ subscription. The number of subscriptions per installation is limited. Callback delivery uses HMAC-SHA256 signature verification (X-CloakShell-Signature header). Deliveries are retried on failure. Subscriptions are disabled if callbacks consistently fail. Callback URLs must use HTTPS.

POST /api/v1/bots/{botID}/installations/{installationID}/subscriptions

Create Subscription

Creates a new event subscription for a bot installation. Requires CloakShell+. The subscription secret is returned exactly once in the response. Use the secret to verify HMAC-SHA256 signatures on incoming callback payloads. Subscriptions per installation are limited. Each subscription can listen for up to 13 event types.

JWT Moderate

Path Parameters

botID string (UUID) path required

The bot account ID.

installationID string (UUID) path required

The installation ID. Must belong to the specified bot.

Body Parameters

event_types string[] body required

Array of event types to subscribe to. Must contain 1 to 13 entries with no duplicates. Valid types: message_create, message_update, message_delete, member_join, member_leave, channel_create, channel_update, channel_delete, reaction_add, reaction_remove, post_create, post_update, reply_create.

callback_url string body required

HTTPS URL where event payloads will be delivered via POST requests.

curl -X POST https://api.cloakshell.com/api/v1/bots/01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012/installations/01965c8a-4e5f-7a6b-9c7d-8e9f0a1b2c3d/subscriptions \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_types": ["message_create", "member_join", "member_leave"],
    "callback_url": "https://mybot.example.com/events"
  }'

Response

{
  "data": {
    "id": "01965c8a-c03b-7d4e-5f6a-7b8c9d0e1f2a",
    "installation_id": "01965c8a-4e5f-7a6b-9c7d-8e9f0a1b2c3d",
    "event_types": ["message_create", "member_join", "member_leave"],
    "callback_url": "https://mybot.example.com/events",
    "secret": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6a7b8c9d0e1f2a3b4c5d6a7b8c9d0e1f2",
    "enabled": true,
    "failure_count": 0,
    "created_at": "2026-04-01T16:00:00Z",
    "updated_at": "2026-04-01T16:00:00Z"
  }
}

GET /api/v1/bots/{botID}/installations/{installationID}/subscriptions

List Subscriptions

Returns all event subscriptions for a bot installation. The secret is never included in list responses. The failure_count and last_failure_at fields help monitor callback health. Subscriptions are disabled if callbacks consistently fail.

JWT Standard

Path Parameters

botID string (UUID) path required

The bot account ID.

installationID string (UUID) path required

The installation ID. Must belong to the specified bot.

curl -X GET https://api.cloakshell.com/api/v1/bots/01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012/installations/01965c8a-4e5f-7a6b-9c7d-8e9f0a1b2c3d/subscriptions \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

{
  "data": [
    {
      "id": "01965c8a-c03b-7d4e-5f6a-7b8c9d0e1f2a",
      "installation_id": "01965c8a-4e5f-7a6b-9c7d-8e9f0a1b2c3d",
      "event_types": ["message_create", "member_join", "member_leave"],
      "callback_url": "https://mybot.example.com/events",
      "enabled": true,
      "failure_count": 0,
      "created_at": "2026-04-01T16:00:00Z",
      "updated_at": "2026-04-01T16:00:00Z"
    },
    {
      "id": "01965c8a-d14c-7e5f-6a7b-8c9d0e1f2a3b",
      "installation_id": "01965c8a-4e5f-7a6b-9c7d-8e9f0a1b2c3d",
      "event_types": ["channel_update", "channel_delete"],
      "callback_url": "https://mybot.example.com/channel-events",
      "enabled": false,
      "failure_count": 2,
      "last_failure_at": "2026-04-03T08:15:00Z",
      "created_at": "2026-04-02T09:00:00Z",
      "updated_at": "2026-04-03T08:15:00Z"
    }
  ]
}

DELETE /api/v1/bots/{botID}/installations/{installationID}/subscriptions/{subscriptionID}

Delete Subscription

Deletes an event subscription. No further events will be delivered to the callback URL. Returns 204 No Content on success.

JWT Moderate

Path Parameters

botID string (UUID) path required

The bot account ID.

installationID string (UUID) path required

The installation ID. Must belong to the specified bot.

subscriptionID string (UUID) path required

The subscription ID to delete.

curl -X DELETE https://api.cloakshell.com/api/v1/bots/01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012/installations/01965c8a-4e5f-7a6b-9c7d-8e9f0a1b2c3d/subscriptions/01965c8a-c03b-7d4e-5f6a-7b8c9d0e1f2a \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

(empty body, 204 No Content)

Interactions

Endpoints for executing and responding to bot interactions. Includes slash command execution, component interactions, modal submissions, and deferred response callbacks.

POST /api/v1/interactions

Execute Interaction

Sends a slash command, component interaction, or modal submission to a bot. The bot's interaction endpoint receives the payload and must respond promptly. If the bot needs more time, it can respond with a deferred type and follow up via the callback endpoint.

JWT Moderate

Body Parameters

type string body required

Interaction type. One of: command, component_interaction, modal_submission.

command_id string (UUID) body optional

The command ID. Required for command type.

channel_id string (UUID) body required

The channel where the interaction occurs.

community_id string (UUID) body required

The community where the interaction occurs.

options object body optional

Command options as key-value pairs. Only for command type.

message_id string (UUID) body optional

The message containing the component. Required for component_interaction type.

custom_id string body optional

The component custom ID. Required for component_interaction and modal_submission types.

bot_id string (UUID) body optional

The bot ID. Required for modal_submission type.

modal_values object body optional

Modal input values as key-value pairs. Required for modal_submission type.

curl -X POST https://api.cloakshell.com/api/v1/interactions \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "command",
    "command_id": "01965c8a-3d4e-7f5a-9b6c-7d8e9f0a1b2c",
    "channel_id": "01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
    "community_id": "01965c8a-6a7b-7c8d-9e0f-1a2b3c4d5e6f",
    "options": { "location": "San Francisco" }
  }'

Response

{
  "data": {
    "type": "message",
    "content": "The weather in San Francisco is 72°F and sunny.",
    "embeds": [
      {
        "title": "Weather Report",
        "description": "Current conditions for San Francisco, CA",
        "color": "#0088FF"
      }
    ]
  }
}

POST /api/v1/bot-api/interactions/{token}/callback

Deferred Response Callback

Sends a deferred response after the bot initially responded with a deferred type. The interaction token is provided in the original interaction payload delivered to the bot. Tokens are short-lived.

Bot Token Moderate

Path Parameters

token string path required

The interaction token from the original interaction payload.

Body Parameters

type string body required

Response type. One of: message, update_message, ephemeral.

content string body optional

Message content. Maximum 4000 characters.

embeds array body optional

Array of embed objects.

components array body optional

Array of action row objects containing interactive components.

curl -X POST https://api.cloakshell.com/api/v1/bot-api/interactions/INTERACTION_TOKEN/callback \
  -H "Authorization: Bot YOUR_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "message",
    "content": "Here are the results of your query.",
    "embeds": [
      {
        "title": "Query Results",
        "description": "Found 42 matching records.",
        "color": "#0088FF"
      }
    ]
  }'

Response

(empty body, 204 No Content)

OAuth2

OAuth2 endpoints for authorizing bot installations and managing OAuth2 clients. All authorization flows require PKCE (S256). OAuth2 clients are created per-bot and used for the authorization code flow.

GET /api/v1/oauth2/authorize

Get Authorization Data

Returns authorization page data including bot information, requested scopes, and redirect URI. Used to render the authorization approval screen.

JWT Standard

Query Parameters

client_id string query required

The OAuth2 client ID.

redirect_uri string query required

The redirect URI. Must match one of the registered redirect URIs.

scope integer query required

Requested permission scopes as a bitfield integer.

state string query required

Opaque state value for CSRF protection. Returned unchanged in the redirect.

code_challenge string query required

PKCE code challenge (Base64url-encoded SHA-256 of the code verifier).

code_challenge_method string query required

Must be S256.

curl -X GET "https://api.cloakshell.com/api/v1/oauth2/authorize?client_id=01965c8a-6a7b-7c8d-9e0f-1a2b3c4d5e6f&redirect_uri=https%3A%2F%2Fmyapp.example.com%2Fcallback&scope=3&state=RANDOM_STATE&code_challenge=CODE_CHALLENGE&code_challenge_method=S256" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

{
  "data": {
    "bot": {
      "id": "01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012",
      "name": "Weather Bot",
      "description": "Real-time weather updates for your community",
      "avatar_url": "https://cdn.cloakshell.com/uploads/bot-avatar/01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012.webp"
    },
    "scopes": 3,
    "redirect_uri": "https://myapp.example.com/callback"
  }
}

POST /api/v1/oauth2/authorize

Approve Authorization

Approves the authorization request and installs the bot in the specified community. Returns a redirect URL containing the authorization code.

JWT Moderate

Body Parameters

client_id string body required

The OAuth2 client ID.

redirect_uri string body required

The redirect URI. Must match one of the registered redirect URIs.

scope integer body required

Approved permission scopes as a bitfield integer.

state string body required

Opaque state value for CSRF protection.

code_challenge string body required

PKCE code challenge.

code_challenge_method string body required

Must be S256.

community_id string (UUID) body required

The community to install the bot in.

curl -X POST https://api.cloakshell.com/api/v1/oauth2/authorize \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "01965c8a-6a7b-7c8d-9e0f-1a2b3c4d5e6f",
    "redirect_uri": "https://myapp.example.com/callback",
    "scope": 3,
    "state": "RANDOM_STATE",
    "code_challenge": "CODE_CHALLENGE",
    "code_challenge_method": "S256",
    "community_id": "01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e"
  }'

Response

{
  "data": {
    "redirect_url": "https://myapp.example.com/callback?code=AUTH_CODE_PLACEHOLDER&state=RANDOM_STATE"
  }
}

POST /api/v1/oauth2/token

Exchange Token

Exchanges an authorization code for installation information. Uses client credentials for authentication (client_id and client_secret in the request body). The code verifier is validated against the original code challenge.

Client Credentials Restricted

Body Parameters

grant_type string body required

Must be authorization_code.

code string body required

The authorization code from the redirect.

redirect_uri string body required

The redirect URI used in the authorization request.

client_id string body required

The OAuth2 client ID.

client_secret string body required

The OAuth2 client secret.

code_verifier string body required

The PKCE code verifier used to generate the original code challenge.

curl -X POST https://api.cloakshell.com/api/v1/oauth2/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "AUTH_CODE_PLACEHOLDER",
    "redirect_uri": "https://myapp.example.com/callback",
    "client_id": "01965c8a-6a7b-7c8d-9e0f-1a2b3c4d5e6f",
    "client_secret": "cs_oauth_a1b2c3d4e5f6...full_secret",
    "code_verifier": "CODE_VERIFIER_STRING"
  }'

Response

{
  "data": {
    "installation_id": "01965c8a-4e5f-7a6b-9c7d-8e9f0a1b2c3d",
    "community_id": "01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
    "scopes": 3
  }
}

POST /api/v1/bots/{botID}/oauth2

Create OAuth2 Client

Creates an OAuth2 client for a bot you own. The client secret is returned exactly once in the response. Store it securely; it cannot be retrieved again. Redirect URIs must use HTTPS.

JWT Moderate

Path Parameters

botID string (UUID) path required

The bot account ID.

Body Parameters

redirect_uris string[] body required

Array of HTTPS redirect URIs for the OAuth2 flow.

curl -X POST https://api.cloakshell.com/api/v1/bots/01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012/oauth2 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "redirect_uris": ["https://myapp.example.com/callback"]
  }'

Response

{
  "data": {
    "client_id": "01965c8a-6a7b-7c8d-9e0f-1a2b3c4d5e6f",
    "client_secret": "cs_oauth_a1b2c3d4e5f6...full_secret",
    "redirect_uris": ["https://myapp.example.com/callback"],
    "created_at": "2026-04-01T12:00:00Z"
  }
}

GET /api/v1/bots/{botID}/oauth2

Get OAuth2 Client

Returns the OAuth2 client for a bot you own. The client secret is never included in the response.

JWT Standard

Path Parameters

botID string (UUID) path required

The bot account ID.

curl -X GET https://api.cloakshell.com/api/v1/bots/01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012/oauth2 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

{
  "data": {
    "client_id": "01965c8a-6a7b-7c8d-9e0f-1a2b3c4d5e6f",
    "redirect_uris": ["https://myapp.example.com/callback"],
    "created_at": "2026-04-01T12:00:00Z"
  }
}

PATCH /api/v1/bots/{botID}/oauth2

Update OAuth2 Client

Updates the redirect URIs for the OAuth2 client. All redirect URIs must use HTTPS.

JWT Moderate

Path Parameters

botID string (UUID) path required

The bot account ID.

Body Parameters

redirect_uris string[] body required

Updated array of HTTPS redirect URIs.

curl -X PATCH https://api.cloakshell.com/api/v1/bots/01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012/oauth2 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "redirect_uris": ["https://myapp.example.com/callback", "https://staging.example.com/callback"]
  }'

Response

{
  "data": {
    "client_id": "01965c8a-6a7b-7c8d-9e0f-1a2b3c4d5e6f",
    "redirect_uris": ["https://myapp.example.com/callback", "https://staging.example.com/callback"],
    "created_at": "2026-04-01T12:00:00Z"
  }
}

DELETE /api/v1/bots/{botID}/oauth2

Delete OAuth2 Client

Deletes the OAuth2 client for a bot you own. All existing authorization codes are invalidated. Returns 204 No Content on success.

JWT Moderate

Path Parameters

botID string (UUID) path required

The bot account ID.

curl -X DELETE https://api.cloakshell.com/api/v1/bots/01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012/oauth2 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

(empty body, 204 No Content)

POST /api/v1/bots/{botID}/oauth2/reset-secret

Reset Client Secret

Generates a new client secret for the OAuth2 client. The old secret is invalidated. The new secret is returned exactly once in the response.

JWT Moderate

Path Parameters

botID string (UUID) path required

The bot account ID.

curl -X POST https://api.cloakshell.com/api/v1/bots/01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012/oauth2/reset-secret \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

{
  "data": {
    "client_id": "01965c8a-6a7b-7c8d-9e0f-1a2b3c4d5e6f",
    "client_secret": "cs_oauth_b2c3d4e5f6a7...new_secret",
    "redirect_uris": ["https://myapp.example.com/callback"],
    "created_at": "2026-04-01T12:00:00Z"
  }
}

Developer Portal

Endpoints for monitoring bot performance and managing verification. All endpoints require JWT authentication and bot ownership.

GET /api/v1/bots/{botID}/analytics

Get Analytics

Returns performance metrics for a bot you own, including install count, active communities, and usage statistics.

JWT Standard

Path Parameters

botID string (UUID) path required

The bot account ID.

curl -X GET https://api.cloakshell.com/api/v1/bots/01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012/analytics \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

{
  "data": {
    "install_count": 12,
    "active_communities": 8,
    "total_commands_executed": 1547,
    "total_events_delivered": 3892
  }
}

GET /api/v1/bots/{botID}/errors

Get Error Log

Returns a paginated list of recent errors for a bot you own. Includes callback failures, interaction timeouts, and delivery errors.

JWT Standard

Path Parameters

botID string (UUID) path required

The bot account ID.

Query Parameters

cursor string query optional

Pagination cursor from a previous response.

limit integer query optional

Number of entries to return. Maximum 100. (Default: 50)

curl -X GET "https://api.cloakshell.com/api/v1/bots/01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012/errors?limit=50" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

{
  "data": [
    {
      "id": "01965c8a-7b8c-7d9e-0f1a-2b3c4d5e6f7a",
      "type": "callback_failure",
      "message": "Connection refused",
      "callback_url": "https://mybot.example.com/events",
      "status_code": 0,
      "created_at": "2026-04-03T14:30:00Z"
    },
    {
      "id": "01965c8a-8c9d-7e0f-1a2b-3c4d5e6f7a8b",
      "type": "interaction_timeout",
      "message": "Bot did not respond within the timeout period",
      "callback_url": "https://mybot.example.com/interactions",
      "status_code": 0,
      "created_at": "2026-04-03T10:15:00Z"
    }
  ],
  "cursor": {
    "next": "MDEyMzQ1Njc4OWFi",
    "has_more": true
  }
}

POST /api/v1/bots/{botID}/test-event

Send Test Event

Sends a test event to the bot's callback URL. The event is signed with HMAC-SHA256 using the subscription secret. Use this to verify your callback endpoint is configured correctly.

JWT Restricted

Path Parameters

botID string (UUID) path required

The bot account ID.

Body Parameters

event_type string body required

The event type to send as a test. Must be a valid event type.

curl -X POST https://api.cloakshell.com/api/v1/bots/01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012/test-event \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"event_type": "message_create"}'

Response

{
  "data": {
    "status_code": 200,
    "response_body": "OK",
    "duration_ms": 142
  }
}

POST /api/v1/bots/{botID}/verification

Submit for Verification

Submits the bot for verification review. The bot must have a name, description, and interaction endpoint URL configured. Can only be submitted when the current status is unverified or rejected.

JWT Restricted

Path Parameters

botID string (UUID) path required

The bot account ID.

Body Parameters

privacy_policy_url string body required

HTTPS URL to the bot's privacy policy.

data_usage_description string body required

Description of what data the bot collects and how it is used.

terms_accepted boolean body required

Must be true to acknowledge acceptance of the developer terms.

curl -X POST https://api.cloakshell.com/api/v1/bots/01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012/verification \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "privacy_policy_url": "https://mybot.example.com/privacy",
    "data_usage_description": "This bot reads message content to provide weather updates. No data is stored.",
    "terms_accepted": true
  }'

Response

{
  "data": {
    "id": "01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012",
    "verification_status": "pending",
    "updated_at": "2026-04-03T16:00:00Z"
  }
}

Bot API

Endpoints for bot runtime actions within communities. All endpoints require bot token authentication (`Authorization: Bot <token>`). The effective permissions for any action are the intersection of the token scopes and the installation scopes.

POST /api/v1/bot-api/channels/{channelID}/messages

Send Message

Sends a message to a channel as the bot. The message can include text content, embeds, and interactive components.

Bot Token Moderate Scopes: SEND_MESSAGES

Path Parameters

channelID string (UUID) path required

The channel to send the message to.

Body Parameters

content string body optional

Message content. Maximum 4000 characters.

embeds array body optional

Array of embed objects. Maximum 5 embeds per message.

components array body optional

Array of action row objects containing buttons and select menus.

curl -X POST https://api.cloakshell.com/api/v1/bot-api/channels/01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e/messages \
  -H "Authorization: Bot YOUR_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello from the bot!",
    "embeds": [
      {
        "title": "Welcome",
        "description": "This is an automated message.",
        "color": "#0088FF"
      }
    ]
  }'

Response

{
  "data": {
    "id": "01965c8a-9d0e-7f1a-2b3c-4d5e6f7a8b9c",
    "channel_id": "01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
    "content": "Hello from the bot!",
    "author": {
      "id": "01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012",
      "username": "moderation-helper",
      "display_name": "Moderation Helper",
      "avatar_url": "https://cdn.cloakshell.com/uploads/bot-avatar/01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012.webp",
      "is_bot": true
    },
    "embeds": [],
    "components": [],
    "created_at": "2026-04-03T12:00:00Z"
  }
}

PATCH /api/v1/bot-api/channels/{channelID}/messages/{messageID}

Edit Message

Edits a message previously sent by the bot. Only provided fields are updated; omitted fields remain unchanged.

Bot Token Moderate Scopes: MANAGE_OWN_MESSAGES

Path Parameters

channelID string (UUID) path required

The channel containing the message.

messageID string (UUID) path required

The message to edit.

Body Parameters

content string body optional

Updated message content. Maximum 4000 characters.

embeds array body optional

Updated array of embed objects.

components array body optional

Updated array of action row objects.

curl -X PATCH https://api.cloakshell.com/api/v1/bot-api/channels/01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e/messages/01965c8a-9d0e-7f1a-2b3c-4d5e6f7a8b9c \
  -H "Authorization: Bot YOUR_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Updated message content."}'

Response

{
  "data": {
    "id": "01965c8a-9d0e-7f1a-2b3c-4d5e6f7a8b9c",
    "channel_id": "01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
    "content": "Updated message content.",
    "author": {
      "id": "01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012",
      "username": "moderation-helper",
      "display_name": "Moderation Helper",
      "avatar_url": "https://cdn.cloakshell.com/uploads/bot-avatar/01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012.webp",
      "is_bot": true
    },
    "embeds": [],
    "components": [],
    "edited_at": "2026-04-03T12:05:00Z",
    "created_at": "2026-04-03T12:00:00Z"
  }
}

DELETE /api/v1/bot-api/channels/{channelID}/messages/{messageID}

Delete Message

Deletes a message previously sent by the bot. Returns 204 No Content on success.

Bot Token Moderate Scopes: MANAGE_OWN_MESSAGES

Path Parameters

channelID string (UUID) path required

The channel containing the message.

messageID string (UUID) path required

The message to delete.

curl -X DELETE https://api.cloakshell.com/api/v1/bot-api/channels/01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e/messages/01965c8a-9d0e-7f1a-2b3c-4d5e6f7a8b9c \
  -H "Authorization: Bot YOUR_BOT_TOKEN"

Response

(empty body, 204 No Content)

PUT /api/v1/bot-api/channels/{channelID}/messages/{messageID}/reactions/{emoji}

Add Reaction

Adds a reaction to a message as the bot. The emoji must be URL-encoded. Returns 204 No Content on success.

Bot Token Moderate Scopes: ADD_REACTIONS

Path Parameters

channelID string (UUID) path required

The channel containing the message.

messageID string (UUID) path required

The message to react to.

emoji string path required

URL-encoded emoji character.

curl -X PUT https://api.cloakshell.com/api/v1/bot-api/channels/01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e/messages/01965c8a-9d0e-7f1a-2b3c-4d5e6f7a8b9c/reactions/%F0%9F%91%8D \
  -H "Authorization: Bot YOUR_BOT_TOKEN"

Response

(empty body, 204 No Content)

DELETE /api/v1/bot-api/channels/{channelID}/messages/{messageID}/reactions/{emoji}

Remove Reaction

Removes the bot's reaction from a message. Returns 204 No Content on success.

Bot Token Moderate Scopes: ADD_REACTIONS

Path Parameters

channelID string (UUID) path required

The channel containing the message.

messageID string (UUID) path required

The message to remove the reaction from.

emoji string path required

URL-encoded emoji character.

curl -X DELETE https://api.cloakshell.com/api/v1/bot-api/channels/01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e/messages/01965c8a-9d0e-7f1a-2b3c-4d5e6f7a8b9c/reactions/%F0%9F%91%8D \
  -H "Authorization: Bot YOUR_BOT_TOKEN"

Response

(empty body, 204 No Content)

GET /api/v1/bot-api/channels

List Channels

Returns all channels accessible to the bot in the installed community.

Bot Token Standard

curl -X GET https://api.cloakshell.com/api/v1/bot-api/channels \
  -H "Authorization: Bot YOUR_BOT_TOKEN"

Response

{
  "data": [
    {
      "id": "01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
      "name": "general",
      "type": "text",
      "community_id": "01965c8a-4e5f-7a6b-9c7d-8e9f0a1b2c3d",
      "position": 0
    },
    {
      "id": "01965c8a-6a7b-7c8d-9e0f-1a2b3c4d5e6f",
      "name": "announcements",
      "type": "text",
      "community_id": "01965c8a-4e5f-7a6b-9c7d-8e9f0a1b2c3d",
      "position": 1
    }
  ]
}

GET /api/v1/bot-api/channels/{channelID}/messages

Get Messages

Returns messages from a channel. Supports backward pagination using the before parameter.

Bot Token Standard Scopes: READ_MESSAGES

Path Parameters

channelID string (UUID) path required

The channel to read messages from.

Query Parameters

before string (UUID) query optional

Fetch messages before this message ID.

limit integer query optional

Number of messages to return. Maximum 100. (Default: 50)

curl -X GET "https://api.cloakshell.com/api/v1/bot-api/channels/01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e/messages?limit=50" \
  -H "Authorization: Bot YOUR_BOT_TOKEN"

Response

{
  "data": [
    {
      "id": "01965c8a-9d0e-7f1a-2b3c-4d5e6f7a8b9c",
      "channel_id": "01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
      "content": "Hello everyone!",
      "author": {
        "id": "01965c8a-0a1b-7c2d-8e3f-4a5b6c7d8e9f",
        "username": "example-developer",
        "display_name": "Example Developer",
        "avatar_url": null,
        "is_bot": false
      },
      "created_at": "2026-04-03T11:00:00Z"
    }
  ],
  "cursor": {
    "next": "YWJjZGVmMTIzNDU2",
    "has_more": true
  }
}

GET /api/v1/bot-api/communities/{communityID}

Get Community

Returns public information about the community where the bot is installed.

Bot Token Standard

Path Parameters

communityID string (UUID) path required

The community ID.

curl -X GET https://api.cloakshell.com/api/v1/bot-api/communities/01965c8a-4e5f-7a6b-9c7d-8e9f0a1b2c3d \
  -H "Authorization: Bot YOUR_BOT_TOKEN"

Response

{
  "data": {
    "id": "01965c8a-4e5f-7a6b-9c7d-8e9f0a1b2c3d",
    "name": "My Community",
    "description": "A community for developers",
    "member_count": 156,
    "icon_url": "https://cdn.cloakshell.com/uploads/community-icon/01965c8a-4e5f-7a6b-9c7d-8e9f0a1b2c3d.webp"
  }
}

GET /api/v1/bot-api/communities/{communityID}/members

List Members

Returns a paginated list of members in the community where the bot is installed.

Bot Token Standard Scopes: READ_MEMBERS

Path Parameters

communityID string (UUID) path required

The community ID.

Query Parameters

cursor string query optional

Pagination cursor from a previous response.

limit integer query optional

Number of members to return. Maximum 100. (Default: 50)

curl -X GET "https://api.cloakshell.com/api/v1/bot-api/communities/01965c8a-4e5f-7a6b-9c7d-8e9f0a1b2c3d/members?limit=50" \
  -H "Authorization: Bot YOUR_BOT_TOKEN"

Response

{
  "data": [
    {
      "user_id": "01965c8a-0a1b-7c2d-8e3f-4a5b6c7d8e9f",
      "username": "example-developer",
      "display_name": "Example Developer",
      "avatar_url": null,
      "joined_at": "2026-03-15T10:00:00Z"
    },
    {
      "user_id": "01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012",
      "username": "another-member",
      "display_name": "Another Member",
      "avatar_url": "https://cdn.cloakshell.com/uploads/avatar/01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012.webp",
      "joined_at": "2026-03-20T14:30:00Z"
    }
  ],
  "cursor": {
    "next": "eHl6MTIzNDU2Nzg5",
    "has_more": true
  }
}

Bot WebSocket Gateway

Real-time event delivery via WebSocket. The gateway provides an alternative to HTTP callbacks for receiving community events. Each bot can maintain one connection per community.

GET /api/v1/bot-gateway

Connect to Gateway

Upgrades the connection to a WebSocket. After connecting, send an IDENTIFY message (opcode 1) with your bot token promptly. The server responds with READY (opcode 2) containing your session ID and heartbeat interval. Use SUBSCRIBE (opcode 5) to subscribe to specific event types.

Bot Token Restricted

wscat -c "wss://api.cloakshell.com/api/v1/bot-gateway"

# After connecting, send IDENTIFY:
> {"op": 1, "d": {"token": "YOUR_BOT_TOKEN"}}

Response

{
  "op": 2,
  "d": {
    "session_id": "gw_a1b2c3d4e5f6",
    "bot_id": "01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012",
    "bot_name": "Moderation Helper",
    "community_id": "01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
    "heartbeat_interval": "<interval_ms>"
  }
}

Gateway Protocol

Message Format

All gateway messages use a JSON envelope with four fields: `op` (opcode integer), `d` (payload object), `s` (sequence number, server-to-client only), and `t` (event type name, only present when op is 0/DISPATCH).

Connection Lifecycle

After opening the WebSocket, send IDENTIFY (op 1) with your bot token promptly. The server responds with READY (op 2) containing a session ID and heartbeat interval. Send SUBSCRIBE (op 5) with the event types you want to receive. Events are delivered via DISPATCH (op 0) with a sequence number for resuming.

Heartbeat

The server sends HEARTBEAT (op 3) at the interval specified in the READY payload. Respond promptly with HEARTBEAT_ACK (op 4) or the connection will be closed.

Resume

If disconnected, reconnect and send RESUME (op 7) with your bot token, session ID, and the last sequence number received. The server replays missed events and sends RESUMED (op 8). Subscriptions persist across resume.

Constraints

1 concurrent connection per bot per community
Events are rate limited per connection
Messages exceeding the maximum size are rejected

Opcodes

Opcode	Name	Direction	Description
`0`	`DISPATCH`	Server → Bot	Event dispatched to the bot
`1`	`IDENTIFY`	Bot → Server	Authenticate with bot token
`2`	`READY`	Server → Bot	Authentication succeeded
`3`	`HEARTBEAT`	Server → Bot	Heartbeat ping from server
`4`	`HEARTBEAT_ACK`	Bot → Server	Heartbeat response from bot
`5`	`SUBSCRIBE`	Bot → Server	Subscribe to community events
`7`	`RESUME`	Bot → Server	Resume a disconnected session
`8`	`RESUMED`	Server → Bot	Resume succeeded
`9`	`ERROR`	Server → Bot	Error message

Events

Event	Description	Scope Required
`MESSAGE_CREATE`	New message posted in a channel. Content and embeds are included only if the bot has READ_MESSAGES scope; otherwise they are stripped.	Content requires READ_MESSAGES
`MESSAGE_UPDATE`	Message edited. Content and embeds are included only if the bot has READ_MESSAGES scope; otherwise they are stripped.	Content requires READ_MESSAGES
`MESSAGE_DELETE`	Message deleted. Only includes IDs.	None
`MEMBER_JOIN`	User joined the community. User details included only with READ_MEMBERS scope.	User details require READ_MEMBERS
`MEMBER_LEAVE`	User left, was kicked, or was banned. Only includes IDs.	None
`CHANNEL_CREATE`	New channel created in the community.	None
`CHANNEL_UPDATE`	Channel metadata changed (name, topic, position).	None
`CHANNEL_DELETE`	Channel deleted. Only includes the channel ID.	None
`REACTION_ADD`	Reaction added to a message.	None
`REACTION_REMOVE`	Reaction removed from a message.	None
`POST_CREATE`	New forum post created. Content is included only if the bot has READ_MESSAGES scope; otherwise it is stripped.	Content requires READ_MESSAGES
`POST_UPDATE`	Forum post edited. Content is included only if the bot has READ_MESSAGES scope; otherwise it is stripped.	Content requires READ_MESSAGES
`REPLY_CREATE`	New reply added to a forum post. Content is included only if the bot has READ_MESSAGES scope; otherwise it is stripped.	Content requires READ_MESSAGES

{
  "event_type": "message_create",
  "community_id": "01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
  "channel_id": "01965c8a-9d0e-7f1a-2b3c-4d5e6f7a8b9c",
  "data": {
    "id": "01965c8a-a1b2-7c3d-4e5f-6a7b8c9d0e1f",
    "channel_id": "01965c8a-9d0e-7f1a-2b3c-4d5e6f7a8b9c",
    "author": {
      "id": "01965c8a-0a1b-7c2d-8e3f-4a5b6c7d8e9f",
      "username": "example-developer",
      "display_name": "Example Developer",
      "avatar_url": ""
    },
    "content": "Hello everyone!",
    "created_at": "2026-04-03T14:30:00Z"
  }
}

{
  "event_type": "message_update",
  "community_id": "01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
  "channel_id": "01965c8a-9d0e-7f1a-2b3c-4d5e6f7a8b9c",
  "data": {
    "id": "01965c8a-a1b2-7c3d-4e5f-6a7b8c9d0e1f",
    "channel_id": "01965c8a-9d0e-7f1a-2b3c-4d5e6f7a8b9c",
    "author": {
      "id": "01965c8a-0a1b-7c2d-8e3f-4a5b6c7d8e9f",
      "username": "example-developer",
      "display_name": "Example Developer",
      "avatar_url": ""
    },
    "content": "Hello everyone! (edited)",
    "created_at": "2026-04-03T14:30:00Z",
    "edited_at": "2026-04-03T14:32:00Z"
  }
}

{
  "event_type": "message_delete",
  "community_id": "01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
  "channel_id": "01965c8a-9d0e-7f1a-2b3c-4d5e6f7a8b9c",
  "data": {
    "id": "01965c8a-a1b2-7c3d-4e5f-6a7b8c9d0e1f",
    "channel_id": "01965c8a-9d0e-7f1a-2b3c-4d5e6f7a8b9c"
  }
}

{
  "event_type": "member_join",
  "community_id": "01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
  "data": {
    "user_id": "01965c8a-0a1b-7c2d-8e3f-4a5b6c7d8e9f",
    "username": "example-developer",
    "display_name": "Example Developer",
    "avatar_url": "",
    "joined_at": "2026-04-03T15:00:00Z"
  }
}

{
  "event_type": "member_leave",
  "community_id": "01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
  "data": {
    "user_id": "01965c8a-0a1b-7c2d-8e3f-4a5b6c7d8e9f"
  }
}

{
  "event_type": "channel_create",
  "community_id": "01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
  "data": {
    "id": "01965c8a-9d0e-7f1a-2b3c-4d5e6f7a8b9c",
    "name": "announcements",
    "topic": "",
    "position": 2
  }
}

{
  "event_type": "channel_update",
  "community_id": "01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
  "data": {
    "id": "01965c8a-9d0e-7f1a-2b3c-4d5e6f7a8b9c",
    "name": "general",
    "topic": "Welcome to the community",
    "position": 0
  }
}

{
  "event_type": "channel_delete",
  "community_id": "01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
  "data": {
    "id": "01965c8a-9d0e-7f1a-2b3c-4d5e6f7a8b9c"
  }
}

{
  "event_type": "reaction_add",
  "community_id": "01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
  "channel_id": "01965c8a-9d0e-7f1a-2b3c-4d5e6f7a8b9c",
  "data": {
    "message_id": "01965c8a-a1b2-7c3d-4e5f-6a7b8c9d0e1f",
    "channel_id": "01965c8a-9d0e-7f1a-2b3c-4d5e6f7a8b9c",
    "user_id": "01965c8a-0a1b-7c2d-8e3f-4a5b6c7d8e9f",
    "emoji": "👍"
  }
}

{
  "event_type": "reaction_remove",
  "community_id": "01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
  "channel_id": "01965c8a-9d0e-7f1a-2b3c-4d5e6f7a8b9c",
  "data": {
    "message_id": "01965c8a-a1b2-7c3d-4e5f-6a7b8c9d0e1f",
    "channel_id": "01965c8a-9d0e-7f1a-2b3c-4d5e6f7a8b9c",
    "user_id": "01965c8a-0a1b-7c2d-8e3f-4a5b6c7d8e9f",
    "emoji": "👍"
  }
}

{
  "event_type": "post_create",
  "community_id": "01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
  "channel_id": "01965c8a-9d0e-7f1a-2b3c-4d5e6f7a8b9c",
  "data": {
    "id": "01965c8a-b2c3-7d4e-5f6a-7b8c9d0e1f2a",
    "channel_id": "01965c8a-9d0e-7f1a-2b3c-4d5e6f7a8b9c",
    "title": "Welcome to the forum",
    "content": "This is our first post!",
    "author": {
      "id": "01965c8a-0a1b-7c2d-8e3f-4a5b6c7d8e9f",
      "username": "example-developer",
      "display_name": "Example Developer",
      "avatar_url": ""
    },
    "created_at": "2026-04-03T16:00:00Z"
  }
}

{
  "event_type": "post_update",
  "community_id": "01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
  "channel_id": "01965c8a-9d0e-7f1a-2b3c-4d5e6f7a8b9c",
  "data": {
    "id": "01965c8a-b2c3-7d4e-5f6a-7b8c9d0e1f2a",
    "channel_id": "01965c8a-9d0e-7f1a-2b3c-4d5e6f7a8b9c",
    "title": "Welcome to the forum (updated)",
    "content": "This is our first post, now edited!",
    "author": {
      "id": "01965c8a-0a1b-7c2d-8e3f-4a5b6c7d8e9f",
      "username": "example-developer",
      "display_name": "Example Developer",
      "avatar_url": ""
    },
    "created_at": "2026-04-03T16:00:00Z",
    "edited_at": "2026-04-03T16:10:00Z"
  }
}

{
  "event_type": "reply_create",
  "community_id": "01965c8a-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
  "channel_id": "01965c8a-9d0e-7f1a-2b3c-4d5e6f7a8b9c",
  "data": {
    "id": "01965c8a-c3d4-7e5f-6a7b-8c9d0e1f2a3b",
    "post_id": "01965c8a-b2c3-7d4e-5f6a-7b8c9d0e1f2a",
    "channel_id": "01965c8a-9d0e-7f1a-2b3c-4d5e6f7a8b9c",
    "content": "Great first post!",
    "author": {
      "id": "01965c8a-1b2e-7d3f-8a4b-5c6d7e8f9012",
      "username": "another-member",
      "display_name": "Another Member",
      "avatar_url": ""
    },
    "created_at": "2026-04-03T16:15:00Z"
  }
}

Event Delivery

HTTP Callback Delivery

Events are delivered as POST requests to your subscription callback URL. Each request includes an `X-CloakShell-Signature` header containing an HMAC-SHA256 signature of the request body, signed with your subscription secret. Verify this signature to authenticate that the event came from CloakShell. Callback URLs must use HTTPS.

WebSocket Gateway Delivery

Events are delivered via DISPATCH (opcode 0) messages on the bot gateway WebSocket. Each dispatch includes a sequence number for resuming missed events. Subscribe to specific event types using the SUBSCRIBE opcode after connecting.

const crypto = require("crypto");
const signature = crypto
  .createHmac("sha256", subscriptionSecret)
  .update(requestBody)
  .digest("hex");
const isValid = signature === request.headers["x-cloakshell-signature"];

Guides

Slash Command Flow

How slash commands are executed from user input to bot response.

1
User Types Command
The user types a slash command (e.g., `/weather San Francisco`) in a channel where the bot is installed.
2
Frontend Sends Interaction
The frontend sends `POST /api/v1/interactions` with the command ID, channel ID, community ID, and command options.
3
Bot Receives Payload
CloakShell delivers the interaction payload to the bot's configured interaction endpoint URL via an HTTP POST request, signed with HMAC-SHA256.
4
Bot Responds
The bot processes the command and responds promptly with a response type (`message`, `ephemeral`, or `deferred`) and optional content, embeds, and components.
5
Message Created
For `message` responses, a bot message is created in the channel and broadcast to all members.
6
Deferred Follow-up (Optional)
If the bot responded with `deferred`, it calls `POST /api/v1/bot-api/interactions/{token}/callback` with the final response before the token expires.

Component Interaction Flow

How users interact with buttons and select menus on bot messages.

1
User Clicks Component
The user clicks a button or selects an option from a menu on a bot message.
2
Frontend Sends Interaction
The frontend sends `POST /api/v1/interactions` with the message ID, component custom ID, channel ID, and community ID.
3
Bot Receives Payload
CloakShell delivers the interaction to the bot's endpoint with the component's custom ID and the triggering user's context.
4
Bot Responds
The bot responds with one of: `message` (new message), `update_message` (edit the original), `ephemeral` (visible only to the user), `modal` (open a modal dialog), or `acknowledge` (no visible response).

OAuth2 Authorization Flow

How third-party applications authorize bot installations using OAuth2 with PKCE.

1
Redirect to CloakShell
Your application redirects the user to the CloakShell authorization page with your client ID, redirect URI, requested scopes, a random state parameter, and a PKCE code challenge (S256).
2
User Approves Installation
The user reviews the requested permissions, selects a community, and approves the bot installation.
3
Authorization Code Returned
CloakShell redirects back to your redirect URI with an authorization code and the state parameter for CSRF verification.
4
Exchange Code for Installation
Your server exchanges the authorization code via `POST /api/v1/oauth2/token` with your client credentials and PKCE code verifier.
5
Installation Complete
The response includes the installation ID, community ID, and granted scopes. The bot is now installed in the selected community.

Reference

Limits

Constraint	Value
Bots per developer	Limited per account (CloakShell+ only)
Bots per community	Limited per community (CloakShell+ only)
Embeds per message	5
Embed fields per embed	25
Embed total characters	6,000
Action rows per message	5
Buttons per action row	5
Select options per menu	25
Modal text inputs	5
Modal title length	45 characters
Text input value length	4,000 characters
Interaction token expiry	Short-lived
Slash command response timeout	Short window
Bot gateway connections	1 concurrent connection per bot per community
Callback URL protocol	HTTPS only
Event subscriptions per installation	Limited per installation
Event types per subscription	All supported event types