> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trygravity.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversation context

> Pass your session ID and Index recommends from the whole conversation, not just the current query

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.

```json theme={null}
{
  "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`](/ai-platforms/request-ads): Index summaries are keyed to your publisher
account and are only built from messages you post here.

```bash theme={null}
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`:

```json theme={null}
{
  "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.