Chat History API

Edge function to retrieve conversation history with metadata.

Overview

This API enables the frontend to:

1. Load session history - Retrieve all messages for a session with associated metadata
2. List conversations - Get all conversation sessions for the authenticated user

Endpoints

GET /chatHistory?sessionId={sessionId}

Retrieves full conversation history with metadata for a specific session.

Request:

curl -X GET "https://<project>.supabase.co/functions/v1/chatHistory?sessionId=my-session" \
  -H "Authorization: Bearer ${JWT_TOKEN}"

Response:

{
  "sessionId": "my-session",
  "messages": [
    {
      "id": "msg-001",
      "role": "user",
      "content": "What is Smart Data?",
      "timestamp": "2026-01-16T10:00:00.000Z",
      "metadata": null
    },
    {
      "id": "msg-002",
      "role": "assistant",
      "content": "Smart Data is...",
      "timestamp": "2026-01-16T10:00:08.500Z",
      "metadata": {
        "model": {
          "provider": "openai",
          "model": "gpt-4o-mini",
          "mode": "platform"
        },
        "confidence": {
          "confidence": 85,
          "sourcesContributed": true,
          "reasoning": "...",
          "sourcesFound": 5,
          "llmAssessmentConfidence": 92
        },
        "sources": {
          "totalSources": 5,
          "usedAttention": true,
          "sources": [
            {
              "index": 1,
              "percent": 45.2,
              "title": "Smart Data Overview",
              "source": "https://example.com/smart-data-overview",
              "chunkCount": 3
            },
            {
              "index": 2,
              "percent": 30.1,
              "title": "Data Management Best Practices",
              "source": "https://example.com/data-best-practices",
              "chunkCount": 2
            }
          ]
        },
        "transaction": {
          "platform_fee": 0.0236,
          "roc_credits_distributed": 0.0140,
          "usage_duration_seconds": 8.5,
          "transaction_type": "query_usage",
          "transaction_id": "txn-uuid-001",
          "balance_before": 99.9764,
          "balance_after": 99.9528,
          "sources": [...]
        },
        "timing": {
          "ttf_ms": 1704,
          "duration_ms": 8500
        }
      }
    }
  ]
}

GET /chatHistory (no sessionId)

Lists all conversation sessions for the authenticated user.

Request:

curl -X GET "https://<project>.supabase.co/functions/v1/chatHistory" \
  -H "Authorization: Bearer ${JWT_TOKEN}"

Response:

{
  "userId": "user-123",
  "conversations": [
    {
      "userId": "user-123",
      "sessionId": "session-abc",
      "messageCount": 10,
      "lastActivity": "2026-01-16T10:05:00.000Z"
    },
    {
      "userId": "user-123",
      "sessionId": "session-xyz",
      "messageCount": 4,
      "lastActivity": "2026-01-15T14:30:00.000Z"
    }
  ]
}

Authentication

Uses JWT v3 authentication. The org_id and userId are extracted from the JWT token's app_claims.

Required header:

Authorization: Bearer <jwt_token>

Query Parameters

Parameter	Type	Required	Description
sessionId	string	No	Session to retrieve. If omitted, lists all sessions.
verbose	boolean	No	Enable verbose logging (default: false)

Metadata Structure

See PLAN_chat-metadata-persistence.md for the complete metadata schema and TypeScript types.

Key Metadata Fields

Category	Description
model	LLM provider, model name, and mode (platform/byok)
confidence	Answer confidence score, source contribution assessment
sources	Source contribution data (matches SSE events-sources-data format)
transaction	Platform fee, RoC distribution, balance changes
timing	Time to first response, total duration

Sources Structure (matches SSE events-sources-data)

Field	Type	Description
totalSources	number	Total number of contributing sources
usedAttention	boolean	Whether attention-based scoring was used
sources[]	array	Array of source contributions
sources[].index	number	1-based index of the source
sources[].percent	number	Contribution percentage (0-100)
sources[].title	string | null	Document title from metadata
sources[].source	string	Source URL
sources[].chunkCount	number	Number of chunks from this source

Backwards Compatibility

• Legacy messages (before metadata persistence) will have metadata: null
• User messages always have metadata: null (only assistant responses have metadata)
• Frontend should handle missing metadata gracefully

Related Documentation

• PLAN_chat-metadata-persistence.md - Feature specification and mock data
• SSE_EVENTS_REFERENCE.md - SSE events that generate metadata
• supabase-chat-history.ts - Storage implementation

Change Log

Date	Change
2026-01-16	Fix sources schema to match SSE events-sources-data format (index, percent, title, source, chunkCount)
2026-01-16	Initial implementation for chat metadata persistence feature