Saving structured data

For the complete BrainAPI documentation index, see llms.txt. A markdown version of any docs page is available by appending .md to its URL. Docs MCP: /docs/mcp.

Structured ingestion lets you push already-shaped facts into the brain instead of asking an LLM to infer them from free text. Use direct triples for timeless structure such as product attributes and preferences; use event-centric triples for actions whose identity or time matters.

POST /ingest/structured accepts a list of IngestionTripleSet objects, an optional anchor that ties the new facts into an existing node, and optional text for extra context. The API returns 202 Accepted with a task_id. Poll status with task polling.

For agents

POST https://brainapi.lumen-labs.ai/ingest/structured (or your deploy URL) with BrainPAT + brain scope (X-Brain-ID / brain_id)
Body: { "data": [IngestionTripleSet, …], "anchor"?, "text"?, "mode"?, "brain_id"? } — not old json_data / element schema
Expect 202 + task_id; poll GET /tasks/{id}; 404 = unknown task
Direct triple: required subject + subj_event + object, with event and event_obj omitted
Event-centric triple: event and event_obj must both be present; object is always required

The previous element-based payload (json_data, metadata, types, identification_params, textual_data, observate_for) is removed. Send event-centric triples only.

Choose direct or event-centric shape

Direct edges represent stable structure without manufacturing an event:

[subject] --subj_event--> [object]

PRODUCT --HAS--> ATTR
USER --PREFERS--> ATTR

Event-centric facts preserve an action, timestamp, or provenance-bearing hub:

[subject?] --subj_event--> [event] --event_obj--> [object]
                              ^
                         optional anchor

event and event_obj are a pair: sending only one is a validation error. A legacy HAS → HAS-event → HAS wrapper with no happened_at is collapsed to one direct HAS edge. A dated event is preserved as two edges.

Processing modes

Mode	Submitted triples	Optional `text`	LLM behavior
`deterministic`	Persisted directly	Ignored for enrichment	No Scout/Architect; anchor must resolve exactly
`hybrid`	Persisted first	May add context/enrichment	Optional LLM enrichment without re-persisting submitted triples
`enrich`	Persisted first	Used for backfill	Explicit LLM enrichment path

When mode is omitted, BrainAPI chooses hybrid if text is present and deterministic otherwise. Deterministic anchors resolve by UUID or exact name + type and fail closed when unresolved.

Direct preference example

{
  "data": [
    {
      "subject": {"uuid": "user:u01", "name": "u01", "type": "USER"},
      "subj_event": {"name": "PREFERS", "amount": 0.8},
      "object": {"uuid": "hub:attr:70s", "name": "70s", "type": "ATTR"}
    }
  ],
  "mode": "deterministic",
  "brain_id": "commerce"
}

Quick path

Submit one purchase event anchored to a user, then poll the task:

curl -X POST "<DEPLOYMENT_URL>/ingest/structured" \
  -H "Content-Type: application/json" \
  -H "BrainPAT: YOUR_BRAIN_PAT" \
  -H "X-Brain-ID: ecommerce" \
  -d '{
    "data": [
      {
        "subject": {
          "name": "Alice",
          "type": "Person",
          "properties": { "user_id": "123" }
        },
        "subj_event": { "name": "MADE" },
        "event": {
          "name": "Product purchase",
          "type": "Event",
          "happened_at": "2026-01-01T00:00:00Z"
        },
        "event_obj": { "name": "TARGETED" },
        "object": {
          "name": "Product 1",
          "type": "Product",
          "description": "Wireless headphones",
          "properties": { "product_id": "sku-123" }
        }
      }
    ],
    "anchor": { "name": "Alice", "type": "Person" },
    "text": "Alice purchased Product 1 during checkout.",
    "brain_id": "ecommerce"
  }'

Expected response shape:

{
  "message": "Structured ingestion accepted",
  "task_id": "…"
}

HTTP status: 202.

Example payloads

A user likes a post. Anchor the batch to the liking user so the event hangs off their graph.

{"data": [  {    "subject": {      "name": "John Doe",      "type": "Person",      "properties": { "user_id": "123" }    },    "subj_event": { "name": "MADE" },    "event": {      "name": "Post liked",      "type": "Event",      "happened_at": "2026-01-01T00:00:00Z",      "properties": { "action": "POST_LIKED" }    },    "event_obj": { "name": "TARGETED" },    "object": {      "name": "Post 123",      "type": "Post",      "description": "This is the title of the post that was liked.",      "properties": { "post_id": "123", "author_id": "312" }    }  }],"anchor": { "name": "John Doe", "type": "Person" },"text": "John Doe liked post 123.","brain_id": "socialnetwork"}

Usage

Available via REST, Python SDK, and TypeScript SDK.

const result = await brain.ingestStructuredData({data: [  {    subject: { name: "Alice", type: "Person" },    subj_event: { name: "MADE" },    event: { name: "Product purchase", type: "Event", happened_at: "2026-01-01T00:00:00Z" },    event_obj: { name: "TARGETED" },    object: { name: "Product 1", type: "Product" },  },],anchor: { name: "Alice", type: "Person" },text: "Alice purchased Product 1.",brain_id: "example01",});// result.task_id — poll GET /tasks/{task_id}

Request body

Prop

Type

`IngestionTripleSet`

Field	Required	Description
`subject`	conditional	Required with `subj_event` for a direct triple; optional actor for an event-centric triple.
`subj_event`	conditional	Required with `subject` for a direct triple; optional subject → event predicate for an event-centric triple.
`event`	paired	Event hub node. Must be supplied together with `event_obj`, or both omitted.
`event_obj`	paired	Event → object predicate. Must be supplied together with `event`, or both omitted.
`object`	yes	Target node (product, post, article, …).