> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Products

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

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

### Request Body

<ParamField body="query" type="string">
  Search query for full-text search across product names, descriptions, and SKUs
</ParamField>

<ParamField body="filters" type="object">
  Additional filters to narrow results

  <Expandable title="Filter options">
    <ParamField body="categories" type="array">
      Filter by one or more categories
    </ParamField>

    <ParamField body="brands" type="array">
      Filter by one or more brands
    </ParamField>

    <ParamField body="price_range" type="object">
      Price range filter

      <Expandable title="Price range properties">
        <ParamField body="min" type="integer">
          Minimum price in cents
        </ParamField>

        <ParamField body="max" type="integer">
          Maximum price in cents
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="in_stock" type="boolean">
      Only show products with available inventory
    </ParamField>

    <ParamField body="tags" type="array">
      Filter by product tags
    </ParamField>

    <ParamField body="status" type="string">
      Filter by status: "active", "draft", or "archived"
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="sort" type="object">
  Sort options

  <Expandable title="Sort properties">
    <ParamField body="field" type="string">
      Sort field: "relevance", "price", "name", "created\_at", "popularity"
    </ParamField>

    <ParamField body="order" type="string">
      Sort order: "asc" or "desc"
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="pagination" type="object">
  Pagination options

  <Expandable title="Pagination properties">
    <ParamField body="limit" type="integer">
      Number of results (default: 20, max: 100)
    </ParamField>

    <ParamField body="offset" type="integer">
      Number of results to skip
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="include_facets" type="boolean">
  Include aggregated facets for building filter UIs (default: true)
</ParamField>

### Response

<ResponseField name="results" type="array">
  Array of matching products with relevance scores
</ResponseField>

<ResponseField name="total_count" type="integer">
  Total number of matching products
</ResponseField>

<ResponseField name="facets" type="object">
  Aggregated data for building filter UIs

  <Expandable title="Facet properties">
    <ResponseField name="categories" type="array">
      Category counts
    </ResponseField>

    <ResponseField name="brands" type="array">
      Brand counts
    </ResponseField>

    <ResponseField name="price_ranges" type="array">
      Price range distributions
    </ResponseField>

    <ResponseField name="tags" type="array">
      Tag counts
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  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
      }
  }'
  ```

  ```graphQL GraphQL theme={null}
  mutation SearchProducts($input: SearchProductsInput!) {
    searchProducts(input: $input) {
      results {
        id
        name
        sku
        description
        category
        brand
        price {
          amount
          currency
        }
        relevance_score
      }
      total_count
      facets {
        categories {
          value
          count
        }
        brands {
          value
          count
        }
      }
    }
  }
  ```

  ```javascript Node.js theme={null}
  const searchResults = await stateset.products.search({
    query: "wireless headphones",
    filters: {
      categories: ["Electronics"],
      price_range: {
        min: 5000,
        max: 20000
      },
      in_stock: true
    },
    sort: {
      field: "relevance",
      order: "desc"
    }
  });
  ```

  ```python Python theme={null}
  search_results = stateset.products.search({
      "query": "wireless headphones",
      "filters": {
          "categories": ["Electronics"],
          "price_range": {
              "min": 5000,
              "max": 20000
          },
          "in_stock": True
      },
      "sort": {
          "field": "relevance",
          "order": "desc"
      }
  })
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "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
        }
      ]
    }
  }
  ```
</ResponseExample>