Skip to main content
The System API provides endpoints for monitoring bot health, retrieving configuration, accessing statistics, and managing global key-value storage.

​
Get Bot State

Retrieve the current state of the bot, including registered commands. Endpoint: GET /bot-state
Get Bot State
curl -X GET "https://splashtail-staging.antiraid.xyz/bot-state"

​
Response

​
commands
array
Array of registered Discord commands with their configuration.
{
  "commands": [
    {
      "name": "help",
      "description": "Get help with AntiRaid commands",
      "type": 1,
      "options": [],
      "contexts": [0, 1]
    }
  ]
}
Bot state is cached and updated whenever commands are registered. This endpoint is public and does not require authentication.

​
Get API Configuration

Retrieve the base API configuration, including server IDs and OAuth client information. Endpoint: GET /config
Get Configuration
curl -X GET "https://splashtail-staging.antiraid.xyz/config"

​
Response

​
main_server
string
The main Discord server (guild) ID for Anti-Raid
​
client_id
string
The Discord OAuth2 client ID
​
support_server_invite
string
Invite link to the support server
{
  "main_server": "1234567890",
  "client_id": "987654321",
  "support_server_invite": "https://discord.gg/example"
}
This configuration is useful for client applications that need to know the Discord client ID for OAuth2 flows or want to direct users to the support server.

​
Get Bot Statistics

Retrieve real-time statistics about the bot, including shard information, guild count, and user count. Endpoint: GET /bot-stats
Get Bot Stats
curl -X GET "https://splashtail-staging.antiraid.xyz/bot-stats"

​
Response

​
shard_conns
object
Map of shard IDs to shard connection information
​
total_guilds
integer
Total number of guilds across all shards
​
total_users
integer
Total number of cached users
{
  "shard_conns": {
    "0": {
      "status": "READY",
      "real_latency": 45.2,
      "guilds": 150,
      "uptime": 3600,
      "total_uptime": 86400
    },
    "1": {
      "status": "READY",
      "real_latency": 52.1,
      "guilds": 143,
      "uptime": 3600,
      "total_uptime": 86400
    }
  },
  "total_guilds": 293,
  "total_users": 15420
}
Statistics are cached for 100 seconds to reduce load on the system. Subsequent requests within this window will return cached data.

​
List Global Key-Value Pairs

List global key-value pairs from the template shop or other global storage scopes. This is used for discovering available templates and other shared resources. Endpoint: GET /global-kvs
List Global KVs
curl -X GET "https://splashtail-staging.antiraid.xyz/global-kvs?scope=template_shop&query=%" \
  -H "Authorization: YOUR_TOKEN"
​
scope
string
required
The scope to filter by (e.g., “template_shop” for template shop listings)
​
query
string
default:"%"
SQL LIKE pattern to filter keys. Use ’%’ for wildcards. Defaults to ’%’ which lists all keys.

​
Response

​
items
array
Array of partial global KV objects
{
  "items": [
    {
      "scope": "template_shop",
      "key": "moderation-suite",
      "version": 3,
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "scope": "template_shop",
      "key": "welcome-system",
      "version": 1,
      "created_at": "2024-01-20T14:22:00Z"
    }
  ]
}
Authentication is required for this endpoint. Use an OAuth2 session or API token.

​
Get Specific Global Key-Value

Retrieve the full data for a specific global key-value entry, including its complete value and metadata. Endpoint: GET /global-kvs/{scope}/{key}/{version}
Get Global KV
curl -X GET "https://splashtail-staging.antiraid.xyz/global-kvs/template_shop/moderation-suite/3" \
  -H "Authorization: YOUR_TOKEN"
​
scope
string
required
The scope of the KV entry (e.g., “template_shop”)
​
key
string
required
The key identifier
​
version
integer
required
The version number to retrieve

​
Response

​
scope
string
The scope of the KV entry
​
key
string
The key identifier
​
version
integer
Version number
​
value
object
The stored value (structure depends on the use case)
​
created_at
string
ISO 8601 timestamp of creation
​
updated_at
string
ISO 8601 timestamp of last update
{
  "scope": "template_shop",
  "key": "moderation-suite",
  "version": 3,
  "value": {
    "name": "Moderation Suite",
    "description": "Complete moderation toolkit",
    "author": "123456789",
    "commands": ["ban", "kick", "mute"]
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

​
Use Cases

Health Monitoring

Use /bot-stats to monitor bot health, shard status, and detect connectivity issues

Template Discovery

List and retrieve template shop entries using the global KV endpoints

Client Configuration

Use /config to get OAuth2 client ID and support server links for your application

Command Registry

Query /bot-state to see all registered commands and their configuration

​
Rate Limiting

All system endpoints respect standard API rate limits. Statistics endpoints have additional caching:
  • /bot-stats - 100 second cache
  • /bot-state - Cached indefinitely, updated on command registration

​
Next Steps

Authentication

Learn how to authenticate API requests

Internal API

Explore internal monitoring and management endpoints

Build docs developers (and LLMs) love

Get started for freeTalk to us