TrueFloat API

Quickstart

Base URL https://truefloat.app/api/v1

Try curl https://truefloat.app/api/v1/items/7/44/seeds/387

Everything curl https://truefloat.app/api/v1/dump

Auth None. No keys, no sign-up.

/v1/dump new — the whole dataset, one request, gzip. See calls.

Local: uvicorn api.app:app → http://127.0.0.1:8000

Guides: 308
Items: 146
Systems: 536
Gradings: 83,836

counts.items from /v1/meta is 298 (def_index, paint_index) pairs; the 146 above are item files, each covering one or more paint indexes.

Data shape

item        AK-47 | Case Hardened        def_index 7, paint_index 44
 └ guide     one Steam guide, one author
    └ system  one property being ranked   "Blue Gem", "Max Black"
       └ level one place in that ranking   "top", "1", "2"
          └ seeds

scale.kind	levels
`tier`	numbered, 1 best
`rank`	strict order, P1..Pn
`group`	one level, membership only
`sublevel`	named, best first
`band`	numeric thresholds (Fade %)

Key: (def_index, paint_index). Slugs and market hash names are aliases → /v1/resolve.
Levels are ordered best first. level.key is opaque, never an ordinal. Use place / of.
scale.kind says how to draw a system, not how to read it. Same JSON for every kind.
Guides are stored as written. Contradictions stay, in discrepancies. A seed listed twice gets two verdicts.

Calls

call	returns
`GET /v1/items/{def}/{paint}`	item + menu of guides and systems, no seeds
`GET /v1/guides/{steam_id}`	whole guide file, provenance included
`GET /v1/items/{def}/{paint}/seeds/{seed}`	one seed, every guide's verdict
`GET /v1/items/{def}/{paint}/patterns`	every graded seed, bulk
`GET /v1/resolve`	slug or market hash name → `(def, paint)`
`GET /v1/meta`	dataset version, counts
`GET /v1/dump` new	the whole dataset, one request, gzip
`GET /health`	200 when loaded

Every /v1 response is wrapped in the envelope. Examples below show data.

GET/v1/items/{def}/{paint}

param	in	type
`def`	path	int	`def_index`
`paint`	path	int	`paint_index`
`topic`	query	string	optional, coming. Keeps matching systems, drops guides with none

GET /v1/items/7/44

{"item": {"def_index": 7, "paint_index": 44, "slug": "ak47-case-hardened",
          "weapon": "AK-47", "finish": "Case Hardened", "paint_label": "Case Hardened"},
 "guides": [
   {"steam_id": "2941982575", "title": "AK-47 Case Hardened | Blue Gem",
    "authors": ["korenevskiy"], "url": "https://steamcommunity.com/sharedfiles/filedetails/?id=2941982575",
    "permission": "unknown", "updated": "2026-03-01T13:29:00",
    "systems": [{"id": "ak47-blue-gem", "label": "AK-47 Blue Gem", "alias": null,
                 "topic": null, "kind": "tier", "levels": 4, "seeds": 97}]},
   {"steam_id": "3313951742", "title": "The Complete Gold Gem Patterns Guide", "...": "...",
    "systems": [{"id": "ak47-gold-gem", "label": "Gold Gem Patterns", "alias": null,
                 "topic": null, "kind": "group", "levels": 1, "seeds": 4}]}]}

404 `not_found`	unknown `def`, or a `paint` the item does not have
400	`topic` not in `data/topics.json`
200 `guides: []`	known item, no guide

GET/v1/guides/{steam_id}

param	in	type
`steam_id`	path	string	Steam guide id
`system`	query	string	optional. Narrows `systems` to that one

The guide file exactly as stored in data/guides/. Field reference: CONVENTIONS.md.

GET /v1/guides/2941982575 · trimmed

