Overview
Send your own stable conversation ID assession_id on every /search call. If Gravity has a current summary of that conversation, the Index uses it as private context. Your query stays the current task. The summary tells the Index what the user tried to do before. You do not send earlier turns in the search request.
/search uses only the query. A summary expires two hours after the last message in the session. The response never contains the summary.
Gravity keeps each summary in your publisher account scope. Gravity stores it as a summary embedding and in the Gravity data warehouse for ranking and reports. Gravity does not keep the raw turns.
Before you start
- Get a publisher API key for an approved publisher account. The message endpoint returns
403for accounts that are not approved. - Select a stable session ID for each conversation. Use the same value on every call.
Send the conversation to Gravity
Send each user turn and each assistant turn to the message endpoint. Use your publisher API key as a Bearer token. This endpoint does not serve an ad or record an impression. It is also separate from thesessionId that you send on /api/v1/ad. Index summaries belong to your publisher account. Gravity builds them only from the messages that you send to this endpoint.
202 Accepted when Gravity has queued the message:
Request fields
Your conversation ID, 1 to 256 characters. Send the same value as
session_id on /search. If you also call /shop/search, use 200 characters or fewer, because /shop/search accepts only 200.A stable ID for this turn, 1 to 200 characters. Gravity uses it to remove duplicates, so a retry with the same ID is safe.
Responses
If a user message looks like it comes from a minor, Gravity does not store messages from that session. The response is still
202.
Search with only the session
Sometimes the agent has no query of its own and wants to know what fits the conversation. In that case, callPOST https://index.trygravity.com/session/search with the session ID and your X-API-Key header.
user_ip is required, as on /search: the user’s IP address, or "caller" if the request leaves the user’s own device. The request also accepts country, user_agent and the identity fields of /search (external_user_id, external_user_id_hash, hashed_email, phone_hash, metadata) and monetization. max_options is 1 to 10 (default 5).
To balance relevance and sponsored results for a session search, send "monetization": {"relevance": 0.5}. Set relevance to 0 to return only sponsored results, which are still relevant but appear less often, or 1 to let the best result win, even over a good sponsored one. An explicit numeric value overrides your saved Index default in Ad settings → Relevance; omit it or send null to use that default. See the search request fields for precedence and account restrictions.
The response has the same shape as the /search response, with two changes: it has no query field, and it has a session_id field.