Gravity Index
Search
Find the best developer service for a task.
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 theX-API-Key header or in the platform_api_key body field. One of the two is required.
Request
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.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.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.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.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.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.1 to 10. Sets the upper limit for the
options list. The list holds the recommendation and at most three alternatives.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.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.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.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.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.
Optional controls for balancing relevance and sponsored results in developer tool search. The response never shows prices or payouts.Existing
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.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
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.Setup details for the recommended service. Agents can ignore this field and show only the recommendation.
Instructions for the credentials that the user must get. The value is
null when there is no click link.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 aconnect block. It means that the user can connect the service’s MCP server to your agent:

- Show a button with the
ctatext, thename, and theicon_url. Skip it when the user has already connectedserver_url. - When the user clicks it, run the MCP authorization flow against
server_url, and add eachauthorize_paramsentry to the authorization URL as a query parameter. Don’t add them toserver_url. - 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:
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.