Migrating from the v1 API

Four things that change everywhere

1. Item ids changed type. v1 ids were 64-bit integers (the Steam assetDescriptionId). v2 ids are GUID strings. Every id you have stored is dead — a v1 id will not resolve.

There are two ways out, and the second is better. The v2 item DTO still carries assetDescriptionId, so you can sweep the catalogue once, build an assetDescriptionId → guid table and rewrite your keys. Or stop storing ids: every endpoint that takes an item id also accepts the item’s nameHash — the same value v1 returned as marketHashName — which is stable across both APIs and readable in a log. Note the rename: v2 has no marketHashName field, so a straight port of that property access yields undefined.

curl "https://api.scmm.app/api/item/f6f4f1a2-1c3a-4b6e-9d0f-0a1b2c3d4e5f"
curl "https://api.scmm.app/api/item/Tempered%20AK47"

2. Money is integer hundredths, always. v1 gave you a per-currency scale and expected value / 10^scale. v2 is value / 100 for every currency, with no exceptions.

3. language is gone. Every v1 path accepted language and currency. v2 has no language parameter anywhere and no /api/language endpoint. Strip it. currency survives, with the same 3-letter codes, on the endpoints that return money — but PLN and RUB no longer exist, so a hard-coded one now falls back to USD instead of erroring.

4. Pagination changed shape. v1 took start/count and returned { items, start, count, total }. v2 takes page (1-based)/pageSize and returns { items, page, pageSize, total }.

Authentication

v1 was fully open and said so. v2 keeps that for reads: the catalogue, prices, stores, workshop and inventory endpoints still take no credential. What changed is that the handful of endpoints touching your own account — /api/profile/me, /api/profile/data, inventory import — now need an x-api-key header or a session cookie. See Authentication.

Items

Marketplace, store and workshop

Profile and inventory

Statistics

App, currency and language

The bulk price feed is back — with different numbers

GET /api/item/prices returns the whole catalogue in one response, at the same path it had in v1. If you were sweeping GET /api/item page by page as a workaround, stop — that is ~62 requests against a 100/minute limit and this is one.

Three differences matter, and the third changes your numbers without changing your code.

• –One response shape, not two. v1 returned a different object depending on whether you passed markets. v2 always returns the same object; passing markets= adds a prices array to it and restricts which markets are considered.
• –Your stored ids still work here. This is the one endpoint where they do: v1’s id on this response was the Steam class id, not the assetDescriptionId used elsewhere, and v2 returns it as classId. nameHash is still the better key to move to.
• –The price is the cheapest one, not Steam’s. v1 sorted first-party sources ahead of every third-party market regardless of price, so it reported Steam’s number even when somewhere else was far cheaper. v2 reports the genuinely cheapest offer and names it in marketType.

Gaps, stated plainly

Three things v1 did that v2 does not. We would rather you read it here than find out in production.

• –Eight statistics endpoints have no successor — the typeDistribution/largestCollections/mostSaturated family, market activity, the rank and creator leaderboards, and contributors/donators.
• –Inventory mosaics are gone. Inventory value returns a number, not an image.
• –Workshop search changed shape, not just its path — submissions, accepted or not, come back grouped by the week they were published rather than as a flat list.

Tell us which gap blocks you, in our Discord. That is what drives the order we close them in.

New in v2

Suggested migration order

• –Re-point the base URL to https://api.scmm.app and delete every language parameter. Both fail loudly, so do them first and let the errors guide you.
• –Fix money handling — divide by 100, delete scale. Do this before anything that reads a price, because it fails silently.
• –Switch your item keys to nameHash (v1’s marketHashName, renamed), or build the assetDescriptionId → guid remap.
• –Convert pagination to 1-based page/pageSize and read the new envelope.
• –Re-point the moved trees last — statistics (/api/stats → /api/statistics) and inventory (/api/profile/{id}/inventory → /api/inventory/{profileId}).