API Цифрового мозку

Старт

Усі REST-ендпоінти мають префікс /api/v1 і працюють із JSON. Дані живуть у сховищах (vault): ключ акаунта разом із X-Vault-ID вибирає, у якому працювати. Ключ акаунта й id сховища — у кабінеті: «Інтеграції» → «Доступ до API»; там же — рядки export з вашими значеннями для змінних DB_API_KEY і DB_VAULT_ID з прикладів нижче.

curl -s https://api.digital-brain.io/api/v1/vaults \
  -H "X-API-Key: $DB_API_KEY"

curl -s https://api.digital-brain.io/api/v1/notes?limit=5 \
  -H "X-API-Key: $DB_API_KEY" \
  -H "X-Vault-ID: $DB_VAULT_ID"

Автентифікація

REST-ендпоінти автентифікуються ключем у заголовку X-API-Key: ключ акаунта (з X-Vault-ID) або ключ сховища dbk_…, який уже знає своє сховище. Для MCP — той самий ключ сховища або MCP-токен у Authorization: Bearer.

Конвенції

Тіла запитів і відповідей — JSON. Списки пагінуються через ?page=&limit=. Часові мітки — у форматі RFC3339. Ідентифікатори — UUID.

{
  "error": "note not found",
  "code": "NOT_FOUND"
}

Нотатки

Повний CRUD із м'яким видаленням і відновленням, плюс batch-синхронізація з Markdown-файлів.

{
  "title": "ADR-012: міграції в бінарник",
  "content": "Вбудовуємо міграції через //go:embed…",
  "tags": ["adr", "migrations"],
  "priority": 7,
  "file_path": "adr/012.md"
}

{
  "id": "a3f1c8e2-…",
  "title": "ADR-012: міграції в бінарник",
  "tags": ["adr", "migrations"],
  "priority": 7,
  "embedding_current": false,
  "created_at": "2026-06-22T10:00:00Z",
  "updated_at": "2026-06-22T10:00:00Z"
}

Пошук

Три режими в одному ендпоінті: text (повнотекстовий), vector (семантичний), hybrid (text×0.3 + vector×0.7). Плюс GraphRAG для розширеного контексту.

{
  "mode": "hybrid",
  "total": 1,
  "results": [
    {
      "id": "a3f1c8e2-…",
      "title": "ADR-012: міграції в бінарник",
      "excerpt": "Вбудовуємо міграції через //go:embed…",
      "tags": ["adr", "migrations"],
      "final_score": 0.87
    }
  ]
}

Граф і зв'язки

Типізовані зв'язки між нотатками: reference, extends, contradicts, inspired_by, example_of.

{
  "source_id": "a3f1…",
  "target_id": "b7c2…",
  "link_type": "extends",
  "weight": 1.0
}

Чанки

Контент авточанкується при створенні/оновленні. Ці ендпоінти дають ручний контроль для воркерів і кастомного RAG.

Теги

Learn pipeline

LLM-куратор розбиває сирий текст на факти, шукає схожі й вирішує CREATE / EXTEND / CONTRADICT / LINK. Доступний лише коли заданий LEARN_API_KEY або OPENAI_API_KEY.

{
  "text": "сирий markdown або проза…",
  "mode": "auto",
  "sensitivity": "medium"
}

Темпоральні запити

Історичний стан нотаток через ревізії. Параметр at — мітка RFC3339.

Vaults, MCP-токени і доступ

Кожне сховище ізольоване й має власний доступ. MCP-токени видаються на конкретне сховище й повертаються лише раз.

MCP-інструменти

https://api.digital-brain.io/mcp — MCP-сервер (streamable HTTP) для Claude Code, Claude Desktop, Cursor та інших клієнтів. Кабінет генерує готовий конфіг для кожного клієнта в один клік; вручну — так:

claude mcp add --transport http digital-brain --scope user \
  https://api.digital-brain.io/mcp --header "Authorization: Bearer $TOKEN"

{ "mcpServers": { "digital-brain": {
  "url": "https://api.digital-brain.io/mcp",
  "headers": { "Authorization": "Bearer <TOKEN>" } } } }

Ключ сховища з правом лише read замість токена дає агенту пам'ять, яку він не може змінити. Кожен інструмент позначений для клієнта як «лише читання» чи «змінює дані», тож читання можна дозволяти без підтвердження.

CLI

Бінарник rdb керує сервером, міграціями і нотатками.

Коди помилок

Поле code у тілі помилки дозволяє обробляти кейси програмно. Нижче — найчастіші; повний перелік — у довіднику.