Thottbot Forever API

Everything on this site is available as JSON. The API is public for reads and uses bearer tokens for writes. The OpenAPI 3.1 document describes every endpoint and field.

Base URL

https://thottbot-forever.com/api/v1

Format

JSON, UTF-8. Timestamps are ISO 8601 in UTC, money is in copper, durations in milliseconds.

Every path below is relative to the base URL.

curl "https://thottbot-forever.com/api/v1/items/19019"

Responses

A response that worked has the result in data. One that did not has error instead, with an HTTP status to match. Both carry meta, whose requestId is worth quoting when you report a problem.

One entry

{
  "data": {
    "type": "item",
    "item": {
      "id": 19019,
      "name": "Thunderfury, Blessed Blade of the Windseeker",
      "slug": "thunderfury-blessed-blade-of-the-windseeker",
      "quality": 5,
      "itemLevel": 80,
      …
    },
    "droppedBy": [],
    "soldBy": [],
    "rewardFrom": [],
    …
  },
  "meta": {
    "requestId": "a556f622888a7b74",
    "generatedAt": "2026-11-04T22:12:40.132Z"
  }
}

A listing

Listings add how they are paged and sorted to meta: page, perPage, total, totalPages, sort and dir.

{
  "data": [
    { "id": 22632, "name": "Atiesh, Greatstaff of the Guardian", "itemLevel": 90, … },
    { "id": 22631, "name": "Atiesh, Greatstaff of the Guardian", "itemLevel": 90, … }
  ],
  "meta": {
    "requestId": "a556f6292b8cdf73",
    "generatedAt": "2026-11-04T22:12:40.862Z",
    "page": 1,
    "perPage": 2,
    "total": 28,
    "totalPages": 14,
    "sort": "ilvl",
    "dir": "desc",
    "type": "item"
  }
}

An error

error.code is the one to act on: it is fixed, while message is for people and may change. details is there only when there is more to say.

{
  "error": {
    "code": "validation_failed",
    "message": "Request validation failed",
    "details": {
      "issues": [
        { "path": "perPage", "message": "Invalid input: expected number, received NaN" }
      ]
    }
  },
  "meta": {
    "requestId": "a556f63208358aaa"
  }
}

Caching, limits and CORS

• Public reads send Cache-Control and a weak ETag; send it back in If-None-Match to get a 304 when nothing changed.
• Anonymous reads may make 120 requests a minute per IP address, and requests with a token 600 a minute. Writes are limited separately. Where you stand is reported in X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.
• CORS is open (Access-Control-Allow-Origin: *). A browser session (a cookie) counts only on requests from this site; everything else authenticates with a token.

Authentication

Create a token on your account page and send it as a bearer token:

curl "https://thottbot-forever.com/api/v1/me" -H "Authorization: Bearer tbf_…"

There is no way to exchange credentials for a token over the API: identity comes from Battle.net, there is no password to send, and an endpoint that traded something weaker for a token would undo the point of that.

A token never carries a moderator’s or an administrator’s role. What only they can do — the /admin endpoints, hiding somebody else’s comment — needs a browser session on this site that has passed its second factor, and an administrator’s changes a sign-in through Battle.net from the last ten minutes too.

Game data

Paged collections

Each takes q (part of the name), sort, dir (asc or desc), page and perPage (up to 200), and the filters its page on this site has. /{id} is the game’s id, and returns the entry with everything its page shows.

Whole lists

These are short enough to come back in one piece, so they are not paged. One entry is found by its slug or its id.

Search and the rest

Examples

# The highest item level legendaries
curl "https://thottbot-forever.com/api/v1/items?quality=5&sort=ilvl&dir=desc"

# One item, with everything its page shows
curl "https://thottbot-forever.com/api/v1/items/19019"

# Search every collection
curl "https://thottbot-forever.com/api/v1/search?q=thunderfury"

# The bosses of Molten Core
curl "https://thottbot-forever.com/api/v1/npcs?zone=2717&classification=boss"

# Two items side by side
curl "https://thottbot-forever.com/api/v1/items/compare?i=19019&i=18816"

Comments and screenshots

Token means a bearer token, or a browser session on this site; session means a browser session only.

Comment markup

Bodies are plain text with a small BBCode-style dialect. The API returns both the raw body and a sanitized bodyHtml.

Formatting

[b], [i], [u], [code], [quote]

Links

[url=https://…]text[/url]

Entries

[item=19019], [spell=133], [quest=7848], [npc=11502], [zone=2717], [object=179703]

Account

Signing in is a browser flow through Battle.net at /login, not an API call.

Contributions

POST /contributions accepts batches of observations from the in-game collector (or any tool). See Contribute for the format. A batch is stored as received, acknowledged with 202, and merged into the database shortly after, one uploader’s batches at a time; GET /me/contributions then reports how many records were applied and why any were rejected. It takes a token and nothing else, as the file upload below does: a browser session cannot upload.

POST /contributions/files takes the addon’s SavedVariables file as the game wrote it, gzipped, with its SHA-256 in X-Content-SHA256: the site checks the hash before it reads anything, then reads the file and stores it in batches. It is what the desktop uploader sends, a large file in parts; GET /uploader lists the uploader’s releases, and uploading needs the newest.

Two rules govern the merge. Existing data is never overwritten, so a record creates an entity when it is missing and otherwise only fills fields that are still empty. Drop rates are computed from reported loot tables rather than taken from a record, which is why drop responses carry observed and encounters alongside dropChance.

Moderators can inspect and retry the queue with GET and POST /admin/contributions, from a browser session that has passed its second factor.

Versioning

The API is versioned in the path. Fields may be added to responses at any time; removing or renaming a field means a new version. Ids are the game’s own ids wherever they are known.