# GET /v1/schema

Full CS2 item schema keyed by market_hash_name: metadata, wears, variants, marketplace ids, and images.

Returns a single schema containing all Counter-Strike 2 items. It's updated automatically when the game updates and contains ~47,500 items and ~110 collections keyed by `market_hash_name`, with rarities, wears and float ranges, marketplace ids, and item images.

Variants are included. Where applicable, items list their collections and containers.

## Access

Available on all plans, including Demo and Developer.

## Request

`GET https://api.cs2.sh/v1/schema`

**curl**

```bash
curl https://api.cs2.sh/v1/schema \
  -H "Authorization: Bearer <<YOUR_API_KEY>>" \
  -H "Accept-Encoding: gzip" --compressed
```

**Python**

```python
import requests

headers = {
    "Authorization": "Bearer <<YOUR_API_KEY>>",
    "Accept-Encoding": "gzip",
}

response = requests.get(
    "https://api.cs2.sh/v1/schema",
    headers=headers,
)

response.raise_for_status()
data = response.json()
```

**Node**

```javascript
const headers = {
  "Authorization": "Bearer <<YOUR_API_KEY>>",
  "Accept-Encoding": "gzip",
};

const response = await fetch("https://api.cs2.sh/v1/schema", { headers });

if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();
```

**Go**

```go
package main

import (
    "compress/gzip"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://api.cs2.sh/v1/schema", nil)
    req.Header.Set("Authorization", "Bearer <<YOUR_API_KEY>>")
    req.Header.Set("Accept-Encoding", "gzip")

    resp, err := http.DefaultClient.Do(req)
    if err != nil { panic(err) }
    defer resp.Body.Close()

    if resp.StatusCode < 200 || resp.StatusCode >= 300 {
        body, _ := io.ReadAll(resp.Body)
        panic(fmt.Sprintf("HTTP %d: %s", resp.StatusCode, body))
    }

    var reader io.Reader = resp.Body
    if resp.Header.Get("Content-Encoding") == "gzip" {
        gz, err := gzip.NewReader(resp.Body)
        if err != nil { panic(err) }
        defer gz.Close()
        reader = gz
    }

    var data any
    if err := json.NewDecoder(reader).Decode(&data); err != nil { panic(err) }
    fmt.Printf("%#v\n", data)
}
```

**R**

```r
library(httr2)

resp <- request("https://api.cs2.sh/v1/schema") |>
  req_headers(
    Authorization = "Bearer <<YOUR_API_KEY>>",
    `Accept-Encoding` = "gzip"
  ) |>
  req_perform()

data <- resp_body_json(resp)
```

## Response

