> For the complete documentation index, see [llms.txt](https://fredhopper.gitbook.io/product-discovery/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://fredhopper.gitbook.io/product-discovery/resources/archived-pages/introduction/api/search-api.md).

# Search API

## Search

<mark style="color:green;">`POST`</mark> `https://api-eu.attraqt.io/search`

Search for items using the XO Search engine.

#### Request Body

| Name                       | Type    | Description                                                                                                                                                                                                                                                                                                                                                          |
| -------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| token                      | string  | XO Search token (can be found in the XO Console)                                                                                                                                                                                                                                                                                                                     |
| query                      | string  | The query string used for the search                                                                                                                                                                                                                                                                                                                                 |
| options.offset             | integer | <p><strong>Pagination:</strong></p><p>\</p></p><p>If specified, only fetch results starting from this offset. It should be a multiple of</p><p><strong><code>limit</code></strong></p><p>parameter.</p><p>\</p></p><p><em>Defaults to 0.</em></p><p>\</p></p><p>Check</p><p><em>Pagination</em></p><p>page for more info.</p>                                        |
| options.limit              | integer | <p><strong>Pagination:</strong></p><p>\</p></p><p>If specified, fetch the specified number of results per page. Should be used in conjunction with</p><p><strong><code>offset</code></strong></p><p>.</p><p>\</p></p><p><em>Defaults to 10.</em></p><p>\</p></p><p>Check</p><p><em>Pagination</em></p><p>page for more info.</p>                                     |
| options.sortBy             | array   | <p><strong>Sorting:</strong></p><p>\</p></p><p>Sort the results using the specified sort options.</p><p>\</p></p><p><em>Defaults to an empty array (no sort applied, ie. results are sorted by relevancy).</em></p><p>\</p></p><p>Check</p><p><em>Sorting</em></p><p>page for more info about the</p><p><strong><code>sortBy</code></strong></p><p>array format.</p> |
| options.facets             | array   | <p><strong>Faceting:</strong></p><p>\</p></p><p>Filters the results that match the provided facets names and values.</p><p>\</p></p><p><em>Defaults to an empty array (no filter applied).</em></p><p>\</p></p><p>Check</p><p><em>Faceting</em></p><p>page for more info about the</p><p><strong><code>facets</code></strong></p><p>array format.</p>                |
| options.filter             | string  | <p><strong>Filtering:</strong></p><p>\</p></p><p>Filters the results based on the filter query (SQL-like syntax).</p><p>\</p></p><p><em>Defaults to an empty array (no filter applied).</em></p><p>\</p></p><p>Check</p><p><em>Filtering</em></p><p>page for more info about the</p><p><strong><code>filter</code></strong></p><p>string format.</p>                 |
| options.customResponseMask | string  | <p><strong>Attributes to retrieve:</strong></p><p>\</p></p><p>If specified, you have the control which attributes to retrieve and which not to retrieve.</p>                                                                                                                                                                                                         |
| options.disable            | array   | <p><strong>Disable features:</strong></p><p>\</p></p><p>If specified, disable features from the query.</p><p>\</p></p><p>Check</p><p><em>Disable features</em></p><p>page for more info about the</p><p><strong><code>disable</code></strong></p><p>array format.</p>                                                                                                |

#### Example search request

The following sample request includes all possible parameters you can use

```http
POST https://api-eu.attraqt.io/search HTTP/1.1
Content-Type: application/json; charset=UTF-8

{
  "token": "SEARCH_API_TOKEN",
  "query": "T-Shirt",
  "options": {
    "offset": 40,
    "limit": 20,
    "sortBy": [
      {
        "attribute": "price",
        "order": "asc"
      }
    ],
    "facets": [
      {
        "id": "color",
        "values": ["red"]
      }
    ],
    "filter": "price < 100",
    "customResponseMask": "id, product(title, price, photo)",
    "disable": [{ "name": "facet" }]
  }
}
```

## Search

<mark style="color:blue;">`GET`</mark> `https://api-eu.attraqt.io/search/:token`

Same as the

**POST**

method. The

**`token`**

must be specified in the

*URL*

path. Other parameters should be url-encoded and send as a single query parameter.

#### Path Parameters

| Name  | Type   | Description                                      |
| ----- | ------ | ------------------------------------------------ |
| token | string | XO Search token (can be found in the XO Console) |

#### Query Parameters

| Name    | Type   | Description                                                                                                                                      |
| ------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| encoded | string | <p>Every other parameters (as specified in the</p><p><strong>POST</strong></p><p>method), as a</p><p><em>URL-encoded JSON</em></p><p>object.</p> |

## Response

The search response contains two parts:

| Property       | Type     | Description                                                                                         |
| -------------- | -------- | --------------------------------------------------------------------------------------------------- |
| **`items`**    | `array`  | Array of fetched items from the catalog                                                             |
| **`metadata`** | `object` | Metadata about the search request: available facets, pagination, number of items, elapsed time, ... |

### **`items`**

The items matching the search query.

| Property       | Type     | Description                                                                        |
| -------------- | -------- | ---------------------------------------------------------------------------------- |
| **`id`**       | `string` | ID of the item                                                                     |
| **`score`**    | `number` | Relevancy score of the item. Higher is better                                      |
| **`product`**  | `object` | If present, contains the item's attributes, as specified in the XO catalog         |
| **`redirect`** | `object` | If present, a search redirect was triggered, and contains the redirect information |

### **`metadata`**

Metadata about the search query and its results.

| Property              | Type      | Description                                                                                     |
| --------------------- | --------- | ----------------------------------------------------------------------------------------------- |
| **`count`**           | `number`  | Number of items matching the query                                                              |
| **`time`**            | `number`  | Time the request took to complete (in milliseconds)                                             |
| **`token`**           | `string`  | Search API token used for the request                                                           |
| **`url`**             | `string`  | Equivalent url that can be used to send the same request                                        |
| **`offset`**          | `number`  | **Pagination:** index of the first fetched item                                                 |
| **`limit`**           | `number`  | **Pagination:** Size of the page (ie. number of elements returned)                              |
| **`facets`**          | `string`  | List of facets (and their values) matching the query. Facets must be defined in the XO console. |
| **`id`**              | `string`  | Unique identifier                                                                               |
| **`configurationId`** | `string`  | Search configuration id used                                                                    |
| **`exactCount`**      | `boolean` | If true, the count of the results is exact                                                      |

### Example

{% tabs %}
{% tab title="JSON Format" %}

```javascript
{
  "items": [
    ...
  ],
  "metadata": {
    "id": "573e30b1-7d97-46a0-bbe0-110527150534",
    "configurationId": "cddda87b-c99d-45aa-bf45-cd53d2bc8ace",
    "count": 170,
    "exactCount": true,
    "time": 35.23,
    "token": "a28570e6ac94e8d86c19e820",
    "url": "/search?...",
    "offset": 19,
    "limit": 20,
    "facets": [
      {
        "id": "color",
        "title": "Color",
        "count": 2,
        "values": [
          {
            "value": "red",
            "count": 25,
            "selected": true
          },
          {
            "value": "blue",
            "count": 5,
            "selected": false
          }
        ]
      }
    ]
  }
}
```

{% endtab %}
{% endtabs %}