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

# Sessions

> Group a multi-step task with a session_id so feedback and ranking signals connect across calls.

Every response includes a `session_id`. If you do not send one, the server generates a fresh UUID for that request and returns it:

```bash theme={"system"}
curl -s https://alpha.api.trycaesar.com/v1/search \
  -H "Authorization: Bearer $CAESAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"linux kernel scheduler","max_results":2}'
```

```json theme={"system"}
{
  "request_id": "cdef84e8-d7ed-4e53-9d1c-243b2dbd4b57",
  "search_id": "3de031fb-c7e0-4ef3-ad56-ac6ccbbc78c6",
  "session_id": "9cb3c9a5-c15b-4763-8fec-40565faf54db",
  "results": ["..."]
}
```

Pass that value back on subsequent calls in the same task — follow-up searches, document reads, feedback — and the server can connect them:

```bash theme={"system"}
curl -s https://alpha.api.trycaesar.com/v1/search \
  -H "Authorization: Bearer $CAESAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "EEVDF scheduler latency",
    "session_id": "9cb3c9a5-c15b-4763-8fec-40565faf54db"
  }'
```

## How to send it

| Endpoint            | Body field `session_id` | Header `X-Session-ID` |
| ------------------- | ----------------------- | --------------------- |
| `POST /v1/search`   | yes                     | yes                   |
| `POST /v1/document` | no — header only        | yes                   |
| `POST /v1/feedback` | yes                     | yes                   |

**The body wins.** If both a body `session_id` and an `X-Session-ID` header are present, the body value is used. Set the header once in your HTTP client as a convenient default; override per request in the body when you need to.

```bash theme={"system"}
curl -s https://alpha.api.trycaesar.com/v1/document \
  -H "Authorization: Bearer $CAESAR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: 9cb3c9a5-c15b-4763-8fec-40565faf54db" \
  -d '{"canonical_url": "https://documentation.ubuntu.com/real-time/latest/explanation/schedulers"}'
```

The value must be a UUID. Anything else is rejected with `400 validation_error` — message `session_id must be a UUID` for the body field, `X-Session-ID must be a UUID` for the header.

## What sessions are — and are not

Sessions provide continuity for ranking, telemetry, and abuse controls, and they give [feedback](/api-reference/index) its task context: a `search` followed by a `document` read followed by `feedback` under one `session_id` reads as a single multi-step task.

What a session is **not**:

* **Not server-side state.** Sessions are not persisted as entities, and a supplied `session_id` is never checked for "existence" — continuity is entirely caller-driven. Any valid UUID works.
* **Not authentication.** A `session_id` grants nothing. Auth is the Bearer key — see [Authentication](/authentication).
* **Not a rate-limit key.** [Rate limits](/rate-limits) are keyed by API key; the session has no effect.

## `client_model`

`client_model` is an optional string identifying the calling model (for example `my-agent-model`), used for analytics and tuning. It appears in two places:

| Where                    | Field                        | Status                                                 |
| ------------------------ | ---------------------------- | ------------------------------------------------------ |
| `POST /v1/search` body   | `client_model` (top level)   | Accepted; reserved for analytics — not persisted today |
| `POST /v1/feedback` body | `agent_context.client_model` | Persisted with the feedback event                      |

If you want model attribution to count, set it on feedback via `agent_context`. The hosted [MCP server](/clients/mcp/remote) sets `client_model: "mcp"` on searches it makes on your behalf. There is no header form of `client_model`.

## `X-Caesar-Client`

First-party clients send an `X-Caesar-Client: client/version` header: `cli/0.2.0`, `python-sdk/0.2.0`, `ts-sdk/0.2.0`. It is an attribution convention, not a protocol — the server does not parse, validate, or store it today, and it changes no behavior. If you build an integration, sending `yourtool/1.2.3` is encouraged:

```bash theme={"system"}
curl -s https://alpha.api.trycaesar.com/v1/search \
  -H "Authorization: Bearer $CAESAR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Caesar-Client: yourtool/1.2.3" \
  -d '{"query":"site reliability postmortem patterns"}'
```

Unlike `session_id`, there is no body equivalent and no precedence rule to think about.