# Ricardo Categories API Documentation

<p><strong>Ricardo Categories API Documentation</strong> Retrieve the Ricardo.ch category tree as a flat list: category id, name, tree level (1 is top level), leaf flag and parent id. Filter by parent category or level. Use the ids with the search and category endpoints. The tree changes rarely and is cached for 24 hours.</p>

- **Documentation:** [https://scrappa.co/docs/ricardo-api/ricardo_categories](https://scrappa.co/docs/ricardo-api/ricardo_categories)
- **API group:** Ricardo API
- **Endpoint:** `GET https://scrappa.co/api/ricardo/categories`

## 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 |
| --- | --- | --- | --- |
| `parent_id` | string | No | Return only the direct children of this category number, e.g. 41950. Omit to return the full tree as a flat list. |
| `level` | integer | No | Return only categories of this tree level, 1 (top level) to 6. |
| `language` | string | No | Language of labels and the listing url: de or fr. Defaults to de. |

## Example response

```json
{
    "data": {
        "total": 28,
        "categories": [
            {
                "name": "Antiquit\u00e4ten & Kunst",
                "level": 1,
                "is_leaf": false,
                "category_id": "38399"
            },
            {
                "name": "Briefmarken",
                "level": 1,
                "is_leaf": false,
                "category_id": "38766"
            },
            {
                "name": "B\u00fccher & Comics",
                "level": 1,
                "is_leaf": false,
                "category_id": "38889"
            }
        ]
    },
    "meta": {
        "billable": true,
        "endpoint_family": "categories"
    },
    "success": true
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | The parent_id is not a category number, or the level or language is out of range. This response is not billable. |
| 404 | Resource Not Found | The parent_id does not exist in the category tree. This response is not billable. |
| 503 | Invalid Source Response | Ricardo answered with a response Scrappa could not read. This response is not billable. |
| 503 | Service Unavailable | The upstream service is temporarily unavailable. Please retry shortly. |

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