API-документація — Цифровий мозок

Старт

Усі REST-ендпоінти мають префікс /api/v1 і працюють із JSON. Сервер слухає порт 8080 (налаштовується через PORT). Кожен запит (крім /health) потребує API-ключа в заголовку.

Перший запит

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

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

REST-ендпоінти автентифікуються ключем у заголовку X-API-Key. Для транспорту MCP використовується Bearer-токен.

REST

Секретний API-ключ на всі REST-ендпоінти.

X-API-Key: <key>

MCP (Bearer)

Per-vault токен для транспорту /mcp.

Authorization: Bearer <token>

Конвенції

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

Формат помилки

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

Код	Значення
200 · 201 · 204	Успіх (отримано / створено / без тіла)
400	Помилка валідації
401	Невірний або відсутній ключ
404	Ресурс не знайдено
409	Конфлікт стану (напр., титул при відновленні)
503	Ембедер / Learn недоступні

Нотатки

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

POST/notesX-API-Key

Створити нотатку. Контент автоматично розбивається на чанки.

Тіло запиту

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

Відповідь · 201

{
  "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"
}

GET/notesX-API-Key

Список нотаток із пагінацією.

Параметр	Тип	Опис
page	int	Номер сторінки (з 1).
limit	int	Розмір сторінки.

GET/notes/{id}

Отримати нотатку за UUID.

PUT/notes/{id}

Частково оновити нотатку.

DELETE/notes/{id}

М'яке видалення (зворотне).

GET/notes/deleted

Кошик — список видалених нотаток.

POST/notes/{id}/restore

Відновити видалену нотатку.

POST/sync

Batch-upsert файлів: парсинг frontmatter і [[wikilinks]].

Пошук

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

GET/searchX-API-Key

Пошук нотаток у вибраному режимі.

Параметр	Тип	Опис
q *	string	Запит (обов'язковий для text / hybrid).
mode	enum	text · vector · hybrid (типово text).
limit	int	1–50 (типово 10).
embedding	base64	Готовий вектор; інакше сервер ембедить запит сам.

Відповідь · 200

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

GET/chunks/search

Пошук на рівні чанків — гранулярний RAG.

POST/search/graph-rag

Top-N семантично схожих нотаток + їхні сусіди в графі.

GET/notes/{id}/similar

Семантично схожі нотатки (за векторами).

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

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

GET/graph

Увесь граф сховища: вузли + ребра.

GET/notes/{id}/graph

Вхідні та вихідні зв'язки нотатки.

POST/links

Створити явний типізований зв'язок.

Тіло запиту

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

DELETE/links/{id}

Видалити зв'язок.

Чанки

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

POST/notes/{id}/chunks

Upsert чанків нотатки.

PUT/chunks/{id}/embedding

Оновити вектор окремого чанка.

GET/embeddings/stale

Нотатки з застарілими/відсутніми векторами (для воркера).

PUT/notes/{id}/embedding

Записати вектор нотатки.

Learn pipeline

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

POST/learn?stream=1

Режими: plan (запропонувати дії), execute (виконати план), auto (план + виконання впевнених дій), apply_links, rebuild_links. З ?stream=1 — SSE-потік подій.

Тіло запиту

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

GET/learn/runs

Аудит-лог операцій Learn.

GET/learn/runs/{id}

Деталі конкретного запуску (план + результат).

POST/notes/{id}/reanalyze

Перебудувати авто-зв'язки для нотатки.

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

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

GET/notes/{id}/at?at=…

Стан нотатки на момент часу.

GET/notes/{id}/history

Повна історія ревізій.

GET/notes/{id}/graph-at?at=…

Стан графа на момент часу.

GET/search/at?at=…

Текстовий пошук у минулому стані.

GET/vault/snapshot?at=…

Список нотаток, що існували на момент часу.

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

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

POST/vaults

Створити сховище.

GET/vaults

Список ваших сховищ.

DELETE/vaults/{id}

Видалити сховище (каскадно).

POST/mcp/tokens

Видати MCP Bearer-токен (повертається один раз).

GET/mcp/tokens

Список токенів (із префіксами, без секрету).

DELETE/mcp/tokens/{id}

Відкликати токен.

GET/mcp/info

Інфо про MCP-сервер і прив'язку.

GET/healthбез авторизації

Статус сервісу.

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

Сервер віддає набір інструментів через /mcp (Bearer) для Claude Desktop, Cursor, Claude Code. Частина реєструється лише за наявності ембедера / Learn-ключа.

search_notesпошук нотаток (text/vector/hybrid)

get_noteотримати нотатку за UUID

add_noteстворити нотатку, авточанкінг

update_noteчастково оновити нотатку

delete_note · restore_noteм'яке видалення і відновлення

list_deleted_notesкошик видалених нотаток

similar_notesсемантично схожі нотатки

note_graph · full_graphзв'язки нотатки / увесь граф

graph_ragtop-N + сусіди графа

create_linkтипізований зв'язок між нотатками

list_tags · notes_by_tagтеги і нотатки за тегом

chunk_searchпошук на рівні чанків

sync_notesbatch-upsert нотаток

get_note_at · note_historyтемпоральні запити

reanalyze_note · suggest_tagsавто-зв'язки і підказки тегів

learn_textкуратор: декомпозиція, дедуп, авто-лінк

record_interactionauto-capture: лог діалогу як знання

CLI

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

Команда	Опис
rdb serve	Запустити HTTP API-сервер.
rdb migrate	Застосувати/відкотити міграції.
rdb bootstrap	Ініціалізувати сховище і записати креденшіали.
rdb vault	Керування сховищами (list / create / delete).
rdb notes	CRUD нотаток, імпорт .md, пошук.
rdb mcp-stdio	MCP через stdin/stdout для `claude mcp add`.

Коди помилок

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

code	Значення
UNAUTHORIZED	Невірний або відсутній ключ.
VAULT_NOT_FOUND	Сховище не існує.
NOT_FOUND	Ресурс не знайдено.
TITLE_CONFLICT	Конфлікт титулу при відновленні.
EMBEDDER_UNAVAILABLE	Векторний пошук без налаштованого ембедера.
LEARN_UNAVAILABLE	Learn вимкнений (немає ключа).
LEARN_FAILED	Помилка Learn pipeline.

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

Старт

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

REST

MCP (Bearer)

Конвенції

Нотатки

Пошук

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

Чанки

Теги

Learn pipeline

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

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

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

CLI

Коди помилок