> ## 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 API

> Powerful search endpoint for finding records across multiple resources with advanced filtering and faceting.

### Body

<ParamField body="query" type="string" required>
  The search query string. Supports fuzzy matching and operators
</ParamField>

<ParamField body="resources" type="array">
  Array of resource types to search. If empty, searches all resources.
  Options: \["orders", "customers", "products", "inventory", "returns", "warranties", "tickets"]
</ParamField>

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

  <Expandable title="properties">
    <ParamField body="date_range" type="object">
      Filter by date range

      <Expandable title="properties">
        <ParamField body="field" type="string">
          Date field to filter on (e.g., "created\_at", "updated\_at")
        </ParamField>

        <ParamField body="from" type="string">
          Start date (ISO 8601)
        </ParamField>

        <ParamField body="to" type="string">
          End date (ISO 8601)
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="status" type="array">
      Filter by status values
    </ParamField>

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

    <ParamField body="custom_fields" type="object">
      Filter by custom field values
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="facets" type="array">
  Fields to generate facet counts for
</ParamField>

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

  <Expandable title="properties">
    <ParamField body="field" type="string">
      Field to sort by
    </ParamField>

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

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

  <Expandable title="properties">
    <ParamField body="page" type="number">
      Page number (1-based)
    </ParamField>

    <ParamField body="per_page" type="number">
      Results per page (max 100)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="highlight" type="boolean">
  Whether to include highlighted snippets in results
</ParamField>

<ParamField body="suggest" type="boolean">
  Whether to include search suggestions for typos
</ParamField>

### Response

<ResponseField name="results" type="array">
  Array of search results

  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier of the result
    </ResponseField>

    <ResponseField name="resource_type" type="string">
      Type of resource (e.g., "order", "customer")
    </ResponseField>

    <ResponseField name="score" type="number">
      Relevance score
    </ResponseField>

    <ResponseField name="data" type="object">
      The actual resource data
    </ResponseField>

    <ResponseField name="highlights" type="object">
      Highlighted text snippets (if enabled)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="facets" type="object">
  Facet counts for requested fields
</ResponseField>

<ResponseField name="suggestions" type="array">
  Search suggestions for possible typos
</ResponseField>

<ResponseField name="total_results" type="number">
  Total number of results found
</ResponseField>

<ResponseField name="page" type="number">
  Current page number
</ResponseField>

<ResponseField name="per_page" type="number">
  Results per page
</ResponseField>

