# List the category tree

`GET https://api.cream-ai.de/api/v1/categories`

Returns the categories of the company as a tree: top-level categories with their subcategories in `children`. Categories are a bounded two-level tree, so there is no paging (`has_more` is always `false`). With `external_key` only the category with this key is returned (zero or one entry, on any level). With `include=project_count` every category carries `project_count`; this loads all projects of the company and counts as a write request for the rate limits. The list is cached per company for up to 30 seconds, so changes made in mint (and on other servers) can take up to 30 seconds to appear; `project_count` values can be up to 30 seconds old.

Scopes: `categories:read`

## Parameters

- `external_key` (query): Only the category with this external key (exact match, case-sensitive).
- `include` (query): Comma-separated extras. Allowed: project_count.

## Returns

- 200: The category tree (or the category with the requested external key).

## Errors

- 400: Invalid request (invalid_request, invalid_json, invalid_cursor, idempotency_key_required, invalid_idempotency_key, parent_not_found, max_depth_exceeded, narration_too_long, user_not_in_company, template_not_found, category_not_found, feedback_kind_unsupported, upload_not_found).
- 401: Missing, malformed, revoked or expired API key (unauthorized).
- 403: Not allowed (forbidden_scope, ip_not_allowed, company_inactive, api_not_enabled).
- 429: Too many requests (rate_limited).
- 500: Internal error (internal). Quote the request id when you contact support.
- 503: Temporarily unavailable (service_unavailable). Retry later (after Retry-After seconds, if sent).

## Example request

```sh
curl "https://api.cream-ai.de/api/v1/categories" \
  -H "Authorization: Bearer $MINT_API_KEY"
```

## Example response (200)

```json
{
  "object": "list",
  "data": [
    {
      "object": "category",
      "id": "mk7t2q9x4v1n",
      "name": "Marketing",
      "parent_id": null,
      "external_key": "MKT",
      "children": [
        {
          "object": "category",
          "id": "rz3p8w1d6c0b",
          "name": "MKT101 Marketing basics",
          "parent_id": "mk7t2q9x4v1n",
          "external_key": "MKT101",
          "children": []
        }
      ]
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```