Search Items

Search for items using keyword or hybrid semantic search with advanced filtering options.

Endpoint

POST/search

Perform a search across your product catalog with support for both keyword and hybrid semantic search.

https://search-api.atriai.chat/search

Authentication

Type:

Bearer Token

Header:

Authorization

Your project-specific Bearer token for authentication

Request Parameters

The request body should contain a JSON object with the following parameters:

Request Body Parameters

search_termstringREQUIRED

The search query string to find matching items

search_typestring

Type of search to perform. 'keyword' for traditional search, 'hybrid' for semantic-keyword combination

Possible values: ["keyword", "hybrid"]

Default: "keyword"

consumer_idstring

Optional identifier for the consumer making the request. Used for analytics and tracking

Default: null

filtersstring

Filter expression to narrow down search results (e.g., 'category = Electronics')

Default: null

facetsarray[string]

List of facets to return aggregated data for (e.g., ['category', 'brand'])

Default: null

limitinteger

Maximum number of results to return

Default: null

offsetinteger

Number of results to skip for pagination

Default: null

semantic_ratiofloat

Ratio of semantic vs keyword search (0.0 = full keyword, 1.0 = full semantic). Only used when search_type is 'hybrid'

Default: 0.7

Response Schema

The API returns a JSON object with the following structure:

hitsarray[object]

Array of search results matching the query. Each hit contains the indexed document fields

querystring

The processed search query that was executed

processingTimeMsinteger

Time taken to process the search request in milliseconds

limitinteger

Maximum number of results returned (as requested)

offsetinteger

Number of results skipped (as requested)

estimatedTotalHitsinteger

Estimated total number of documents matching the search query

facetDistributionobject

Aggregated facet data (only included if facets were requested)

Response Example

Example response for a successful search request:

{
  "hits": [
    {
      "id": "prod-123",
      "title": "Gaming Laptop Pro",
      "description": "High-performance laptop perfect for gaming",
      "price": 1599.99,
      "category": "Electronics",
      "brand": "TechBrand",
      "in_stock": true,
      "rating": 4.5
    },
    {
      "id": "prod-456",
      "title": "Business Laptop Elite",
      "description": "Professional laptop for business use",
      "price": 1299.99,
      "category": "Electronics",
      "brand": "BusinessTech",
      "in_stock": true,
      "rating": 4.2
    }
  ],
  "query": "gaming laptop",
  "processingTimeMs": 45,
  "limit": 10,
  "offset": 0,
  "estimatedTotalHits": 147,
  "facetDistribution": {
    "brand": {
      "TechBrand": 89,
      "BusinessTech": 34,
      "GamerTech": 24
    },
    "category": {
      "Electronics": 147
    }
  }
}

Try it out

Select a language to see how to make a request to the AI Search API

cURL Request

curl -L 'https://search-api.atriai.chat/search' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_BEARER_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "search_term": "laptop",
    "search_type": "keyword",
    "limit": 5
  }'

Bearer Token Required

Replace YOUR_BEARER_TOKEN with your actual bearer token to authenticate requests.