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)

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

Response (Simple)

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

Request (Full)

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)

{
  "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

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

{
  "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

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

Response

{
  "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

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

Response

{
  "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