# API Documentation

## Real-time Events

Real-time SSE event stream for memory/profile change propagation with typed event envelopes and optional per-subject filtering.

Subscribe to real-time memory events using Server-Sent Events (SSE). Get instant notifications when memories are created, updated, superseded, or when profile fields change.

### GET `/api/v1/events/memories`

Subscribe to real-time memory events via Server-Sent Events (SSE). The connection stays open and streams events as they occur.

**Scope:** `memories:read or events:read`

### `subject_id`
- Type: string
- Optional. Filter events to a specific subject. If omitted, receives all events for the project.

### Request

```bash
curl -N "https://www.mnexium.com/api/v1/events/memories?subject_id=user_123" \
  -H "x-mnexium-key: $MNX_KEY" \
  -H "Accept: text/event-stream"
```

### Event Types

- `connected` - Initial connection confirmation
- `memory.created` - A new memory was created
- `memory.updated` - A memory was updated
- `memory.deleted` - A memory was deleted
- `memory.superseded` - A memory was superseded by a newer one
- `profile.updated` - Profile fields were updated
- `heartbeat` - Keepalive signal (every 30s)

### Example Events

```bash
event: connected
data: {"project_id":"proj_abc","subject_id":"user_123","timestamp":"2024-12-15T10:30:00Z"}

event: memory.created
data: {"id":"mem_xyz","subject_id":"user_123","text":"User prefers dark mode","kind":"preference","importance":75}

event: memory.superseded
data: {"id":"mem_old123","superseded_by":"mem_xyz"}

event: profile.updated
data: {"subject_id":"user_123","fields":{"name":"John","timezone":"America/New_York"},"updated_at":"2024-12-15T10:31:00Z"}

event: heartbeat
data: {"timestamp":"2024-12-15T10:31:30Z"}
```

### Usage Example

```bash
# SSE stream stays open — events arrive in real time
curl -N "https://www.mnexium.com/api/v1/events/memories?subject_id=user_123" \
  -H "x-mnexium-key: $MNX_KEY" \
  -H "Accept: text/event-stream"
```

**Recommendation:** Use SSE instead of polling for real-time updates. Events are delivered immediately when memories change and reduce unnecessary API traffic.