Skip to main content

​
Endpoint

POST /search/:collection
Searches for documents in a specific Blnk collection using Typesense full-text search capabilities. This endpoint provides powerful search features including filtering, sorting, and faceting.

​
Path Parameters

​
collection
string
required
The collection to search. Supported values:
  • ledgers: Search ledgers
  • balances: Search balances
  • transactions: Search transactions
  • identities: Search identities
  • reconciliations: Search reconciliations

​
Request Body

The request body accepts Typesense search parameters.
​
q
string
required
The search query. Use * to match all documents
​
query_by
string
Comma-separated list of fields to search in. If not specified, searches all text fieldsExamples:
  • For transactions: "reference,description"
  • For identities: "first_name,last_name,email_address"
  • For balances: "balance_id,currency"
​
filter_by
string
Filter conditions to narrow down results. Use Typesense filter syntaxExamples:
  • "currency:USD"
  • "status:completed && amount:>100"
  • "created_at:>1704067200"
​
sort_by
string
Field(s) to sort by. Prefix with - for descending orderExamples:
  • "created_at:desc"
  • "amount:asc"
​
per_page
integer
default:"10"
Number of results per page (max 250)
​
page
integer
default:"1"
Page number to retrieve
​
facet_by
string
Comma-separated list of fields to facet byExample: "currency,status"

​
Response

​
found
integer
Total number of documents matching the search
​
hits
array
Array of search results
​
facet_counts
array
Facet counts for the requested facet fields
​
page
integer
Current page number
​
out_of
integer
Total number of pages

​
Example Requests

​
Search Transactions by Reference

{
  "q": "INV-2024",
  "query_by": "reference,description",
  "filter_by": "status:completed",
  "sort_by": "created_at:desc",
  "per_page": 20,
  "page": 1
}

​
Search USD Balances

{
  "q": "*",
  "filter_by": "currency:USD",
  "sort_by": "balance:desc",
  "per_page": 50
}

​
Search Identities by Email

{
  "q": "[email protected]",
  "query_by": "email_address,first_name,last_name",
  "per_page": 10
}

​
Search with Faceting

{
  "q": "*",
  "query_by": "currency",
  "facet_by": "currency,status",
  "per_page": 100
}

​
Example Response

{
  "found": 142,
  "hits": [
    {
      "document": {
        "transaction_id": "txn_123abc",
        "amount": 100.50,
        "currency": "USD",
        "reference": "INV-2024-001",
        "description": "Payment for invoice",
        "status": "completed",
        "created_at": 1709553600
      },
      "highlights": [
        {
          "field": "reference",
          "snippet": "<mark>INV-2024</mark>-001"
        }
      ]
    }
  ],
  "facet_counts": [
    {
      "field_name": "status",
      "counts": [
        {"value": "completed", "count": 120},
        {"value": "pending", "count": 22}
      ]
    }
  ],
  "page": 1,
  "out_of": 8
}

​
Advanced Filtering

​
Numeric Filters

{
  "q": "*",
  "filter_by": "amount:>100 && amount:<1000"
}

​
Date Range Filters

{
  "q": "*",
  "filter_by": "created_at:>1704067200 && created_at:<1709553600"
}

​
Multiple Conditions

{
  "q": "*",
  "filter_by": "currency:USD && status:completed && amount:>500"
}

​
Error Responses

​
error
string
Error message describing what went wrong

​
Common Errors

  • 400 Bad Request: Invalid collection name or search parameters
  • 500 Internal Server Error: Search service error

​
Performance Tips

  1. Use specific query_by fields: Searching specific fields is faster than searching all fields
  2. Apply filters: Use filter_by to narrow results before searching
  3. Limit results: Use appropriate per_page values (smaller is faster)
  4. Leverage facets: Use faceting to understand data distribution before refining searches

Build docs developers (and LLMs) love

Get started for freeTalk to us