# How to Map a CS2 Paint Index to Skin Names

Use `GET /v1/schema` to build a lookup from `paint_index` to every matching CS2 schema row. The relationship is one-to-many, so a paint index should return candidates rather than one assumed skin name.

## Why one paint index can return many items

A paint kit can be used across several weapons. Each weapon-finish pair can also have multiple exteriors and edition states.

Keep these fields beside every match:

- `paint_index`;
- `def_index`;
- exact `market_hash_name`;
- exterior;
- StatTrak and Souvenir state;
- item category;
- parent and variant identity when applicable.

This context lets a caller refine the candidate set without reconstructing a market name.

## Include nested phase records

Doppler and Gamma Doppler require special handling. Their parent rows can intentionally omit `paint_index`, while nested phases and gems expose phase-specific paint identities.

Build the lookup from both:

1. top-level schema rows with a `paint_index`;
2. nested variant rows with a `paint_index`.

Retain the parent name for every nested match. A label such as Phase 2 is not globally unique across weapons, exteriors, or edition states.

## Do not force an ambiguous match

If a caller supplies only `paint_index`, return every candidate. Add `def_index` to narrow the weapon, then exterior and edition state to reach an exact `market_hash_name`.

An empty result can mean the paint index is unknown in the current generation or exists only in a structure the caller did not traverse. Check both ordinary and nested records before declaring it absent.

## Track schema generation

Store `generation_id` with the derived lookup. The public schema supports ETag validation, is cached for one hour, and is available on every plan.

Rebuild on a generation change so new items and corrected mappings do not leave stale resolver results.

For all schema fields and caching behavior, see [get the CS2 item schema](/resources/how-to-get-cs2-item-schema). If you also need external catalog identifiers, keep them as attributes through the [BUFF, Youpin, and C5Game ID mapping](/resources/how-to-map-buff-youpin-c5game-item-ids).