Query Records

post/v1/records/query

Runs an ad-hoc, workspace-scoped query against a records root, selecting fields by dot path with optional filtering, sorting, and cursor pagination. This is the engine behind the records tables and powers flexible reads across the financial graph. Read only, no side effects. Each field is an array path (e.g. ["transactions","instructed_amount"]) and at least one path of depth two is required.

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

Request

cURL

curl -X POST https://api.wellapp.ai/v1/records/query \
  -H "Authorization: Bearer $WELL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "root": "transactions",
  "fields": [
    [
      "transactions",
      "transaction_id"
    ],
    [
      "transactions",
      "status"
    ],
    [
      "transactions",
      "instructed_amount"
    ]
  ],
  "limit": 2,
  "orderBy": {
    "field": "created_at",
    "direction": "desc"
  }
}'

Request body

{
  "root": "transactions",
  "fields": [
    [
      "transactions",
      "transaction_id"
    ],
    [
      "transactions",
      "status"
    ],
    [
      "transactions",
      "instructed_amount"
    ]
  ],
  "limit": 2,
  "orderBy": {
    "field": "created_at",
    "direction": "desc"
  }
}

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
      }
    }
  ]
}

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"
  }
}