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

# Product search

> Find consumer products that a user can buy (shoes, cookware, electronics), not developer tools.

`POST /shop/search` finds consumer products that a user can buy. The Index has two verticals (catalogs) behind one publisher API key:

| The user wants | Call | The response |
| - | - | - |
| A developer service ("a Postgres with a free tier", "email API for Node") | [`POST /search`](https://docs.trygravity.com/gravity-index/search) | **One** recommendation, the reasons for it, and a tracked link |
| A physical product ("running shoes for wide feet under \$150") | `POST /shop/search` (this page) | A **ranked list** of in-stock products, each with a price, an image, and a tracked link |

Your agent selects the endpoint from the user's intent. Use this rule: if the answer is software or a service that the user signs up for, call `/search`. If the answer is an item that a store ships to the user, call `/shop/search`. Both endpoints accept the same identity fields.

## Authentication

Use the same key as for all other Index endpoints. Send your publisher API key in the `X-API-Key` header or in the `platform_api_key` body field. You do not need a separate entitlement for the Index or for products. A request without a key gets `401`. A blocked publisher gets `403`.

## Request

**query** `string`

A description of the product in natural language, up to 1,000 characters. The Index does a full-text search on the product name, brand, merchant, and category. Concrete nouns give better results: "wide toe box running shoes" is better than "something comfy for my feet". The field is required unless you send `context.messages`.

**context** `object`

Optional hints from the conversation. `context.style` (alias `context.vibe`) is free text that gives a soft boost in the order, for example `"neutral cushioned daily trainer"` or `"minimalist Scandinavian"`. `context.messages` (`[{role, content}]`) lets the Index find the product need in the conversation when you send no `query`. The Index uses the last 12 turns. The `query` field of the response shows what the Index found. The Index stores other keys with the search and does not use them now.

**max\_results** `integer` (default: 5)

1 to 25. Ask only for the number that you will show, because each result makes a tracked click link.

**rerank** `boolean` (default: true)

When `true`, an LLM reranks the results. It keeps only the products that fit the request, so the list can be empty. When `false`, you get the keyword order, and no LLM runs.

### Structured filters

The Index applies filters **before** it ranks the results. Filters are hard limits, not preferences. Send them only when the user stated them.

**price\_min** `number`

The lowest current (sale) price, in `currency`. Inclusive. Must be 0 or more.

**price\_max** `number`

The highest current (sale) price, in `currency`. Inclusive. Must be 0 or more.

**currency** `string` (default: USD)

An ISO 4217 code. Price filters and returned prices use this currency. Most of the catalog is in USD.

**brands** `string[]`

Up to 20 brand names. The match ignores case (`"Nike"` and `"nike"` are the same). Use this filter when the user names a brand. Do not use it for "any brand".

**merchants** `string[]`

Up to 20 merchant names (`"Nike"`, `"Walmart"`, `"Lululemon"`). The match ignores case. Use this filter when the user wants to buy from a specific store.

**on\_sale\_only** `boolean` (default: false)

Return only products that have a price below their regular price now.

**colors** `string[]`

Up to 10 color words (`"black"`, `"navy"`). Listings are for a product, not for a variant, so this filter matches the color in the product title.

**sizes** `string[]`

Up to 10 sizes, as the merchant writes them (`"10"`, `"M"`, `"32x34"`). The Index removes listings that name a different size. It keeps listings that name no size, because the user can select the size at checkout.

**gender** `string`

`men`, `women`, or `kids`.

**categories** `string[]`

Up to 10 of these values: `apparel`, `footwear`, `furniture_decor`, `home_kitchen`, `beauty_personal_care`,
`electronics_computing`, `jewelry_watches`, `sports_outdoors`, `tools_hardware`, `toys_kids`,
`baby`, `pets`, `auto`, `books_media`, `other`. Any other value returns `422`.

> [!NOTE]
>
> The merchant catalog sets the region (US stores now). There is no region filter.

### Identity and attribution (optional)

These fields are the same as on `/search`. Send them for attribution and conversion reports for each user.

**external\_session\_id** `string`

Your ID for this conversation, up to 200 characters on this endpoint.

**external\_user\_id** `string`

Your stable ID for this user. Gravity stores only a SHA-256 hash of it.

**external\_user\_id\_hash** `string`

A hash of your user ID. Send this in place of `external_user_id` when you can.

**hashed\_email** `string`

The SHA-256 hash of the user email, after you trim it and change it to lowercase. The Index also accepts the old name `email_hash`.

**phone\_hash** `string`

The SHA-256 hash of the user phone number (digits only).

**metadata** `object`

Free-form keys and values that Gravity stores with the search (surface, locale, A/B arm). The JSON must be 20,000 characters or fewer. Do not put secrets or raw personal data here.

## Response

**vertical** `string`

Always `"consumer"` on this endpoint. If one handler processes both endpoints, use this field to select the display.

**api\_version** `string`

The response contract version, now `"2026-09-09"`.

**search\_id** `string`

A unique ID for this search. Log it. It is the join key for click and conversion reports.

**query** `string`

The product request that the Index searched: your `query`, or what the Index found in `context.messages`.

**recommendation** `object | null`

`products[0]`, or `null` when no product fits.

**reasoning** `string`

One sentence on why the Index selected the top product, or why it selected none.

**products** `object[]`

The products, best first. The list is empty when no in-stock product matches the query **and** all filters. Make a filter wider or change the words before you tell the user that there is nothing.

**product**

**product\_id** `string`

A stable catalog ID.

**name** `string`

The merchant's product title, as the merchant wrote it.

**brand** `string | null`

**merchant** `string`

The store that sells and ships the product.

**category** `string | null`

The merchant's category path, for example `Clothing > Shoes > Mens Shoes > Mens Running Shoes`. `null` for live Shopify listings.

**description** `string`

Shortened to 400 words or fewer.

**currency** `string`

**price** `number`

The current price that the user pays.

**regular\_price** `number | null`

The list price. It is the same as `price` when the product is not on sale. `null` when the merchant does not publish one.

**on\_sale** `boolean`

**image\_url** `string`

The product image. Always present: the Index removes products that have no image.

**click\_url** `string`

The tracked link to the merchant's product page. **Show only this URL to the user.** It sends the user to the merchant and records the click against `search_id`. In iMessage, Slack, and WhatsApp it shows as a product card (image, price, merchant). For Shopify listings that carry Shopify's attribution, it is Shopify's own product link, which can open in Shop (`shop.com`); pass it on unchanged, since a rewritten or redirected link loses the commission.

**promoted** `boolean`

`true` for a paid placement. Label these results so users can tell them apart from the rest, and show `disclosure` with them.

**grclid** `string`

The Gravity click ID in `click_url`. Use it if you report conversions yourself.

**checkout** `object | null`

A destination for machine payment, when the merchant accepts agent checkout (now: Shopify storefronts, through [UCP](https://ucp.dev)). `null` for listings that convert only through `click_url`. See [Buy for the user](#buy-for-the-user).

**checkout**

**protocol** `string`

`"ucp"`.

**endpoint** `string`

The merchant's own UCP MCP endpoint (`https://STORE_DOMAIN/api/ucp/mcp`). Your agent calls it directly. Gravity is not in the payment path.

**continue\_url** `string`

The merchant's browser checkout for this variant. Give it to the user when the agent does not complete the purchase.

**item\_id** `string`

The ID for `line_items[].item.id`, for example `gid://shopify/ProductVariant/32262292013136`.

**agent\_profile** `string`

A hosted UCP agent profile. Send it as `meta.ucp-agent.profile` if you do not host your own.

**attribution** `object`

Send it without changes as the `attribution` argument of `create_checkout`. It puts the `grclid` on the merchant's order, in the same slot that Google uses for `gclid`.

**count** `integer`

`products.length`.

**web\_results** `object[]`

Has items only when `products` is empty: up to 5 plain web listings for the same request, so the agent has something to show. Each item has `name`, `brand`, `price`, `currency`, `description`, `image_url`, `url`, and `site`. `price` and `currency` are `null` unless the page states both. Do not make up a price. These items have **no** tracked link and **no** `checkout`. Link to `url` directly, tell the user that they come from the web and not from the catalog, and do not offer to buy them.

**web result**

**name** `string`

The product or page title.

**brand** `string | null`

**price** `number | null`

The listed price in `currency`, or `null`.

**currency** `string | null`

An ISO 4217 code, only when the page states it.

**description** `string | null`

One sentence.

**image\_url** `string | null`

A verified raster image, or `null`.

**url** `string`

The page. Not tracked.

**site** `string`

The hostname without `www.`, for example `chewy.com`.

**disclosure** `string | null`

A disclosure to show before the user acts on a result, when any product is `promoted`. `null` otherwise.

**ranking** `string`

How the Index put the list in order. `"llm"`: the reranker kept only products that fit, best relevance tier first. In one tier, the listing that pays your platform more comes first. `"retrieval"`: keyword order (`rerank: false`, or the reranker was not available). For information only.

**facets** `object`

Values that the agent can filter on next, from the retrieved set: `brands`, `merchants`, `categories` (the 10 most frequent of each), and `price_range` (`{min, max}` or `null`). `categories` uses the values of the `categories` filter, for example `footwear`.

The products do not have a `reasoning` field each. The Index ranks the products as a list.

```json Query + price cap theme={null}
{
  "query": "running shoes for wide feet",
  "price_max": 150,
  "max_results": 2,
  "external_user_id": "user_8f3a"
}
```

```json Brand + size + style hint theme={null}
{
  "query": "running shoes",
  "brands": ["Nike", "Brooks", "Hoka"],
  "sizes": ["10"],
  "gender": "men",
  "price_min": 80,
  "price_max": 180,
  "context": { "style": "neutral cushioned daily trainer" },
  "max_results": 3
}
```

```json From conversation only theme={null}
{
  "context": {
    "messages": [
      { "role": "user", "content": "my espresso machine died, I want something under $500 that does milk too" }
    ]
  },
  "max_results": 3
}
```

```json 200 with products theme={null}
{
  "api_version": "2026-09-09",
  "vertical": "consumer",
  "search_id": "885eb1e4-ad46-417a-ae3f-7259291132e6",
  "query": "running shoes for wide feet",
  "recommendation": {
    "product_id": "1024849053674592846",
    "name": "Fdrone Women s Wide Toe Box Mesh Shoes Road Running Shoes",
    "brand": "Fdrone",
    "merchant": "Walmart",
    "category": "Clothing > Shoes > Womens Shoes > Womens Shoes",
    "description": "Elevate your active lifestyle with our premium women s sports shoes ...",
    "currency": "USD",
    "price": 17.0,
    "regular_price": 18.89,
    "on_sale": true,
    "image_url": "https://i5.walmartimages.com/asr/7593a41e-....jpeg",
    "click_url": "https://index.trygravity.com/go/e92f37c0-e2a3-4ba0-8526-b93e783becd1",
    "grclid": "e92f37c0-e2a3-4ba0-8526-b93e783becd1",
    "checkout": null
  },
  "reasoning": "Fdrone Women s Wide Toe Box Mesh Shoes from Walmart is the closest match; the Allbirds pair also has a wide fit and is under the cap.",
  "products": [
    {
      "product_id": "1024849053674592846",
      "name": "Fdrone Women s Wide Toe Box Mesh Shoes Road Running Shoes",
      "brand": "Fdrone",
      "merchant": "Walmart",
      "category": "Clothing > Shoes > Womens Shoes > Womens Shoes",
      "description": "Elevate your active lifestyle with our premium women s sports shoes ...",
      "currency": "USD",
      "price": 17.0,
      "regular_price": 18.89,
      "on_sale": true,
      "image_url": "https://i5.walmartimages.com/asr/7593a41e-....jpeg",
      "click_url": "https://index.trygravity.com/go/e92f37c0-e2a3-4ba0-8526-b93e783becd1",
      "grclid": "e92f37c0-e2a3-4ba0-8526-b93e783becd1",
      "checkout": null
    },
    {
      "product_id": "shopify:32262292013136",
      "name": "Women's Tree Dasher 2 - Natural White",
      "brand": "Allbirds",
      "merchant": "Allbirds",
      "category": null,
      "description": "A lightweight everyday running shoe with a roomy toe box ...",
      "currency": "USD",
      "price": 135.0,
      "regular_price": null,
      "on_sale": false,
      "image_url": "https://cdn.shopify.com/s/files/1/1104/4168/files/TD2W-NW-1.png",
      "click_url": "https://index.trygravity.com/go/2a7f0c9e-51d3-4c0a-9b8e-6f2d1e4c8a11",
      "grclid": "2a7f0c9e-51d3-4c0a-9b8e-6f2d1e4c8a11",
      "checkout": {
        "protocol": "ucp",
        "endpoint": "https://www.allbirds.com/api/ucp/mcp",
        "continue_url": "https://www.allbirds.com/cart/32262292013136:1",
        "item_id": "gid://shopify/ProductVariant/32262292013136",
        "agent_profile": "https://index.trygravity.com/ucp/agent-profile.json",
        "attribution": {
          "referring_domain": "index.trygravity.com",
          "click_id_tag": "grclid",
          "click_id_value": "2a7f0c9e-51d3-4c0a-9b8e-6f2d1e4c8a11"
        }
      }
    }
  ],
  "count": 2,
  "web_results": [],
  "ranking": "llm",
  "facets": {
    "brands": ["Fdrone", "Allbirds", "Brooks", "New Balance"],
    "merchants": ["Walmart", "Allbirds", "Zappos"],
    "categories": ["footwear"],
    "price_range": { "min": 17.0, "max": 139.95 }
  }
}
```

```json 200 with no catalog match (web fallback) theme={null}
{
  "api_version": "2026-09-09",
  "vertical": "consumer",
  "search_id": "bc9fe59c-0b1e-4d3a-9c7f-2e8a4d6b1f05",
  "query": "Zorblax titanium dog leash",
  "recommendation": null,
  "reasoning": "No in-stock product in the catalog matches this request and its filters; web_results are plain web listings with no tracked link or checkout.",
  "products": [],
  "count": 0,
  "web_results": [
    {
      "name": "Titanium Dog Leash - Ultralight",
      "brand": "Zorblax",
      "price": 18.5,
      "currency": "USD",
      "description": "A 5 ft titanium-clip leash for dogs up to 60 lb.",
      "image_url": "https://zorblax.example/cdn/leash-ti.jpg",
      "url": "https://zorblax.example/products/titanium-dog-leash",
      "site": "zorblax.example"
    },
    {
      "name": "Zorblax leash review",
      "brand": null,
      "price": null,
      "currency": null,
      "description": "Hands-on review of the Zorblax titanium leash.",
      "image_url": null,
      "url": "https://dogblog.example/zorblax-leash-review",
      "site": "dogblog.example"
    }
  ],
  "ranking": "retrieval",
  "facets": {
    "brands": [],
    "merchants": [],
    "categories": [],
    "price_range": null
  }
}
```

```json 422 validation theme={null}
{
  "detail": [
    {
      "type": "value_error",
      "loc": ["body"],
      "msg": "Value error, query is required unless context.messages carries the conversation"
    }
  ]
}
```

## Examples

### Query in natural language with a price limit

```bash cURL theme={null}
curl -X POST https://index.trygravity.com/shop/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "running shoes for wide feet",
    "price_max": 150,
    "max_results": 3,
    "external_user_id": "user_8f3a"
  }'
```

```typescript TypeScript theme={null}
const res = await fetch("https://index.trygravity.com/shop/search", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.GRAVITY_PUBLISHER_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "running shoes for wide feet",
    price_max: 150,
    max_results: 3,
    external_user_id: "user_8f3a",
  }),
});
const { products, search_id } = await res.json();
```

```python Python theme={null}
import httpx, os

r = httpx.post(
    "https://index.trygravity.com/shop/search",
    headers={"X-API-Key": os.environ["GRAVITY_PUBLISHER_KEY"]},
    json={
        "query": "running shoes for wide feet",
        "price_max": 150,
        "max_results": 3,
        "external_user_id": "user_8f3a",
    },
)
products = r.json()["products"]
```

The response panel at the top of this page shows a full response with two products, a response with no catalog match (with `web_results`), and a `422` error. `recommendation` repeats `products[0]`. `checkout` is `null` for affiliate catalog listings and has a value for Shopify storefronts.

### Brand, price band, and a style hint

The user said: "I want Nikes or Brooks, something cushioned for daily miles, under \$180."

```bash theme={null}
curl -X POST https://index.trygravity.com/shop/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "running shoes",
    "brands": ["Nike", "Brooks", "Hoka"],
    "price_min": 80,
    "price_max": 180,
    "context": { "style": "neutral cushioned daily trainer" },
    "max_results": 3
  }'
```

### Only sale items

```json theme={null}
{ "query": "cast iron dutch oven", "on_sale_only": true, "merchants": ["Walmart"], "max_results": 5 }
```

## Show results

Show `name`, `brand`, `merchant`, `price` (with `regular_price` struck through when `on_sale` is `true`), and
`image_url`. Link the full card to `click_url`. In chat surfaces, `click_url` alone is sufficient, because it shows as a card.

Do not change or shorten `click_url`. Do not link to the merchant page directly. The redirect attributes the sale to your platform.

## Buy for the user

When a product has a `checkout` value, your agent can complete the purchase itself. It does not have to give the user a link. Call the merchant's `endpoint` (an MCP server) directly, and send the `attribution` object without changes. When there is no click, this object attributes the order to your platform. Gravity never sees the payment.

```json theme={null}
"checkout": {
  "protocol": "ucp",
  "endpoint": "https://www.allbirds.com/api/ucp/mcp",
  "continue_url": "https://www.allbirds.com/cart/32262292013136:1",
  "item_id": "gid://shopify/ProductVariant/32262292013136",
  "agent_profile": "https://index.trygravity.com/ucp/agent-profile.json",
  "attribution": {
    "referring_domain": "index.trygravity.com",
    "click_id_tag": "grclid",
    "click_id_value": "e92f37c0-e2a3-4ba0-8526-b93e783becd1"
  }
}
```

This call creates a checkout. It does not charge the user.

```bash theme={null}
curl -X POST https://www.allbirds.com/api/ucp/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
    "params": {
      "name": "create_checkout",
      "arguments": {
        "meta": { "ucp-agent": { "profile": "https://index.trygravity.com/ucp/agent-profile.json" } },
        "checkout": {
          "currency": "USD",
          "line_items": [{ "quantity": 1, "item": { "id": "gid://shopify/ProductVariant/32262292013136" } }],
          "attribution": {
            "referring_domain": "index.trygravity.com",
            "click_id_tag": "grclid",
            "click_id_value": "e92f37c0-e2a3-4ba0-8526-b93e783becd1"
          }
        }
      }
    }
  }'
```

The merchant returns a checkout and sends `attribution` back. The status is `"requires_escalation"` until you supply the buyer, delivery, and payment. Continue with `update_checkout` and `complete_checkout`, as the merchant's UCP profile at `https://STORE_DOMAIN/.well-known/ucp` describes. Or give the user `checkout.continue_url` to finish in a browser.

> [!WARNING]
>
> `complete_checkout` charges the user's payment method. Get the user's explicit consent before you call it.

Attribution rules:

* Always send `attribution` exactly as the Index returned it. Do not make your own click IDs.
* If the merchant rejects the call, or if `checkout` is `null`, use `click_url`.

## Select `/search` or `/shop/search`

A router of three lines in the agent prompt is usually sufficient. Over REST, the two verticals are separate endpoints.

```text theme={null}
If the user asks for software, an API, hosting, a database, or anything
they would sign up for, call POST /search.
If they ask for a physical product or something delivered to them,
call POST /shop/search.
Otherwise, answer normally.
```

Over MCP, only the Python version of the [Gravity Index MCP server](https://docs.trygravity.com/gravity-index/mcp.md) can search products. It uses one tool, `gravity_index_search`, with `vertical: "consumer"`. The npm package `@gravity-ai/index-mcp` searches developer services only.

If your platform serves only one audience, connect only that endpoint. There is no penalty if you do not use the other vertical.

## Errors

| Status | Description |
| - | - |
| `401` `platform_api_key required` | The request has no key in the header or the body. |
| `403` `valid platform_api_key required` | The key is not valid. |
| `403` `publisher_not_approved` | The publisher account is blocked. This is the same rule as for production ads. |
| `413` `metadata is too large` | `metadata` is more than 20,000 characters as JSON. |
| `422` | Validation failed. For example: no `query` and no `context.messages`, `query` is more than 1,000 characters, `max_results` is not 1 to 25, more than 20 brands or merchants, more than 10 colors, sizes, or categories, an unknown category, or `external_session_id` is more than 200 characters. |
| `429` `daily_request_limit_reached` | Your account used its daily request limit. Self-serve publisher accounts can make 1,000 requests per UTC day. SDK ad requests and Index searches (`/search`, `/session/search`, and `/shop/search`) share the count. Try again after the `Retry-After` header (seconds). The limit resets at midnight UTC. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.