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. If you also need external catalog identifiers, keep them as attributes through the BUFF, Youpin, and C5Game ID mapping.