REST API

REST API v1 Doska для CI и скриптов: обновление диаграмм из кода, импорт и проверка инфраструктуры, публикация Markdown-документов из git.

REST API помогает CI и скриптам держать Doska в согласии с репозиториями: отправлять код диаграмм на доску, перестраивать схему инфраструктуры после terraform apply, проверять нарисованную вручную схему на расхождения и публиковать папку Markdown-файлов как документы. Изменения проходят через живую доску, поэтому все, у кого она открыта, видят их сразу.

#Аутентификация

Каждый запрос передаёт API-токен в заголовке Authorization:

curl -s https://getdoska.top/api/v1/boards/$BOARD_ID/diagrams \
  -H "Authorization: Bearer $DOSKA_TOKEN"

Токен создаётся в разделе Настройки и API-токены → Токены доступа → Создать токен. Он привязан к одной организации, может быть ограничен проектами и имеет уровень: read, comment или edit. Токен никогда не даёт больше прав, чем у владельца: токен edit не позволит менять доску, где вы наблюдатель. Подробнее — на странице Claude и MCP.

Токены работают только для /api/v1/* и MCP. Остальные адреса отвечают 403 с кодом token_forbidden. Запросы и ответы — в JSON.

ID доски и проекта видны в адресной строке: https://getdoska.top/b/<boardId> и https://getdoska.top/p/<projectId>.

#Диаграммы

diagramId — ваш стабильный идентификатор диаграммы на доске: латиница, цифры, - и _, до 64 символов. Например, architecture.

#Создать или обновить диаграмму

PUT /api/v1/boards/:boardId/diagrams/:diagramId · уровень токена edit, роль на доске «Редактор»

Создаёт диаграмму, если её нет, или применяет новый код к существующей по тем же правилам, что и кнопка Применить в редакторе кода: ручные позиции и стили сохраняются.

jq -Rs '{source: ., name: "Архитектура"}' docs/architecture.mmd | \
  curl -fsS -X PUT "https://getdoska.top/api/v1/boards/$BOARD_ID/diagrams/architecture" \
    -H "Authorization: Bearer $DOSKA_TOKEN" -H "Content-Type: application/json" --data-binary @-

Ответ: 201, если диаграмма создана, 200, если обновлена.

{
  "ok": true,
  "created": false,
  "summary": { "nodesAdded": 1, "nodesUpdated": 0, "nodesRemoved": 0, "edgesAdded": 1, "edgesUpdated": 0,
               "edgesRemoved": 0, "groupsAdded": 0, "groupsUpdated": 0, "groupsRemoved": 0,
               "moved": 0, "overridesKept": 0, "detached": 0 },
  "diagnostics": []
}

Если в коде ошибки, ответ — 422, и доска не меняется:

{
  "error": "Код диаграммы содержит ошибки — доска не изменена",
  "code": "invalid_diagram",
  "diagnostics": [{ "line": 2, "col": 6, "severity": "error", "message": "Не закрыта фигура узла «api»: ожидалось «]»" }]
}

#Прочитать диаграммы

GET /api/v1/boards/:boardId/diagrams · уровень токена read

[{ "id": "architecture", "name": "Архитектура", "appliedAt": 1761480000000, "hasUnappliedChanges": false }]

GET /api/v1/boards/:boardId/diagrams/:diagramId · уровень токена read

Возвращает { id, name, source, draft, appliedAt, revisions }. source — последний применённый код, draft — то, что сейчас в редакторе кода, revisions — число сохранённых ревизий.

#Удалить диаграмму

DELETE /api/v1/boards/:boardId/diagrams/:diagramId · уровень токена edit, роль на доске «Редактор»

Удаляет диаграмму вместе со всеми её элементами на доске. Ответ: { "ok": true }.

#Проверить код

POST /api/v1/diagrams/validate · любой токен

Проверяет код, не трогая доску. Удобно для pre-commit хука.

jq -Rs '{source: .}' docs/architecture.mmd | \
  curl -fsS -X POST https://getdoska.top/api/v1/diagrams/validate \
    -H "Authorization: Bearer $DOSKA_TOKEN" -H "Content-Type: application/json" --data-binary @-

Ответ: { ok, diagnostics, stats: { nodes, edges, subgraphs } }; при ошибках stats равно null.

#Инфраструктура

Схемы из Terraform (terraform show -json или файл состояния), манифестов Kubernetes (в том числе вывода helm template) и docker-compose. Что получается на доске, описано в разделе Инфраструктура.

Тело запроса — либо content с текстом файла, либо files: [{ name, content }] для нескольких файлов. detail — "overview" (по умолчанию) или "detailed". Тип файла определяется автоматически, лимит — 25 МБ на файл. Сохраняются только имена, типы и связи, значения атрибутов — никогда.

#Импорт

POST /api/v1/boards/:boardId/infra/import · уровень токена edit, роль на доске «Редактор»

Строит или обновляет диаграмму (ID infra-<source>, если не передан diagramId; name необязателен) и сохраняет импорт на доске для проверок.

terraform show -json > state.json
jq -Rs '{content: .}' state.json | \
  curl -fsS -X POST "https://getdoska.top/api/v1/boards/$BOARD_ID/infra/import" \
    -H "Authorization: Bearer $DOSKA_TOKEN" -H "Content-Type: application/json" --data-binary @-

{ "ok": true, "source": "terraform", "diagramId": "infra-terraform",
  "summary": { "nodesAdded": 12, "…": 0 }, "warnings": [],
  "drift": { "inSync": true, "bound": 13, "total": 13, "missing": [], "gone": [], "missingLinks": [], "extraLinks": [] } }

#Проверка расхождений

POST /api/v1/boards/:boardId/infra/check · уровень токена edit, роль на доске «Редактор»

Сравнивает доску с файлом и запоминает файл как эталон, сама диаграмма не меняется. С notify: true на доске появляется комментарий, если она устарела. Одинаковый комментарий подряд не публикуется.

Ответ: { ok, source, warnings, drift, commentThreadId }. В drift:

Чтобы шаг CI падал, когда доска устарела, передайте ответ в jq -e '.drift.inSync'.

#Список импортов

GET /api/v1/boards/:boardId/infra · уровень токена read

Все импорты доски с текущими расхождениями: [{ source, importedAt, by, detail, diagramId, drift }].

#Документы из git

POST /api/v1/projects/:projectId/docs/sync · уровень токена edit, роль в проекте «Редактор»

CI присылает Markdown-файлы папки репозитория, и каждый файл становится документом проекта.

{
  "repo": "acme/payments",
  "ref": "main",
  "sha": "abc1234",
  "fileUrl": "https://github.com/acme/payments/blob/main/docs/{path}",
  "folder": "Docs",
  "prune": false,
  "files": [{ "path": "adr/0001-kafka.md", "markdown": "# Use Kafka\n…" }]
}

• Документ находится по repo и path. Новые файлы создают документы, изменённые обновляют их (прежний текст остаётся в истории версий), неизменённые не трогаются.
• Название берётся из title: во front matter, иначе из первого # заголовка, иначе из имени файла. Подкаталоги становятся папками внутри folder.
• Относительные ссылки между файлами ведут на соответствующие документы.
• С prune: true документы этого repo, чьих файлов больше нет, удаляются.
• Лимиты: до 500 файлов, 1 МБ на файл и 8 МБ всего.

Ответ: { created, updated, unchanged, removed, docs: [{ path, id, url, status }] }.

Готовый скрипт без зависимостей (Node 18+) отдаёт сам сервер. В GitHub Actions он берёт репозиторий, ветку и коммит из окружения:

curl -fsSL https://getdoska.top/docs-sync.mjs -o docs-sync.mjs
DOSKA_TOKEN=dsk_… node docs-sync.mjs --project <projectId> --dir docs --folder Docs

Готовый workflow с ID вашего проекта есть в интерфейсе: откройте проект и нажмите Создать → Документы из git….

#Пример: GitHub Actions

name: Sync diagrams
on:
  push:
    paths: ['docs/diagrams/**.mmd']
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Push diagrams to Doska
        env:
          DOSKA_BOARD: ${{ vars.DOSKA_BOARD }}
          DOSKA_TOKEN: ${{ secrets.DOSKA_TOKEN }}
        run: |
          for f in docs/diagrams/*.mmd; do
            id=$(basename "$f" .mmd)
            jq -Rs --arg n "$id" '{source: ., name: $n}' "$f" | \
              curl -fsS -X PUT "https://getdoska.top/api/v1/boards/$DOSKA_BOARD/diagrams/$id" \
                -H "Authorization: Bearer $DOSKA_TOKEN" -H "Content-Type: application/json" --data-binary @-
          done

В GitLab CI та же команда curl пишется в script:.

#Ошибки

Ошибка приходит в JSON вместе с HTTP-кодом:

{ "error": "Доска не найдена", "code": "not_found" }

На запрос к недоступной доске API отвечает 404, а не 403, чтобы не раскрывать, что она существует. Сообщения приходят на языке интерфейса владельца токена; заголовок X-Doska-Locale: en или ru задаёт язык явно.

#Лимиты

• Не больше 600 запросов в минуту с одного адреса.
• Импорт и проверка инфраструктуры, синхронизация документов — не больше 30 запросов в минуту на каждый.
• Код диаграммы — до 200 КБ, 2000 узлов и 5000 связей.