TradlyTradly Search Docs

Search API

Semantic search for product listings with hybrid search (semantic + lexical), filters, and pagination.

POST /v1/listings/search

Request Headers

HeaderRequiredDescription
tenant_idYesTenant identifier
Content-TypeYesapplication/json
X-TRADLY-SEARCH-KEYNo*Public API key (for client-side)
AuthorizationNo*Bearer <token> (for server-to-server)

*One of X-TRADLY-SEARCH-KEY or Authorization is required.

Notes

  • Semantic search: Understands intent (e.g., "snacks for kids" matches relevant products).
  • Filter format: Use field paths from your schema; they map to indexed attributes automatically.
  • Pulse filter: When pulse_filter is provided, results are scoped to the matching inventory variant and price fields in each result are overwritten with that variant's contextual pricing (branch price, promo price, etc.). Dimension keys must match your tenant's pulse_config.dimension_fields.
  • Stock filtering: Add "in_stock": true inside pulse_filter to exclude out-of-stock variants from results.

Parameters

query
string
Required
Natural language search query (e.g., 'red shoes', 'rice under 100'). Supports semantic and lexical matching.
limit
number
Maximum number of results to return per page. Defaults to 10. Maximum recommended value is 100.
page
number
Page number to retrieve (1-indexed).
filters
dictionary
Filter conditions organized into must, should, and must_not groups.
locale
string
Filter results to a specific locale (e.g., 'en', 'ar'). Defaults to null (all locales).
user_id
string
User identifier for analytics and personalization tracking. Defaults to null.
pulse_filter
dictionary
Filters results to a specific pulse inventory variant and overwrites price fields in results with that variant's contextual pricing. Keys must match the dimension_fields defined in your tenant's pulse config (e.g., branch_id, service_type, region_id).
POST/v1/listings/search
curl https://api-eu-aisearch.tradly.app/v1/listings/search \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR....." \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{"query":"red running shoes","limit":20,"page":1,"filters":{"must":[{"key":"brand.id","match":{"value":123}}],"should":[],"must_not":[]},"locale":"en","user_id":"user_123","pulse_filter":{"branch_id":"branch_A","service_type":"home_delivery","in_stock":true}}'
RESPONSE
{
  "success": true,
  "total_matching_records": 42,
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_pages": 3,
    "has_next_page": true,
    "has_previous_page": false
  },
  "execution_time_seconds": 0.125,
  "results": [
    {
      "id": "prod_123",
      "title": "Nike Air Max Red",
      "price": 129.99
    }
  ]
}