# How to Filter CS2 Items by Rarity and Category

> `GET /v1/schema` returns structured category and rarity metadata for the full CS2 catalog, so filters can select exact items without guessing from display names.

Name matching alone produces false positives. A word such as "case" can appear in an item's name without making its catalog `category` a container.

## Filterable schema fields

| Filter dimension | Fields |
| --- | --- |
| Item type | `category`, `is_tradable` |
| Rarity | `rarity.name`, `rarity.tier`, `rarity.color` |
| Origin | `collections`, `containers` |
| Skin identity | `weapon`, `finish`, `base_name`, `wear`, `float_range` |
| Special form | `stattrak`, `souvenir`, `has_stattrak`, `has_souvenir` |
| Variant | Nested `variants`, standalone `variant`, `phase` |

Top-level `rarities` provides the catalog's current rarity definitions, and `counts.by_category` summarizes category coverage. Fields that do not apply to an item are omitted.

## Building the filter

Read the top-level `items` map and evaluate structured fields before applying optional text search. Return the record's exact `market_hash_name`, because that is the common key for prices, history, archives, and liquidity.

For a skin-only screen, require `category: skin` and the desired `is_tradable` state before checking rarity. For UI filters, derive category and rarity choices from the current response rather than freezing a copied list.

Treat variants deliberately. Base items can list supported phases or tiers under `variants`, and standalone variant rows link back through `variant`. Decide whether the output needs base records, variants, or both so the same identity is not counted twice.

## Applicable endpoint

| Endpoint | Returns | Plans |
| --- | --- | --- |
| `GET /v1/schema` | Full catalog and structured metadata | All plans |

## Filtering limits

- Missing fields mean the attribute does not apply or is unavailable. They should not be coerced to empty values that accidentally pass a filter.
- `rarity.tier` is suitable for ordering within the schema's rarity model; retain `rarity.name` for display.
- Catalog inclusion does not guarantee a non-null current price on every marketplace.
- Use `generation_id` or ETag to refresh saved filter options when a new immutable schema generation appears.

See the [item schema guide](/resources/how-to-get-cs2-item-schema) for the complete metadata inventory.