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

# Sessions API — Conversation History

> List, retrieve, and delete agent conversation sessions, and fetch the complete run history within each session for auditing and replay.

Sessions are the unit of conversational continuity in Agent Manager. Every agent run is associated with a session, and sessions persist the full message history in PostgreSQL so agents can rehydrate context across multiple turns. The Sessions API lets you list sessions, inspect their message history, retrieve their constituent runs, and delete session data.

All requests require a valid bearer token in the `Authorization` header.

***

## List sessions

```
GET /api/sessions
```

Returns a paginated list of agent sessions. Optionally filter by user or agent to narrow results.

<ParamField query="userId" type="string">
  Filter sessions to those belonging to a specific user.
</ParamField>

<ParamField query="agentId" type="string">
  Filter sessions to those associated with a specific agent.
</ParamField>

<ParamField query="page" type="number" default="0">
  Zero-based page index.
</ParamField>

<ParamField query="size" type="number" default="20">
  Number of sessions per page.
</ParamField>

<ResponseField name="content" type="object[]">
  Array of `AgentSession` objects.

  <Expandable title="AgentSession fields">
    <ResponseField name="sessionId" type="string">
      Unique session identifier. Pass this as `sessionId` in run requests to continue the conversation.
    </ResponseField>

    <ResponseField name="userId" type="string">
      The user this session belongs to.
    </ResponseField>

    <ResponseField name="agentId" type="string">
      The agent associated with this session.
    </ResponseField>

    <ResponseField name="messages" type="object[]">
      Full message history as a JSONB array. Each entry contains `role` (`user` or `assistant`) and `content`.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO-8601 timestamp when the session was created.
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO-8601 timestamp of the last message in the session.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL — all sessions theme={null}
  curl --request GET \
    --url "http://localhost:8080/api/sessions" \
    --header "Authorization: Bearer {token}"
  ```

  ```bash cURL — filter by user theme={null}
  curl --request GET \
    --url "http://localhost:8080/api/sessions?userId=user_abc123&agentId=finance_agent" \
    --header "Authorization: Bearer {token}"
  ```
</CodeGroup>

**Example response**

```json theme={null}
{
  "content": [
    {
      "sessionId": "550e8400-e29b-41d4-a716-446655440000",
      "userId": "user_abc123",
      "agentId": "finance_agent",
      "messages": [
        { "role": "user", "content": "What is the current NVDA stock price?" },
        { "role": "assistant", "content": "The current stock price of NVIDIA (NVDA) is **$875.40**." }
      ],
      "createdAt": "2026-05-06T09:00:00Z",
      "updatedAt": "2026-05-06T09:00:04Z"
    }
  ],
  "totalElements": 1,
  "totalPages": 1,
  "number": 0
}
```

***

## Get session details

```
GET /api/sessions/{sessionId}
```

Fetches the full details of a single session, including the complete message history. Returns `404 Not Found` if no session exists with the given ID.

<ParamField path="sessionId" type="string" required>
  The unique identifier of the session to retrieve.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url "http://localhost:8080/api/sessions/550e8400-e29b-41d4-a716-446655440000" \
    --header "Authorization: Bearer {token}"
  ```
</CodeGroup>

**Example response**

```json theme={null}
{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "user_abc123",
  "agentId": "finance_agent",
  "messages": [
    { "role": "user", "content": "What is the current NVDA stock price?" },
    { "role": "assistant", "content": "The current stock price of NVIDIA (NVDA) is **$875.40**." },
    { "role": "user", "content": "How does that compare to AMD?" },
    { "role": "assistant", "content": "AMD (AMD) is currently trading at **$168.20**, down 0.8% today..." }
  ],
  "createdAt": "2026-05-06T09:00:00Z",
  "updatedAt": "2026-05-06T09:01:22Z"
}
```

| Status          | Description                                       |
| --------------- | ------------------------------------------------- |
| `404 Not Found` | No session exists with the specified `sessionId`. |

***

## Get runs in a session

```
GET /api/sessions/{sessionId}/runs
```

Returns the list of all agent runs that occurred within a specific session, ordered by creation time. Useful for auditing, replaying, or displaying the history of a conversation.

<ParamField path="sessionId" type="string" required>
  The session whose runs you want to list.
</ParamField>

<ResponseField name="[]" type="object[]">
  Array of `AgentRun` objects.

  <Expandable title="AgentRun fields">
    <ResponseField name="id" type="string">
      Unique run identifier.
    </ResponseField>

    <ResponseField name="agentId" type="string">
      The agent that executed this run.
    </ResponseField>

    <ResponseField name="sessionId" type="string">
      The session this run belongs to.
    </ResponseField>

    <ResponseField name="status" type="string">
      Final status: `COMPLETED`, `FAILED`, `PAUSED`, or `CANCELLED`.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO-8601 timestamp when the run was submitted.
    </ResponseField>

    <ResponseField name="completedAt" type="string">
      ISO-8601 timestamp when the run reached a terminal state. `null` for in-flight runs.
    </ResponseField>

    <ResponseField name="output" type="string">
      The agent's final response content, when `status` is `COMPLETED`.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url "http://localhost:8080/api/sessions/550e8400-e29b-41d4-a716-446655440000/runs" \
    --header "Authorization: Bearer {token}"
  ```
</CodeGroup>

**Example response**

```json theme={null}
[
  {
    "id": "run_7f3a9c12-4e2b-4d1a-8c5f-abc123def456",
    "agentId": "finance_agent",
    "sessionId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "COMPLETED",
    "createdAt": "2026-05-06T09:00:00Z",
    "completedAt": "2026-05-06T09:00:04Z",
    "output": "The current stock price of NVIDIA (NVDA) is **$875.40**."
  },
  {
    "id": "run_8a4b2d34-5c6e-4f3a-b7d8-def456ghi789",
    "agentId": "finance_agent",
    "sessionId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "COMPLETED",
    "createdAt": "2026-05-06T09:01:18Z",
    "completedAt": "2026-05-06T09:01:22Z",
    "output": "AMD (AMD) is currently trading at **$168.20**, down 0.8% today..."
  }
]
```

***

## Delete a session

```
DELETE /api/sessions/{sessionId}
```

Permanently deletes a session and its complete conversation history. This operation is unconditional — it returns `204 No Content` regardless of whether the session existed.

<ParamField path="sessionId" type="string" required>
  The unique identifier of the session to delete.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url "http://localhost:8080/api/sessions/550e8400-e29b-41d4-a716-446655440000" \
    --header "Authorization: Bearer {token}"
  ```
</CodeGroup>

Returns `204 No Content` with an empty body.

<Warning>
  Session deletion permanently removes the conversation history. Associated run records remain in the database but lose their session linkage. This operation cannot be undone.
</Warning>