COS category listing
GET https://api.api.sh/cos/v1/category
Every product in a COS category, with the same fields, sort, filters and paging as search. category takes the site's category path (a product's main_category, or a path from suggest's categories, e.g. women/womenswear/knitwear) or a cos.com category link.
Every response includes credits_used: the credits this call cost.
Part of the COS API: 13 endpoints with prices, use cases and example responses.
Parameters
| name | type | description |
|---|---|---|
categoryrequired | string | Category path such as women/womenswear/knitwear, or a cos.com category link (e.g. https://www.cos.com/en-us/women/knitwear). Example: women/womenswear/knitwear |
market | string | Market: us (default), ca, gb, ie, de, at, ch, fr, es, it, nl, dk, no, se, pl, eu, eue, au, ww, or a site locale such as de-ch. Prices, currency and stock follow the market. country is accepted as the same thing. |
language | string | Language of names and texts, one the market offers (ch: de, en, fr; de: de, en; ca: en, fr; others their own). Default: the market's first language, or the link's. |
sort | recommended | newest | price_asc | price_desc | recommended (default), newest, price_asc, price_desc. |
color | string | Colour filter, comma = any of (black, beige, blue, ...; values in facets). |
size | string | Size filter, comma = any of (xs, s, m, l, xl, 36, ...). |
material | string | Material filter (cashmere, wool, linen, cotton, ...). |
fit | string | Fit filter (regular_fit, relaxed_fit, slim_fit, oversized_fit, ...). |
product_type | string | Product type filter (cardigan, jumper, coat, ...). |
feature | string | Product feature filter (classic_collar, collarless, ...). |
gender | string | women or men. |
min_price | number | Lowest price, in the market's currency. |
max_price | number | Highest price (below this), in the market's currency. |
filter | string | Any other site filter as attribute:value (repeatable; a leading ! excludes), with attributes and values from facets. |
page | integer | Page number (1-based). Pass next_page back; null on the last page. |
page_size | integer | Products per page, 1-48 (default 24). |
offset | integer | Start at this product instead of page (next_offset of the previous answer). |
Every endpoint also takes fresh, raw, fields (see lean responses and caching).
Example
curl "https://api.api.sh/cos/v1/category?category=women%2Fwomenswear%2Fknitwear" \
-H "x-api-key: $APISH_KEY" import os, requests
res = requests.get(
"https://api.api.sh/cos/v1/category",
params={"category": "women/womenswear/knitwear"},
headers={"x-api-key": os.environ["APISH_KEY"]},
timeout=120,
)
res.raise_for_status()
data = res.json() const url = new URL("https://api.api.sh/cos/v1/category");
url.searchParams.set("category", "women/womenswear/knitwear");
const res = await fetch(url, { headers: { "x-api-key": process.env.APISH_KEY } });
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json(); Response
A JSON object with the fields described above, plus raw (the source's own data), cached, fetched_at and credits_used. Errors return {"success": false, "error": "…"} with the HTTP status (see errors). A lookup that ran but found nothing (404) costs the price above; refused calls and errors on our side are free (what's charged).
Example response (real call, trimmed: lists cut to 2 items, long text shortened, raw left out)
{"category": "women/womenswear/knitwear","category_url": null,"market": "us","language": "en","total": 250,"count": 24,"page": 1,"page_size": 24,"offset": 0,"next_page": 2,"next_offset": 24,"redirect": null,"products": [{"id": 25967,"sku": "1346686003","style_sku": "1346686","uri": "argyle-brushed-pure-cashmere-funnel-neck-jumper-blue-1346686003","name": "ARGYLE BRUSHED PURE CASHMERE MOCK-NECK SWEATER","url": "https://www.cos.com/en-us/women/womenswear/knitwear/jumpers/cashmere/product/argyle-brushed-pure-cashmere-funnel-neck-jumper-blue-1346686003","price": {"value": 349,"currency": "USD","label": "$349.00"},"price_before_discount": {"value": 349,"currency": "USD","label": "$349.00"},"lowest_price_30d": {"value": 349,"currency": "USD","label": "$349.00"},"discount_percent": null,"on_sale": false,"is_new": true,"coming_soon": false,"in_stock": true,"color": "BLUE","color_hex": "#254E89","colors": [{"name": "BLUE","hex": "#254E89","available": true,"id": 25967,"image": "https://media.cos.com/assets/001/ff/b7/ffb754b721be3aa6bbbc2b9ac5a2e1cc7f53f2a6_xxl-1.jpg"},{"name": "BROWN","hex": "#7D706B","available": true,"id": 25745,"image": "https://media.cos.com/assets/001/8a/2f/8a2f3388840373d854a5177fa3423fa276ae7939_xxl-1.jpg"}],"variants_count": 1,"product_type": "Jumper","gender": "Female","main_category": "women/womenswear/knitwear/jumpers/cashmere","tags": ["EU Unisex Black Friday Exclusions","cashmere","… 9 more"],"launch_date": "2026-11-03T09:00:00.000Z","image": "https://media.cos.com/assets/001/80/ee/80ee2951d45fcc9abef1e0e59bd93941e9e405bd_xxl-1.jpg","images": ["https://media.cos.com/assets/001/5d/ab/5dab604d00f345a7f1d46215886e45e65ebf4137_xxl-1.jpg","https://media.cos.com/assets/001/76/a8/76a8d33ddd52b81a098cff895a6c0acd355aac4b_xxl-1.jpg","… 10 more"],"position": 1},{"id": 25899,"sku": "1358145001","style_sku": "1358145","uri": "merino-wool-funnel-neck-zip-up-jumper-cobalt-blue-1358145001","name": "MERINO WOOL MOCK-NECK ZIP-UP SWEATER","url": "https://www.cos.com/en-us/women/womenswear/knitwear/jumpers/wool/product/merino-wool-funnel-neck-zip-up-jumper-cobalt-blue-1358145001","price": {"value": 199,"currency": "USD","label": "$199.00"},"price_before_discount": {"value": 199,"currency": "USD","label": "$199.00"},"lowest_price_30d": {"value": 199,"currency": "USD","label": "$199.00"},"discount_percent": null,"on_sale": false,"is_new": true,"coming_soon": false,"in_stock": true,"color": "COBALT BLUE","color_hex": "#3B4EA3","colors": [{"name": "COBALT BLUE","hex": "#3B4EA3","available": true,"id": 25899,"image": "https://media.cos.com/assets/001/a3/f5/a3f549e1a45cd813108f2e85cf8289ba92acc78f_xxl-1.jpg"},{"name": "NAVY","hex": "#2B2C32","available": true,"id": 25588,"image": "https://media.cos.com/assets/001/3e/18/3e18f83de7363b80419d1cb2d07986595ec3aa74_xxl-1.jpg"}],"variants_count": 1,"product_type": "Jumper","gender": "Female","main_category": "women/womenswear/knitwear/jumpers/wool","tags": ["EU Unisex Black Friday Exclusions","wool","… 6 more"],"composition": [{"type": "Shell","materials": [{"…": "3 fields"}]}],"launch_date": "2026-11-05T04:48:00.000Z","image": "https://media.cos.com/assets/001/26/31/26314f1abe550ab94b1c4fc6df96eb16eaa7f852_xxl-1.jpg","images": ["https://media.cos.com/assets/001/95/08/9508dc59f36f2da5a5f68c94e533d41d55bc31f5_xxl-1.jpg","https://media.cos.com/assets/001/0a/90/0a905073fdef70a12eb6fe60bf3af1ac8e83629d_xxl-1.jpg","… 10 more"],"position": 2},"… 22 more"],"facets": [{"param": "product_type","attribute": "product_types","title": "Product Type","type": "set","values": [{"value": "balaclava","label": "Balaclava","count": 2},{"value": "beanie","label": "Beanie","count": 10},"… 18 more"]},{"param": "feature","attribute": "product_features","title": "Product Feature","type": "set","values": [{"value": "classic_collar","label": "Classic collar","count": 23},{"value": "roll_neck","label": "Turtleneck","count": 8},"… 40 more"]},"… 6 more"],"cached": false,"credits_used": 1}The fastest way to see the full response is the playground: it runs this endpoint with your account and shows the exact JSON.