The official JavaScript/TypeScript API library for Kiai - a powerful Discord leveling and rewards system.
# Using npm
npm install kiai.js
# Using yarn
yarn add kiai.js
# Using pnpm
pnpm add kiai.js
# Using bun
bun add kiai.jsimport { KiaiClient } from "kiai.js"
const kiai = new KiaiClient("your-api-key") // API v3 by default
const member = await kiai.leveling.getMember("guild_id", "user_id")
console.log(`User XP: ${member?.xp ?? 0}`)For detailed documentation, visit our documentation site.
kiai.js provides several handlers to interact with different aspects of the API. These handlers mirror the API categories on our API v3 docs.
Leveling- Levels, XP, prestige, leaderboards, and server statsRewards- Declarative rewards, reward paths, capabilities, and reconciliation jobsLeaderboardRolesandAutoLeaderboards- Leaderboard role and message managementLevelUpMessages- Read configured level-up messagesSettings- Read guild settingsMultipliersandCooldowns- XP multipliers and cooldown overridesDenylist- Manage denied channels, roles, and usersMisc- Application, guild status, export, feature preview, and XP drop endpoints
// Add XP to a user
await kiai.leveling.addXp("guild_id", "user_id", 100)
// Query a leaderboard by category and period
const leaderboard = await kiai.leveling.getLeaderboard("guild_id", {
type: "xp",
time: "WEEK",
start: 1,
end: 10
})// Create a role reward
const reward = await kiai.rewards.createReward("guild_id", {
type: "ROLE",
threshold: { level: 10, prestige: null },
eligibility: { requiredRoleId: null },
config: { roleId: "role_id", operation: "ADD", durationMs: null }
})
// List rewards (or filter by type, level, and prestige)
const rewards = await kiai.rewards.getRewards("guild_id", { type: "ROLE" })const path = await kiai.rewards.createPath("guild_id", { name: "Explorer" })
const paths = await kiai.rewards.getPaths("guild_id")
const current = await kiai.rewards.getPath("guild_id", path.id)
// Replaces all editable fields. Use archived: true to archive instead of deleting.
await kiai.rewards.replacePath("guild_id", path.id, {
name: current.name,
description: current.description,
emoji: current.emoji,
archived: false
})
const settings = await kiai.rewards.getPathSettings("guild_id")
await kiai.rewards.setPathSettings("guild_id", { allowRewardPathSwitching: true })
const memberPath = await kiai.rewards.getMemberPath("guild_id", "user_id")
await kiai.rewards.assignMemberPath("guild_id", "user_id", {
rewardPathId: path.id,
expectedRewardPathId: memberPath.rewardPathId
})Assignment returns synced as well as the member and path IDs. Omit expectedRewardPathId to skip the concurrency check; null expects no current path. Role reward create/update inputs also accept rewardPathId: null means Everyone, while omission on update preserves the current assignment. Other reward types do not accept it. Path operations require the guild's rewards-path experiment and appropriate API permissions; server errors propagate normally. An archived path cannot be newly assigned.
This project is licensed under the MIT License - see the LICENSE file for details.
Developed and maintained by Buape Studios.