# GET /v1/schema

按 market_hash_name 键控的完整 CS2 饰品 schema：元数据、外观、变体、市场 id 和图片。

返回一份包含所有 Counter-Strike 2 饰品的完整 schema。它会在游戏更新时自动更新，包含约 47,500 件饰品和约 110 个收藏品，按 `market_hash_name` 键控，并提供稀有度、外观与磨损区间、市场 id 和饰品图片。

支持变体。在适用时，饰品会列出其收藏品和容器。

## 访问

适用于所有套餐，包括 Demo 和 Developer。

## 请求

`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)
```

## 响应

```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"
}
```

## 响应字段

[SchemaResponse](/zh-cn/docs/objects#schemaresponse) 字段:

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `schema_version` | `string` | 是 | 目录 schema 版本。变化时客户端应重新同步。 |
| `generation_id` | `string` | 是 | 此不可变 schema 代次的稳定标识符。 |
| `generated_at` | `string (date-time)` | 是 | 此不可变 schema 代次的构建时间。比较 `generation_id` 可检测代次变化。 |
| `counts` | `object` | 是 | 目录实体计数。 |
| `rarities` | [SchemaRarity[]](/zh-cn/docs/objects#schemararity) | 是 | 稀有度分层。 |
| `collections` | [`Record<string, SchemaCollection>`](/zh-cn/docs/objects#schemacollection) | 是 | 按收藏品名称键控的收藏品元数据。 |
| `items` | [`Record<string, SchemaItem>`](/zh-cn/docs/objects#schemaitem) | 是 | 按 `market_hash_name` 键控的饰品记录。 |

## 饰品元数据

| 字段 | 描述 |
| --- | --- |
| `items` | `market_hash_name`（与价格端点所接受的名称一致）到饰品元数据的映射。 |
| `items.<name>.ids` | 在已知时提供 `buff`、`youpin` 和 `c5game` 市场 id。 |
| `items.<name>.def_index`、`paint_index` | 游戏的饰品定义索引和涂装索引。 |
| `items.<name>.variants` | 基础饰品上的变体元数据；变体行通过 `variant` 回链。 |
| `items.<name>.is_tradable` | 对无法交易的饰品为 `false`。 |
| `collections`、`rarities` | 饰品记录所引用的收藏品与稀有度分层。 |

- 不适用于某件饰品的字段会被省略。
- `schema_version` 描述响应格式。每次重新生成 schema 数据时，`generation_id` 都会变化。

完整结构：[SchemaItem](/zh-cn/docs/objects#schemaitem)、[SchemaItemVariant](/zh-cn/docs/objects#schemaitemvariant)、[SchemaCollection](/zh-cn/docs/objects#schemacollection) 和 [SchemaRarity](/zh-cn/docs/objects#schemararity)。

### SchemaItem

一条目录记录，在顶层 `items` 映射中按 `market_hash_name` 键控。不适用于该饰品的字段会被省略。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `market_hash_name` | `string` | 是 | 规范的 Steam market hash name（与价格端点一致）。 |
| `category` | `string` | 是 | 饰品类别（例如 `skin`、`sticker`、`container`、`agent`）。 |
| `image` | `string` | 是 | `cs2.sh` 自有图片 URL。 |
| `steam_image` | `string` | 否 | 可选的 Valve Economy/static 官方图片 URL；仅在精确饰品来源已得到独立证明时提供。缺少该字段不会移除必需的自有 `image`。 |
| `is_tradable` | `boolean` | 是 | 该饰品是否可交易。 |
| `rarity` | `object` | 否 | 饰品稀有度：`name`、`tier` 和 `color`。 |
| `collections` | `string[]` | 否 | 饰品所属的收藏品。没有时省略。 |
| `containers` | `string[]` | 否 | 掉落该饰品的容器。没有时省略。 |
| `ids` | `object` | 否 | 已知的市场目录 id。 |
| `def_index` | `integer` | 否 | 饰品定义索引。 |
| `base_name` | `string` | 否 | 不含外观后缀的基础饰品名称。仅限皮肤。 |
| `weapon` | `string` | 否 | 武器名称。仅限皮肤。 |
| `finish` | `string` | 否 | 涂装名称。仅限皮肤。 |
| `paint_index` | `integer` | 否 | 涂装索引。仅限皮肤；Doppler 和 Gamma Doppler 基础饰品会省略。 |
| `wears` | `string[]` | 否 | 该饰品存在的外观。仅限有外观分级的饰品。 |
| `has_stattrak` | `boolean` | 否 | 是否存在 StatTrak 版本。仅限有外观分级的饰品。 |
| `has_souvenir` | `boolean` | 否 | 是否存在 Souvenir 版本。仅限有外观分级的饰品。 |
| `float_range` | `object` | 否 | 该饰品的磨损上下界。仅限有外观分级的饰品。 |
| `wear` | `string` | 否 | 该饰品的外观（例如 `Field-Tested`）。仅限有外观分级的饰品。 |
| `wear_float_range` | `object` | 否 | 该外观行自身的磨损上下界，即 `float_range` 截取到该外观区间后的范围。仅限有外观分级的饰品。 |
| `stattrak` | `boolean` | 否 | 该行是否为 StatTrak 版本。 |
| `souvenir` | `boolean` | 否 | 该行是否为 Souvenir 版本。 |
| `variants` | [SchemaItemVariant[]](/zh-cn/docs/objects#schemaitemvariant) | 否 | 该基础饰品的 Doppler / Gamma Doppler 相位或 Case Hardened 分层。 |
| `variant` | `object` | 否 | 变体行回链到其基础饰品。 |
| `phase` | `string` | 否 | 相位或宝石名称。仅限 Doppler 和 Gamma Doppler 变体行。 |
| `color` | `string` | 否 | 十六进制强调色。仅限 Doppler 和 Gamma Doppler 变体行。 |

### SchemaItemVariant

列在基础饰品 `variants` 下的一个 Doppler / Gamma Doppler 相位或 Case Hardened 分层。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `market_hash_name` | `string` | 是 | 完整的变体 `market_hash_name`。 |
| `family` | `string` | 是 | 允许值: `doppler`, `gamma_doppler`, `case_hardened`. 变体家族。 |
| `name` | `string` | 是 | 变体名称（例如 `Phase 2`、`Ruby`、`Tier 1`）。 |
| `phase` | `string` | 否 | 相位或宝石名称。Case Hardened 会省略。 |
| `color` | `string` | 否 | 十六进制强调色。Case Hardened 会省略。 |
| `paint_index` | `integer` | 否 | 该变体的涂装索引。 |
| `image` | `string` | 是 | `cs2.sh` 自有图片 URL。 |
| `steam_image` | `string` | 否 | 可选的 Valve Economy/static 官方图片 URL；仅在精确变体来源已得到独立证明时提供。缺少该字段不会移除必需的自有 `image`。 |

### SchemaCollection

收藏品元数据。在顶层 `collections` 映射中按收藏品名称键控。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `name` | `string` | 是 | 收藏品名称。 |
| `kind` | `string` | 是 | 收藏品类型（例如 `weapon`、`sticker`）。 |
| `release_date` | `string` | 否 | 发布日期（`YYYY-MM-DD`），已知时提供。饰品的发布日期即其收藏品的发布日期；饰品带有 `collections`，请据此关联，而不要指望每件饰品自带日期。 |
| `released_at` | `string` | 否 | 发布该收藏品的 Valve 公告的确切发布时刻（RFC 3339 UTC）。仅在该公告已知时提供。 |
| `update_name` | `string` | 否 | Valve 对该次更新的自有名称，例如 `Season 5, Armory, and More`。 |
| `announcement_url` | `string` | 否 | 该次更新的规范 Steam 公告地址。 |
| `image` | `string` | 否 | 由 `cs2.sh` 提供的自有图片 URL，可用时提供。 |
| `steam_image` | `string` | 否 | 可选的 Valve Economy/static 官方图片 URL；仅在精确来源已得到独立证明时提供。 |

### SchemaRarity

一个稀有度分层。列在顶层 `rarities` 数组中，并由饰品层的 `rarity` 引用。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `key` | `string` | 是 | 稳定的稀有度键（例如 `ancient`、`legendary`）。 |
| `name` | `string` | 是 | 显示名称（例如 `Covert`、`Classified`）。 |
| `tier` | `integer` | 是 | 数值稀有度分层，随稀有度递增。 |
| `color` | `string` | 是 | 该稀有度的十六进制颜色。 |

## 错误

`400 validation_error` 表示请求包含查询参数或缺少 `Accept-Encoding: gzip`。`503 service_unavailable` 表示 schema 尚未就绪。共有错误见[请求错误](/zh-cn/docs/using-the-api#请求错误)。