COS product search
GET https://api.api.sh/cos/v1/search
Search the COS store: every product with price and the price before discount (value, ISO currency, label), the lowest price of the last 30 days, sale/new/in-stock flags, colour and the other colours, sizes, product type, materials, category and images, plus the site's filters with counts (facets). The site's sort and every filter it offers (colour, size, material, fit, product type, feature, gender, price range). Page with page (next_page, null on the last page).
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 |
|---|---|---|
qrequired | string | Keywords, e.g. cashmere cardigan. Example: cashmere cardigan |
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/search?q=cashmere+cardigan" \
-H "x-api-key: $APISH_KEY" import os, requests
res = requests.get(
"https://api.api.sh/cos/v1/search",
params={"q": "cashmere cardigan"},
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/search");
url.searchParams.set("q", "cashmere cardigan");
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)
{"query": "cashmere cardigan","market": "us","language": "en","total": 23,"count": 23,"page": 1,"page_size": 24,"offset": 0,"next_page": null,"next_offset": null,"redirect": null,"products": [{"id": 25663,"sku": "1357457002","style_sku": "1357457","uri": "brushed-cashmere-v-neck-cardigan-wine-red-1357457002","name": "BRUSHED PURE CASHMERE V-NECK CARDIGAN","url": "https://www.cos.com/en-us/men/menswear/knitwear/cardigans/product/brushed-cashmere-v-neck-cardigan-wine-red-1357457002","price": {"value": 329,"currency": "USD","label": "$329.00"},"price_before_discount": {"value": 329,"currency": "USD","label": "$329.00"},"lowest_price_30d": {"value": 329,"currency": "USD","label": "$329.00"},"discount_percent": null,"on_sale": false,"is_new": true,"coming_soon": false,"in_stock": true,"color": "WINE RED","color_hex": "#503B40","colors": [{"name": "WINE RED","hex": "#503B40","available": true,"id": 25663,"image": "https://media.cos.com/assets/001/1e/1f/1e1ff1c3e7da418c9355c9c99366242ba76ad266_xxl-1.jpg"},{"name": "MOCHA","hex": "#7B7164","available": true,"id": 25664,"image": "https://media.cos.com/assets/001/5b/cd/5bcd5a721746ca1df77ceb63d0b24c7bff0137cc_xxl-1.jpg"}],"variants_count": 1,"product_type": "Cardigan","gender": "Male","main_category": "men/menswear/knitwear/cardigans","tags": ["cashmere","cardigans","… 7 more"],"launch_date": "2026-10-06T01:53:00.000Z","image": "https://media.cos.com/assets/001/a5/ab/a5ab9cda7d0173954198df436886949833f763f5_xxl-1.jpg","images": ["https://media.cos.com/assets/001/8e/af/8eafd86099efdd9eea17fceba443a545738b2b56_xxl-1.jpg","https://media.cos.com/assets/001/4c/e0/4ce04a5a5e69971880550f6552912b82039544d5_xxl-1.jpg","… 6 more"],"position": 1},{"id": 25664,"sku": "1357457001","style_sku": "1357457","uri": "brushed-cashmere-v-neck-cardigan-mocha-1357457001","name": "BRUSHED PURE CASHMERE V-NECK CARDIGAN","url": "https://www.cos.com/en-us/men/menswear/knitwear/cardigans/product/brushed-cashmere-v-neck-cardigan-mocha-1357457001","price": {"value": 329,"currency": "USD","label": "$329.00"},"price_before_discount": {"value": 329,"currency": "USD","label": "$329.00"},"lowest_price_30d": {"value": 329,"currency": "USD","label": "$329.00"},"discount_percent": null,"on_sale": false,"is_new": false,"coming_soon": false,"in_stock": true,"color": "MOCHA","color_hex": "#7B7164","colors": [{"name": "MOCHA","hex": "#7B7164","available": true,"id": 25664,"image": "https://media.cos.com/assets/001/5b/cd/5bcd5a721746ca1df77ceb63d0b24c7bff0137cc_xxl-1.jpg"},{"name": "WINE RED","hex": "#503B40","available": true,"id": 25663,"image": "https://media.cos.com/assets/001/1e/1f/1e1ff1c3e7da418c9355c9c99366242ba76ad266_xxl-1.jpg"}],"variants_count": 1,"product_type": "Cardigan","gender": "Male","main_category": "men/menswear/knitwear/cardigans","tags": ["cashmere","cardigans","… 9 more"],"launch_date": "2026-09-24T10:39:00.000Z","image": "https://media.cos.com/assets/001/f9/26/f9260fb667f15a0bcc4fb81c714067ca2116c474_xxl-1.jpg","images": ["https://media.cos.com/assets/001/39/71/3971b275b3eac63370f6696386b2e53380d1a21b_xxl-1.jpg","https://media.cos.com/assets/001/d3/91/d39126df92f5d0b6cf36e75501ef127c357226c6_xxl-1.jpg","… 6 more"],"position": 2},"… 21 more"],"facets": [{"param": "product_type","attribute": "product_types","title": "Product Type","type": "set","values": [{"value": "cardigan","label": "Cardigan","count": 21},{"value": "jumper","label": "Jumper","count": 1},"… 1 more"]},{"param": "feature","attribute": "product_features","title": "Product Feature","type": "set","values": [{"value": "high_collar","label": "High Collar","count": 2},{"value": "long_sleeve","label": "Long sleeve","count": 22},"… 6 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.