Documents

Read, write, edit, and list markdown documents at brain paths. Path root decides visibility: /private/, /workspace/teams/<slug>/, or /workspace/.

Documents are markdown files stored at brain paths. The path root decides who sees them — write to /private/ for caller-only, /workspace/teams/<slug>/ for a team, /workspace/ for the whole workspace. Every path must end in .md.

Write a document

import { BrainClient } from "@unisonlabs/sdk";

const brain = new BrainClient({ token: process.env.UNISON_TOKEN });

await brain.write({
  path: "/private/notes/onboarding.md",
  bodyMd: "# Onboarding notes\n\nDeploy with `bun run deploy`.",
  title: "Onboarding notes",
});

from unisonlabs import UnisonBrain

client = UnisonBrain()
client.write("/private/notes/onboarding.md", "# Onboarding notes\n\nDeploy with `bun run deploy`.")

curl -X PUT https://brain.unisonlabs.ai/v1/brain/doc \
  -H "Authorization: Bearer $UNISON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "path": "/private/notes/onboarding.md", "bodyMd": "# Onboarding notes\n\nDeploy with `bun run deploy`.", "title": "Onboarding notes" }'

Read a document

const doc = await brain.get("/private/notes/onboarding.md");
console.log(doc.bodyMd);

curl 'https://brain.unisonlabs.ai/v1/brain/doc?path=%2Fprivate%2Fnotes%2Fonboarding.md' \
  -H "Authorization: Bearer $UNISON_TOKEN"

Edit (patch) a document

PATCH /v1/brain/doc updates individual fields without a full rewrite. Supports optimistic concurrency via etag:

curl -X PATCH https://brain.unisonlabs.ai/v1/brain/doc \
  -H "Authorization: Bearer $UNISON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "path": "/private/notes/onboarding.md", "bodyMd": "# Onboarding\n\nUpdated deploy step.", "etag": "abc123" }'

Omit etag to skip the concurrency check. A stale etag returns 409 conflict.

List documents

curl 'https://brain.unisonlabs.ai/v1/brain/list?prefix=%2Fworkspace%2Fdecisions%2F' \
  -H "Authorization: Bearer $UNISON_TOKEN"

CLI: unison ls /workspace/decisions/

Delete a document

curl -X DELETE 'https://brain.unisonlabs.ai/v1/brain/doc?path=%2Fprivate%2Fnotes%2Fonboarding.md' \
  -H "Authorization: Bearer $UNISON_TOKEN"

Batch write

PUT /v1/brain/docs (plural) accepts an array of {path, bodyMd, title?, tags?} items — useful for seeding a brain from an existing knowledge base without calling ingest:

curl -X PUT https://brain.unisonlabs.ai/v1/brain/docs \
  -H "Authorization: Bearer $UNISON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "docs": [{ "path": "/workspace/runbooks/deploy.md", "bodyMd": "…", "title": "Deploy runbook" }] }'

Path rules

Must start with /private/, /workspace/teams/<slug>/, or /workspace/
Must end in .md
/system/ and /private/sources/ are read-only; writes return 403

See also: Scopes & visibility · API reference