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

# Sessions

> Manage multi-turn chat sessions and their message/run history.

Sessions store the conversation history between users and agents. Each session contains messages (user inputs, assistant responses, tool calls, tool results, plus the retrieved context that grounded each assistant turn) and can span multiple agent runs. When the agent is configured for reasoning, sessions also track reasoning configuration per run. Sessions persist until explicitly deleted.

## Common Patterns

Sessions are created automatically when you run an agent without a session\_id. To continue a conversation, pass the session\_id from the start event of a previous run. Retrieve message history with GET /api/sessions/\{id}/messages to display conversation context.

### GET /api/sessions/{id}

Get a session by ID.

<ParamField path="id" type="string" required>
  Session ID
</ParamField>

<CodeGroup>
  ```python Python theme={null}
  response = requests.get(f"{BASE_URL}/api/sessions/{session_id}", headers=headers)
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch(`${BASE_URL}/api/sessions/${sessionId}`, { headers });
  ```

  ```bash cURL theme={null}
  curl '{BASE_URL}/api/sessions/{id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"
  ```
</CodeGroup>

### GET /api/sessions/{id}/messages

Get assembled chat messages for a session. Each assistant message includes its retrieved\_context (knowledge-base chunks fetched during the run) so you can surface citations alongside replies.

<ParamField path="id" type="string" required>
  Session ID
</ParamField>

<CodeGroup>
  ```python Python theme={null}
  response = requests.get(f"{BASE_URL}/api/sessions/{session_id}/messages", headers=headers)
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch(`${BASE_URL}/api/sessions/${sessionId}/messages`, { headers });
  ```

  ```bash cURL theme={null}
  curl '{BASE_URL}/api/sessions/{id}/messages' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"
  ```
</CodeGroup>

### GET /api/sessions/{id}/runs

List all agent runs within a session.

<ParamField path="id" type="string" required>
  Session ID
</ParamField>

<CodeGroup>
  ```python Python theme={null}
  response = requests.get(f"{BASE_URL}/api/sessions/{session_id}/runs", headers=headers)
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch(`${BASE_URL}/api/sessions/${sessionId}/runs`, { headers });
  ```

  ```bash cURL theme={null}
  curl '{BASE_URL}/api/sessions/{id}/runs' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"
  ```
</CodeGroup>

### GET /api/sessions/{id}/runs/{run_id}/retrieved-context

Get the retrieved context (knowledge-base chunks fetched during retrieval) for a single run within a session. Useful for debugging RAG behavior: you can see which chunks the agent saw before generating a given turn, separate from the assembled `/messages` view.

<ParamField path="id" type="string" required>Session ID</ParamField>
<ParamField path="run_id" type="string" required>Run ID (the `run_id` of an `agent_run` belonging to this session)</ParamField>

<ResponseExample>
  ```json Response theme={null}
  {
    "session_id": "sess_abc",
    "run_id": "run_xyz",
    "retrieved_context": [
      { "_type": "retrieval_diagnostics", "...": "..." },
      {
        "id": "chunk-uuid",
        "text": "...",
        "score": 0.84,
        "retrieval_score": 0.71,
        "reranker_score": 0.84,
        "source_id": "src-uuid",
        "source_name": "Q3-2025.pdf",
        "knowledge_base_id": "kb-uuid",
        "kb_name": "Finance docs",
        "indexing_strategy": "chunk_embed",
        "meta": {},
        "included_in_context": true
      }
    ]
  }
  ```
</ResponseExample>

<CodeGroup>
  ```python Python theme={null}
  response = requests.get(f"{BASE_URL}/api/sessions/{session_id}/runs/{run_id}/retrieved-context", headers=headers)
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch(`${BASE_URL}/api/sessions/${sessionId}/runs/${runId}/retrieved-context`, { headers });
  ```

  ```bash cURL theme={null}
  curl '{BASE_URL}/api/sessions/{id}/runs/{run_id}/retrieved-context' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"
  ```
</CodeGroup>

### DELETE /api/sessions/{id}

Delete a session and all its runs.

<ParamField path="id" type="string" required>
  Session ID
</ParamField>

<CodeGroup>
  ```python Python theme={null}
  response = requests.delete(f"{BASE_URL}/api/sessions/{session_id}", headers=headers)
  ```

  ```typescript TypeScript theme={null}
  await fetch(`${BASE_URL}/api/sessions/${sessionId}`, { method: "DELETE", headers });
  ```

  ```bash cURL theme={null}
  curl -X DELETE '{BASE_URL}/api/sessions/{id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"
  ```
</CodeGroup>

## Error Responses

Errors return `{"error": "<message>"}`.

| Status | Description                                                                                                               |
| ------ | ------------------------------------------------------------------------------------------------------------------------- |
| 404    | No session exists with the given ID, or the session is owned by another user (returned as 404 to avoid leaking existence) |
| 404    | The given run does not exist within this session (`/runs/{run_id}/retrieved-context`)                                     |