API Documentation

Node SDK Python SDK Download Skill

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

Profiles

GETprofilesPATCHprofilesDELETEprofilesGETschema

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_idrequired

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_idrequired

string

The subject ID to update profile for.

updatesrequired

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_idrequired

string

The subject ID.

field_keyrequired

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

nameUser's full name

emailEmail address

timezoneUser's timezone (e.g., "America/New_York")

languagePreferred language

Source Types

chatAutomatically extracted from conversation

manualSet via UI or API with high confidence

apiSet via API