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.
Saving structured data
Ingest direct or event-centric triple sets into the knowledge graph
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) withBrainPAT+ brain scope (X-Brain-ID/brain_id)- Body:
{ "data": [IngestionTripleSet, …], "anchor"?, "text"?, "mode"?, "brain_id"? }— not oldjson_data/ element schema - Expect 202 +
task_id; pollGET /tasks/{id}; 404 = unknown task - Direct triple: required
subject+subj_event+object, witheventandevent_objomitted - Event-centric triple:
eventandevent_objmust both be present;objectis 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--> ATTREvent-centric facts preserve an action, timestamp, or provenance-bearing hub:
[subject?] --subj_event--> [event] --event_obj--> [object]
^
optional anchorevent 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
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, …). |
Node fields (RequestPartialNode)
Prop
Type
Predicate fields (RequestPartialPredicate)
Prop
Type
anchor (PartialNodeFilter)
Must include either uuid, or both name and type. Plain strings are rejected.
Prop
Type
Submit a staged batch
When staged enrichment is enabled, POST /ingest/structured/batch accepts a JSON array of 1–100 structured ingestion requests with a combined body limit of 12 MiB. The response is HTTP 202 with one root task ID. Use that ID to poll or cancel the entire batch. A deployment without staged enrichment returns HTTP 404 for this endpoint. Batch API reference
Related
Last updated on
