Documentation
Claims
Dashboard

API Documentation

Node SDKPython SDKDownload Skill

Typed fact graph operations for truth resolution, slot-based supersession, lineage inspection, and reversible claim state transitions.

Claims
GETtruthGET:slotGETslotsGETgraphGEThistoryGET:idPOSTclaimsPOSTretract

Claims are structured, slot-anchored facts extracted from memories. While memories store raw text, claims provide a precise graph of what the system believes about a subject — with automatic supersession, provenance tracking, and conflict resolution.

Slot
A canonical bucket for a claim type (e.g., favorite_color, works_at). Single-valued slots allow only one active claim at a time.
Predicate
The relationship type (e.g., favorite_color, lives_in, pet_name).
Truth
The current active claim for each slot — what the system believes right now about the subject.
GET/api/v1/claims/subject/:subject_id/truth

Get the current truth for a subject — all active slot values. This is the primary 'what do we believe?' endpoint.

Scope:memories:read
subject_idrequired
path
The subject to get truth for.
include_source
boolean
Include provenance (memory_id, observation_id). Default: true
Request
bash
curl "https://www.mnexium.com/api/v1/claims/subject/user_123/truth" \
  -H "x-mnexium-key: $MNX_KEY"
Response
json
{
  "subject_id": "user_123",
  "project_id": "proj_abc",
  "slot_count": 2,
  "slots": [
    {
      "slot": "favorite_color",
      "active_claim_id": "clm_xyz789",
      "predicate": "favorite_color",
      "object_value": "yellow",
      "claim_type": "preference",
      "confidence": 0.95,
      "updated_at": "2024-12-15T10:30:00Z",
      "source": { "memory_id": "mem_abc", "observation_id": null }
    },
    {
      "slot": "works_at",
      "active_claim_id": "clm_def456",
      "predicate": "works_at",
      "object_value": "Acme Corp",
      "claim_type": "fact",
      "confidence": 0.9,
      "updated_at": "2024-12-14T09:00:00Z",
      "source": { "memory_id": "mem_def", "observation_id": null }
    }
  ]
}
GET/api/v1/claims/subject/:subject_id/slot/:slot

Get the current value for a specific slot. Quick lookup for single values like 'what is their favorite color?'

Scope:memories:read
subject_idrequired
path
The subject ID.
slotrequired
path
The slot/predicate to look up (e.g., favorite_color, works_at).
Request
bash
curl "https://www.mnexium.com/api/v1/claims/subject/user_123/slot/favorite_color" \
  -H "x-mnexium-key: $MNX_KEY"
Response
json
{
  "subject_id": "user_123",
  "project_id": "proj_abc",
  "slot": "favorite_color",
  "active_claim_id": "clm_xyz789",
  "predicate": "favorite_color",
  "object_value": "yellow",
  "claim_type": "preference",
  "confidence": 0.95,
  "updated_at": "2024-12-15T10:30:00Z",
  "tags": ["preference"],
  "source": { "memory_id": "mem_abc", "observation_id": null }
}
Returns 404 if the slot has no active claim.
GET/api/v1/claims/subject/:subject_id/history

Get claim history showing how values evolved over time. See supersession chains and previous values.

Scope:memories:read
subject_idrequired
path
The subject ID.
slot
string
Optional. Filter to a specific slot/predicate.
limit
number
Max claims to return. Default: 100, Max: 500
Request
bash
curl -G "https://www.mnexium.com/api/v1/claims/subject/user_123/history" \
  -H "x-mnexium-key: $MNX_KEY" \
  --data-urlencode "slot=favorite_color"
Response
json
{
  "subject_id": "user_123",
  "project_id": "proj_abc",
  "slot_filter": "favorite_color",
  "total_claims": 2,
  "by_slot": {
    "favorite_color": [
      {
        "claim_id": "clm_xyz789",
        "predicate": "favorite_color",
        "object_value": "yellow",
        "confidence": 0.95,
        "asserted_at": "2024-12-15T10:30:00Z",
        "is_active": true,
        "replaced_by": null
      },
      {
        "claim_id": "clm_old123",
        "predicate": "favorite_color",
        "object_value": "blue",
        "confidence": 0.9,
        "asserted_at": "2024-12-10T08:00:00Z",
        "is_active": false,
        "replaced_by": "clm_xyz789"
      }
    ]
  },
  "edges": [...]
}
GET/api/v1/claims/subject/:subject_id/slots

List slot states for a subject, grouped by active/superseded/other status.

