Bulk API

For scripts: send many finished items in one request with a personal token, and read your play time back.

Get a personal token

In the game: Account > Finished items > Create a personal token. Copy it straight away; it's shown once. You can have up to 5. A token can only send finished items and read your play time, and you can revoke it at any time on the same panel. Only a hash of it is stored.

POST /api/items

curl -X POST https://ironvaleidle.com/api/items \
  -H "Authorization: Bearer ivp_..." -H "Content-Type: application/json" \
  -d '{"items":[{"source":"github","id":"PR_kwDO123","type":"pr_merged","completedAt":"2026-10-29T16:05:00Z"}]}'

Field	Rules
`source`	Lowercase letters, digits, `.`, `-` or `_`, up to 32 characters. `github.com` is reserved for the built-in GitHub connection (refused as `reserved_source`)
`id`	The tool's id for the item: a string of 1 to 256 characters, or a number. Hashed on arrival
`type`	Same characters as `source`; sets the weight
`completedAt`	ISO 8601 or epoch milliseconds; not more than 35 days old nor 10 minutes in the future

Up to 200 items and 64 KB per request. A bare array instead of { "items": [...] } also works.
Repeats count once, within one request or across requests, so re-sending a whole day is harmless.
Any other field is ignored and never stored.
At most 16 different sources per player.

The answer lists what was accepted, what was already known, what was refused and why, and your play time:

{ "accepted": 1, "duplicates": 0, "rejected": [], "credit": { ... } }

Each refused item comes back as { "index": 3, "code": "..." } with the item's position in your list.

GET /api/credit

With the same Bearer token: play time left, the most your bank can hold (96 h), your time zone and rest days, today's items against your benchmark, your sources with their benchmarks and weights, and this and last week's counts.

curl https://ironvaleidle.com/api/credit -H "Authorization: Bearer ivp_..."

Limits

A short burst of requests, then one every 2 minutes per player (shared with the Claude connector).
500 new items a day per player, counted by the UTC day they arrive and shared with Claude and webhooks. Past it, each item is rejected with daily_limit.
Anything finished more than 7 days ago is stored for your history but earns no play time.

GET /api/leaderboard

The public boards, with no token: the top 100 of one board, refreshed about every 15 minutes.

curl "https://ironvaleidle.com/api/leaderboard?board=season&metric=gold"

Parameter	Values
`metric`	`skill` (default): total level, ties broken by total XP, then by who got there first. `gold`: lifetime coins earned. Any other value gets `skill`
`board`	`alltime` (default), `30d` or `season`. The last two rank what was gained in the window: levels (ties: XP) or coins. Anything else is refused as `bad_board`

{ "board": "season", "metric": "gold", "metrics": ["skill", "gold"], "generatedAt": 1793000000000,
  "season": { "number": 1, "startsAt": ..., "endsAt": ..., "started": true },
  "rows": [{ "rank": 1, "name": "Brisk Otter", "value": 48200, "tie": 9310000, "level": 412, "xp": 31800000, "coins": 520400 }] }

value is what the board ranks and tie the XP that breaks ties, both as gains on the 30-day and season boards; level, xp and coins are all-time totals.