How to Build a Searchable CS2 Item Selector
Updated
API reference: GET /v1/schema
GET /v1/schemaprovides the canonical names and metadata needed to build a searchable CS2 item selector without reconstructing item names from free text.
Price and history endpoints use exact market_hash_name values. A selector should return that key, including wear, StatTrak, Souvenir, or variant identity, while displaying friendlier metadata alongside it.
Schema fields an item selector can use
| Selector need | Schema fields |
|---|---|
| Search and selected value | market_hash_name, base_name, weapon, finish |
| Grouping and filters | category, rarity, collections, containers, is_tradable |
| Wear choices | wears, wear, float_range |
| Special forms | stattrak, souvenir, has_stattrak, has_souvenir |
| Visual result | Required image, optional verified steam_image, rarity color |
| Phase or tier selection | Nested variants and standalone rows linked through variant |
Fields that do not apply to an item are omitted. The selector must handle absence instead of assuming every record is a skin with wear or rarity metadata.
Building and refreshing the search data
Fetch the schema in a trusted server or build process because /v1 requests require a bearer key and gzip support. Reduce each record to the fields the interface needs, but retain the exact market_hash_name as its value.
Use generation_id or the response ETag to detect a new immutable catalog generation. The endpoint supports If-None-Match and returns 304 Not Modified when the generation is unchanged. The current pipeline checks Valve manifests every 30 minutes and publishes a new generation only when semantic inputs change.
For variants, display the phase or tier label while storing the variant's full market_hash_name. A base item and Phase 2 are separate selectable identities even when price responses nest the phase under its base item.
Applicable endpoint
| Endpoint | Returns | Plans |
|---|---|---|
GET /v1/schema |
Full CS2 catalog, metadata, variants, IDs, and images | All plans |
Selector boundaries
- The schema identifies catalog items and variants; it does not indicate which source currently has a non-null price. Price availability must be checked separately.
- Marketplace IDs are present only where known. The exact
market_hash_nameremains the common key across cs2.sh datasets. steam_imagecan be omitted when exact Valve origin is not independently proven. The required cs2.shimagestill remains available.
See schema field coverage and rarity/category filtering for adjacent selector inputs.