# CS2 Item Preview API: Steam class metadata by class ID

`GET /v1/cs2/item-preview` resolves a known Counter-Strike 2 Steam
`classid` and optional `instanceid` into the item description Steam currently
publishes through [`ISteamEconomy/GetAssetClassInfo`](https://partner.steamgames.com/doc/webapi/ISteamEconomy).
Use it when your application already has the IDs and needs a name, Steam market
hash name, icon, type, tags or descriptions. The endpoint does not discover
unknown IDs by scanning inventories or the marketplace.

## Request

```bash
curl --fail-with-body --silent --show-error --get \
  -H "Authorization: Bearer ${WOK_API_KEY}" \
  --data-urlencode "classid=${CS2_CLASS_ID}" \
  --data-urlencode 'instanceid=0' \
  https://woksteamapi.com/v1/cs2/item-preview
```

| Parameter | Required | Meaning |
| --- | --- | --- |
| `classid` | Yes | Positive decimal Steam class ID, within uint64 range. Pass it as a string to avoid rounding large IDs. |
| `instanceid` | No | Decimal Steam instance ID within uint64 range; defaults to `0`. |

Authenticate with a WOK Bearer key. Any active plan can use this route; the
Inspect add-on is not required. Each request consumes one normal WOK quota
unit. WOK bounds and caches direct Valve Web API lookups; this endpoint does
not spend residential proxy traffic.

## Response

```json
{
  "status": "resolved",
  "scope": "class",
  "source": "steam_get_asset_class_info",
  "appid": 730,
  "classid": "1234567890123456789",
  "instanceid": "0",
  "observed_at": 1790467200.0,
  "item": {
    "name": "Example Steam item name",
    "markethashname": "Example Steam market hash name",
    "image": "Steam icon value",
    "image_url": "https://community.cloudflare.steamstatic.com/economy/image/...",
    "tags": [],
    "descriptions": []
  }
}
```

The example shows response structure, not a real Steam class. Steam only
supplies fields that exist for a given class. `item` may also contain
`marketname`, `image_url_large`, `type`, `name_color`, `background_color`, and
`commodity`. `image` is Steam's raw icon value. WOK supplies `image_url` only
when it can safely derive a renderable Steam CDN URL. `observed_at` is the
Unix time when this class description was fetched, not when a player obtained
an item. Check it before treating metadata as fresh.

The `scope: "class"` marker is deliberate: a class definition has no
individual asset ID, owner, float, paint seed, applied stickers or charms,
price, trade lock or trade-protection state. Use
[`POST /v1/cs2/inspect`](/api/integration-guide.md#individual-cs2-market-listings-and-floats)
for supported individual inspect links and
[`GET /v1/inventory`](/api/integration-guide.md#inventory-for-any-named-game)
for visible player assets. A class preview cannot recover assets hidden from
Steam's public inventory during its visibility delay.

## Errors and new classes

| HTTP status | Code | Meaning |
| --- | --- | --- |
| `400` | `invalid_class_id` | An ID is not a valid decimal uint64 value. |
| `422` | Query validation error | A required parameter is missing or exceeds the accepted length. |
| `401` | Standard WOK auth error | Bearer key is missing or invalid. |
| `402` | Standard WOK quota error | The key's normal request quota is exhausted. |
| `404` | `class_not_found` | Steam successfully answered but did not expose that class. |
| `429` | Standard WOK rate limit | Retry after the supplied limit resets. |
| `503` | `steam_asset_class_info_unavailable` or `steam_daily_budget_exhausted` | Steam class lookup or its shared upstream budget is temporarily unavailable. |

Valve can publish class data after a new CS2 item is introduced. A `404` is
therefore an observation at request time, not proof the class never exists.
WOK does not guarantee immediate appearance of new skins, stickers, slabs or
charms before Steam's own class API exposes them.

See the [integration guide](/api/integration-guide.md) for the WOK key setup and
the [OpenAPI contract](/api/openapi.json) for machine-readable fields.