List Records

get/v1/records/{root}

The RESTful GET counterpart to POST /v1/records/query. Lists records of the given root under workspace row-level security, with the same query engine and response shape. Omit `fields` to project every top-level column. Use `sort` (`-field` for descending), `where` (a JSON Hasura whereClause, URL-encoded) for filtering, and `cursor`/`limit` for keyset pagination.

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

Path parameters

Name	Type	Required	Description
root	string	Yes	The record root to list (e.g. companies, invoices, transactions). One of the 32 read-only roots.e.g. companies

Query parameters

Name	Type	Required	Description
fields	string	No	Comma-separated dot paths to project, e.g. `companies.registered_name,companies.domain`. Defaults to every top-level column of the root.e.g. companies.registered_name,companies.domain
sort	string	No	Sort field; prefix with `-` for descending, e.g. `-created_at`.e.g. -created_at
limit	integer	No	Page size, 1..500 (default 20).e.g. 25
cursor	string	No	Keyset pagination cursor from a prior page (nextCursor).e.g. eyJjcmVhdGVkX2F0IjoiMjAyNi0wMS0wMVQwMDowMDowMFoiLCJpZCI6IjEyMyJ9
where	string	No	A JSON Hasura whereClause (URL-encoded), passed through unchanged, e.g. `{"status":{"_eq":"open"}}`. Workspace RLS is still enforced.e.g. {"status":{"_eq":"open"}}
workspaceId	string <uuid>	No	Target workspace (defaults to the caller scope).e.g. 0b5f691a-c870-4762-ad50-2c34e0d1f826

Request

cURL

curl -X GET https://api.wellapp.ai/v1/records/{root} \
  -H "Authorization: Bearer $WELL_API_TOKEN"

Responses

200 — The query result: flattened rows, pagination meta, and per-column metadata.

{
  "data": [
    {
      "transactions.transaction_id": "f0e1d2c3-0000-4000-8000-0000000000a1",
      "transactions.status": "booked",
      "transactions.instructed_amount": {
        "amount": 4820.5,
        "currency": "USD"
      }
    }
  ],
  "meta": {
    "total": 318,
    "count": 1,
    "nextCursor": "eyJwayI6OTAxfQ"
  },
  "columns": [
    {
      "key": "transactions.transaction_id",
      "meta": {
        "displayType": "uuid",
        "isEditable": false
      }
    },
    {
      "key": "transactions.status",
      "meta": {
        "displayType": "string",
        "isEditable": false
      }
    },
    {
      "key": "transactions.instructed_amount",
      "meta": {
        "displayType": "amount",
        "isEditable": false
      }
    }
  ]
}

401 — Unauthorized

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