# tutti.ch Search API Documentation

Search public tutti.ch classified ads. Filter by keyword, category id, canton code or locality id and a price range in CHF, and page with the opaque cursor. Each ad carries the id, title, integer CHF price (when priced) and price label, publish time (ISO 8601, UTC), category, location with canton, thumbnail, images and the seller alias. Pages hold 30 ads. A valid empty result is a successful response; an upstream failure is not billed.

- **Documentation:** [https://scrappa.co/docs/tutti-api/tutti_search](https://scrappa.co/docs/tutti-api/tutti_search)
- **API group:** tutti.ch API
- **Endpoint:** `GET https://scrappa.co/api/tutti/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 | No | Search keywords, up to 200 characters. At least one of query, category, canton or locality is required. Example: velo. |
| `category` | string | No | Category id from /api/tutti/categories, root or sub category. Example: bicycles. |
| `canton` | string | No | Two-letter canton code: ZH, BE, LU, UR, SZ, OW, NW, GL, ZG, FR, SO, BS, BL, SH, AR, AI, SG, GR, AG, TG, TI, VD, VS, NE, GE or JU. Example: BE. |
| `locality` | string | No | Up to 5 comma-separated locality ids from /api/tutti/locations. Not combinable with canton. Example: geo-city-zurich. |
| `price_min` | integer | No | Minimum price in CHF, 0 to 10000000. |
| `price_max` | integer | No | Maximum price in CHF, 0 to 10000000, not below price_min. |
| `direction` | string | No | desc for newest first (default) or asc for oldest first. |
| `cursor` | string | No | The next_cursor value of the previous response to load the next 30 ads. |
| `language` | string | No | Label language: de (default), fr or it. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/tutti/search?query=velo&category=bicycles&canton=BE&price_min=100&price_max=500"
```

## Example response

```json
{
    "success": true,
    "data": {
        "total": 827,
        "listings": [
            {
                "id": "83552223",
                "title": "Woom 3 16 Zoll",
                "price": 325,
                "price_label": "325.-",
                "published_at": "2026-10-15T18:52:49Z",
                "category": {
                    "id": "bicycles",
                    "label": "Velos"
                },
                "location": {
                    "postcode": "3250",
                    "name": "Lyss",
                    "canton": {
                        "code": "BE",
                        "name": "Bern"
                    }
                },
                "thumbnail": "https://c.tutti.ch/big/2279645995.jpg",
                "images": [
                    "https://c.tutti.ch/big/2279645995.jpg"
                ]
            }
        ],
        "has_more": true,
        "next_cursor": "eyJ0IjoxNzkyMDkyOTA2LCJjdiI6ODYyODY4MTYzLCJvIjozMCwic20iOjAsInNhIjpmYWxzZX0="
    },
    "meta": {
        "endpoint_family": "search",
        "billable": true
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | No filter was given, or a canton, locality, price, direction or cursor value is invalid. This response is not billable. |
| 422 | Invalid Category or Cursor | The category id is not in the category tree or the cursor is not a next_cursor of tutti.ch. This response is not billable. |
| 502 | Unexpected Upstream Response | tutti.ch answered with an error or an unexpected shape. This response is not billable; retry later. |
| 503 | Upstream Unavailable | tutti.ch is temporarily unreachable or blocked the request. This response is not billable; retry later. |

## 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)