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.

userId · string

Filter sessions to those belonging to a specific user.

agentId · string

Filter sessions to those associated with a specific agent.

page · number · default: "0"

Zero-based page index.

size · number · default: "20"

Number of sessions per page.

content · object[]

Array of AgentSession objects.

Show AgentSession fields

sessionId · string

Unique session identifier. Pass this as sessionId in run requests to continue the conversation.

userId · string

The user this session belongs to.

agentId · string

The agent associated with this session.

messages · object[]

Full message history as a JSONB array. Each entry contains role (user or assistant) and content.

createdAt · string

ISO-8601 timestamp when the session was created.

updatedAt · string

ISO-8601 timestamp of the last message in the session.

cURL — all sessions

curl --request GET \
  --url "http://localhost:8080/api/sessions" \
  --header "Authorization: Bearer {token}"

Example response

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

sessionId · string · required

The unique identifier of the session to retrieve.

cURL

curl --request GET \
  --url "http://localhost:8080/api/sessions/550e8400-e29b-41d4-a716-446655440000" \
  --header "Authorization: Bearer {token}"

Example response

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

sessionId · string · required

The session whose runs you want to list.

[] · object[]

Array of AgentRun objects.

Show AgentRun fields

id · string

Unique run identifier.

agentId · string

The agent that executed this run.

sessionId · string

The session this run belongs to.

status · string

Final status: COMPLETED, FAILED, PAUSED, or CANCELLED.

createdAt · string

ISO-8601 timestamp when the run was submitted.

completedAt · string

ISO-8601 timestamp when the run reached a terminal state. null for in-flight runs.

output · string

The agent’s final response content, when status is COMPLETED.

cURL

curl --request GET \
  --url "http://localhost:8080/api/sessions/550e8400-e29b-41d4-a716-446655440000/runs" \
  --header "Authorization: Bearer {token}"

Example response

[
  {
    "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.

sessionId · string · required

The unique identifier of the session to delete.

cURL

curl --request DELETE \
  --url "http://localhost:8080/api/sessions/550e8400-e29b-41d4-a716-446655440000" \
  --header "Authorization: Bearer {token}"

Returns 204 No Content with an empty body.

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