# How to Build a Searchable CS2 Item Selector

> `GET /v1/schema` provides 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_name` remains the common key across cs2.sh datasets.
- `steam_image` can be omitted when exact Valve origin is not independently proven. The required cs2.sh `image` still remains available.

See [schema field coverage](/resources/how-to-get-cs2-item-schema) and [rarity/category filtering](/resources/how-to-filter-cs2-items-by-rarity-and-category) for adjacent selector inputs.