Schemas and the protocol
Every response shape and record kind, and the protocol version.
The contract behind the API is one package, @everloot/protocol, version 1.2.0: the 33 record kinds the addon writes, the upload envelope and its limits, the 18 response shapes below and the MCP tool table. The site validates uploads with it, the MCP server registers its tools from it, and these pages are rendered from it.
JSON Schema files#
https://everloot.app/schema/index.json: what is published, with the protocol version./schema/records/<kind>.json: one JSON Schema (draft 2020-12) per record kind, with the rules the server checks that a schema cannot express written into the description./schema/upload.jsonand/schema/limits.json: the upload envelope and its sizes./schema/api/<name>.jsonand/schema/mcp/<tool>.json: the response shapes and the tool inputs.- The OpenAPI document,
/api/openapi.json, refers to the same shapes.
Protocol version#
The version is 1.2.0. It follows semver. A new kind, field or tool is a minor release. A removal, a rename, a new required field or a tighter limit is a major release, and the server accepts the current major and the one before it. The source and its changelog are in packages/protocol.
Record kinds#
The addon writes records, and each has a kind. The public corpus holds the kinds marked below; the rest stay private to the upload. Each kind has its own schema file.
| Kind | In the public corpus |
|---|---|
npc_sighting | Yes |
loot | Yes |
quest | Yes |
vendor | Yes |
item_seen | Yes |
guild_snapshot | Yes |
raid_lockout | Yes |
attendance | Yes |
loot_award | Yes |
gear_snapshot | Yes |
collection_catalog | Yes |
collection_owned | Yes |
achievement_catalog | No |
reputation_catalog | No |
title_catalog | No |
quest_chain_catalog | No |
achievement_owned | No |
reputation_owned | No |
title_owned | No |
quest_owned | No |
auction_scan | Yes |
auction_snapshot | No |
recipe_seen | Yes |
price_seen | Yes |
recipe_observed | Yes |
trainer_seen | Yes |
gold_snapshot | Yes |
money_event | Yes |
addon_seen | No |
map_bounds | Yes |
talent_snapshot | No |
census_self | No |
census_seen | No |
Upload limits#
An upload is a JSON envelope of records. The server enforces every limit; the Desktop App and the upload page stay inside them. The same numbers are at /schema/limits.json.
| Limit | Value |
|---|---|
| Records in one request | 2,000 |
| Request body, refused above this with 413 | 1,000,000 bytes |
| What an uploader puts in one request | 600,000 bytes |
| Records one SavedVariables file may hold before it is split | 100,000 |
| Length of addonVersion | 20 characters |
| Auction realms in one upload | 3 |
Sending an upload is POST /intake.
Response shapes#
One section per shape. The fields are the top-level ones; the full shape, with everything nested, is in the JSON Schema file named under each heading.
attribution#
/schema/api/attribution.json A part of other answers.
licencestringrequired- No description.
licenceUrlstringrequired- No description.
creditstringrequired- No description.
sourcestringrequired- No description.
termsstringrequired- No description.
gameDataNotice#
/schema/api/gameDataNotice.json A part of other answers.
labelstringrequired- The evidence label pages show, such as "found in game files, unconfirmed".
buildstringrequired- The game build the rows were read from.
extractedAtstring or null, or null- No description.
creditstring- No description.
apiError#
/schema/api/apiError.json Used by GET /corpus/public, GET /rollups/drops, GET /edges, GET /items, GET /market/prices, GET /tools/{tool}, GET /tooltip/{type}/{id}.
okexactly falserequired- No description.
errorstringrequired- No description.
getAKeystring- No description.
page#
/schema/api/page.json A part of other answers.
offsetinteger, 0 to 9007199254740991required- No description.
limitinteger, 0 to 9007199254740991required- No description.
totalinteger, 0 to 9007199254740991required- No description.
nextstring, or nullrequired- No description.
corpusPublicResponse#
/schema/api/corpusPublicResponse.json Used by GET /corpus/public.
okexactly truerequired- No description.
uploadsinteger, 0 to 9007199254740991required- No description.
recordsarray of objectsrequired- Records of the public kinds, each without its installId. Shapes: schema/records/<kind>.json.
dataAsOfstring, or null- When these records were current. Null or absent when unrecorded, never "now".
kindsarray of string- Present when the request asked for some kinds.
legacyRecordsinteger, 0 to 9007199254740991- No description.
attributionobjectrequired- No description.
offsetinteger, 0 to 9007199254740991required- No description.
limitinteger, 0 to 9007199254740991required- No description.
totalinteger, 0 to 9007199254740991required- No description.
nextstring, or nullrequired- No description.
marketRealmsResponse#
/schema/api/marketRealmsResponse.json A part of other answers.
okexactly truerequired- No description.
dataAsOfstring, or nullrequired- No description.
realmsarray of stringrequired- No description.
housesobject- Per realm, the auction houses that have public values of their own (scans that named their house).
attributionobjectrequired- No description.
marketPricesResponse#
/schema/api/marketPricesResponse.json Used by GET /market/prices.
okexactly truerequired- No description.
dataAsOfstring, or nullrequired- No description.
rulestringrequired- How a day becomes public and how the values are computed.
fieldsarray of valuesrequired- No description.
realmstring or null, or nullrequired- No description.
houseone of: Alliance, Horde, Neutral- Present when the request named a house: the values come only from scans of that house.
itemsarray of arrayrequired- [itemId, market, min, historical, quantity, day, reporters]; copper per unit.
attributionobjectrequired- No description.
dropsResponse#
/schema/api/dropsResponse.json Used by GET /rollups/drops.
generatedAtstringrequired- No description.
dataAsOfstring, or nullrequired- No description.
statsobjectrequired- No description.
unreachablebooleanrequired- True when storage could not be read: the lists are then empty, not zero.
ratesarray of objectsrequired- No description.
measuredZerosarray of objectsrequired- No description.
queuedinteger, 0 to 9007199254740991, or nullrequired- Rates and zeros waiting for their third install; null when unreachable.
totalRatesinteger, 0 to 9007199254740991required- No description.
totalMeasuredZerosinteger, 0 to 9007199254740991required- No description.
attributionobjectrequired- No description.
offsetinteger, 0 to 9007199254740991required- No description.
limitinteger, 0 to 9007199254740991required- No description.
totalinteger, 0 to 9007199254740991required- No description.
nextstring, or nullrequired- No description.
edgesResponse#
/schema/api/edgesResponse.json Used by GET /edges.
generatedAtstringrequired- No description.
dataAsOfstring, or nullrequired- No description.
unreachablebooleanrequired- No description.
edgesarray of objectsrequired- No description.
attributionobjectrequired- No description.
gameDataobject, or nullrequired- Present when the page holds at least one game-file edge.
offsetinteger, 0 to 9007199254740991required- No description.
limitinteger, 0 to 9007199254740991required- No description.
totalinteger, 0 to 9007199254740991required- No description.
nextstring, or nullrequired- No description.
itemsResponse#
/schema/api/itemsResponse.json Used by GET /items.
generatedAtstringrequired- No description.
itemsarray of objectsrequired- No description.
gameDataobjectrequired- No description.
offsetinteger, 0 to 9007199254740991required- No description.
limitinteger, 0 to 9007199254740991required- No description.
totalinteger, 0 to 9007199254740991required- No description.
nextstring, or nullrequired- No description.
itemCategoriesResponse#
/schema/api/itemCategoriesResponse.json Used by GET /items/categories.
classesarray of objectsrequired- No description.
slotsarray of objectsrequired- No description.
qualitiesarray of objectsrequired- No description.
gameDataobjectrequired- No description.
toolAnswerResponse#
/schema/api/toolAnswerResponse.json Used by GET /tools/{tool}.
toolstringrequired- The tool's name, as in the MCP tool list.
argumentsobjectrequired- The arguments as the tool read them, defaults applied.
answerobjectrequired- The tool's structured answer. Its schema: /schema/mcp/{tool}.json#/outputSchema.
textstringrequired- The same answer as the MCP text block, for a reader.
schemastringrequired- The URL of the tool's schema file.
tooltipResponse#
/schema/api/tooltipResponse.json Used by GET /tooltip/{type}/{id}.
okexactly truerequired- No description.
typeone of: item, npc, quest, objectrequired- No description.
idinteger, 1 to 9007199254740991required- No description.
titlestringrequired- The agreed name, or "Item 123" style when no name has 3 installs behind it.
colorstring, or nullrequired- Title colour (item quality), or null.
iconstring, or nullrequired- An icon from the game files asset folder, or null.
linesarray of stringrequired- The card's lines, in order. A value the game files do not give is shown as [?].
partialbooleanrequired- A line holds a [?] for a value the game files do not give yet.
urlstringrequired- The page this card is for.
attributionobjectrequired- No description.
gameDataobject, or nullrequired- No description.
bulkIndex#
/schema/api/bulkIndex.json A part of other answers.
protocolstringrequired- The protocol version the rows follow.
generatedAtstringrequired- No description.
dataAsOfstring, or nullrequired- When the uploads behind the observed rows were current; null when storage was unreachable, then those files are absent, not empty.
buildstring or null, or nullrequired- Game build of the game-file rows.
sitestringrequired- No description.
licencestringrequired- No description.
licenceUrlstringrequired- No description.
creditstringrequired- No description.
filesarray of objectsrequired- No description.
intakeRequest#
/schema/api/intakeRequest.json Used by POST /intake.
addonVersionstring, up to 20 charactersrequired- No description.
clientBuildstring- No description.
protocolstring- No description.
recordsarray of valuesrequired- No description.
sharingobject- Named categories the player chose to share: guild, gear, gold, collection.
grantTokensarray of string- No description.
intakeReceipt#
/schema/api/intakeReceipt.json Used by POST /intake.
okexactly truerequired- No description.
persistedexactly truerequired- No description.
uploadIdstringrequired- No description.
acceptedarray of objectsrequired- No description.
rejectedarray of objectsrequired- No description.
intakeRefused#
/schema/api/intakeRefused.json Used by POST /intake.
okexactly falserequired- No description.
errorstring- No description.
persistedexactly false- No description.
uploadIdstring- No description.
acceptedarray of objects- No description.
rejectedarray of objects- No description.
healthResponse#
/schema/api/healthResponse.json Used by GET /health.
okbooleanrequired- No description.
snapshotobjectrequired- No description.