{"schema": "0.5.0", "steam_id": "2941982575", "title": "AK-47 Case Hardened | Blue Gem",
 "authors": ["korenevskiy"], "collaborators": 1,
 "url": "https://steamcommunity.com/sharedfiles/filedetails/?id=2941982575",
 "posted": "2023-03-04T04:00:00", "updated": "2026-03-01T13:29:00",
 "snapshot": {"path": "sources/2941982575", "retrieved_at": "2026-09-11T09:44:29.010688+00:00",
              "sha256": "aa15d4cdf6cd970ea4165a4a0cad3dee0873df42a5c6858c2af8e859080e3936"},
 "permission": "unknown",
 "systems": [{"id": "ak47-blue-gem", "label": "AK-47 Blue Gem", "item": "ak47-case-hardened",
              "paint_indexes": [44], "scale": {"kind": "tier", "best": 1, "worst": 3, "definition": {"quote": "..."}},
              "levels": [{"key": "top", "label": "#1", "...": "..."}, {"key": "1", "label": "Rank 1", "...": "..."},
                         {"key": "2", "label": "Rank 2", "...": "..."}, {"key": "3", "label": "Rank 3", "...": "..."}],
              "gradings": [{"seed": 387, "level": "1", "position": 4,
                            "quote": "151 168 179 321 387 555 592 617 670 760 809 828 955", "evidence": "text"},
                           "..."]}],
 "callouts": ["..."], "discrepancies": [], "...": "..."}

404 not_found unknown steam_id, or unknown system

GET/v1/items/{def}/{paint}/seeds/{seed}

param	in	type
`def`, `paint`	path	int	item key
`seed`	path	int	pattern seed

GET /v1/items/7/44/seeds/387

{"item": {"def_index": 7, "paint_index": 44, "slug": "ak47-case-hardened"},
 "seed": 387,
 "verdicts": [
   {"guide": {"steam_id": "2941982575", "title": "AK-47 Case Hardened | Blue Gem",
              "authors": ["korenevskiy"], "url": "https://steamcommunity.com/sharedfiles/filedetails/?id=2941982575",
              "permission": "unknown", "updated": "2026-03-01T13:29:00"},
    "system": {"id": "ak47-blue-gem", "label": "AK-47 Blue Gem", "topic": null, "kind": "tier"},
    "level": {"key": "1", "label": "Rank 1", "place": 2, "of": 4},
    "rank": null, "equivalent_to": null, "value": null,
    "evidence": "text", "quote": "151 168 179 321 387 555 592 617 670 760 809 828 955"}],
 "not_listed": [{"steam_id": "3313951742", "system": "ak47-gold-gem"}]}

Verdict · one seed in one system of one guide

field	meaning
`level.key`, `level.label`	the author's level, as written
`level.place`, `level.of`	1-based place in that system's own list, best first, and its length: "2nd of 4"
`rank`	author's explicit rank within the level, else `null`
`equivalent_to`	seed the author says this one equals, else `null`
`value`	`{name, value}` written beside the entry, else `null`
`evidence`, `quote`	`text`, `caption` or `image`, and the verbatim span

404 `not_found`	unknown `def` or `paint`
200 `verdicts: []`	known item, seed no guide grades; every covering system in `not_listed`

GET/v1/items/{def}/{paint}/patterns

param	in	type
`def`, `paint`	path	int	item key

Bulk twin of /seeds/{seed}. One fetch per item page, then look up each listing locally. Guide and system details are given once; of = length of that system's levels.

GET /v1/items/7/44/patterns · trimmed

{"item": {"def_index": 7, "paint_index": 44, "slug": "ak47-case-hardened"},
 "guides": {"2941982575": {"title": "...", "authors": ["korenevskiy"], "url": "...", "permission": "unknown", "updated": "...",
                           "systems": {"ak47-blue-gem": {"label": "AK-47 Blue Gem", "topic": null, "kind": "tier",
                                        "levels": [{"key": "top", "label": "#1"}, {"key": "1", "label": "Rank 1"},
                                                   {"key": "2", "label": "Rank 2"}, {"key": "3", "label": "Rank 3"}]}}}},
 "seeds": {"387": [{"guide": "2941982575", "system": "ak47-blue-gem", "level": "1", "place": 2,
                    "rank": null, "equivalent_to": null, "value": null}],
           "661": [{"guide": "2941982575", "system": "ak47-blue-gem", "level": "top", "place": 1,
                    "rank": 1, "equivalent_to": null, "value": null}]}}

404 `not_found`	unknown `def` or `paint`
200 `seeds: {}`	known item, no guide

GET/v1/resolve

param	in	type
`slug`	query	string	e.g. `karambit-doppler`
`market_hash_name`	query	string	e.g. `★ Karambit \| Doppler (Factory New)`

