Documentation
Records
Dashboard

API Documentation

Node SDKPython SDKDownload Skill

Schema-defined entity layer with CRUD, filtering, and semantic retrieval to support deterministic business data in agent workflows.

Records
POSTschemasGETschemasGET:typePOST:typeGET:idPUT:idDELETE:idPOSTqueryPOSTsearch

Overview

Records provide a transactional, schema-backed data API with full CRUD, structured filtering, and semantic search. Unlike memories, records let you define typed schemas and store structured objects that your AI can query and reason over.

Use cases: CRM contacts, product catalogs, knowledge bases, task lists, inventory, support tickets — any structured data your AI needs to read, write, and search.

AI Integration: Records can be automatically recalled and learned during chat via the mnx.records config — the LLM can read and write structured data as part of the conversation flow.

1. Define a Schema

Schemas define the structure of your records. Each schema has a type_name and a set of typed fields.

type_namerequired
string
Unique identifier for the record type (e.g., "account", "deal", "ticket").
fieldsrequired
object
Field definitions — keys are field names, values describe the type and constraints.
display_name
string
Human-readable name for the schema.
description
string
Description of what this record type represents.
bash
curl -X POST "https://www.mnexium.com/api/v1/records/schemas" \
  -H "x-mnexium-key: $MNX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type_name": "account",
    "display_name": "Customer Account",
    "description": "CRM customer accounts",
    "fields": {
      "name": { "type": "text", "required": true },
      "industry": { "type": "text" },
      "revenue": { "type": "number" },
      "is_active": { "type": "boolean" }
    }
  }'

2. Insert Records

Create a record of a given type. The data is validated against the schema and automatically embedded for semantic search.

datarequired
object
Record data matching the schema fields.
owner_id
string
Owner subject ID for access control.
visibility
string
Access level: "public" (default) or "private".
collaborators
string[]
Subject IDs that can read/write this record.
bash
curl -X POST "https://www.mnexium.com/api/v1/records/account" \
  -H "x-mnexium-key: $MNX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "name": "TechCorp",
      "industry": "Technology",
      "revenue": 5000000,
      "is_active": true
    },
    "owner_id": "user_123",
    "visibility": "private",
    "collaborators": ["user_456"]
  }'

3. Get, Update & Delete

Standard CRUD operations on individual records.

bash
# Get a record
curl "https://www.mnexium.com/api/v1/records/account/rec_abc123" \
  -H "x-mnexium-key: $MNX_KEY"

# Update (partial merge)
curl -X PUT "https://www.mnexium.com/api/v1/records/account/rec_abc123" \
  -H "x-mnexium-key: $MNX_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "revenue": 7500000 } }'

# Delete (soft)
curl -X DELETE "https://www.mnexium.com/api/v1/records/account/rec_abc123" \
  -H "x-mnexium-key: $MNX_KEY"

4. Query with Filters

Filter records with field-value matching and server-side sorting.

where
object
Exact-match filter object (all provided fields must match).
order_by
string
Field to sort by (prefix with - for descending).
limit
number
Max records to return.
offset
number
Pagination offset.
bash
curl -X POST "https://www.mnexium.com/api/v1/records/account/query" \
  -H "x-mnexium-key: $MNX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "where": {
      "industry": "Technology",
      "is_active": true
    },
    "order_by": "-revenue",
    "limit": 10
  }'
// Response
{
  "records": [
    {
      "record_id": "rec_abc123",
      "type_name": "account",
      "data": { "name": "TechCorp", "industry": "Technology", "revenue": 7500000, "is_active": true },
      "owner_id": "user_123",
      "visibility": "private",
      "created_at": "2025-01-15T10:00:00Z"
    }
  ]
}

5. Semantic Search

Search records by natural language query using pgvector embeddings. Records are automatically embedded on insert/update.

queryrequired
string
Natural language search query.
limit
number
Max results to return.
bash
curl -X POST "https://www.mnexium.com/api/v1/records/account/search" \
  -H "x-mnexium-key: $MNX_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "enterprise technology companies", "limit": 5 }'

6. Access Control

Records support fine-grained access control via owner_id, visibility, and collaborators.

Read access

public records are visible to all. private records are visible only to the owner and collaborators.

Write access

Only the owner or collaborators can update or delete a record. System actors (no subject_id) bypass ownership checks.

AI-Powered Records in Chat

Enable automatic record recall and learning during conversations via the mnx.records config:

bash
curl -X POST "https://www.mnexium.com/api/v1/chat/completions" \  -H "x-mnexium-key: $MNX_KEY" \  -H "x-openai-key: $OPENAI_KEY" \  -d '{    "model": "gpt-4o-mini",    "messages": [{ "role": "user", "content": "What deals do we have with TechCorp?" }],    "mnx": {      "subject_id": "user_123",      "records": {        "recall": true,        "learn": "auto",        "tables": ["account", "deal"]      }    }  }'

When records.recall: true, relevant records are injected into the LLM context. Set records.learn to "auto", "force", or false. When using "force", records.tables is required. Set records.sync to true to block the response until writes complete. For dependency graphs (for example, fields typed as ref:<type>), partial writes fail the request.

How mnx.records Expands

In chat requests, mnx.records controls two independent runtime steps: record recall before generation, and structured extraction after generation.

json
{
  "mnx": {
    "subject_id": "user_123",
    "records": {
      "recall": true,
      "learn": "force",
      "sync": true,
      "tables": ["account", "deal"]
    }
  }
}
recall: true → injects relevant records from selected schemas into model context.
learn: "auto" → runs async selective extraction by default; for streaming requests with explicit write intent and scoped tables, Mnexium attempts a pre-stream write first.
learn: "force" → higher-intent extraction with required table allowlist.
sync: true → response waits for writes; if a dependency graph write is partial, the request fails.
tables → scopes recall/extraction to specific schemas.
ref:<type> fields → extraction plans can link operations using {"$ref":"op_id"} (or @ref:op_id) and Mnexium resolves DB-generated record IDs in dependency order.

Extraction Classifier Timeout

Classification timeout is configurable via MNX_EXTRACT_CLASSIFY_TIMEOUT_MS. Values are clamped to 250..15000 ms. Invalid values fall back to 2000 ms.

On timeout/failure, Mnexium keeps existing fallback behavior and routes extraction as both_unclassified.