# impartire API — Reference: Categories

Every path is under `https://impartire.com/api/v1`. The machine-readable contract is https://impartire.com/api/v1/openapi.json (OpenAPI 3.1).

#### GET /api/v1/categories

List the org's asset categories

The org's category taxonomy for assets — categories whose group is for assets or for every kind of thing — each with its group, by group (as the app orders them) then name. Returned whole, at most 1000. Use an id with `GET /assets?category_id=`. Read only: the taxonomy is managed in the app. For an OAuth token, empty unless its person is a member of the org. 404 when the org does not have categories.

Scopes: `taxonomy:read`

Response 200 — `CategoryList`

- `data` (array of Category, required) — By group (its order in the app, then name), then name. Returned whole, at most 1000.
  - `group` (object, required) — The category group (a facet: Genre, Territory…).
    - `id` (string (uuid), required)
    - `name` (string, required)
  - `id` (string (uuid), required)
  - `name` (string, required)
  - `description` (string or null, required)
  - `parent_id` (string (uuid) or null, required) — The category this one sits under (one level deep at most), or null.
  - `is_system` (boolean, required) — A category the platform seeded; it cannot be deleted in the app.
- `next_cursor` (string or null, required) — Always null: the list is returned whole.

Other responses:

- 401 (Problem) — unauthenticated — no key, or an unknown, revoked or expired one.
- 403 (Problem) — insufficient-scope — the key lacks a required scope.
- 404 (Problem) — not-found.
- 429 (Problem) — rate-limited — the key's request budget is spent; wait Retry-After seconds.
- 500 (Problem) — internal.