Home/Spells API

Spells API

TF2 cosmetic spells, footprint effects, and unusual effects database.

General Information

Base URL:https://spells.pricedb.io

Read-only API for observed TF2 spell markets, historical listing asks and exact spell-combination lookup.

A market is the complete canonical SKU plus its exact unordered spell set. Single-spell, double-spell, killstreak and other represented SKU variants remain separate markets.

Estimates and history describe observed sell-listing asks, not completed sales, guaranteed bids or predicted base-item-plus-spell premiums. Preserve null, unpriced, stale and pending states when displaying prices. Collection is forward-only and incomplete; reconnect gaps are not reconciled.

No application authentication is required for these public endpoints.

Markets

GET/api/marketsSearch observed exact spell markets

Paginated summaries of observed sell asks. Check estimate.status, pending,
pricingCurrent and lastEvidenceAt independently. A full SKU matches exactly;
variants are not pooled. Spell-name queries constrain actual attributes,
rather than incidental text in an item name.

Parameters

NameInTypeDescription
qoptionalquerystringCase/diacritic-insensitive item words, exact full SKU, spell names or aliases.Default:
spelloptionalquerystringContains a canonical spell ID; includes double-spell markets.Default:
combinationoptionalquerystringExact unordered comma-separated canonical spell-ID set, at most six IDs. One ID excludes doubles. Market search also accepts repeated combination keys from native multi-select forms; listing history uses the comma form.Default:
categoryoptionalquerystring ( | paint | footprints | voice | weapon)Contains any canonical spell in this category, including double-spell markets. Not item-name text matching.Default:
craftableoptionalquerystring ( | true | false)Craftability represented by the full SKU. Empty means any state.Default:
australiumoptionalquerystring ( | true | false)Require or exclude the canonical australium SKU token.Default:
festiveoptionalquerystring ( | true | false)Require or exclude the canonical festive SKU token.Default:
spellCountoptionalquerystring ( | 1 | 2)Single-spell or double-spell market; empty does not constrain the count.Default:
sortoptionalquerystring (updated | name | priceAsc | priceDesc | coverage)Recently updated; folded name A-Z; numeric key estimate ascending or descending; or independent sellers then active listings descending. Missing estimates sort last in BOTH price directions. Exact market ID breaks ties deterministically. Sorting occurs before pagination.Default: updated
statusoptionalquerystring ( | supported | estimate | stale | unpriced)Market evidence quality, not listing lifecycle status.Default:
qualityoptionalquerystring ( | 0 | 1 | 3 | 5 | 6 | 7 | 8 | 9 | 11 | 12 | 13 | 14 | 15)Exact quality ID; empty means all qualities.Default:
killstreakoptionalquerystring ( | 0 | 1 | 2 | 3)Exact tier: 0 none, 1 Killstreak, 2 Specialized, 3 Professional.Default:
limitoptionalqueryintegerDefault: 50
offsetoptionalqueryintegerDefault: 0

Response

Matching market summaries and total before pagination.

GET/api/markets/{id}Get one exact market, ask history and evidence

Retained evidence is bounded to 500 active listings and 1000 observations.
History contains observed ask buckets, trends and configured moving averages,
not executed trades. No history-range query parameter is supported.

Parameters

NameInTypeDescription
idpathstringOpaque exact-market ID obtained from search; not an item SKU.

Response

Exact market and its bounded retained evidence.

GET/api/items/{sku}/marketsList observed spell markets for one exact full normal SKU

Used by the bare /item/{sku} combination picker. Applies exact SKU equality,
never text matching or variant pooling. Includes historical/unpriced markets.
An unobserved valid SKU returns an empty list, not an invented default quote.
Stable name/ID ordering and bounded pagination retain all observed choices.

Parameters

NameInTypeDescription
skupathstring
limitoptionalqueryintegerDefault: 50
offsetoptionalqueryintegerDefault: 0

Response

Observed exact-SKU spell combinations; no top-level estimate.

GET/api/items/{sku}Resolve a full normal SKU and readable spell names to exact market evidence

Uses the standard full SKU, not HAT Z. The required spells query contains
comma-separated permanent URL slugs, such as die-job,voices-from-below.
Order and duplicates do not change identity. Unknown/conflicting spells,
missing selection and unobserved combinations never select another market.
Returns the same bounded evidence as /api/markets/{id}, which is retained.

Parameters

NameInTypeDescription
skupathstring
spellsquerystring

Response

Listings

GET/api/listingsSearch retained public listing observations

Stream observations are not inventory snapshots or completed trades.
Original keys and metal are preserved. historyComplete and bookComplete
remain false. Parameters are strict: unsupported keys are rejected.
Date filters use UTC days; from must not be after to.

Parameters

NameInTypeDescription
qoptionalquerystringCase/diacritic-insensitive item words, exact full SKU, spell names or aliases.Default:
spelloptionalquerystringContains a canonical spell ID; includes double-spell markets.Default:
combinationoptionalquerystringExact unordered comma-separated canonical spell-ID set, at most six IDs. One ID excludes doubles. Market search also accepts repeated combination keys from native multi-select forms; listing history uses the comma form.Default:
selleroptionalquerystringPublic individual SteamID64; validated by range as well as format.Default:
statusoptionalquerystring (all | active | removed | historical | changed | conflict)Observation lifecycle; conflict observations are quarantined.Default: all
fromoptionalquerystringInclusive UTC calendar day.
tooptionalquerystringInclusive UTC calendar day; internally next-midnight exclusive.
limitoptionalqueryintegerDefault: 50
offsetoptionalqueryintegerDefault: 0

Response

Retained observations, including their lifecycle and native asks.

Reference

GET/api/spellsList canonical spell definitions

Canonical IDs use attribute:value, not legacy spell-handler numeric IDs.

Response

Full canonical spell catalog.

GET/api/statsGet observed spell coverage and distribution

Counts cover the retained book only. Double-spell markets contribute to both
applicable spell and category rows, but remain one unique market.

Response

Observed totals and per-spell counts.

Search

GET/api/search/suggestionsGet bounded typed item and spell suggestions

Unknown query keys are rejected. The website normally runs autocomplete
locally over its complete catalog, not a network call per keystroke.

Parameters

NameInTypeDescription
qquerystringTrimmed item and spell query, not a HAT resolver.
limitoptionalqueryintegerDefault: 10

Response

Item suggestions have a SKU; spell suggestions have a spell ID.

GET/api/search/catalogDownload the complete versioned public search catalog

Non-paginated public market summaries only: no raw observations, listings or
history. Above 100000 markets the endpoint fails closed with 503, never
returns a misleading truncated catalog. Verify schemaVersion, mode,
dataOrigin and configVersion before restoring IndexedDB data. Cached prices
require visible stale-data warnings. Cache-Control is private, no-cache.

Parameters

NameInTypeDescription
If-None-MatchoptionalheaderstringMatching strong/weak ETag or * returns 304 without a body.

Response

Complete catalog for this provenance and configuration.

HAT

GET/api/hatResolve HAT Z to an exact observed market identity

Identity resolution, not premium prediction. An unseen exact identity returns
200 with null marketId and marketUrl, never an unspelled/base-item quote.
Exactly one Z segment is required; spells are field 11. Unknown version
bodies are retained but not interpreted. The marketable flag is retained
but is not a market dimension. Unrepresented paints, parts, filters,
war paints, sheens, killstreakers and loaners are rejected, not dropped.
HAT support has no separate public lookup page.

Parameters

NameInTypeDescription
hatquerystringComplete version/body-pair HAT, URL query encoded normally.

Response

Canonical identity and an observed-market link, or null link when unseen.