Sessions - Caesar

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

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}'

{
  "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:

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.

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 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.
Not a rate-limit key. 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 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:

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.

​How to send it

​What sessions are — and are not

​client_model

​X-Caesar-Client

How to send it

What sessions are — and are not

`client_model`

`X-Caesar-Client`