```json
{
  "schema_version": "v3",
  "generated_at": "2026-08-12T22:18:51Z",
  "counts": {
    "items": 48696,
    "by_category": {
      "agent": 63,
      "collectible": 468,
      "container": 479,
      "graffiti": 2111,
      "highlight_reel": 926,
      "key": 39,
      "keychain": 78,
      "music_kit": 188,
      "patch": 112,
      "skin": 21924,
      "sticker": 11132,
      "sticker_slab": 11132,
      "tool": 4,
      "vanilla_skin": 40
    },
    "collections": 110
  },
  "rarities": [
    {
      "key": "default",
      "name": "Stock",
      "tier": 0,
      "color": "#b0c3d9"
    },
    {
      "key": "common",
      "name": "Consumer Grade",
      "tier": 1,
      "color": "#b0c3d9"
    },
    {
      "key": "uncommon",
      "name": "Industrial Grade",
      "tier": 2,
      "color": "#5e98d9"
    },
    {
      "key": "rare",
      "name": "Mil-Spec Grade",
      "tier": 3,
      "color": "#4b69ff"
    },
    {
      "key": "mythical",
      "name": "Restricted",
      "tier": 4,
      "color": "#8847ff"
    },
    {
      "key": "legendary",
      "name": "Classified",
      "tier": 5,
      "color": "#d32ce6"
    },
    {
      "key": "ancient",
      "name": "Covert",
      "tier": 6,
      "color": "#eb4b4b"
    },
    {
      "key": "immortal",
      "name": "Contraband",
      "tier": 7,
      "color": "#e4ae39"
    }
  ],
  "collections": {
    "2025 Community Sticker Collection": {
      "name": "2025 Community Sticker Collection",
      "kind": "sticker",
      "release_date": "2025-10-01",
      "released_at": "2025-10-01T23:42:32Z",
      "update_name": "Community Maps, Charms, and More",
      "announcement_url": "https://steamcommunity.com/games/CSGO/announcements/detail/498333631688738073",
      "image": "https://cs2.sh/image/5-y5BqjoeymuHNzv",
      "steam_image": "https://cdn.steamstatic.com/apps/730/icons/econ/set_icons/set_community_2025.280d945244b90804541bf84784796793fd3bad00.png"
    },
    "Auto Racing Sticker Collection": {
      "name": "Auto Racing Sticker Collection",
      "kind": "sticker",
      "release_date": "2026-07-08",
      "released_at": "2026-07-08T22:50:43Z",
      "update_name": "Season 5, Armory, and More",
      "announcement_url": "https://steamcommunity.com/games/CSGO/announcements/detail/701021228894257509",
      "image": "https://cs2.sh/image/UuGTutGWjf5OvoVM",
      "steam_image": "https://cdn.steamstatic.com/apps/730/icons/econ/set_icons/set_auto_racing.2bb35a9a9c95a4757596a2ebd2085c73529f184b.png"
    }
  },
  "items": {
    "USP-S | Printstream (Factory New)": {
      "market_hash_name": "USP-S | Printstream (Factory New)",
      "category": "skin",
      "image": "https://cs2.sh/image/N8Agkakkrq4y1Hm1",
      "steam_image": "https://community.akamai.steamstatic.com/economy/image/i0CoZ81Ui0m-9KwlBY1L_18myuGuq1wfhWSaZgMttyVfPaERSR0Wqmu7LAocGIGz3UqlXOLrxM-vMGmW8VNxu5Dx60noTyLkjYbf7itX6vytbbZSI-WsG3SA_v5kue99XD2hkBwqjDGMnYftb3yUPFR0XsNyRrNc5kO5ltziMenr5lONj4kXyi2riywc7y9o5LtQAqQ7uvqAkScWnv4",
      "is_tradable": true,
      "rarity": {
        "name": "Covert",
        "tier": 6,
        "color": "#eb4b4b"
      },
      "collections": [
        "The Recoil Collection"
      ],
      "containers": [
        "Recoil Case"
      ],
      "ids": {
        "buff": 900565,
        "youpin": 102375,
        "c5game": 1017617021485346800
      },
      "def_index": 61,
      "base_name": "USP-S | Printstream",
      "weapon": "USP-S",
      "finish": "Printstream",
      "wears": [
        "Factory New",
        "Minimal Wear",
        "Field-Tested",
        "Well-Worn",
        "Battle-Scarred"
      ],
      "has_stattrak": true,
      "has_souvenir": true,
      "float_range": {
        "min": 0,
        "max": 0.85
      },
      "paint_index": 1142,
      "wear": "Factory New",
      "wear_float_range": {
        "min": 0,
        "max": 0.07
      },
      "stattrak": false,
      "souvenir": false
    },
    "★ Karambit | Doppler (Factory New)": {
      "market_hash_name": "★ Karambit | Doppler (Factory New)",
      "category": "skin",
      "image": "https://cs2.sh/image/vJQM7YiSwMZS1GsE",
      "steam_image": "https://community.akamai.steamstatic.com/economy/image/i0CoZ81Ui0m-9KwlBY1L_18myuGuq1wfhWSaZgMttyVfPaERSR0Wqmu7LAocGIGz3UqlXOLrxM-vMGmW8VNxu5Dx60noTyL6kJ_m-B1Q7uCvZaZkNM-SA1iSze91u_FsTju_qhAmoT-Jn4bjJC_4Ml93UtZuRLQPsBawkNfiMbnl5AKMiopCnin7iCJBv31j4rkBBKEg-6zUjV3GY6p9v8dpLWT3Fg",
      "is_tradable": true,
      "rarity": {
        "name": "Covert",
        "tier": 6,
        "color": "#eb4b4b"
      },
      "containers": [
        "Chroma Case",
        "Chroma 2 Case",
        "Chroma 3 Case"
      ],
      "ids": {
        "buff": 42998,
        "youpin": 1785,
        "c5game": 22702
      },
      "def_index": 507,
      "base_name": "★ Karambit | Doppler",
      "weapon": "Karambit",
      "finish": "Doppler",
      "wears": [
        "Factory New",
        "Minimal Wear"
      ],
      "has_stattrak": true,
      "has_souvenir": false,
      "float_range": {
        "min": 0,
        "max": 0.08
      },
      "wear": "Factory New",
      "wear_float_range": {
        "min": 0,
        "max": 0.07
      },
      "stattrak": false,
      "souvenir": false,
      "variants": [
        {
          "market_hash_name": "★ Karambit | Doppler (Factory New) | Phase 1",
          "family": "doppler",
          "name": "Phase 1",
          "image": "https://cs2.sh/image/f7tv2IWIqPDquMsV",
          "steam_image": "https://community.akamai.steamstatic.com/economy/image/i0CoZ81Ui0m-9KwlBY1L_18myuGuq1wfhWSaZgMttyVfPaERSR0Wqmu7LAocGIGz3UqlXOLrxM-vMGmW8VNxu5Dx60noTyL6kJ_m-B1Q7uCvZaZkNM-SA1iUzv5mvOR7cDm7lA4i4gKJk4jxNWXFb1cpDJR2FOFbsBTql9bjYbzq7gPZiN1MxH7_2ytNuCdpte1UB_Ui5OSJ2GbkVqni",
          "phase": "Phase 1",
          "color": "#6e1b3a",
          "paint_index": 418
        }
      ]
    }
  },
  "generation_id": "7645176062026597595"
}
```

