UnisonIngesting data
POST /v1/brain/ingest streams conversations and documents into the brain - conversations run entity resolution and fact extraction, documents become extractable notes.
POST /v1/brain/ingest is the primary write: batch up to 100 items per call. Conversations are routed through the signal-extraction pipeline (entity resolution + fact extraction); documents are written as extractable notes. Extraction runs async - the response returns job ids, not extracted facts.
Item shapes
// Conversation
{
type: "conversation",
turns: [{ role: "user" | "assistant" | "system", content: string, name?: string }],
sourceRef: string, // stable caller-side id (session / thread id)
visibility?: "workspace" | "private", // default "private"
idempotencyKey?: string
}
// Document
{
type: "document",
content: string,
title?: string,
path?: string, // brain path; auto-routed if omitted
tags?: string[],
visibility?: "workspace" | "private",
sourceRef?: string
}Response
{ items: (
| { type: "conversation", jobId: string }
| { type: "document", docId: string, path: string, jobIds: string[] }
)[] }Example
curl -X POST https://brain.unisonlabs.ai/v1/brain/ingest \
-H "Authorization: Bearer $UNISON_TOKEN" -H 'content-type: application/json' \
-d '{
"items": [{
"type": "conversation",
"sourceRef": "session-42",
"turns": [
{ "role": "user", "content": "lets switch the queue to pgmq" },
{ "role": "assistant", "content": "Done - migrated worker to pgmq, dropped redis." }
]
}]
}'Use idempotencyKey when re-running pipelines so retries don't double-ingest. Set visibility: "workspace" to share extracted knowledge with the whole workspace immediately; default is private. Track extraction with unison jobs ls (scope brain:admin) or GET /v1/brain/status (pendingJobs, lastIngestAt).
For direct document writes with full control (path, kind, tags, optimistic concurrency), use PUT /v1/brain/doc - see Path namespaces.