Search & metadata

Search via DB

Filter a collection with a JSON query against the database.

POST/{collection}/filter

The Filter API lets you retrieve records from any collection using server-side filters with a clean JSON interface. Use it when you need precise, composable queries without the overhead of Typesense.

Authorization

If set, the API uses an API key for authentication. Include the following header in your requests: X-blnk-key: <api-key>.

Replace <api-key> with your secret API key. Ensure the key is kept secure and not exposed in public repositories or client-side code.

Path

collectionstringrequiredpath

The collection to filter. Supported values:

ledgers - Filter ledgers by name or metadata
balances - Filter balance records across all ledgers
transactions - Filter transaction records
identities - Filter customer identity records

Body

filtersarrayrequiredbody

Array of filter objects. Each object has field, operator, and optionally value or values. Learn more: Search via DB docs

Examples:

[{"field": "status", "operator": "eq", "value": "APPLIED"}] - Exact match
[{"field": "currency", "operator": "in", "values": ["USD", "EUR"]}] - Multiple values

logical_operatorstringbody

Combines multiple filters with and or or. Default: and.

sort_bystringbody

Field to sort by. Only indexed fields are sortable. Default: created_at. Learn more: Performance Tuning

sort_orderstringbody

Sort direction: asc or desc. Default: desc.

include_countbooleanbody

Include total count in response. May impact performance on large datasets. Default: false.

limitintegerbody

Max records to return. Default: 20, max: 100.

offsetintegerbody

Records to skip for pagination. Default: 0.

Response

dataarray

Array of matching records. Structure varies by collection type (ledger, balance, transaction, or identity).

total_countinteger

Total number of matching records. Only present when include_count is true.

curl -X POST "http://localhost:5001/transactions/filter" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      { "field": "status", "operator": "eq", "value": "APPLIED" },
      { "field": "currency", "operator": "in", "values": ["USD", "EUR"] }
    ],
    "logical_operator": "and",
    "sort_by": "created_at",
    "sort_order": "desc",
    "include_count": true,
    "limit": 20,
    "offset": 0
  }'

{
  "data": [
    {
      "transaction_id": "txn_6164573b-6cc8-45a4-ad2e-7b4ba6a60f7d",
      "amount": 15000,
      "currency": "USD",
      "status": "APPLIED",
      "source": "bln_28edb3e5-c168-4127-a1c4-16274e7a28d3",
      "destination": "bln_ebcd230f-6265-4d4a-a4ca-45974c47f746",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total_count": 150
}

{
  "error": "Invalid filter: invalid operator 'resembles' for field 'amount': must be one of eq, ne, gt, gte, lt, lte, in, between, like, ilike, isnull, isnotnull",
  "error_detail": {
    "code": "GEN_BAD_REQUEST",
    "message": "Invalid filter: invalid operator 'resembles' for field 'amount': must be one of eq, ne, gt, gte, lt, lte, in, between, like, ilike, isnull, isnotnull"
  }
}