# API Documentation

## Profiles

Schema-backed profile subsystem for stable user attributes, controlled field updates, and extraction-compatible identity context.

### Overview

Profiles provide structured, schema-defined data about subjects. Unlike free-form memories, profile fields have defined keys (like `name`, `email`, `timezone`) and are automatically extracted from conversations or can be set via API.

#### Automatic Extraction

When `learn: true`, the LLM extracts profile fields from conversation context.

#### Superseding

New values automatically supersede old ones. Higher confidence or manual edits take priority.

## GET `/api/v1/profiles`

Get the profile for a subject. Returns all profile fields with their values and metadata.

**Scope:** `profiles:read`

- **`subject_id`** (required): string - The subject ID to get profile for.
- **`format`**: string - Response format: "simple" (default) returns key-value pairs, "full" returns detailed metadata including confidence, source, and timestamps.

### Request (Simple)

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

### Response (Simple)

```json
{
  "data": {
    "name": "Sarah Chen",
    "email": "sarah@example.com",
    "timezone": "America/New_York",
    "language": "English"
  }
}
```

### Request (Full)

```bash
curl -G "https://www.mnexium.com/api/v1/profiles" \
  -H "x-mnexium-key: $MNX_KEY" \
  --data-urlencode "subject_id=user_123" \
  --data-urlencode "format=full"
```

### Response (Full)

```json
{
  "data": {
    "name": {
      "value": "Sarah Chen",
      "confidence": 0.95,
      "source_type": "chat",
      "updated_at": "2024-12-15T10:30:00Z",
      "memory_id": "mem_abc123"
    },
    "timezone": {
      "value": "America/New_York",
      "confidence": 0.85,
      "source_type": "chat",
      "updated_at": "2024-12-14T09:00:00Z",
      "memory_id": "mem_xyz789"
    }
  }
}
```

## PATCH `/api/v1/profiles`

Update profile fields for a subject. Supports batch updates with confidence scores.

**Scope:** `profiles:write`

- **`subject_id`** (required): string - The subject ID to update profile for.
- **`updates`** (required): array - Array of field updates. Each update must have `field_key` and `value`.

### Request

```bash
curl -X PATCH "https://www.mnexium.com/api/v1/profiles" \
  -H "x-mnexium-key: $MNX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_id": "user_123",
    "updates": [
      { "field_key": "name", "value": "Sarah Chen", "confidence": 1.0 },
      { "field_key": "timezone", "value": "America/New_York" }
    ]
  }'
```

### Response

```json
{
  "data": {
    "results": [
      { "field_key": "name", "created": true, "skipped": false },
      { "field_key": "timezone", "created": true, "skipped": false }
    ]
  }
}
```

**Note:** Updates with `confidence: 1.0` are treated as manual edits and will supersede any existing value regardless of its confidence. Lower confidence values may be rejected if a higher-confidence value already exists.

## DELETE `/api/v1/profiles`

Delete a specific profile field for a subject. The underlying memory is soft-deleted.

**Scope:** `profiles:write`

- **`subject_id`** (required): string - The subject ID.
- **`field_key`** (required): string - The profile field key to delete (e.g., "timezone").

### Request

```bash
curl -X DELETE "https://www.mnexium.com/api/v1/profiles?subject_id=user_123&field_key=timezone" \
  -H "x-mnexium-key: $MNX_KEY"
```

### Response

```json
{
  "data": {
    "deleted": true,
    "field_key": "timezone"
  }
}
```

## GET `/api/v1/profiles/schema`

Get the active profile schema for the project, including system and custom fields.

**Scope:** `profiles:read`

### Request

```bash
curl "https://www.mnexium.com/api/v1/profiles/schema" \
  -H "x-mnexium-key: $MNX_KEY"
```

### Response

```json
{
  "data": {
    "version": 1,
    "extraction_mode": "auto",
    "fields": [
      { "key": "name", "type": "text", "required": true },
      { "key": "email", "type": "email", "required": false },
      { "key": "timezone", "type": "timezone", "required": false }
    ]
  }
}
```

### Profile Schema

Each project has a configurable profile schema that defines which fields are available. The schema includes both system fields (name, email, timezone, language) and custom fields you define.

#### Default System Fields

- **`name`**: User's full name
- **`email`**: Email address
- **`timezone`**: User's timezone (e.g., "America/New_York")
- **`language`**: Preferred language

#### Source Types

- **`chat`**: Automatically extracted from conversation
- **`manual`**: Set via UI or API with high confidence
- **`api`**: Set via API