# Worten Product Search API Documentation

`GET /api/worten/search` returns Worten Portugal products as structured JSON. One page holds 24 or 48 products.

## What you get

Each item has `id`, `sku`, `ean`, `title`, `brand`, `price`, `original_price`, `discount_percent`, `currency`, `rating`, `review_count`, `in_stock`, `seller_id`, `shipping` and a full-size `image`. Use `id` unchanged with the product, specifications and variants endpoints. `facets[]` lists the public filter slugs and their option values.

## Parameters and filters

`page` is 1-based. `page_size` accepts only 24 and 48; any other value returns 422. `sort` is `relevance`, `rating_bazaar`, `purchases`, `relative_striked_price` or `price`, with `order` `ASC` or `DESC`.

`category` takes a public `_cc1` facet value such as `CMS-01G2YYDYYVP212M9N4DGER68ZK`. `min_price` and `max_price` are EUR bounds; both are required and together build one `price` filter. A single bound returns 422. A named parameter replaces a raw filter for the same slug. `filters` is a JSON array of `{"key":<facet-slug>,"value":[...]}` objects for every other facet. Only slugs published by the storefront are accepted. Bad JSON, an unknown slug or an empty value array returns 422 before any lookup. If the upstream cannot apply a filter, the route returns 422 and bills nothing. A page is never mislabelled.

## Credits

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

- **Documentation:** [https://scrappa.co/docs/worten-api/worten_search](https://scrappa.co/docs/worten-api/worten_search)
- **API group:** Worten API
- **Endpoint:** `GET https://scrappa.co/api/worten/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 |
| --- | --- | --- | --- |
| `query` | string | Yes | Search words. |
| `category` | string | No | Public _cc1 facet value such as CMS-01G2YYDYYVP212M9N4DGER68ZK. |
| `min_price` | number | No | Lowest EUR price. Use with max_price. |
| `max_price` | number | No | Highest EUR price. Use with min_price. |
| `page` | integer | No | Result page, 1-based. |
| `page_size` | integer | No | Hits per page. Only 24 and 48 are accepted. |
| `sort` | string | No | relevance, rating_bazaar, purchases, relative_striked_price or price. |
| `order` | string | No | ASC or DESC. |
| `filters` | string | No | JSON array of facet filters, for example [{"key":"brand_name","value":["APPLE"]}]. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/worten/search?query=iphone&page_size=24"
```

## Example response

```json
{
    "success": true,
    "site": "pt",
    "query": "iphone",
    "items": [
        {
            "position": 1,
            "id": "ffffffff-0000-4000-a000-000077b0f986",
            "sku": "8600340",
            "ean": [
                "5601234567890"
            ],
            "title": "Example iPhone",
            "brand": "APPLE",
            "price": 899,
            "original_price": 999,
            "discount_percent": 10,
            "currency": "EUR",
            "rating": 4.5,
            "review_count": 120,
            "in_stock": true,
            "seller_id": "worten",
            "shipping": {
                "price": 0
            },
            "image": "https://www.worten.pt/i/example.jpg"
        }
    ],
    "page": 1,
    "page_size": 24,
    "total_hits": 15311,
    "next_page": 2,
    "has_more": true,
    "sort": "relevance",
    "order": "ASC",
    "applied_filters": [],
    "facets": [],
    "filter_errors": [],
    "meta": {
        "endpoint_family": "worten-search",
        "billable": true,
        "attempts": 1,
        "credits_charged": 1
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 404 | Not Found | The storefront has no product with that id (`not_found`). Non-billable. |
| 422 | Validation Error | A parameter is missing or unsupported. Only page sizes 24 and 48 are accepted, and filters use facet slugs from the search result. Non-billable. |
| 503 | Upstream Unavailable | The storefront could not be reached, answered with a challenge, or changed its response shape. 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)
