Gravity Index
Product search
Find consumer products that a user can buy (shoes, cookware, electronics), not developer tools.
POST
POST /shop/search finds consumer products that a user can buy. The Index has two verticals (catalogs) behind one publisher API key:
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 theX-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
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.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.1 to 25. Ask only for the number that you will show, because each result makes a tracked click link.
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.An ISO 4217 code. Price filters and returned prices use this currency. Most of the catalog is in USD.
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”.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.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.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.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.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.
Your ID for this conversation, up to 200 characters on this endpoint.
external_session_id is the older name for this field and still works.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.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
Always
"consumer" on this endpoint. If one handler processes both endpoints, use this field to select the display.The product request that the Index searched: your
query, or what the Index found in context.messages.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.
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.A disclosure to show before the user acts on a result, when any product is
promoted. null otherwise.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.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.reasoning field each. The Index ranks the products as a list.
Examples
Query in natural language with a price limit
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.”Only sale items
Show results
Showname, 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 acheckout 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.
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.
Attribution rules:
- Always send
attributionexactly as the Index returned it. Do not make your own click IDs. - If the merchant rejects the call, or if
checkoutisnull, useclick_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.
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.