A slug can cover several paint indexes: karambit-doppler is Ruby 415, Sapphire 416, Black Pearl 417, … Not a query key on its own.

GET /v1/resolve?slug=karambit-doppler · trimmed

{"items": [
   {"def_index": 507, "paint_index": 415, "slug": "karambit-doppler",
    "weapon": "Karambit", "finish": "Doppler", "paint_label": "Ruby"},
   {"def_index": 507, "paint_index": 416, "slug": "karambit-doppler",
    "weapon": "Karambit", "finish": "Doppler", "paint_label": "Sapphire"},
   "..."]}

400 `bad_request`	neither param given
404 `not_found`	alias unknown

GET/v1/meta

GET /v1/meta

{"dataset_version": "0e4c92f", "loaded_at": "2026-09-24T16:14:22.898312+00:00",
 "counts": {"items": 294, "guides": 295, "aliases": 1288, "systems": 510, "gradings": 80335}}

items counts (def_index, paint_index) pairs; 142 item files cover them.

GET/v1/dumpnew

The whole dataset in one request: every item and every guide. Served gzip when Accept-Encoding includes it, cached per dataset_version and reused for every request. For a bulk consumer that wants a local copy rather than crawling item by item.

GET /v1/dump · trimmed

{"dataset_version": "ec84670",
 "data": {"items": [{"def_index": 7, "paint_index": 44, "slug": "ak47-case-hardened", "...": "..."}, "..."],
          "guides": [{"steam_id": "2941982575", "title": "AK-47 Case Hardened | Blue Gem", "...": "..."}, "..."]}}

curl

curl -H 'Accept-Encoding: gzip' https://truefloat.app/api/v1/dump

GET/health

200 when the database is loaded. No /v1, no envelope, never rate limited.

Envelope & errors

{"dataset_version": "3c76d2d", "data": { }}
{"dataset_version": "3c76d2d", "error": {"code": "not_found", "message": "no item def 7 paint 45"}}

dataset_version = git commit the database was loaded from.

status	code	when
200		found, possibly empty (below)
304		`If-None-Match` equals current ETag
400	`bad_request`*	unknown `topic`; `/resolve` without a param
404	`not_found`	unknown item, paint, steam_id, system, path
429	`rate_limited`*	over limit; see `Retry-After`

* code name from the current server; API.md fixes only the status.

Empty vs missing

request	answer
unknown `def_index`, or a `paint_index` the item does not have	404 `not_found`
known item, seed no guide grades	200, `verdicts: []`, every covering system in `not_listed`
known item with no guide	200, `guides: []` or `seeds: {}`
unknown `steam_id` or system	404 `not_found`

Access, limits, caching

No keys. No sign-up. Every caller gets the same access, rate-limited per IP.

limit	value
rate limit	1000 requests per minute per IP
over the limit	429, header `Retry-After`
edge cache	responses are cached at the Cloudflare edge for 10 minutes
`ETag`	`"<dataset_version>"`. Changes only on a data reload; send `If-None-Match` for a 304

Conditional request

curl -H 'If-None-Match: "3c76d2d"' https://truefloat.app/api/v1/items/7/44/patterns

The Diamond Index runs its own internal key with no limit, for the site's own traffic; it is not issued to anyone else.

Attribution · required

Wherever you show a grade, show its guide's author and link.

guide block
`steam_id`	Steam guide id
`title`	as written
`authors`	array
`url`	Steam guide page
`permission`	e.g. `unknown`
`updated`	guide's last update

Minimum display

Rank 12nd of 4

AK-47 Blue Gem · AK-47 Case Hardened | Blue Gem by korenevskiy

Guides are never merged

Each verdict is read against its own guide's list. No cross-guide tier is emitted.

seed 387, AK-47 Case Hardened
  2941982575  "AK-47 Blue Gem"     level "1" (Rank 1)   2nd of 4 levels
  3313951742  "Gold Gem Patterns"  not listed

Topics coming

what	our word for what a system ranks (`blue-gem` for "Blue Gem", "Playside Blue")
where	on the system; one topic per system. Groups, never merges
now	`topic` is present and `null`. Vocabulary in audit (139 draft topics)
then	`/v1/items/{def}/{paint}?topic=blue-gem`. Same shape, no breaking change