Public API
Everything public on this site is readable as JSON. Read-only, no sign-up, version 1.
Using the API
The base is https://scarletweb.io/api/v1/public. Answers are JSON in UTF-8, wrapped as {"data": ..., "meta": {...}}. Times are ISO 8601 in UTC, durations are seconds, money is copper. Any origin may call it from a browser. Answers can be cached for 5 minutes, those that name characters (leaderboards, search and characters) for 30 seconds, and carry an ETag: send it back as If-None-Match and an unchanged answer is 304.
curl https://scarletweb.io/api/v1/public/stats
Limits and keys
60 requests a minute per IP address without a key; IPv6 addresses count by their /64. A key from your account page raises that to 600 for your account, shared by all its keys: any personal access token with the public:read ability, sent as Authorization: Bearer <key>. Over the limit the answer is 429 with Retry-After in seconds. A key that is unknown, expired or lacks the ability is 401 invalid_token, and after 10 of those in a minute an address gets 429.
Pagination
A list answers its rows in data and meta.next_cursor. Pass the cursor back as ?cursor= with the same other parameters. A null cursor is the end. limit is 1 to 100, 25 by default. A number a bucket cannot show because fewer than meta.min_characters characters contributed comes back as null or is left out.
Errors
A refusal is {"error": {"code": "...", "message": "..."}} with the HTTP status: 404 not_found, 422 invalid_request (with fields), 401 invalid_token, 429 rate_limited (with retry_after). Codes do not change; messages are for people.
GET/api/v1/public/stats
Headline numbers: characters, experience, time recorded, kills, deaths, quests and money, with when the data starts and was last updated.
| Parameter | Meaning |
|---|---|
ruleset | Query. string. A ruleset slug from /rulesets. Leave out for all rulesets. |
server | Query. string. all, pve or pvp: the rulesets of one kind of server. Ignored when ruleset is given. |
data.totals, data.coverage, data.rulesets. A total is null while fewer than meta.min_characters characters contributed to it.
curl https://scarletweb.io/api/v1/public/stats
GET/api/v1/public/camps
How characters use campfires: visits, how long they last, what gets set up, the Camp Benefits players leave with, play while holding them, where and when characters camp, and the characters with the most time by the fire.
| Parameter | Meaning |
|---|---|
ruleset | Query. string. A ruleset slug from /rulesets. Leave out for all rulesets. |
server | Query. string. all, pve or pvp: the rulesets of one kind of server. Ignored when ruleset is given. |
data.totals (visits, characters, seconds, median_seconds, played_seconds and the counts of visits that earned Camp Benefits, sat, used a tent, logged out or died after, with the AFK and crafting figures), fires (visits by the campfire the character placed, and spell_id null for a fire already there), camp_benefits, benefits (the nine benefit buffs: spell_id, label, effect, gains, two_hour_gains, seconds, lost_to_death, characters), lengths (visits by step of 30 seconds, 40 is 20 minutes and over), by_level, hours (visit starts by UTC weekday, 0 is Sunday, and hour), buffed (play with Camp Benefits against the same levels across all play), zones, heat (cells of the zone map with the most visits), board (the first rows of most-time-by-the-fire) and rulesets. A figure is null or its row is left out while fewer than meta.min_characters characters contributed to it.
curl https://scarletweb.io/api/v1/public/camps
GET/api/v1/public/professions/{slug}
How characters work with one profession. The four gatherings, fishing, herbalism, mining and skinning, answer with attempts and catches, the time they take, what they give, the rank characters reach, where and when they gather, and the characters with the most catches. The eight crafts, alchemy, blacksmithing, enchanting, engineering, leatherworking, tailoring, cooking and first-aid, answer with crafts, their sittings, recipes, reagents, the rank characters reach, where and when they craft, and the characters with the most crafts. Every other slug answers 404.
| Parameter | Meaning |
|---|---|
slug | In the path. string. A profession slug: fishing, herbalism, mining, skinning, alchemy, blacksmithing, enchanting, engineering, leatherworking, tailoring, cooking or first-aid. |
ruleset | Query. string. A ruleset slug from /rulesets. Leave out for all rulesets. |
server | Query. string. all, pve or pvp: the rulesets of one kind of server. Ignored when ruleset is given. |
For a crafting profession: data.profession (the slug), totals (crafts, made, characters, scope_characters, recipes, sittings, median_sitting_crafts, median_sitting_seconds, median_gap, skill_ups, trivial, median_skill, at_cap), recipes (the twelve with the most crafts, with item_id, item, crafts, made, skill_ups, characters, median_skill and reagents), difficulty (crafts and skill_ups by the recipe's difficulty, 0 optimal to 3 trivial), per_point (by band of 25 ranks), by_level, hours (crafts by UTC weekday, 0 is Sunday, and hour), reagents (what the crafts used), zones, board (the first rows of the board of crafts) and rulesets. For a gathering: data.kind (fish, herb, ore or skin), totals (attempts, looted, characters, scope_characters, seconds, played_seconds, median_seconds, trips with their median length and attempts, in_combat, skill_ups, median_skill, at_cap, items, container_catches, and schools for fishing or first_strikes for mining, null for the others), items and contents (what came out of caught containers), waits (looted attempts by step of 2 seconds, 15 is 30 seconds and over), per_point (by band of 25 ranks), by_level, hours (attempt starts by UTC weekday, 0 is Sunday, and hour), lures, lured and poles (fishing), creatures (skinning), zones, heat (cells of the zone map with the most attempts, counted as visits), board (the first rows of the board of looted attempts) and rulesets. A figure is null or its row is left out while fewer than meta.min_characters characters contributed to it.
curl https://scarletweb.io/api/v1/public/professions/fishing
GET/api/v1/public/rulesets
Every ruleset with the numbers of the comparison table and its levelling curve.
data: a list of rulesets with slug, label, hardcore, war_mode, kind (normal, pvp, roleplay, roleplay-pvp or hardcore, null while Scarlet cannot tell which ruleset a character is on), recorded (false for the row of characters whose ruleset is not known yet), characters, seconds, deaths, xp, quest_xp, reached (characters whose level is at least the target, whether or not Scarlet saw them level up), median_to_target (only from recorded level-ups) and levelling (level, median seconds, characters that recorded the level-up).
curl https://scarletweb.io/api/v1/public/rulesets
GET/api/v1/public/rulesets/{slug}
The headline numbers of one ruleset.
| Parameter | Meaning |
|---|---|
slug | In the path. string. A ruleset slug from /rulesets. |
The same as /stats, for this ruleset.
curl https://scarletweb.io/api/v1/public/rulesets/normal
GET/api/v1/public/rulesets/{slug}/series/{series}
One series of a ruleset: levels, cap, xp, deaths, dungeons, professions, gold or activity. Use all as the slug for every ruleset.
| Parameter | Meaning |
|---|---|
slug | In the path. string. A ruleset slug, or all. |
series | In the path. string. The series name. |
data: the rows of the series. Buckets with fewer than meta.min_characters characters are left out.
curl https://scarletweb.io/api/v1/public/rulesets/all/series/levels
GET/api/v1/public/leaderboards
The boards: fastest to level 20, 40 and 60, highest level without dying, most quests turned in, most quests completed, most kills, most jumps, most dungeon runs, most distance, most time by the fire, most fish caught, most herbs gathered, most ore mined and most creatures skinned.
data: a list of boards with board (the name used in the path), title, description and value (the heading of the value column).
curl https://scarletweb.io/api/v1/public/leaderboards
GET/api/v1/public/leaderboards/{board}
One board, best first. Only public characters with counted sessions are listed.
| Parameter | Meaning |
|---|---|
board | In the path. string. A board name from /leaderboards. |
ruleset | Query. string. A ruleset slug from /rulesets. Leave out for all rulesets. |
server | Query. string. all, pve or pvp: the rulesets of one kind of server. Ignored when ruleset is given. |
class | Query. string. A class file name such as WARRIOR. |
cursor | Query. string. The next_cursor of the previous page. |
limit | Query. integer. Rows per page, 1 to 100. Default 25. |
data: rows with rank, name, race, class, value, ruleset, hardcore, deaths, since (the date the character was first recorded, null when recorded from level 1) and at. meta.next_cursor, meta.total.
curl https://scarletweb.io/api/v1/public/leaderboards/most-quests?limit=2
GET/api/v1/public/search
Characters (only those made public), creatures, items, zones and quests whose name holds every word of the text, and the site's own pages. Best match first: exact, prefix, word, contains, then a close spelling when nothing else matched.
| Parameter | Meaning |
|---|---|
q | Query. string. The text to search for, 2 to 80 characters. |
kind | Query. string. characters, creatures, items, zones or quests. Leave out for the first hits of every kind and the pages. |
cursor | Query. string. The next_cursor of the previous page. |
limit | Query. integer. Rows per page, 1 to 100. Default 25. |
Without kind: data has one entry per kind and a sixth, pages, each with count and hits. With kind: data is the list of hits, paged with meta.next_cursor. A hit has kind, id, name, path, match (exact, prefix, word, contains or fuzzy) and the numbers of its kind; a text of digits also finds the creature, item, quest or zone with that id as an exact hit. A page hit has title, path, meta and match.
curl https://scarletweb.io/api/v1/public/search?q=ash&kind=zones
GET/api/v1/public/characters/{name}
A public character: race, class, level, ruleset, time played, this week, distance walked, feats and standings. A character that is not public answers 404.
| Parameter | Meaning |
|---|---|
name | In the path. string. The character name, Name-Surname. |
data: name, race, class, faction, level, played_seconds (the total the game reports, null until Scarlet has read it), recorded_seconds (play Scarlet counted), first_level, recorded_since, whole_life (recorded from level 1), ruleset, last_seen_at, week, distance, feats (every feat that applies to the character: those earned first, rarest first, then those not yet earned, closest first; pinned is true for a feat the owner pinned, which keeps its place in the list. key is one of summit, veteran, devoted, steadfast, seasoned, regular, long-haul, longstanding, unbroken, slayer, bestiary, finisher, gladiator, rampage, fallen, flattened, nemesis, territorial, roamer, questing, errand-runner, fickle, cartographer, local-hero, thorough, delver, vanquisher, spelunker, raider, conqueror, deep-dweller, flawless, familiar, soloist, full-house, explorer, globetrotter, local, wayfarer, jumper, swimmer, runner, rider, stroller, flyer, tracker, scout, witness, naturalist, skullseer, looter, scavenger, lucky, collector, jackpot, curator, unboxer, angler, fishmonger, wading, gatherer, forager, artisan, master, practised, crafter, repertoire, earner, spender, tycoon, windfall, expressive, mime, signature, indecisive; the gold feats earner, spender, tycoon and windfall are listed only when meta.economy is true; name, value, tier from 0 for none to 5 for legend, with tier_name one of Copper, Silver, Gold, Scarlet or Legend, threshold of the tier held and next, the threshold of the tier above, null at the top; artisan counts the sum of the character's profession ranks), standings (a list, best place first, of the boards the character is on among public characters of every ruleset: board, title, place, total and value). meta.economy says whether the owner shows money.
curl https://scarletweb.io/api/v1/public/characters/Tolvir-Greane
GET/api/v1/public/characters/{name}/series/{series}
One series of a public character: levelling (played time before each level, with the ruleset median and middle half), xp, deaths, dungeons, activity, sessions, and gold when the owner shows money.
| Parameter | Meaning |
|---|---|
name | In the path. string. The character name. |
series | In the path. string. The series name. |
data: the rows of the series.
curl https://scarletweb.io/api/v1/public/characters/Tolvir-Greane/series/levelling
GET/api/v1/public/creatures/{id}
One creature: its level range and kind, kills, deaths to it, drops under each loot rule and the world cells where it was met.
| Parameter | Meaning |
|---|---|
id | In the path. integer. The creature id, as in the address of its page. |
ruleset | Query. string. A ruleset slug from /rulesets. Leave out for all rulesets. |
server | Query. string. all, pve or pvp: the rulesets of one kind of server. Ignored when ruleset is given. |
data: facts, kills, deaths, deaths_by_level, drops (item, loot rule, drops, opens, rate) and cells. Drop rates cover every ruleset.
curl https://scarletweb.io/api/v1/public/creatures/257926
GET/api/v1/public/items/{id}
One item: what it is, where it drops by source and loot rule, the boss encounters that dropped it, the recipes that make or use it, and its auction prices.
| Parameter | Meaning |
|---|---|
id | In the path. integer. The item id, as in the address of its page. |
data: item, sources (source, loot rule, drops, opens, rate), prices (one entry for each ruleset and realm: ruleset, realm, and days of day, price in copper and browse), dropped, source_count, best_rate, first_at, encounters (encounter, item, dropped, characters), made_by and used_in (recipes: spell, output, reagents).
curl https://scarletweb.io/api/v1/public/items/1465
GET/api/v1/public/spells/{id}
One spell: what the client says about it (icon, cast time, range, cost, description) and, for a recipe, what it makes and needs.
| Parameter | Meaning |
|---|---|
id | In the path. integer. The spell id, as in the address of its page. |
data: name, facts (icon_id, cast_ms, min_range, max_range, costs as powerType:cost joined by commas, passive, description) and recipe (output, optional_slots, reagents).
curl https://scarletweb.io/api/v1/public/spells/133
GET/api/v1/public/encounters/{id}
One boss encounter: the items it dropped, each drop counted once however many players of the group uploaded it.
| Parameter | Meaning |
|---|---|
id | In the path. integer. The encounter id, as in the address of its page. |
data.drops: item_id, item, dropped and characters, most dropped first.
curl https://scarletweb.io/api/v1/public/encounters/1065
GET/api/v1/public/zones/{id}
One zone: time played, deaths, what killed characters there and the creatures met. A dungeon has a negative id.
| Parameter | Meaning |
|---|---|
id | In the path. integer. The zone id, as in the address of its page. |
ruleset | Query. string. A ruleset slug from /rulesets. Leave out for all rulesets. |
server | Query. string. all, pve or pvp: the rulesets of one kind of server. Ignored when ruleset is given. |
data: rect (the zone on the world map), played, deaths, killers, creatures.
curl https://scarletweb.io/api/v1/public/zones/1446
GET/api/v1/public/quests/{id}
One quest: accepts, turn-ins, abandons, experience, and the levels and zones where it is turned in.
| Parameter | Meaning |
|---|---|
id | In the path. integer. The quest id, as in the address of its page. |
ruleset | Query. string. A ruleset slug from /rulesets. Leave out for all rulesets. |
server | Query. string. all, pve or pvp: the rulesets of one kind of server. Ignored when ruleset is given. |
data: totals, levels (level, turn-ins) and zones.
curl https://scarletweb.io/api/v1/public/quests/6521
GET/api/v1/public/map/heat
Heat on the world grid: the cells where characters walked, died or met creatures, each with a level from 1 to 4.
| Parameter | Meaning |
|---|---|
ruleset | Query. string. A ruleset slug from /rulesets. Leave out for all rulesets. |
layer | Query. string. paths, deaths or creatures. Default paths. |
creature | Query. integer. A creature id: narrows creatures to one creature. |
data.cells: i, j, level, value, characters. meta.grid gives the grid size.
curl https://scarletweb.io/api/v1/public/map/heat?layer=deaths
GET/api/v1/public/map/density
One whole level of the heat grid, for drawing a density surface. Level 0 is 192 by 128 cells; each level doubles both.
| Parameter | Meaning |
|---|---|
ruleset | Query. string. A ruleset slug from /rulesets. Leave out for all rulesets. |
layer | Query. string. paths, deaths or creatures. Default paths. |
level | Query. integer. 0 to 3 for paths, 0 to 2 for the other layers. Default 0. |
creature | Query. integer. A creature id: narrows creatures to one creature. |
data: level, columns, rows and cells, a flat list of pairs: the cell index (j * columns + i) minus the previous cell's, then the cell's counter.
curl https://scarletweb.io/api/v1/public/map/density?layer=paths&level=2