hermes - 💡(How to fix) Fix [Feature]: Session List & Management REST API Endpoints [1 comments, 2 participants]

Problem or Use Case

The API server currently has no way to enumerate or query past sessions. Clients that want to implement a "conversation history" panel (e.g. a JetBrains / VS Code plugin, a custom web dashboard) must either:

• parse the SQLite database directly (brittle, bypasses business logic, breaks on schema changes), or
• scrape GET /health/detailed which only exposes a live count of active sessions — not a browsable list.

Meanwhile, the internal SessionDB already provides:

• list_sessions_rich() — paginated session listing with metadata
• search_sessions() — FTS5 full-text search across session content

These are used by hermes sessions list (CLI) and the dashboard's /api/status endpoint. The same data simply needs to be surfaced through the API server under the same bearer-auth guard that protects all other endpoints.

Concrete use-cases blocked today:

• JetBrains / VS Code plugin showing a "Chat History" sidebar with past sessions
• Custom web dashboards for multi-user deployments
• A2A orchestrators that need to hand off work to a prior session by ID
• Automated tooling that archives or prunes old sessions via the API

Proposed Solution

All endpoints follow the same bearer auth pattern as the rest of the API server.

GET /v1/sessions

List sessions with optional filtering and pagination.

Query parameters:

Example request:

GET /v1/sessions?limit=10&platform=api_server&search=kubernetes
Authorization: Bearer <key>

Example response:

{
  "object": "list",
  "data": [
    {
      "id": "20260501_143012_a1b2c3d4",
      "object": "hermes.session",
      "platform": "api_server",
      "title": "Kubernetes deployment review",
      "model": "anthropic/claude-opus-4",
      "started_at": "2026-05-01T14:30:12Z",
      "last_active_at": "2026-05-01T15:42:07Z",
      "ended_at": "2026-05-01T15:42:07Z",
      "turn_count": 14,
      "parent_session_id": null
    }
  ],
  "total": 42,
  "has_more": true
}

GET /v1/sessions/{session_id}

Retrieve metadata for a single session.

Example response:

{
  "id": "20260501_143012_a1b2c3d4",
  "object": "hermes.session",
  "platform": "api_server",
  "title": "Kubernetes deployment review",
  "model": "anthropic/claude-opus-4",
  "started_at": "2026-05-01T14:30:12Z",
  "last_active_at": "2026-05-01T15:42:07Z",
  "ended_at": "2026-05-01T15:42:07Z",
  "turn_count": 14,
  "parent_session_id": null,
  "child_session_ids": []
}

GET /v1/sessions/{session_id}/messages

Return the message history for a session (useful for resuming or displaying context).

Query parameters:

Example response:

{
  "object": "list",
  "session_id": "20260501_143012_a1b2c3d4",
  "data": [
    {"role": "user",      "content": "Review my k8s deployment manifest", "timestamp": "2026-05-01T14:30:12Z"},
    {"role": "assistant", "content": "I'll take a look...",               "timestamp": "2026-05-01T14:30:18Z"}
  ],
  "has_more": false
}

PATCH /v1/sessions/{session_id}

Update mutable session metadata (title).

Request body:

{"title": "My updated session title"}

DELETE /v1/sessions/{session_id}

Delete a session and its stored messages.

Capabilities advertisement

The GET /v1/capabilities response should grow a sessions_api flag so clients can detect support at runtime:

{
  "features": {
    "chat_completions": true,
    "responses_api": true,
    "run_submission": true,
    "sessions_api": true
  }
}

Implementation Notes

• No new storage layer needed. All data lives in SessionDB already. This is purely an HTTP façade.
• list_sessions_rich() already filters by parent_session_id IS NULL for display — expose an include_children=true query param to let callers opt in to child sessions (also fixes the counting bug described in #15722).
• Message retrieval could reuse the same session file / SQLite row structure used by session_search and hermes sessions list.
• Bearer auth is already applied globally in the API server — no new auth code needed.
• The conversation parameter in /v1/responses already creates named sessions; GET /v1/sessions would make those sessions discoverable by name.

Alternatives Considered

Feature Type

Gateway / messaging improvement

Scope

None

Contribution

• I'd like to implement this myself and submit a PR

Debug Report (optional)