Kiwi API Documentation

Overview

The API is authenticated with API tokens. You create your account and mint tokens in the developer portal - a website you use in your browser - and your programs then send one of those tokens with every request.

Get an API token

Everything in this step happens in the developer portal - a website, in your browser. Programs don't sign up or sign in; they only use the token you create here.

1. Create an account. Open the developer portal and sign up - protected by a captcha and rate limiting. You'll get a verification email; confirm it before creating tokens.
2. Sign in and open the Tokens tab.
3. Create a token. Give it a name, choose its scopes (e.g. rotations:read, feeds:read) or grant all access, restrict it to the IP addresses your code runs from, and pick an expiry (30 / 60 / 90 days, or none).
4. Copy the secret. It looks like kiwi_xxxxxxxx…_xx and is shown exactly once - store it in your secrets manager now. Only a hash is kept server-side, so it can never be shown again (rotate the token if you lose it).

Authenticating

Send your API token as a Bearer credential on every request to the data API. There's no login call and no session to manage - the token is the credential.

export KIWI_TOKEN="kiwi_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Once data endpoints are published, authenticate them like this:
curl https://api.aallyn.net/v1/<endpoint> \
  -H "Authorization: Bearer $KIWI_TOKEN"

Each request is checked against the token's restrictions:

• A request from an IP that isn't on the token's allowlist → 403 ip_not_allowed.
• A token missing a required scope → 403 insufficient_scope.
• A revoked or expired token → 401 not_authenticated.

Data endpoints

Live Trove game data, grouped by function into nine categories, each with its own scope: rotations (rotations:read) - server time, bonuses, merchants, biomes; feeds (feeds:read) - news, Twitch streams, YouTube / Bilibili videos, and the Trovesaurus event calendar; stats (stats:read) - raw stat tables and class definitions; gems (gems:read) - a gem simulator, evaluator, and build optimizer; misc (misc:read) - a modding-software list and a time converter; mods (mods:read) - decompile and build .tmod files; updates (updates:read) - browse the archived game files (versions, directory tree, single-file download); codexes (codexes:read) - structured game data (allies, mounts, dragons, mementos, recipes, items, fish, badges) parsed from the archive; and btt (btt:read) - BetterTroveTools releases (latest version per platform, per channel) for in-app update checks. Rotations, feeds and stats are GET, read-only (timestamps are real-UTC unix seconds); the gem and mod tools add POST calculators. The API reference has the full field-level schema for each.

rotations, feeds, codexes and btt are public - callable with no token at a stricter per-IP rate limit (30 req/min/IP by default). Send a token carrying the scope to lift it to the full per-token limit (120 req/min). codexes gets 5× both budgets (150 req/min/IP anonymous, 600 req/min/token). Every other category requires a token with the matching scope.

News, streams, videos, and events are relayed from upstream sources and cached/stored server-side (refreshed on a timer), so your code hits one fast, consistent API. Events are kept after they leave the upstream feed, so /events/history and /events/upcoming work alongside what's ongoing; categories are free-form and discovered dynamically. Stat tables and classes are raw game data - transmitted as-is, no calculation. Each class carries a stable tech_name token you can store and look it up by later.

The gem tools are stateless: nothing is stored server-side. generate returns a gem object; you hold it and POST it back to an action endpoint (augment, spark, flare, level-up, set-level) with a stat_position (0, 1 or 2) to mutate it, and it's returned updated. evaluate and builds/calculate are pure calculators; the lookups and builds/options endpoints tell you every valid field value to send.

The mod tools are stateless too. /mods/read takes the raw .tmod bytes as the request body and returns its header properties and file table (paths, sizes, FNV checksums); pass ?metadata_only=true to skip the (base64) file contents. /mods/build takes header fields + files and returns a freshly built .tmod as application/octet-stream - built in memory and discarded once sent. The built mod's modLoader header is stamped KiwiAPI. These two endpoints accept a larger 20 MB body.

Example: a merchant timer

curl https://api.aallyn.net/v1/rotations/fluxion \
  -H "Authorization: Bearer $KIWI_TOKEN"

# → {
#   "active": true,
#   "state": "voting",                 // voting | selling | away
#   "starts_at": 1717326000,
#   "ends_at": 1717585200,
#   "seconds_remaining": 46800,        // to leaving when active, else to arriving
#   "schedule": [                      // upcoming windows, soonest first
#     { "starts_at": …, "ends_at": …, "state": "voting" },
#     { "starts_at": …, "ends_at": …, "state": "selling" }
#   ]
# }

Example: the biome rotation

curl https://api.aallyn.net/v1/rotations/biomes \
  -H "Authorization: Bearer $KIWI_TOKEN"

# → {
#   "current":  { "starts_at": …, "ends_at": …,
#                 "biomes": [ { "name": "Volcanic Fields", "final_name": "Dragonfire Peaks", "icon": "dragon" }, … ] },
#   "upcoming": [ { "starts_at": …, "ends_at": …, "biomes": [ … ] }, … ]
# }

News refreshes on a background timer; everything else is computed on demand. daily-buffs / weekly-buffs return the current buff plus the whole rotation (full game data: name, color, emoji, buff lists, icons).

Rate limits

Limits are enforced per fixed window. Every rate-limited response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (unix seconds) headers so you can self-throttle. When you exceed a limit you receive 429 with an additional Retry-After header (seconds to wait).

Error responses

Every error returns a consistent JSON envelope with a stable, machine-readable code you can branch on, a human-readable message, and optional details.

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Slow down and try again later.",
    "details": { "limit": 120, "window_seconds": 60 }
  }
}