Skip to main content
This page tells you how to give the Index the context of a conversation. With context, the Index can recommend from the full conversation, not only from the current query.

Overview

Send your own stable conversation ID as session_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.
If there is no summary, /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 403 for 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 the sessionId 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.
The response is 202 Accepted when Gravity has queued the message:

Request fields

string
required
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.
string
required
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.
string
required
user or assistant.
string
required
The text of the turn, 1 to 50,000 characters.

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, call POST https://index.trygravity.com/session/search with the session ID and your X-API-Key header.
The Index uses the conversation summary as the query. 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.

Troubleshoot