## Response fields

[SchemaResponse](/docs/objects#schemaresponse) fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `schema_version` | `string` | Yes | Schema version. Re-sync clients when it changes. |
| `generation_id` | `string` | Yes | Stable identifier for this immutable schema generation. |
| `generated_at` | `string (date-time)` | Yes | When this immutable schema generation was built. Compare `generation_id` to detect a generation change. |
| `counts` | `object` | Yes | Schema entity counts. |
| `rarities` | [SchemaRarity[]](/docs/objects#schemararity) | Yes | Rarity tiers. |
| `collections` | [`Record<string, SchemaCollection>`](/docs/objects#schemacollection) | Yes | Collection metadata keyed by collection name. |
| `items` | [`Record<string, SchemaItem>`](/docs/objects#schemaitem) | Yes | Item records keyed by `market_hash_name`. |

## Item metadata

| Field | Description |
| --- | --- |
| `items` | Map of `market_hash_name` (the same names the price endpoints accept) to item metadata. |
| `items.<name>.ids` | `buff`, `youpin`, and `c5game` marketplace ids, where known. |
| `items.<name>.def_index`, `paint_index` | The game's item definition and paint kit indexes. |
| `items.<name>.variants` | Variant metadata on base items; variant rows link back through `variant`. |
| `items.<name>.is_tradable` | `false` for items that cannot be traded. |
| `collections`, `rarities` | The collections and rarity tiers item records reference. |

- Fields that do not apply to an item are omitted.
- `schema_version` describes the response format. `generation_id` changes when the schema data is regenerated.

Full schemas: [SchemaItem](/docs/objects#schemaitem), [SchemaItemVariant](/docs/objects#schemaitemvariant), [SchemaCollection](/docs/objects#schemacollection), and [SchemaRarity](/docs/objects#schemararity).

### SchemaItem

One schema record, keyed by `market_hash_name` in the top-level `items` map. Fields that do not apply to the item are omitted.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `market_hash_name` | `string` | Yes | Canonical Steam market hash name (matches the price endpoints). |
| `category` | `string` | Yes | Item category (e.g. `skin`, `sticker`, `container`, `agent`). |
| `image` | `string` | Yes | Owned image URL served from `cs2.sh`. |
| `steam_image` | `string` | No | Optional official Valve Economy/static image URL, emitted only when the exact item origin is independently proven. Its absence does not remove the required owned `image`. |
| `is_tradable` | `boolean` | Yes | Whether the item can be traded. |
| `rarity` | `object` | No | Item rarity with `name`, `tier`, and `color`. |
| `collections` | `string[]` | No | Collections the item belongs to. Omitted when none. |
| `containers` | `string[]` | No | Containers the item drops from. Omitted when none. |
| `ids` | `object` | No | Marketplace catalog ids where known. |
| `def_index` | `integer` | No | Item definition index. |
| `base_name` | `string` | No | Base item name without the wear suffix. Skins only. |
| `weapon` | `string` | No | Weapon name. Skins only. |
| `finish` | `string` | No | Finish name. Skins only. |
| `paint_index` | `integer` | No | Paint kit index. Skins only; omitted on Doppler and Gamma Doppler base items. |
| `wears` | `string[]` | No | Wears the item exists in. Wear-carrying items only. |
| `has_stattrak` | `boolean` | No | Whether a StatTrak version exists. Wear-carrying items only. |
| `has_souvenir` | `boolean` | No | Whether a Souvenir version exists. Wear-carrying items only. |
| `float_range` | `object` | No | Float bounds for this item. Wear-carrying items only. |
| `wear` | `string` | No | This item's wear (e.g. `Field-Tested`). Wear-carrying items only. |
| `wear_float_range` | `object` | No | Float bounds for this exact wear row, `float_range` clamped to this wear's bracket. Wear-carrying items only. |
| `stattrak` | `boolean` | No | Whether this row is the StatTrak version. |
| `souvenir` | `boolean` | No | Whether this row is the Souvenir version. |
| `variants` | [SchemaItemVariant[]](/docs/objects#schemaitemvariant) | No | Doppler / Gamma Doppler phases or Case Hardened tiers for this base item. |
| `variant` | `object` | No | Back-link on a variant row to its base item. |
| `phase` | `string` | No | Phase or gem name. Doppler and Gamma Doppler variant rows only. |
| `color` | `string` | No | Hex accent color. Doppler and Gamma Doppler variant rows only. |

### SchemaItemVariant

A Doppler / Gamma Doppler phase or Case Hardened tier listed under a base item's `variants`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `market_hash_name` | `string` | Yes | Full variant `market_hash_name`. |
| `family` | `string` | Yes | Allowed: `doppler`, `gamma_doppler`, `case_hardened`. Variant family. |
| `name` | `string` | Yes | Variant name (e.g. `Phase 2`, `Ruby`, `Tier 1`). |
| `phase` | `string` | No | Phase or gem name. Omitted for Case Hardened. |
| `color` | `string` | No | Hex accent color. Omitted for Case Hardened. |
| `paint_index` | `integer` | No | Paint kit index for this variant. |
| `image` | `string` | Yes | Owned image URL served from `cs2.sh`. |
| `steam_image` | `string` | No | Optional official Valve Economy/static image URL, emitted only when the exact variant origin is independently proven. Its absence does not remove the required owned `image`. |

### SchemaCollection

Collection metadata. Keyed by collection name in the top-level `collections` map.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Yes | Collection name. |
| `kind` | `string` | Yes | Collection kind (e.g. `weapon`, `sticker`). |
| `release_date` | `string` | No | Release date (`YYYY-MM-DD`), when known. An item's release date is its collection's; items carry `collections`, so join on that rather than expecting a date per item. |
| `released_at` | `string` | No | Exact publication instant of the Valve announcement that shipped the collection (RFC 3339 UTC). Present only where that announcement is known. |
| `update_name` | `string` | No | Valve's own name for that update, e.g. `Season 5, Armory, and More`. |
| `announcement_url` | `string` | No | Canonical Steam announcement for that update. |
| `image` | `string` | No | Owned image URL served from `cs2.sh`, when available. |
| `steam_image` | `string` | No | Optional official Valve Economy/static image URL, emitted only when the exact origin is independently proven. |

### SchemaRarity

A rarity tier. Listed in the top-level `rarities` array and referenced by item-level `rarity`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `key` | `string` | Yes | Stable rarity key (e.g. `ancient`, `legendary`). |
| `name` | `string` | Yes | Display name (e.g. `Covert`, `Classified`). |
| `tier` | `integer` | Yes | Numeric rarity tier, ascending with rarity. |
| `color` | `string` | Yes | Hex color for the rarity. |

## Errors

`400 validation_error` means query parameters were supplied or `Accept-Encoding: gzip` is missing. `503 service_unavailable` means the schema is not ready. See [Request errors](/docs/using-the-api#request-errors) for shared errors.