Using the API

This page covers the conventions shared across cs2.sh API endpoints, including authentication, request types, response objects, variants, timestamps, missing data, partial success, errors, and limits.

• For a guided first request, start with the Quickstart.
• For marketplace fields, refresh rates, and historical coverage, see Data Coverage.
• Individual endpoint pages document their exact parameters and response fields.

Authentication#

The public API base URL is https://api.cs2.sh.

All /v1 endpoints require a Bearer API key. Every /v1 request must also accept gzip compression, and POST requests should also include Content-Type: application/json:

Successful /v1 responses are gzip-encoded. Most HTTP clients decompress them automatically. Error responses are returned as plain JSON.

Rotating your API key from the dashboard generates a new key and immediately invalidates the old one.

GET and POST requests#

cs2.sh uses two main request patterns:

• GET snapshot: fetch the complete current dataset for an endpoint.
• POST query: request data for up to 100 specific items, with endpoint-specific parameters such as dates, sources, or intervals.

For example, this fetches the complete current price snapshot:

GET /v1/prices/latest

This fetches current prices for two specific items:

POST /v1/prices/latest
Content-Type: application/json

{
  "items": [
    "USP-S | Printstream (Factory New)",
    "AK-47 | Redline (Field-Tested)"
  ]
}

GET snapshots can be large, but are useful since you can save a single response and perform future lookups locally. POST requests are better when you need a bounded response for a known set of items. These are also used for history endpoints to limit response size.

Items#

POST endpoints identify items using market_hash_name:

{
  "items": [
    "USP-S | Printstream (Factory New)"
  ]
}

GET /v1/schema returns every supported item by the same market_hash_name accepted by all endpoints. It also contains item metadata, marketplace ids, images, wears, float ranges, and variants.

POST endpoints accept up to 100 items in one request.

Responses#

Most item endpoints return an items object keyed by market_hash_name.

{
  "response_time": "2026-07-26T18:54:04.041Z",
  "currency": "USD",
  "items": {
    "USP-S | Printstream (Factory New)": {
      "market_hash_name": "USP-S | Printstream (Factory New)",
      "buff": {
        "updated_at": "2026-07-26T18:50:53Z",
        "collected_at": "2026-07-26T18:53:10.67Z",
        "ask": 109.72,
        "ask_volume": 463,
        "bid": 106.17,
        "bid_volume": 41
      }
    }
  }
}

Common top-level fields include:

Current-price items contain one object per marketplace. Historical endpoints use the same items map, with time-series data nested inside each item.

See API Objects for the complete response schemas.

Variants#

Items with supported Doppler, Gamma Doppler, or Case Hardened variants can include a variants object.

{
  "market_hash_name": "★ Karambit | Doppler (Factory New)",
  "buff": {
    "ask": 1336.26,
    "bid": 1281.77
  },
  "variants": {
    "Ruby": {
      "market_hash_name": "★ Karambit | Doppler (Factory New)",
      "name": "★ Karambit | Doppler (Factory New) | Ruby",
      "display_name": "Ruby",
      "version": "ruby",
      "buff": {
        "ask": 7671.41,
        "bid": 7287.47
      },
      "csfloat": {
        "ask": 7590,
        "bid": 7220
      }
    }
  }
}

On a variant object:

Version codes#

Supported version codes for variant items:

Variant availability depends on the marketplace and endpoint. See Data Coverage for variant support and GET /v1/schema for the variants attached to each item.

Timestamps#

Current marketplace price objects can include three different timestamps:

response_time does not indicate when an individual marketplace price was collected. Use the timestamps inside that marketplace's object when checking freshness.

Refresh rates are approximate and differ by marketplace. See Data Coverage for the expected refresh rate of each endpoint and source.

Historical response buckets#

prices/history and market/buff/history return fixed, UTC-aligned OHLC buckets. Each marketplace object inside a bucket includes the following observation fields:

ask_volume and bid_volume are the last observed values inside the bucket.

Not every historical endpoint returns OHLC. market/steam/history returns sampled Steam orderbook history, while archive endpoints return the data documented on their individual endpoint pages. See Data Coverage for the difference between OHLC, sampled, and archive history.

Missing data#

A missing price is not a price of zero.

On current-price base items, marketplace objects can be present with unavailable fields set to null:

{
  "skinport": {
    "updated_at": null,
    "collected_at": null,
    "ask": null,
    "ask_volume": null
  }
}

Variant and historical response objects can be sparse. A marketplace object may be absent when that marketplace has no data for the variant or interval.

Some historical endpoints omit a valid item when no data exists inside the requested range. The relevant endpoint page documents its exact empty-data behavior.

Partial success#

POST endpoints validate requested items independently. A request can return successful items and per-item errors in the same 200 response.

{
  "items": {
    "USP-S | Printstream (Factory New)": {
      "market_hash_name": "USP-S | Printstream (Factory New)"
    }
  },
  "errors": [
    {
      "item": "Invalid Item Name",
      "code": "unknown_item",
      "message": "item not found"
    }
  ]
}

An entry in errors applies only to that requested item. It does not invalidate the items returned successfully.

Item error codes#

The relevant endpoint page documents which item-error codes it can return. See ItemError for the complete object.

Item errors are different from request-level errors.

Request errors#

Request-level errors use a shared JSON object:

{
  "error": "validation_error",
  "message": "items must contain at most 100 entries",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Some errors also include a details object.

request_id identifies the failed request and should be included when contacting support.

Correct 400, 401, 403, 404, and 405 errors before retrying. Retry 429 and temporary 5xx errors with a bounded delay.

Individual endpoint pages document any additional error behavior specific to that endpoint.

Limits#

Historical endpoints also have interval-specific maximum request ranges. These are documented in Data Coverage and on the relevant endpoint page.

The complete GET snapshots can be large. Cache them when you need repeated access to the same current dataset, and use POST endpoints for smaller item-specific requests.

OpenAPI#

The complete OpenAPI 3.1 specification is available at cs2.sh/openapi.yaml.

It contains the request parameters, response schemas, enums, and examples used by the endpoint reference.