Scope:memories:read
subject_idrequired
path
The subject ID.
limit
number
Max slots to return. Default: 100, Max: 500
Request
bash
curl "https://www.mnexium.com/api/v1/claims/subject/user_123/slots?limit=100" \
  -H "x-mnexium-key: $MNX_KEY"
Response
json
{
  "subject_id": "user_123",
  "total": 3,
  "active_count": 2,
  "slots": {
    "active": [{ "slot": "favorite_color", "active_claim_id": "clm_xyz789" }],
    "superseded": [{ "slot": "favorite_color", "active_claim_id": "clm_old123" }],
    "other": []
  }
}
GET/api/v1/claims/subject/:subject_id/graph

Get a claim graph snapshot (claims + typed edges) for a subject.

Scope:memories:read
subject_idrequired
path
The subject ID.
limit
number
Max claims to include. Default: 50, Max: 200
Request
bash
curl "https://www.mnexium.com/api/v1/claims/subject/user_123/graph?limit=50" \
  -H "x-mnexium-key: $MNX_KEY"
Response
json
{
  "subject_id": "user_123",
  "claims_count": 2,
  "edges_count": 1,
  "edges_by_type": { "supersedes": 1 },
  "claims": [...],
  "edges": [...]
}
POST/api/v1/claims

Create a claim directly. Automatically computes slot, triggers graph linking, and handles supersession.

Scope:memories:write
subject_idrequired
string
The subject this claim is about.
predicaterequired
string
The relationship type (e.g., favorite_color, works_at, pet_name).
object_valuerequired
string
The value (e.g., "yellow", "Acme Corp", "Max").
claim_type
string
Optional. Type: fact, preference, trait, event, goal, plan. Auto-inferred from predicate.
confidence
number
Optional. Confidence 0-1. Default: 0.8
importance
number
Optional. Importance 0-1. Default: 0.5
tags
array
Optional. Tags for categorization.
source_text
string
Optional. Source text that creates an observation for provenance.
Request
bash
curl -X POST "https://www.mnexium.com/api/v1/claims" \
  -H "x-mnexium-key: $MNX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_id": "user_123",
    "predicate": "favorite_color",
    "object_value": "yellow",
    "confidence": 0.95,
    "source_text": "User said: my favorite color is yellow"
  }'
Response
json
{
  "claim_id": "clm_xyz789",
  "subject_id": "user_123",
  "predicate": "favorite_color",
  "object_value": "yellow",
  "slot": "favorite_color",
  "claim_type": "preference",
  "confidence": 0.95,
  "observation_id": "obs_abc123",
  "linking_triggered": true
}
Execution model: Graph linking runs fire-and-forget after insert. Supersession and slot winner updates happen shortly after creation.
GET/api/v1/claims/:id

Get one claim with supporting assertions, connected edges, and supersession chain.

Scope:memories:read
idrequired
path
The claim ID.
Request
bash
curl "https://www.mnexium.com/api/v1/claims/clm_xyz789" \
  -H "x-mnexium-key: $MNX_KEY"
Response
json
{
  "claim": {
    "claim_id": "clm_xyz789",
    "subject_id": "user_123",
    "predicate": "favorite_color",
    "object_value": "yellow"
  },
  "assertions": [...],
  "edges": [...],
  "supersession_chain": [...]
}
POST/api/v1/claims/:id/retract

Soft-retract a claim. Preserves provenance and restores the previous claim as active if one exists.

Scope:memories:write
idrequired
path
The claim ID to retract.
reason
string
Optional. Reason for retraction: user_requested, incorrect, outdated, etc.
Request
bash
curl -X POST "https://www.mnexium.com/api/v1/claims/clm_xyz789/retract" \
  -H "x-mnexium-key: $MNX_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "user_requested" }'
Response
json
{
  "success": true,
  "claim_id": "clm_xyz789",
  "slot": "favorite_color",
  "previous_claim_id": "clm_old123",
  "restored_previous": true,
  "reason": "user_requested"
}
Note: If a previous claim exists for this slot, it will be restored as the active truth. The retracted claim is preserved for audit but no longer affects the subject's truth.

Claims vs Memories

Memories and claims work together but serve different purposes:

Memories — Raw extracted text from conversations. Good for context and recall. Example: "User mentioned they love hiking in the mountains"
Claims — Structured facts with predicates and values. Good for precise lookups and truth tracking. Example: hobby = hiking

When you use learn: true with the Chat API, both memories and claims are automatically extracted. Claims provide the structured graph; memories provide the rich context.