<ResponseField name="query_time_ms" type="number">
  Time taken to execute the query in milliseconds
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --location --request POST 'https://api.stateset.com/v1/search' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Token <token>' \
  --data-raw '{
      "query": "john doe refund",
      "resources": ["orders", "customers", "returns"],
      "filters": {
          "date_range": {
              "field": "created_at",
              "from": "2024-01-01",
              "to": "2024-12-31"
          },
          "status": ["active", "pending"]
      },
      "facets": ["resource_type", "status", "tags"],
      "sort": {
          "field": "created_at",
          "order": "desc"
      },
      "pagination": {
          "page": 1,
          "per_page": 20
      },
      "highlight": true,
      "suggest": true
  }'
  ```

  ```graphQL GraphQL theme={null}
  query searchQuery {
    search(
      query: "${query}",
      resources: ${resources},
      filters: ${filters},
      facets: ${facets},
      sort: ${sort},
      pagination: ${pagination},
      highlight: ${highlight},
      suggest: ${suggest}
    ) {
      results {
        id
        resource_type
        score
        data
        highlights
      }
      facets
      suggestions
      total_results
      query_time_ms
    }
  }
  ```

  ```js Node.js theme={null}
  const searchResults = await stateset.search({
    query: 'john doe refund',
    resources: ['orders', 'customers', 'returns'],
    filters: {
      date_range: {
        field: 'created_at',
        from: '2024-01-01',
        to: '2024-12-31'
      },
      status: ['active', 'pending']
    },
    facets: ['resource_type', 'status', 'tags'],
    sort: {
      field: 'created_at',
      order: 'desc'
    },
    pagination: {
      page: 1,
      per_page: 20
    },
    highlight: true,
    suggest: true
  });
  ```

  ```python Python theme={null}
  search_results = stateset.search({
    'query': 'john doe refund',
    'resources': ['orders', 'customers', 'returns'],
    'filters': {
      'date_range': {
        'field': 'created_at',
        'from': '2024-01-01',
        'to': '2024-12-31'
      },
      'status': ['active', 'pending']
    },
    'facets': ['resource_type', 'status', 'tags'],
    'sort': {
      'field': 'created_at',
      'order': 'desc'
    },
    'pagination': {
      'page': 1,
      'per_page': 20
    },
    'highlight': True,
    'suggest': True
  })
  ```

  ```ruby Ruby theme={null}
  search_results = Stateset.search({
    query: 'john doe refund',
    resources: ['orders', 'customers', 'returns'],
    filters: {
      date_range: {
        field: 'created_at',
        from: '2024-01-01',
        to: '2024-12-31'
      },
      status: ['active', 'pending']
    },
    facets: ['resource_type', 'status', 'tags'],
    sort: {
      field: 'created_at',
      order: 'desc'
    },
    pagination: {
      page: 1,
      per_page: 20
    },
    highlight: true,
    suggest: true
  })
  ```

  ```go Go theme={null}
  searchResults, err := stateset.Search(SearchParams{
    Query: "john doe refund",
    Resources: []string{"orders", "customers", "returns"},
    Filters: Filters{
      DateRange: DateRange{
        Field: "created_at",
        From: "2024-01-01",
        To: "2024-12-31"
      },
      Status: []string{"active", "pending"}
    },
    Facets: []string{"resource_type", "status", "tags"},
    Sort: Sort{
      Field: "created_at",
      Order: "desc"
    },
    Pagination: Pagination{
      Page: 1,
      PerPage: 20
    },
    Highlight: true,
    Suggest: true
  })
  ```

  ```java Java theme={null}
  SearchResults searchResults = stateset.search(new SearchParams()
    .setQuery("john doe refund")
    .setResources(Arrays.asList("orders", "customers", "returns"))
    .setFilters(new Filters()
      .setDateRange(new DateRange()
        .setField("created_at")
        .setFrom("2024-01-01")
        .setTo("2024-12-31"))
      .setStatus(Arrays.asList("active", "pending")))
    .setFacets(Arrays.asList("resource_type", "status", "tags"))
    .setSort(new Sort()
      .setField("created_at")
      .setOrder("desc"))
    .setPagination(new Pagination()
      .setPage(1)
      .setPerPage(20))
    .setHighlight(true)
    .setSuggest(true));
  ```

  ```php PHP theme={null}
  $search_results = $stateset->search([
    'query' => 'john doe refund',
    'resources' => ['orders', 'customers', 'returns'],
    'filters' => [
      'date_range' => [
        'field' => 'created_at',
        'from' => '2024-01-01',
        'to' => '2024-12-31'
      ],
      'status' => ['active', 'pending']
    ],
    'facets' => ['resource_type', 'status', 'tags'],
    'sort' => [
      'field' => 'created_at',
      'order' => 'desc'
    ],
    'pagination' => [
      'page' => 1,
      'per_page' => 20
    ],
    'highlight' => true,
    'suggest' => true
  ]);
  ```

  ```csharp C# theme={null}
  var searchResults = await stateset.Search(new SearchParams {
    Query = "john doe refund",
    Resources = new[] { "orders", "customers", "returns" },
    Filters = new Filters {
      DateRange = new DateRange {
        Field = "created_at",
        From = "2024-01-01",
        To = "2024-12-31"
      },
      Status = new[] { "active", "pending" }
    },
    Facets = new[] { "resource_type", "status", "tags" },
    Sort = new Sort {
      Field = "created_at",
      Order = "desc"
    },
    Pagination = new Pagination {
      Page = 1,
      PerPage = 20
    },
    Highlight = true,
    Suggest = true
  });
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "results": [
      {
        "id": "ord_123abc",
        "resource_type": "order",
        "score": 0.95,
        "data": {
          "id": "ord_123abc",
          "customer_name": "John Doe",
          "total": 299.99,
          "status": "pending",
          "created_at": "2024-03-15T10:30:00Z"
        },
        "highlights": {
          "customer_name": "<em>John Doe</em>",
          "notes": "Customer requested <em>refund</em> for damaged item"
        }
      },
      {
        "id": "cust_456def",
        "resource_type": "customer",
        "score": 0.88,
        "data": {
          "id": "cust_456def",
          "name": "John Doe",
          "email": "john.doe@example.com",
          "status": "active"
        },
        "highlights": {
          "name": "<em>John Doe</em>"
        }
      }
    ],
    "facets": {
      "resource_type": {
        "order": 5,
        "customer": 3,
        "return": 2
      },
      "status": {
        "active": 6,
        "pending": 4
      },
      "tags": {
        "vip": 2,
        "priority": 3
      }
    },
    "suggestions": [
      {
        "text": "john doe refunded",
        "score": 0.92
      }
    ],
    "total_results": 10,
    "page": 1,
    "per_page": 20,
    "query_time_ms": 23
  }
  ```

  ```json Error Response theme={null}
  {
    "error": {
      "code": "invalid_query",
      "message": "Search query cannot be empty",
      "details": {
        "min_query_length": 1,
        "max_query_length": 1000
      }
    }
  }
  ```
</ResponseExample>