KiaiKiai API
Kiai provides a public API that lets developers extend the bot's functionality.
API Endpoints
Find the full list of endpoints and request/response shapes at https://kiai.app/api/v2/docs.
Every endpoint is scoped to a server (guildId) and requires a specific permission on your application:
| Method | Path | Permission required |
|---|---|---|
| GET | /api/v2/me | Any valid token |
| POST | /api/v2/virtual_message | Levels |
| GET | /api/v2/:guildId/leaderboard | Levels |
| GET | /api/v2/:guildId/member/:userId | Levels |
| PATCH | /api/v2/:guildId/member/:userId/xp | Levels |
| PUT | /api/v2/:guildId/member/:userId/xp | Levels |
| GET | /api/v2/:guildId/settings | Levels |
| GET, POST, DELETE | /api/v2/:guildId/denylist | Denylist |
| GET, POST, DELETE | /api/v2/:guildId/multipliers | Multipliers |
| GET, POST, DELETE | /api/v2/:guildId/rewards | Rewards |
| GET, POST, DELETE | /api/v2/:guildId/leaderboard-roles | Rewards |
GET /api/v2/me returns your application's own ID, owning user, rate limit, and the list of permissions it holds in each authorized server. Use it to confirm your token works and to check what it can do.
Getting an Application
To call the API, you need an application and its key (also called a token).
- Go to your Kiai Dashboard and open API Applications.
- Create a new application with a name and a Discord application ID.
- Copy the key shown on the application's page. Kiai only shows the full key here; store it somewhere safe.
If you believe your key has leaked, regenerate it from the same page. Regenerating replaces the old key immediately, and any requests using the old key stop working right away.
Authorizing an Application to a Server
An application must be authorized to each server it accesses, similar to how a Discord bot must be added to a server.
Use the /application command in the server you want to connect. This command requires the Manage Server permission.
/application authorize <id>— Authorizes an application to the server and lets you choose which permissions to grant./application deauthorize <id>— Revokes a previously authorized application's access./application list— Lists every application currently authorized in the server.
You can also build an authorize link from your application's dashboard page and send it to a server manager, who can open it to grant access without needing the application's ID.
Permissions
Permissions determine what actions an application can perform. You grant them during authorization, and you can change them later by running /application authorize again.
Kiai stores permissions as an integer, with each permission assigned to one bit.
List of Permissions
| Permission Name | Description | Bit | Value |
|---|---|---|---|
| Levels | View and edit all levels and XP | 0 | 0x0001 |
| Multipliers | View and edit multipliers | 1 | 0x0002 |
| Export | Export data from your server | 2 | 0x0004 |
| Denylist | View and edit the server's denylist | 3 | 0x0008 |
| Rewards | View and edit the server's rewards and leaderboard position roles | 4 | 0x0010 |
The value for every permission combined is 0x001F.
Authentication
Send your application's key as the Authorization header on every request. Do not add a Bearer prefix.
Authorization: <your-application-key>
Rate Limits
Each application has a rate limit of 60 requests per minute by default. You can raise this to 120 requests per minute from your application's dashboard page.
If you exceed your limit, Kiai responds with 429 Too Many Requests. Every response, not only rate-limited ones, includes these headers so you can track your usage:
x-ratelimit-limitx-ratelimit-remainingx-ratelimit-resetx-ratelimit-reset-after
If 120 requests per minute is not enough for your use case, contact support.