Skip to main content
POST
Search
POST /search finds the best developer service for a task. An LLM compares the query with the catalog. It returns one recommendation and the reasons why the service fits. A matched response has the reasoning and, when the service has a destination URL, a tracked click link that the agent gives to the user. Send your session_id, and the Index uses the conversation as private context. See Conversation context.
For physical products (shoes, cookware, electronics), use POST /shop/search. That vertical returns a ranked list. /search uses the product catalog only when vertical is consumer, when you send filters, or when vertical is auto and Gravity turned on consumer search for your account. In those cases the response is a /shop/search response.

Authentication

Send your publisher API key in the X-API-Key header or in the platform_api_key body field. One of the two is required.
string
Your publisher API key. You can send platform_api_key in the body instead.

Request

string
required
What the user needs, in natural language, up to 1,000 characters. For example: “serverless database with free tier” or “auth for Next.js with SSO”. You can leave it empty only if context.messages contains the conversation. Then the Index uses the last user turn as the query.
string
required
The IP address (IPv4 or IPv6) of the user you search for. Send the user’s own address, not your server’s. It is the same address you send as device.ip in the ad request. If the request leaves the user’s own device (a local CLI or MCP server), send "caller", and the Index uses the address of the connection. Gravity uses the address to find the user’s country, because many sponsored services are only available in some countries. A request without user_ip returns 400.
string
The user’s country as an ISO 3166-1 alpha-2 code, for example US. Optional. Gravity uses it when it cannot find a country for user_ip.
string
The user agent of the user’s browser or client, up to 1,024 characters. It is the same value you send as device.ua in the ad request. Send it on every call to earn the most from sponsored results.
string
The search_id of an earlier response. Send it with a follow-up question, and the Index uses the earlier search as context. The value must be a UUID. The Index ignores other values and runs a new search.
object
Project context for the Index to consider, for example {"framework": "nextjs", "language": "typescript", "constraints": ["free tier", "EU region"]}. The format is free. Put facts about the user’s stack here, not in query. context.messages ([{role, content}]) can carry the conversation. The Index uses the last 12 turns.
string
Your publisher API key. Send this field or the X-API-Key header.
integer
default:"5"
1 to 10. Sets the upper limit for the options list. The list holds the recommendation and at most three alternatives.
string
default:"auto"
developer, consumer, or auto. With auto, the Index sends requests for retail products to the product catalog only if Gravity turned on consumer search for your account. Otherwise it uses the developer catalog.
object
Hard filters for the product catalog: brands, merchants, price_min, price_max, currency, sizes, colors, gender, categories, on_sale_only. If you send filters with auto, the Index uses the product catalog. See Product search for the rules.
string
Your stable chat or session ID, up to 256 characters. Send it on every call. Use the same value you send as sessionId in the ad request, so Gravity can match the search to the same user session. If Gravity has a summary of that conversation, the Index uses it as private context (see Conversation context). Gravity also uses it for attribution and payout matches. The response never contains it. external_session_id is the older name for this field and still works.
string
A hash of your user ID. Send this in place of a raw user ID when you can.
string
A raw user ID (optional). Gravity stores only a SHA-256 hash of it.
string
The SHA-256 hash of the normalized user email (email.strip().lower()), if you have it. This is the canonical field. It is the same as in the ad request. Send it on every call to earn the most from sponsored results. The Index also accepts the old name email_hash.
string
The SHA-256 hash of the user phone number (digits only), if you have it.
object
Publisher metadata that is not sensitive, for example the surface, workspace, plan, or placement. Gravity stores it with the search for attribution and for problem analysis. The LLM does not see it. The JSON must be 20,000 characters or fewer.
object
Optional controls for balancing relevance and sponsored results in developer tool search. The response never shows prices or payouts.
number
A value from 0 to 1. At 0 (sponsored only), search returns only sponsored results. They are still relevant, but fewer searches return a recommendation. At 1 (highest relevance), the best result wins, even over a good sponsored result. Sponsored results still appear when they are the best match. Values between them balance the two. For example, send {"relevance": 0.5}.Sponsored-only searches return no recommendation when no eligible sponsored result fits. An account restricted to sponsored results stays restricted at every value. This setting applies to this request only and does not affect shop search.A numeric relevance, including 0, overrides your saved Index default in Ad settings → Relevance for this request. If omitted or null, your saved default applies. Strings and booleans do not select an override. Account restrictions, eligibility requirements and blocked advertisers always apply.
Existing mode values remain supported: {"mode": "boost_cpa"} gives a small boost to services with an active CPA campaign, and {"mode": "off"} ignores sponsorship. A numeric request relevance takes precedence over the saved default, which takes precedence over mode. Without a request scalar or saved default, the existing mode or system default applies. The Index default is independent of your network ads relevance threshold.

Response

string
The response contract version, now "2026-05-23".
string
"developer" for this response shape.
string
A unique ID for this search. Send it back for a follow-up question.
string
The query that the Index used.
object | null
The recommended service, or null when no service fits.
object[]
The recommendation and the accepted alternatives, in order. Each item has service_id, slug, name, category, description, website_url, docs_url, click_url, and grclid. best_for and tradeoff are always null now.
string
Why this service is the best fit for the query, in natural language.
object | null
Setup details for the recommended service. Agents can ignore this field and show only the recommendation.
object | null
Instructions for the credentials that the user must get. The value is null when there is no click link.
string | null
The tracked short link that the user opens to sign up with the recommended service.
string | null
The Gravity click ID (a UUID) for the tracked click link.
object[]
At most three other services that also fit. Each item is {slug, reason}.
string | null
A service name that the LLM suggested but that is not in the catalog. When this field has a value, recommendation is null. Ask the user before you act on it.

Connect the MCP server

Some sponsored recommendations have a connect block. It means that the user can connect the service’s MCP server to your agent:
In a chat, the connection shows as a card with the service’s icon, name, description, and a button:
A connect card for Exa with the Exa icon, the name Exa, the text Web search and page reading built for AI agents, and a Connect button
To offer the connection:
  1. Show a button with the cta text, the name, and the icon_url. Skip it when the user has already connected server_url.
  2. When the user clicks it, run the MCP authorization flow against server_url, and add each authorize_params entry to the authorization URL as a query parameter. Don’t add them to server_url.
  3. Add the connected server to your MCP client for that user, and let the agent continue the task with its tools.

Use the React SDK

@gravity-ai/react 1.4.0 and later does this for you. McpConnectCard shows the card above and sends the tracked click when the user clicks. createMcpConnectHandler runs the MCP authorization flow in a popup, adds authorize_params to the authorization URL, and gives you the connection to add to your MCP client.
clientName is the name that the user sees on the service’s consent screen. The connection that addServer receives has serverUrl, name, headers (with the Authorization bearer token), and oauth (the token endpoint, client ID, refresh token, and expiry). The redirectUri page must be on your own origin and call completeMcpConnectCallback() when it loads:
Before oauth.expiresAt, renew the access token with refreshMcpConnection(connection), which returns an updated connection. For all options, and for servers that block cross-origin requests from the browser, see the @gravity-ai/react README. Through the Gravity Index MCP server, the connect block is in the tool result’s structured content. To turn off connect blocks for your account, turn off MCP connect on your placements in the Gravity dashboard. The Index applies the setting to the whole account: if any active placement has MCP connect off, no Index result has a connect block. Service providers set up their MCP server as described in Connect your MCP server.

Errors

Examples

The response looks like this (shortened):

Follow-up question

The Index uses the earlier search as context for the answer.