---
updatedAt: 2025-05-14T00:16:43.000Z
agentTools:
  projectIndex: https://docs.ometria.com/llms.txt
---

# Headless Query API reference

Website personalisation: Headless API integration

```
POST "https://{{domainkey}}.store-{{locationkey}}.ometria.services/api/query"
{
    "request_id"    : {{ request_id }},         /* optional (String or Number) */
    "format"        : {{ json_or_html }},       /* optional (String), default: "json" */
    "elements"      : [{{ element_list }}],     /* required (Array) */
    "user": {
        "uid"           : {{ uid }},            /* required (String) */
        "sid"           : {{ sid }},            /* required (String) */
        "ip_address"    : {{ ip_address }}      /* optional (String) */
    },
    "context": {
        "category_id"   : {{ category_id }},    /* optional (String) */
        "product_id"    : {{ product_id }},     /* optional (String) */
        "page_id"       : {{ page_id }},        /* optional (String) */
        "page_url"      : {{ page_url }},       /* optional (String) */
        "user_agent"    : {{ user_agent }},     /* optional (String) */
        "language_id"   : {{ language_id }},    /* optional (String) */
        "currency_id"   : {{ currency_id }}     /* optional (String) */
        "warehouse_id"  : {{ warehouse_id }}    /* optional (String) */
    },
    "args": {
        {{ key_1 }}     : {{ value_1 }},
        {{ key_2 }}     : {{ value_2 }},
        {{ key_n }}     : {{ value_n }}
    },
    "response_options"  : {
        "fields": {
            "products"      : [{{ field_list }}]    /* optional (Array) */
        }
    }
}
```

## request\_id

**Optional**.

A string or number containing a unique identifier.

The API will return this value back with the response.

## format

**Optional**.

A string defining the format of the content returned.

The allowed values are html or json.

If format is not specified then a default value of json is used.

## elements

Required.

An array with a list of element identifiers.

Each element identifier must correspond to those elements defined in the Ometria website personalisation feature.

```
{
   "elements"  : ["category", "category_recs"]
}
```

## user

Required.

An object containing key information about the current site visitor.

These include:

* `uid` (**Required**): A string containing a unique id associated with the current visitor.
* `sid` (**Required**): A string containing a unique id associated with the current visit session.
* `ip_address` (**Optional**): A string containing the IP address associated with the current visit session.

> 📘 Note
>
> The `uid` and `sid` codes are generated by Ometria and returned with each response.
>
> The application ingesting the response is expected to persist the `uid` as a permanent cookie and `sid` as a session cookie.

If no `uid` or `sid` are detected then Ometria generates new IDs and returns with the response.

The only time the `uid` and `sid` should be omitted is when a user visits the site for the first time.

The `ip_address` is required if you want to use merchandising insights.

## context

**Optional**.

An object containing key information about the current request.

These include:

* `page_url` (**Optional**): The full url corresponding to the web page that the end user is currently viewing.
  * We recommend that you always include this field.
* `user_agent` (**Optional**): The web browser user agent.
  * We recommend that you always include this field.
* `category_id` (**Optional**): The id of the category for the current page.
  * This is required for category pages.
  * We recommend including this field in every request.
* `product_id` (**Optional**): The id of the product for the current product detail page.
* `page_id`(**Optional**): The id of the content page for the current page.
  * This is required on product detail pages.
* `language_id` (**Optional**): This is only required if multiple languages are defined.
* `currency_id` (**Optional**): This is only required if multiple currencies are defined.
* `warehouse_id` (**Optional**): This is only required if you have multiple warehouses and would like the stock data to reflect one specific warehouse rather than the sum of all of them.

## args

**Optional**.

In addition to the standard parameters, args allows you to define your own custom parameters in the form of key-value pairs.

E.g. segmentation values, additional product or category details, etc.

Use these to create even more granular personalisation.

```
{
   "args": {
       "site_section"      : "womens",
       "weather"           : "cold",
       "user_location"     : "london",
       "user_type"         : "new",
       "user_affinity"     : "brands"
   }
}
```

## response\_options

**Optional**.

An object containing response definitions and options.

## fields

**Optional**.

An object containing response definitions for fields returned.

## products

**Optional**.

An array of strings that define which product fields should be returned in the request.

We recommend only asking for the fields you need - this is to minimise response sizes.

```
{
   "response_options"  : {
       "fields": {
           "products"  : ["id", "sku", "prices"]
       }
   }
}
```

If **response\_options** > **fields** > **products** is not defined then all fields will be returned, which may result in a large payload.

The allowed fields are:

* `id`
* `sku`
* `stock`
* `url`
* `titles`
* `abstracts`
* `media`
* `pricing`
* `features`
* `variants`
* `properties`
* `tags`
* `created`
* `modified`
* `published`

## product\_features

**Optional**.

An array of strings that define which `features` should be returned.

This is used in conjunction with the products array and is only applied if "features" is included in the `products` list.

If `product_features` is not defined then all features will be returned in the response.

We recommend only asking for the features you need - this is to minimise response sizes.

```
{
   "response_options"  : {
       "fields": {
           "products"          : ["id", "sku", "prices", "features"],
           "product_features"  : ["brand", "material"]
       }
   }
}
```