# Coolblue Product Search API Documentation

`GET /api/coolblue/search` returns public Coolblue products as structured JSON. Use `query` or `category`, not both.

## What you get

Each item appears once: duplicate cards are merged and the richest row wins. Fields are `id`, `title`, `brand`, `price`, `original_price`, `currency`, `rating`, `review_count`, `availability` and `image`. Brand is read from the card that carries the id; a refurbished label is not a brand. When a card publishes no brand, the title supplies a known brand. Rating and review count come from the same card, and rows without reviews return null for both, never zero. `availability` is one short enum: `in_stock`, `out_of_stock` or `unknown`. Prices are numbers in EUR. Use `id` unchanged with the product endpoint.

## Parameters

`market` is `nl` (default). Belgium and Germany are not published until they pass their own production soak. `sort`, `page`, `min_price` and `max_price` have no verified page recipe and return 422 before any lookup; page one is never relabelled and no filter is silently ignored.

A query with no products answers HTTP 200 with `items: []`, `meta.billable: false` and `meta.credits_charged: 0`.

## Credits

A successful request costs **1 credit**. Errors, challenges and empty pages cost nothing. The response shows the charge in `meta.credits_charged`.

- **Documentation:** [https://scrappa.co/docs/coolblue-api/coolblue_search](https://scrappa.co/docs/coolblue-api/coolblue_search)
- **API group:** Coolblue API
- **Endpoint:** `GET https://scrappa.co/api/coolblue/search`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `market` | string | No | nl (default). Other markets return 422 until they pass their own soak. |
| `query` | string | No | Search words. Use this or category. |
| `category` | string | No | Category slug such as koptelefoons. Use this or query. |
| `sort` | string | No | Not supported, returns 422. |
| `page` | integer | No | Not supported, returns 422. |
| `min_price` | number | No | Not supported, returns 422. |
| `max_price` | number | No | Not supported, returns 422. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/coolblue/search?query=koptelefoons"
```

## Example response

```json
{
    "success": true,
    "market": "nl",
    "currency": "EUR",
    "query": "koptelefoons",
    "category": null,
    "resolved_category": "koptelefoons",
    "items": [
        {
            "position": 1,
            "id": "1234567",
            "title": "Example Koptelefoon",
            "brand": "ExampleBrand",
            "url": "https://www.coolblue.nl/product/1234567/example.html",
            "price": 89.95,
            "original_price": 119,
            "currency": "EUR",
            "rating": 8.5,
            "review_count": 120,
            "image": "https://media.coolblue.nl/image.jpg"
        }
    ],
    "page": 1,
    "has_more": false,
    "sort": "relevance",
    "applied_filters": {
        "query": "koptelefoons"
    },
    "unavailable_fields": [],
    "public_ids": [
        "1234567"
    ],
    "meta": {
        "endpoint_family": "coolblue-search",
        "billable": true,
        "attempts": 1,
        "credits_charged": 1
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Parameter Not Available Yet | `sort`, `page`, `min_price` and `max_price` have no verified public page recipe and return 422 before any lookup (`unsupported_filter`). Unsoaked markets return 422 (`unsupported_market`). Non-billable. |
| 422 | Validation Error | A query parameter is missing, unknown, conflicting or unusable. Unknown parameters are rejected, never ignored. Non-billable. |
| 503 | Upstream Unavailable | The storefront could not be reached, answered with a challenge, or changed its page shape (`upstream_blocked`, `upstream_unavailable`, `parser_drift`). Retryable and never billed. Clients are never rate limited. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)
