Read-only contract / v1
Progression data, without guesswork.
A typed, authenticated interface for guild metadata, members, ranks, leaderboards, and rewards. Every endpoint is scoped to an API key's managed guilds.
- Base URL
- /api/v1
- Authentication
- Bearer YOUR_API_KEY
- Page limit
- 1-100 results
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /guilds/{guildId} | Guild metadata |
| GET | /guilds/{guildId}/members/{userId} | Member progression |
| POST | /guilds/{guildId}/members/bulk | Up to 100 members |
| GET | /guilds/{guildId}/leaderboards/total | Total XP leaderboard |
| GET | /guilds/{guildId}/leaderboards/weekly | Weekly XP leaderboard |
| GET | /guilds/{guildId}/members/{userId}/rank | Total or weekly rank |
| GET | /guilds/{guildId}/rewards | Configured level rewards |
TypeScript SDK
import { InochiClient } from "@inochi/sdk";
const inochi = new InochiClient({
apiKey: process.env.INOCHI_API_KEY!,
baseUrl: "https://your-instance.example/api/v1",
});
for await (const member of inochi.leaderboards.iterateTotal(guildId)) {
console.log(member.rank, member.userId, member.xp);
}Pass a custom fetch for testing or non-browser runtimes. Requests time out after 10 seconds by default. A 429 throws InochiRateLimitError with retryAfterMs; all other API failures throw InochiApiError.
Stable errors. Opaque cursors.
Errors use { error: { code, message, requestId, details? } }. Follow nextCursor rather than constructing cursors; pagination is capped at 10,000 ranked results per traversal.