# API Documentation

Conversation persistence APIs for session discovery, transcript retrieval, and chat lifecycle operations keyed by `subject_id` and `chat_id`.

## Chat History

### GET `/api/v1/chat/history/list`

List all chats for a subject. Returns chat summaries with message counts — useful for building chat sidebars.

**Scope:** `history:read`

#### Parameters:
- `subject_id` **(required)**: string - The subject to list chats for.
- `limit`: number - Max chats to return. Default: 50, Max: 500

#### Request

```bash
curl -G "https://www.mnexium.com/api/v1/chat/history/list" \
  -H "x-mnexium-key: $MNX_KEY" \
  --data-urlencode "subject_id=user_123" \
  --data-urlencode "limit=50"
```

#### Response

```json
{
  "chats": [
    {
      "subject_id": "user_123",
      "chat_id": "550e8400-e29b-41d4-a716-446655440000",
      "last_time": "2024-12-17T19:00:01Z",
      "message_count": 12
    },
    {
      "subject_id": "user_123",
      "chat_id": "660e8400-e29b-41d4-a716-446655440001",
      "last_time": "2024-12-16T14:30:00Z",
      "message_count": 8
    }
  ]
}
```

### GET `/api/v1/chat/history/read`

Retrieve message history for a specific conversation. Use after listing chats to load full messages.

**Scope:** `history:read`

#### Parameters:
- `chat_id` **(required)**: string - The conversation ID to fetch history for.
- `subject_id`: string - Filter by subject (optional).
- `limit`: number - Max messages to return. Default: 200

#### Request

```bash
curl -G "https://www.mnexium.com/api/v1/chat/history/read" \
  -H "x-mnexium-key: $MNX_KEY" \
  --data-urlencode "chat_id=550e8400-e29b-41d4-a716-446655440000" \
  --data-urlencode "subject_id=user_123" \
  --data-urlencode "limit=50"
```

#### Response

```json
{
  "messages": [
    {
      "role": "user",
      "message": "I just switched to VS Code for my Rust projects.",
      "message_index": 0,
      "event_time": "2024-12-17T19:00:00Z",
      "tool_call_id": "",
      "tool_calls": "",
      "memory_ids": []
    },
    {
      "role": "assistant",
      "message": "Great choice! Since you work with Rust, I'd recommend installing rust-analyzer and...",