Conversation context

By default, send your own stable conversation ID as external_session_id on every /search call. When Gravity holds a current summary of that conversation, Index uses it as private supporting context: your query stays the current task, the summary explains what the user has been trying to do. You never replay prior turns inside a search request.

{
  "query": "Recommend a hosted database for this application.",
  "external_session_id": "chat_8f3a"
}

If no summary exists yet (or it has expired; summaries live about two hours after the last turn), /search runs on the explicit query alone. The summary is never returned in the response. Like every Gravity conversation summary it is kept, scoped to your publisher account, as a summary embedding and in Gravity’s warehouse for ranking and reporting; the raw turns are not.

How Gravity gets the conversation

Stream each user and assistant turn to the ingestion endpoint with your publisher key. This does not serve an ad or record an impression, and it is separate from the sessionId you may already send on /api/v1/ad: Index summaries are keyed to your publisher account and are only built from messages you post here.

curl -X POST https://server.trygravity.ai/api/v1/index/session/messages \
  -H 'content-type: application/json' \
  -H "Authorization: Bearer $GRAVITY_PUBLISHER_KEY" \
  -d '{
    "session_id": "chat_8f3a",
    "message": {
      "id": "msg_0021",
      "role": "user",
      "content": "I need a hosted Postgres database for my Next.js app."
    }
  }'

Returns 202 Accepted once the message is durably queued. message.id must be stable per turn so retries are deduplicated; role is user or assistant. Requests carrying Sec-GPC: 1 return 204 and store nothing. session_id is up to 200 characters, the same value you pass as external_session_id on /search and /shop/search.

Search with only the session

When the agent has no query of its own (it just wants “what fits this conversation”) call POST https://index.trygravity.ai/session/search with the session ID and your X-API-Key:

{
  "session_id": "chat_8f3a",
  "max_options": 5
}

The response has the same shape as /search (recommendation, reasoning, options, tracked click URL). A 409 session context is not ready means no summary exists yet; retry after the next turn is processed.

Start here

Interfaces

Partners

Conversation context

How Gravity gets the conversation

Search with only the session

​How Gravity gets the conversation

​Search with only the session

How Gravity gets the conversation

Search with only the session