Chat sessions and agentic search

Chat endpoints

Scope model

Each turn can optionally narrow retrieval scope with:

• index_ids
• prompt_run_ids

That scope is stored on the turn as effective_scope.

Example: create a session

curl -X POST /api/v2/chat/sessions \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"title":"Daily review assistant"}'

Example: create a scoped turn

curl -X POST /api/v2/chat/sessions/session_123/turns \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Find scenes where a reporter appears outside a station entrance.",
    "scope": {
      "index_ids": ["idx_archive"],
      "prompt_run_ids": ["run_123"]
    },
    "idempotency_key": "chat-turn-session-123-1"
  }'

Streaming protocol

POST /api/v2/chat/sessions/{session_id}/turns/stream returns text/event-stream.

The DTO layer documents event families such as:

• turn_started
• turn_resumed
• agent_state
• tool_call_started
• tool_call_result
• turn_completed
• error

Use Idempotency-Key, X-Idempotency-Key, or the request-body idempotency_key when you need resumable turn behavior.

Response structure

Completed turns can include:

• user_message
• assistant_message
• effective_scope
• tool_trace
• result_sets
• stats
• terminal error details when the turn fails