auctionhouse.fyiPREVIEW
Sign in
Documentation / API reference

Upload a book

POST /api/v1/ah/books — auction depth and its price summary in one upload.

POST/api/v1/ah/booksDevice token or API key

Request body

marketstringrequired
One of six market IDs. Configure ruleset accurately; faction alone is insufficient.
atintegerrequired
Original observation time in Unix milliseconds, within 24 hours behind or 5 minutes ahead of the server clock.
completebooleanrequired
true only after an unfiltered whole-market read finishes. Partial or interrupted reads use false.
auctionsinteger ≥ 0required
Sum of n across all entries. Counts auctions, not units or grouped rows.
entriesBookEntry[]required
0–200,000 unique tuples, lexicographically ascending by (key, price, stack, band).
viastring · partner only
Optional opaque member ID, 1–64 characters from A–Z, a–z, 0–9, underscore, dot, colon or hyphen. Requires a partner API key; limits count per via, credit goes to the partner account.
book.json · illustrative
{
  "market": "forever.normal.alliance.us",
  "at": 1790683200000,
  "complete": false,
  "auctions": 3,
  "entries": [
    [14047, 125, 20, 4, 2],
    [14047, 150, 10, 2, 1]
  ]
}
cURL + gzip
gzip -c book.json > book.json.gz
curl --fail-with-body --show-error \
  -H "Authorization: Bearer $AHF_KEY" \
  -H "Content-Type: application/json" \
  -H "Content-Encoding: gzip" \
  --data-binary @book.json.gz \
  "$AHF_BASE/api/v1/ah/books"

Use Content-Type: application/json. Gzip is recommended; plain JSON is accepted. Both compressed and decompressed bodies are limited to 32 MiB. The Rust example compresses automatically.

Entry format

BookEntry · tuple positions
[key, price, stack, band, n]
keysafe integer
The item key, preserving suffixes and pet species.
priceinteger · 0…2⁵³−1
Buyout per unit in copper, rounded up from total stack buyout / stack. Zero means bid-only; never substitute a bid price.
stackinteger · 1…2³¹−1
Units in one auction of this group.
bandinteger · 0…4
0 unknown; 1 short; 2 medium; 3 long; 4 very long. The Lua helper converts game bands 0…3 into these wire bands.
ninteger · 1…2³¹−1
Number of identical auctions in this group. Sum duplicate groups before uploading; the API rejects duplicate or unsorted tuples.

In [14047, 125, 20, 4, 2], two auctions each contain 20 Runecloth at 125 copper per unit: 40 units, with a 2,500-copper buyout per auction.

Response

200 · accepted without contributor credit
{
  "at": 1790683200000,
  "credited": false,
  "reason": "incomplete"
}

at is the market’s newest merged observation, not an upload ID. credited reports contributor credit; check reason to distinguish merged data from quarantine or a duplicate.

Read GET /api/v1/ah/:market/:item for the derived price, or GET /api/v1/ah/:market/:item/book for depth (requires books). Your contribution history records the outcome. Public reads remain hourly snapshots.

Merge and retry rules

Only a complete book newer than the current book replaces current depth. Incomplete and late books are stored as historical snapshots and still update eligible price summaries. One new book per caller per market every five minutes. A retry of the same account, credential, market and original at returns the recorded result without merging twice. A book with the same market and timestamp already stored by another caller returns duplicate.

Keep the original file and timestamp on retry. Never change at to make old data fresh. Read the full outcome and error guide before automating uploads.

Versioned contracts and runnable examples live with the source specification →.