List Categories

get/v1/categories

Returns a cursor-paginated list of categories for the active workspace. Read only, no side effects. Results are scoped by workspace via row-level security; for example a transaction category for cloud spend. Attributes mirror the records field set for this root. ## Filtering & sorting Filter via `POST /v1/records/query` (root `categories`) or the `filters` model; operators are gated by each field's data type. See [Filtering & sorting](../filtering-and-sorting). **Filterable fields** | Field | Type | Allowed operators | |---|---|---| | `category_id` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `category_type` | enum | `eq` `neq` `in` `is_null` `is_not_null` | | `composite_category_summary` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_companies_list` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `created_at` | date | `eq` `lt` `gt` `is_null` `is_not_null` | | `deleted_at` | date | `eq` `lt` `gt` `is_null` `is_not_null` | | `name` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `pk` | number | `eq` `neq` `gt` `gte` `lt` `lte` `is_null` `is_not_null` | | `updated_at` | date | `eq` `lt` `gt` `is_null` `is_not_null` | **Sortable fields:** `category_id`, `category_type`, `composite_category_summary`, `composite_companies_list`, `created_at`, `deleted_at`, `name`, `pk`, `updated_at` (via `orderBy` / `sort`, `asc`|`desc`).

Requires a bearer token: Authorization: Bearer <token>.

Query parameters

Name	Type	Required	Description
cursor	string	No	Opaque pagination cursor returned as links.next on the previous page. Omit to fetch the first page.e.g. eyJwayI6MTI4N30
limit	integer	No	Maximum number of records to return per page (1 to 200, defaults to 50).e.g. 50
orderBy	string	No	Field to sort by, using the records dot path or column name (e.g. created_at).e.g. created_at
direction	string	No	Sort direction for orderBy. Defaults to desc.e.g. desc
workspaceId	string <uuid>	No	Explicit workspace scope. The authenticated user must hold an active membership in this workspace. Defaults to the session workspace when omitted.e.g. a1b2c3d4-0000-4000-8000-000000000001

Request

cURL

curl -X GET https://api.wellapp.ai/v1/categories \
  -H "Authorization: Bearer $WELL_API_TOKEN"

Responses

200 — A page of categories.

{
  "data": [
    {
      "type": "category",
      "id": "f2a3b4c5-0000-4000-8000-0000000000ac",
      "attributes": {
        "category_id": "f2a3b4c5-0000-4000-8000-0000000000ac",
        "name": "Cloud and AI infrastructure",
        "category_type": "transaction",
        "created_at": "2026-01-12T18:08:00Z",
        "updated_at": "2026-01-12T18:08:00Z",
        "deleted_at": null
      }
    }
  ],
  "meta": {
    "total": 1,
    "count": 1
  },
  "links": {
    "next": null
  }
}

400 — Bad request

{
  "code": "BAD_REQUEST",
  "status": 400,
  "title": "Bad Request",
  "message": "See title.",
  "meta": {
    "trace_id": "a1b2c3",
    "log_id": "a1b2c3"
  }
}

401 — Unauthorized

{
  "code": "UNAUTHORIZED",
  "status": 401,
  "title": "Unauthorized",
  "message": "See title.",
  "meta": {
    "trace_id": "a1b2c3",
    "log_id": "a1b2c3"
  }
}