Search Products

Advanced product search with full-text search, filters, and faceted results

POST /v1/products/search

cURL

curl --location --request POST 'https://api.stateset.com/v1/products/search' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "query": "wireless headphones",
    "filters": {
        "categories": ["Electronics"],
        "price_range": {
            "min": 5000,
            "max": 20000
        },
        "in_stock": true
    },
    "sort": {
        "field": "relevance",
        "order": "desc"
    },
    "pagination": {
        "limit": 10,
        "offset": 0
    }
}'

Response

{
  "results": [
    {
      "id": "prod_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
      "name": "Wireless Bluetooth Headphones",
      "sku": "WBH-001",
      "description": "Premium noise-cancelling wireless headphones with 30-hour battery life",
      "category": "Electronics",
      "brand": "AudioTech",
      "price": {
        "amount": 14999,
        "currency": "USD"
      },
      "relevance_score": 0.98,
      "inventory_summary": {
        "available": true,
        "quantity": 145
      }
    },
    {
      "id": "prod_abc123def456",
      "name": "Sport Wireless Earbuds",
      "sku": "SWE-001",
      "description": "Waterproof wireless earbuds perfect for workouts",
      "category": "Electronics",
      "brand": "FitAudio",
      "price": {
        "amount": 7999,
        "currency": "USD"
      },
      "relevance_score": 0.85,
      "inventory_summary": {
        "available": true,
        "quantity": 230
      }
    }
  ],
  "total_count": 15,
  "facets": {
    "categories": [
      {
        "value": "Electronics",
        "count": 15
      }
    ],
    "brands": [
      {
        "value": "AudioTech",
        "count": 5
      },
      {
        "value": "FitAudio",
        "count": 3
      },
      {
        "value": "SoundMax",
        "count": 4
      },
      {
        "value": "TechConnect",
        "count": 3
      }
    ],
    "price_ranges": [
      {
        "range": "50-100",
        "count": 3
      },
      {
        "range": "100-150",
        "count": 8
      },
      {
        "range": "150-200",
        "count": 4
      }
    ],
    "tags": [
      {
        "value": "wireless",
        "count": 15
      },
      {
        "value": "bluetooth",
        "count": 12
      },
      {
        "value": "noise-cancelling",
        "count": 6
      }
    ]
  }
}

This endpoint provides powerful search capabilities including fuzzy matching, relevance scoring, and aggregated facets for building filter UIs.

Request Body

query · string

Search query for full-text search across product names, descriptions, and SKUs

filters · object

Additional filters to narrow results

Show Filter options

categories · array

Filter by one or more categories

brands · array

Filter by one or more brands

price_range · object

Price range filter

Show Price range properties

min · integer

Minimum price in cents

max · integer

Maximum price in cents

in_stock · boolean

Only show products with available inventory

tags · array

Filter by product tags

status · string

Filter by status: “active”, “draft”, or “archived”

sort · object

Sort options

Show Sort properties

field · string

Sort field: “relevance”, “price”, “name”, “created_at”, “popularity”

order · string

Sort order: “asc” or “desc”

pagination · object

Pagination options

Show Pagination properties

limit · integer

Number of results (default: 20, max: 100)

offset · integer

Number of results to skip

include_facets · boolean

Include aggregated facets for building filter UIs (default: true)

Response

results · array

Array of matching products with relevance scores

total_count · integer

Total number of matching products

facets · object

Aggregated data for building filter UIs

Show Facet properties

categories · array

Category counts

brands · array

Brand counts

price_ranges · array

Price range distributions

tags · array

Tag counts

cURL

curl --location --request POST 'https://api.stateset.com/v1/products/search' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "query": "wireless headphones",
    "filters": {
        "categories": ["Electronics"],
        "price_range": {
            "min": 5000,
            "max": 20000
        },
        "in_stock": true
    },
    "sort": {
        "field": "relevance",
        "order": "desc"
    },
    "pagination": {
        "limit": 10,
        "offset": 0
    }
}'

Response

{
  "results": [
    {
      "id": "prod_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
      "name": "Wireless Bluetooth Headphones",
      "sku": "WBH-001",
      "description": "Premium noise-cancelling wireless headphones with 30-hour battery life",
      "category": "Electronics",
      "brand": "AudioTech",
      "price": {
        "amount": 14999,
        "currency": "USD"
      },
      "relevance_score": 0.98,
      "inventory_summary": {
        "available": true,
        "quantity": 145
      }
    },
    {
      "id": "prod_abc123def456",
      "name": "Sport Wireless Earbuds",
      "sku": "SWE-001",
      "description": "Waterproof wireless earbuds perfect for workouts",
      "category": "Electronics",
      "brand": "FitAudio",
      "price": {
        "amount": 7999,
        "currency": "USD"
      },
      "relevance_score": 0.85,
      "inventory_summary": {
        "available": true,
        "quantity": 230
      }
    }
  ],
  "total_count": 15,
  "facets": {
    "categories": [
      {
        "value": "Electronics",
        "count": 15
      }
    ],
    "brands": [
      {
        "value": "AudioTech",
        "count": 5
      },
      {
        "value": "FitAudio",
        "count": 3
      },
      {
        "value": "SoundMax",
        "count": 4
      },
      {
        "value": "TechConnect",
        "count": 3
      }
    ],
    "price_ranges": [
      {
        "range": "50-100",
        "count": 3
      },
      {
        "range": "100-150",
        "count": 8
      },
      {
        "range": "150-200",
        "count": 4
      }
    ],
    "tags": [
      {
        "value": "wireless",
        "count": 15
      },
      {
        "value": "bluetooth",
        "count": 12
      },
      {
        "value": "noise-cancelling",
        "count": 6
      }
    ]
  }
}