Skip to main content

​
Endpoint

GET /api/history

​
Overview

Retrieve the chat conversation history for a specific user and optional session. Returns all messages exchanged between the user and AI agents.
Chat history is automatically persisted to the database for all conversations. Sessions can be used to organize related conversations.

​
Request Parameters

​
user_id
string
required
Unique identifier for the user whose history to retrieve
​
query_user_id
string
User ID whose data was queried (for help-ask feature). Defaults to user_id.
​
session_id
string
Optional session ID to filter by specific conversation thread
​
limit
integer
default:"50"
Maximum number of messages to return (max: 100)
​
offset
integer
default:"0"
Number of messages to skip (for pagination)
curl "http://localhost:18080/api/history?user_id=user_123&session_id=session_abc&limit=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Response Format

{
  "code": 0,
  "msg": "ok",
  "data": {
    "messages": [
      {
        "msg_id": "q_550e8400-e29b-41d4-a716-446655440000",
        "role": "user",
        "content": "How many steps did I take yesterday?",
        "timestamp": "2024-01-15T10:30:00.123Z",
        "session_id": "session_abc",
        "file_list": []
      },
      {
        "msg_id": "a_660e8400-e29b-41d4-a716-446655440001",
        "role": "assistant",
        "content": "Based on your Garmin data, you took 10,543 steps yesterday. That's about 200 steps more than your daily average!",
        "timestamp": "2024-01-15T10:30:02.456Z",
        "session_id": "session_abc",
        "agent": "deep",
        "provider": "openrouter",
        "model": "anthropic/claude-3.5-sonnet",
        "tool_calls": [
          {
            "tool_name": "get_health_data",
            "arguments": "{\"indicator\": \"steps\", \"date\": \"2024-01-14\"}",
            "result": "{\"value\": 10543, \"unit\": \"steps\"}"
          }
        ]
      }
    ],
    "total": 2,
    "session_id": "session_abc"
  }
}

​
Message Object

FieldTypeDescription
msg_idstringUnique message identifier
rolestringuser or assistant
contentstringMessage text content
timestampstringISO 8601 timestamp
session_idstringSession identifier
file_listarrayAttached files (user messages only)
agentstringAgent used (assistant messages only)
providerstringLLM provider (assistant messages only)
modelstringModel name (assistant messages only)
tool_callsarrayMCP tool calls made (assistant messages only)

​
Additional Endpoints

Get Session List

GET /api/session
Returns all sessions for a user with summaries

Delete History

POST /api/history/delete
Delete specific messages or entire sessions
For shared sessions (help-ask feature), use /api/history_by_person endpoint to retrieve conversations where you helped another user.