Holkas
Написать в поддержку Поддержка

Справочник

REST API

HTTP-контракт Holkas: найти запрос, передать параметры, разобрать ответ и проследить перенос до результата. Операции, файлы, каталог и администрирование.

На этой странице

Найти запрос

Что это

Holkas Web отдаёт REST API по адресу /api/v1. Этим API пользуется веб-интерфейс, им же работает CLI. Скрипт получает те же операции и те же законы: права на подключения, подтверждение применения в базу и журнал действий.

Страница описывает две части API:

  • Публичный контракт — перенос, план, файлы, каталог, манифесты, сравнение с git, журнал. Контракт версионируется в /api/v1; изменения описываются в заметках к выпуску. Версии у манифеста нет: запрос с version отклоняется ошибкой version_removed; адресуйте состав по имени.
  • Администрирование — подключения, пользователи, группы, токены, автономия, соответствие ролей, хранение. Нужно, чтобы развернуть экземпляр скриптом; каждый раздел называет требуемые права.

Адреса, которых здесь нет, служат веб-интерфейсу и могут меняться без предупреждения. В справочнике можно искать по адресу и назначению запроса; каждый адрес раскрывается отдельно.

Для агента есть отдельная дверь — MCP. Для конвейера сборки обычно удобнее CLI: он дожидается результата и завершается понятным кодом.

Правила, общие для всех запросов

Адрес, токен и формат

Базовый путь — /api/v1. В примерах ниже используется Bash и curl. Адрес сервера, id подключений, операции и значения объектов условные; подставьте свои. JSON-ответы иллюстрируют форму данных и не являются протоколом нового запуска.

HOLKAS_API="https://holkas.example.org/api/v1"
holkas_headers=(-H "Authorization: Bearer $HOLKAS_TOKEN" -H "Content-Type: application/json")

Токен скрипта выпускается человеком в веб-интерфейсе: Полномочия → Мой агент → Токены доступа, назначение «для скрипта». Он передаётся как Authorization: Bearer hpat_…; скрипт действует с правами владельца. Для робота администратор может создать служебную учётную запись и выпустить токен ей.

Токен с назначением «для агента» в REST не принимается (403 mcp_token_door), токен скрипта не принимается в /mcp. Старые токены без назначения работают в обеих дверях. Выпуск и отзыв токенов доступны только в браузерной сессии, не через другой токен.

В режиме Local токен не нужен: запрос действует как локальный администратор. Это не отменяет обязательного подтверждения применения в базу.

Тело обычного запроса — JSON с Content-Type: application/json, имена полей — camelCase. Даты передаются в UTC, ISO 8601. Загрузка файла использует multipart/form-data, скачивание возвращает байты. Успешный 204 No Content не содержит JSON: не пытайтесь разбирать пустое тело.

В описаниях ниже {id}, {connId} и другие обозначения заменяются значениями пути. ? после имени поля означает необязательность, а не часть его имени. В колонке параметров перечислены поля тела или query-параметры — это описание формы, а не готовый JSON.

Права и отказы

Для построения плана нужны права чтения на обоих концах. Для применения — чтение источника и запись в приёмник. У отдельных административных запросов требования указаны в их разделе.

Подключение без нужного права даёт 403 access_denied. Чужая операция и отсутствующая операция одинаково возвращают 404 not_found. Поля секретов подключения маскируются как ********; при обновлении маска или отсутствие поля сохраняют прежний секрет, пустая строка его стирает.

Оформленный приложением отказ содержит error — код для скрипта — и message — пояснение для человека. Ошибка разбора тела возвращает 400 invalid_request с fields. Неизвестный адрес под /api даёт JSON 404 not_found.

Проверяйте и HTTP-код, и тело ответа. Ошибки соединения вообще не дают HTTP-ответа; не считайте пустое тело или неразобранный JSON успешным выполнением. Для неизвестного кода error предусмотрите общий обработчик.

Проверка текущего входа

curl -sS -i -H "Authorization: Bearer $HOLKAS_TOKEN" "$HOLKAS_API/auth/me"

Этот запрос может вернуть 200 и authenticated: false. Доступность сервера и успешный вход — разные проверки.

GET/api/v1/auth/meКто вы для сервера: режим, версия, имя, признак администратора

Кто вы для сервера: режим, версия, имя, признак администратора. Отвечает и без токена — authenticated: false.

Как следить за выполнением

Построение плана и применение выполняются в фоне. Запрос запуска возвращает id операции; последующие запросы читают её состояние. В отличие от CLI, REST-клиент сам организует ожидание.

HTTP-ответ и результат переноса — разные вещи

POST /api/v1/operations200 OK
{ "operationId": "op-demo" }

Запуск принят

Сохраните id. Это ответ о создании операции, а не о результате переноса.

GET /api/v1/operations/op-demo200 OK
{ "id": "op-demo", "status": "Applying", "error": null }

Работа идёт

Сервер успешно сообщил состояние. Окончания применения ещё нужно дождаться.

GET /api/v1/operations/op-demo200 OK
{ "id": "op-demo", "status": "Failed", "error": "Не удалось применить команду." }

Перенос завершился ошибкой

HTTP-запрос выполнен успешно, но операция упала. Разбирайте status и error, затем журнал.

Сокращённые условные ответы. op-demo обозначает одну операцию; сообщение об ошибке выбрано для объяснения.
status операцииЗначениеДействие клиента
PlanBuildingПлан строитсяПродолжить опрос с паузой
PlanReadyПлан готов, применения ещё не былоПрочитать сводку, команды и предупреждения; решить, что применять
ApplyingПрименение идётПродолжить опрос
CompletedВыполнение завершеноПрочитать итог и при необходимости получить файлы
FailedПостроение или применение завершилось ошибкойПрочитать error и журнал; часть команд могла выполниться
CancelledЗафиксирована отменаНе считать это откатом: уже идущее применение запрос отмены не прерывает

У готового плана summary.commands: 0 означает отсутствие изменений. Вызывать apply не нужно: сервер ответит 400 plan_empty. При summary: null сначала смотрите состояние операции — план ещё может строиться или его построение могло завершиться ошибкой.

Устанавливайте собственный предел ожидания и паузу между запросами. По истечении предела сохраните id и продолжайте наблюдение позже. Повторный запрос создания операции создаёт новый запуск: это не способ возобновить ожидание прежнего. Если связь оборвалась до получения id, проверьте историю операций по маршруту, времени и основанию прежде, чем повторять запуск.

У обхода каталога и сравнения с Git свои состояния и адреса опроса: каталог возвращает job, сравнение — runId. Не передавайте их в адрес операции переноса.

Перенос: операции

Операция — один перенос с источника на приёмник. Жизненный цикл:

СтатусЧто значит
PlanBuildingПлан строится.
PlanReadyПлан готов; его можно разобрать, сузить и применить.
ApplyingИдёт применение.
CompletedПрименение завершено либо построен пустой план: completedWithoutChanges: true и completionMessage объясняют завершение без применения. Если совпавшим объектам чего-то не хватает в приёмнике, список лежит в convergedDependencies, а rebuild добавит доступное.
FailedПостроение плана или применение завершилось ошибкой — см. поле error.
CancelledОперацию сняли.

Применяется только PlanReady. Завершённую операцию (Completed, Failed, Cancelled) применить или отменить нельзя; остаток доделывает новый план (replan).

reason — необязательное основание переноса: номер задачи или короткое пояснение до 255 символов после удаления пробелов по краям. Можно задать при построении плана или применении; повтор операции сохраняет прежний текст. Пустая строка очищает поле, отсутствие значения при применении оставляет основание плана. В карточке и списке оно возвращается как reason (или null); canEditReason сообщает о праве на исправление завершённого переноса. При повторе с confirm передайте то же основание, которое было показано человеку.

POST/api/v1/operationsСтроит план (или сразу применяет, direct)

Строит план (или сразу применяет, direct). Возвращает { "operationId" }.

Тело и параметры

см. ниже

GET/api/v1/operationsФильтры q (часть ID или основания), from (включительно), to (исключительно), даты ISO 8601 UTC

Фильтры q (часть ID или основания), from (включительно), to (исключительно), даты ISO 8601 UTC; применяются до окна в 200 результатов. Операции, которые вам видны, — свои и те, у которых оба конца вам доступны на чтение, — до 200 совпадений после применения фильтров, новые сверху.

Тело и параметры

—

GET/api/v1/operations/{id}Состояние операции: статус, ошибка и объект, на котором упала, концы маршрута с адресами, подпись, файлы.

Состояние операции: статус, ошибка и объект, на котором упала, концы маршрута с адресами, подпись, файлы.

Тело и параметры

—

GET/api/v1/operations/{id}/summaryСводка плана: команды по действиям и типам, объекты, аномалии, сошедшиеся объекты

Сводка плана: команды по действиям и типам, объекты, аномалии, сошедшиеся объекты. Пока план строится или если построение упало, summary — null.

Тело и параметры

—

GET/api/v1/operations/{id}/planКоманды плана лёгкими строками: id, objectType, action, objectKey, ignored, предупреждения, hasBody.

Команды плана лёгкими строками: id, objectType, action, objectKey, ignored, предупреждения, hasBody.

Тело и параметры

—

GET/api/v1/operations/{id}/plan/{commandId}Одна команда целиком: поля было/стало, тела, SQL.

Одна команда целиком: поля было/стало, тела, SQL.

Тело и параметры

—

POST/api/v1/operations/{id}/applyПрименяет готовый план

Применяет готовый план. С токеном API в базу — только с подтверждением (428, затем повтор с confirm); в Git, S3 и файл — без подтверждения по умолчанию (личная политика может потребовать его). В браузерном сеансе reviewedPlan: true означает согласие человека кнопкой «Применить» и закрывает заявку в этом вызове; для PAT/OAuth этот флаг не заменяет confirm. Возвращает { "status": "Applying" }.

Тело и параметры

{ "reason"?, "confirm"?, "reviewedPlan"? }

PUT/api/v1/operations/{id}/reasonИсправляет основание завершённого применения

Исправляет основание завершённого применения. Автор операции или администратор; старый и новый текст остаются в аудите.

Тело и параметры

{ "reason", "confirm"? }

POST/api/v1/operations/{id}/cancelСнимает операцию с дороги

Снимает операцию с дороги. Идущее применение не прерывается; отмена фиксирует решение и не откатывает уже выполненное.

Тело и параметры

—

POST/api/v1/operations/{id}/rebuildНовый план того же маршрута, набор которого дополнен непокрытыми зависимостями

Новый план того же маршрута, набор которого дополнен непокрытыми зависимостями. Возвращает { "operationId" } новой операции. Для источника «Файл пакета» — отказ package_dependencies_missing: подготовьте новый пакет с указанными недостающими объектами или перенесите их отдельно.

Тело и параметры

—

POST/api/v1/operations/{id}/replanНовый план того же маршрута и набора после завершения (Completed или Failed): так проверяют сходимость и доделывают остаток

Новый план того же маршрута и набора после завершения (Completed или Failed): так проверяют сходимость и доделывают остаток. Возвращает { "operationId" }.

Тело и параметры

—

GET/api/v1/operations/{id}/progressСохранённый ход: { status, stages }

Сохранённый ход: { status, stages }. Этапы в порядке начала, каждый содержит id, name, state (Running, Completed, Failed), elapsedMs, done, total, currentCommand, error. Повторный запуск этапа сохраняется отдельно. Неизвестные показания — null; у старых операций stages пуст. Статус операции и последние показания этапов записываются последовательно: после завершения статус может обновиться чуть раньше этапа.

Тело и параметры

—

GET/api/v1/operations/{id}/logЖурнал операции строками: { status, inProgress, note, total, shown, lines }

Журнал операции строками: { status, inProgress, note, total, shown, lines }. Пока операция идёт, inProgress равно true, строки появляются с задержкой в пару секунд, а пустой список объясняет note. 404 — операции нет или она завершена, а журнал не сохранён.

Тело и параметры

level = info (по умолчанию), debug, error; tail = сколько последних строк (1000)

GET/api/v1/operations/{id}/log/downloadТот же журнал одним текстовым файлом

Тот же журнал одним текстовым файлом. Пока операция идёт и записей нет, ответ 409 с кодом operation_in_progress.

Тело и параметры

level

Тело POST /api/v1/operations:

ПолеЧто это
sourceConnectionId, targetConnectionIdОбязательные целочисленные id концов маршрута. Нужны права: чтение источника; для плана — чтение приёмника, для применения — запись.
objectsНабор: [{ "type": "CLS", "name": "PARUS_DOC" }]. Коды типов — как в справочнике объектов. Пустой набор допустим только для источника «Файл пакета» и означает «весь пакет». У набора данных (DAT) ещё definition — его описание holkas-dataset/1 JSON-текстом, как его отдаёт parameter строки expand; имя в описании совпадает с name. Из базы-источника набор без описания не строится — 400 dataset_definition_required; негодное описание — 400 с кодом проверки (dataset_format, dataset_key, dataset_name, …). У других типов definition не бывает — 400 definition_not_applicable. Описание записывается в операцию и возвращается в objects из GET /api/v1/operations/{id}.
directПо умолчанию false. true — без отдельного плана: команды строятся на самом применении. Для приёмника-базы запрос сразу требует подтверждения (428) и повторяется с confirm.
reasonНеобязательное основание плана или прямого переноса, до 255 символов.
confirmНомер заявки при повторе direct-запроса.
sourceRef, targetRefУ источника — ветка, тег или SHA коммита Git; у приёмника — ветка. Только у Git-концов.
sourceCompany, targetCompanyОрганизация Паруса (RN из GET /api/v1/connections/{id}/companies); только у концов-баз. Без поля действует организация подключения, а если и её нет — единственная организация базы. В базе несколько организаций и ни одна не выбрана — 400 company_required; организации нет в базе — 400 company_unknown. Выбранная организация возвращается в GET /api/v1/operations/{id}.
inputArtifactIdЗагруженный файл (см. Файлы); обязателен для источника «Файл пакета».
outputFileNameИмя файла результата у приёмников «Файл пакета» и «SQL-скрипт»; расширение добавится само.
parametersПараметры сравнения и применения для этого плана: { "ignoreExtraTargetGrants": true, "ownerMap": { "egiszintegration": "parus" } }. Ключ без значения или null — «по умолчанию»: значение подключения-приёмника, иначе настройки запуска (HolkasWeb:Parameters). Неизвестный ключ — 400 unknown_parameter; у приёмника без сравнения (файл, SQL-скрипт) — 400 parameters_not_applicable. В GET /api/v1/operations/{id} возвращаются parameters (заданное самим планом), effectiveParameters (итог: key, value, source — operation, connection, startup или builtIn; у списка пар — ещё map: from, to, source каждой пары) и keptTargetGrants — сколько лишних прав приёмника план пропустил.

Параметры сравнения и применения

Правила сравнения и применения, которые задаются каскадом: настройка запуска → подключение-приёмник → план; нижний уровень побеждает. Параметры:

  • ignoreExtraTargetGrants (true/false): права, которые есть в приёмнике, но которых нет в источнике (включая WITH GRANT OPTION), не отзываются и не попадают в план. По умолчанию false — сравнение точное, лишние права отзываются отдельными командами *.Grant Delete.
  • roleMap (объект «роль источника → роль приёмника», например { "parus_dev": "parus_prod" }): соответствие ролей. Роль источника в приёмнике называется иначе: меняются и владелец объектов Postgres, и получатели прав. Имя переводится до сравнения, поэтому план сходится; сработавшая пара видна в notes строки плана вместе с уровнем, который её задал. Пары уровней складываются по роли источника, как у ownerMap. Для владельца ownerMap главнее. Настройка запуска: HolkasWeb:Parameters:roleMap:<роль источника> = <роль приёмника>.
  • ownerMap (объект «роль источника → роль приёмника», например { "egiszintegration": "parus" }): замена владельцев. Меняет только владельца объектов Postgres, права не трогает. Пары уровней складываются по роли источника: пара нижнего уровня перекрывает пару с той же ролью, остальные остаются; пара X → X оставляет владельца источника. Пустой объект или null — «по умолчанию». Настройка запуска: HolkasWeb:Parameters:ownerMap:<роль источника> = <роль приёмника>. Не пара ролей — 400 parameter_value_invalid.
  • parusRoleMap (объект «роль Паруса источника → роль Паруса приёмника»): переводит назначения визуальных форм CLS, PCE и REP. Например { "Разработчики": "Операторы" }. Имена чувствительны к регистру. Роли и пользователей не создаёт, роли СУБД и членство не меняет. Пары наследуются по уровням, как у roleMap. Практика назначений.
  • singleTransaction (true/false): весь план в PostgreSQL выполняется одной транзакцией; ошибка откатывает его изменения. У S3 и файла пакета записывает требование полной установки, у PostgreSQL SQL-файла — обёртку BEGIN … COMMIT. Для базы и SQL Oracle, а также Git параметр неприменим. Требование источника-пакета сильнее каскада: итоговый source — package, явное выключение плана вызывает single_transaction_required. Исключённые команды — single_transaction_incomplete; Oracle — single_transaction_unsupported. Поведение, блокировки и проверенный пример.

Строки плана говорят о владельцах отдельно: ownerBlocked — роли, на которых команда упадёт, потому что роли подключения не хватает полномочий (не суперпользователь и не может SET ROLE в нового владельца, у владельца нет CREATE в схеме или объект чужой); сработавшая замена и SECURITY DEFINER («будет выполняться с правами владельца …») — в notes.

GET/api/v1/parametersРеестр параметров: key, group, title, description, kind (flag или roleMap), builtIn, значение настройки запуска startup, значен…

Реестр параметров: key, group, title, description, kind (flag или roleMap), builtIn, значение настройки запуска startup, значение приёмника connection (null — не задано), у списка пар — startupMap и connectionMap, applicable — применимость к выбранному приёмнику, и inherited — что получит план «по умолчанию» (value, source, у списка — map).

Параметры

targetConnectionId

Пример: создать и прочитать план

Подключения 3 и 4 существуют и доступны на чтение. Создаём план для одного класса:

curl -sS -i "${holkas_headers[@]}" \
  -d '{"sourceConnectionId":3,"targetConnectionId":4,"objects":[{"type":"CLS","name":"DemoRequest"}],"reason":"TASK-1234 · Проверка класса"}' \
  "$HOLKAS_API/operations"

Успешный ответ — HTTP 200, тело:

{ "operationId": "op-demo" }

Сохраните полученный id. Читать состояние и сводку можно отдельно:

curl -sS -i "${holkas_headers[@]}" "$HOLKAS_API/operations/op-demo"
curl -sS -i "${holkas_headers[@]}" "$HOLKAS_API/operations/op-demo/summary"

Пример готовой сводки; полный ответ может содержать дополнительные поля:

{
  "id": "op-demo",
  "status": "PlanReady",
  "error": null,
  "summary": {
    "commands": 1,
    "ignored": 0,
    "byAction": { "Update": 1 },
    "byType": { "CLS": 1 },
    "objects": [{ "objectKey": "DemoRequest", "objectType": "CLS", "action": "Update", "commands": 1 }],
    "objectsTotal": 1,
    "anomalies": [],
    "converged": [],
    "convergedTotal": 0
  }
}

Сводка даёт общий результат; список /plan — лёгкие строки команд, а /plan/{commandId} — детали конкретной команды. Прочитайте предупреждения и различия до применения. Продолжение через заявку показано ниже.

Выбор команд

Готовый план можно сузить: выполнить не всё. Зависимости держатся сами: исключённая команда исключает те, что её ждут, а включённая тянет свои обязательные предшественники.

GET/api/v1/operations/{id}/selectionТекущий выбор.

Текущий выбор.

Тело

—

POST/api/v1/operations/{id}/selection/modeРежим с чистого листа: allExcept — всё, кроме исключённого

Режим с чистого листа: allExcept — всё, кроме исключённого; onlySelected — только выбранное.

Тело

{ "mode" }

POST/api/v1/operations/{id}/selection/commandsВключить и исключить команды по их id из плана.

Включить и исключить команды по их id из плана.

Тело

{ "includeCommandIds"?, "excludeCommandIds"? }

Ответ всех трёх:

{ "mode": "allExcept", "explicitCommandIds": [1], "autoIncludedCommandIds": [],
  "cascadedExcludedCommandIds": [2, 3], "excludedCommandIds": [1, 2, 3],
  "includedCount": 2, "excludedCount": 3 }

Менять выбор можно только у PlanReady. selection/mode сбрасывает прежний явный выбор, а selection/commands изменяет его включениями и исключениями. Используйте итоговые includedCount и excludedCommandIds из ответа: зависимости могут изменить больше команд, чем перечислено в запросе. Если включённых команд нет, применение вернёт 400 no_commands_selected.

Пример тела для режима, в котором сначала ничего не выбрано:

{ "mode": "onlySelected" }

Затем тело запроса изменения выбора (числа берутся из вашего /plan):

{ "includeCommandIds": [7, 12], "excludeCommandIds": [] }

reviewedPlan: true у применения предназначен для нажатия человеком в браузерной сессии. Для REST-токена этот флаг не заменяет confirm.

Файлы операций

Операция может читать загруженный файл (источник «Файл пакета») и создавать файлы (приёмники «Файл пакета» и «SQL-скрипт»). Файлы хранятся на сервере вместе с операцией.

Результат SQL-выгрузки и проверка скачанного файла показаны в практическом примере. Статус Completed файловой операции подтверждает создание артефакта; выполнение SQL внешним клиентом Holkas не отслеживает.

POST/api/v1/artifactsЗагружает пакет для будущей операции, до 512 МБ

Загружает пакет для будущей операции, до 512 МБ. Возвращает { "artifactId", "fileName", "sizeBytes", "sha256" }. Файл годится для одной операции и только для того, кто его загрузил.

Тело и параметры

multipart/form-data, поле file

GET/api/v1/operations/{id}/artifactsФайлы операции: id, role (input или output), fileName, contentType, sizeBytes, sha256, createdBy.

Файлы операции: id, role (input или output), fileName, contentType, sizeBytes, sha256, createdBy.

Тело и параметры

—

GET/api/v1/operations/{id}/artifacts/{artifactId}Скачивает файл.

Скачивает файл.

Тело и параметры

—

Загрузить пакет как источник

POST /api/v1/artifacts принимает поле формы file. Не задавайте для этого запроса Content-Type: application/json: curl сам сформирует multipart с границей.

curl -sS -i -H "Authorization: Bearer $HOLKAS_TOKEN" \
  -F "file=@release-1.4.zip" "$HOLKAS_API/artifacts"

Сокращённый пример ответа HTTP 200:

{ "artifactId": "input-demo", "fileName": "release-1.4.zip", "sizeBytes": 12000, "sha256": "9f2c…" }

Полученный artifactId передайте как inputArtifactId при создании операции. Источник — id системного узла PackageFile из списка подключений; его номер не фиксирован. Пустой objects здесь означает весь пакет:

{
  "sourceConnectionId": 1,
  "targetConnectionId": 4,
  "inputArtifactId": "input-demo",
  "objects": []
}

В этом условном примере 1 — найденный id узла пакета. Загрузка сама по себе ничего не применяет. Holkas сразу проверяет, что файл — пакет: битый архив или zip без manifest.json дают 400 invalid_package. Файл привязывается к одной операции; повторное использование занятого входного файла даёт 400 input_taken. Файл, загруженный другим человеком, для вас не существует: 404 input_not_found.

Агент загружает пакет не этим запросом, а по одноразовой ссылке из holkas_upload_link — см. справочник MCP.

Получить выходной файл

Для экспорта в файл пакета или SQL создайте операцию с direct: true, укажите id нужного файлового приёмника и outputFileName. Дождитесь Completed, затем получите список файлов операции и выберите запись с role: "output". Не предполагайте, что первый файл в списке — нужный результат: там могут быть и входные файлы.

curl -sS -i "${holkas_headers[@]}" "$HOLKAS_API/operations/op-demo/artifacts"

Скачивание возвращает байты, а не JSON. После подстановки настоящего id файла:

curl -f -sS -H "Authorization: Bearer $HOLKAS_TOKEN" \
  "$HOLKAS_API/operations/op-demo/artifacts/output-demo" -o release-1.4.zip

Здесь -f делает HTTP-ошибку ненулевым кодом curl, чтобы не принять ответ об отказе за архив. Само наличие скачанного файла не заменяет проверку состояния операции.

Заявки на подтверждение

Применение в базу данных требует подтверждения. Для других действий правило зависит от их вида и личной настройки автономии. Заявка живёт 30 минут, принадлежит пользователю и привязана к конкретному действию. Просроченная, отклонённая, уже использованная или чужая заявка даёт 409 confirmation_invalid.

Первый запрос готового плана:

curl -sS -i "${holkas_headers[@]}" -d '{}' "$HOLKAS_API/operations/op-demo/apply"

HTTP 428, сокращённый условный ответ:

{
  "error": "confirmation_required",
  "message": "Применение требует подтверждения человеком.",
  "proposal": {
    "id": 17,
    "operation": "apply.db",
    "summary": "Применить план op-demo в базу «Тест».",
    "expiresAt": "2026-10-21T10:30:00Z"
  }
}

До подтверждения применение не началось. Человек рассматривает план и заявку. После его одобрения скрипт повторяет запрос к тому же плану:

curl -sS -i "${holkas_headers[@]}" -d '{"confirm":"17"}' "$HOLKAS_API/operations/op-demo/apply"

Ответ HTTP 200 с {"status":"Applying"} означает начало применения. Дальше снова опрашивайте состояние этой операции.

Для direct: true заявка возвращается при создании операции: повторяется исходное создание с теми же параметрами и добавленным confirm. Если задавали reason, сохраняйте то же основание при подтверждении. Автоматический повтор любого 428 с полученным номером не заменяет решение человека.

Способ передачи confirm указан у конкретного запроса: поле тела либо query-параметр у удаления. Это не универсальное поле, которое любой запрос REST обязан принимать.

GET/api/v1/proposalsВаши заявки: id, operation, target, summary, status (pending, confirmed, rejected), подпись, срок.

Ваши заявки: id, operation, target, summary, status (pending, confirmed, rejected), подпись, срок.

Параметры

pendingOnly (true), limit (100)

POST/api/v1/proposals/{id}/rejectОтклоняет заявку

Отклоняет заявку; повтор с её номером больше не пройдёт.

Параметры

—

Подтверждения отдельным запросом нет: подтверждение — это повтор исходного запроса с confirm.

Подключения: чтение

GET/api/v1/connectionsПодключения, на которые у вас есть хоть одно право: id, name, transportType (DB, git, S3, PackageFile, SqlFile), address, compa…

Подключения, на которые у вас есть хоть одно право: id, name, transportType (DB, git, S3, PackageFile, SqlFile), address, company (организация Паруса по умолчанию у базы, RN или null), environment, последняя проверка связи, размер каталога, ваши права canRead/canWrite/canManage.

Параметры

transportType, search

GET/api/v1/connections/{id}Одно подключение, с настройками settingsJson (секреты замаскированы) и состоянием обхода каталога.

Одно подключение, с настройками settingsJson (секреты замаскированы) и состоянием обхода каталога.

Параметры

—

POST/api/v1/connections/{id}/testПроверяет связь: { "ok", "message", "meta" }

Проверяет связь: { "ok", "message", "meta" }. Результат запоминается в lastProbeOk.

Параметры

—

GET/api/v1/connections/environmentsСловарь сред: prod, test, dev.

Словарь сред: prod, test, dev.

Параметры

—

GET/api/v1/connections/{id}/refsВетки (первой — ветка по умолчанию) и теги git-подключения.

Ветки (первой — ветка по умолчанию) и теги git-подключения.

Параметры

—

GET/api/v1/connections/{id}/companiesОрганизации Паруса подключения-базы: [{ "rn", "name" }], живым запросом

Организации Паруса подключения-базы: [{ "rn", "name" }], живым запросом. В базе без таблицы организаций — пустой список. Удачная проверка связи базы возвращает тот же список в meta.companies (JSON-строкой). Организация подключения по умолчанию хранится в settingsJson полями company (RN) и companyName.

Параметры

—

GET/api/v1/connections/{id}/commitsПоследние коммиты ветки или тега.

Последние коммиты ветки или тега.

Параметры

ref, limit (30)

Каталог объектов

Каталог — список объектов подключения, прочитанный заранее: обход большой базы занимает секунды или минуты и идёт в фоне.

POST/api/v1/connections/{connId}/objects/refreshЗапускает обход

Запускает обход; 202 с состоянием.

Параметры

—

GET/api/v1/connections/{connId}/objects/refreshСостояние обхода: { "job": { "status", "typesTotal", "typesDone", "total", "error" } }

Состояние обхода: { "job": { "status", "typesTotal", "typesDone", "total", "error" } }; job — null, если обхода не было.

Параметры

—

DELETE/api/v1/connections/{connId}/objects/refreshОстанавливает зависший обход.

Останавливает зависший обход.

Параметры

—

GET/api/v1/connections/{connId}/objectsСтраница каталога: items (objectType, name), total, cachedAt

Страница каталога: items (objectType, name), total, cachedAt. Для git с ref — живое чтение этой ветки.

Параметры

type, search, limit (500), offset, ref

GET/api/v1/connections/{connId}/objects/typesСколько объектов каждого типа

Сколько объектов каждого типа. Дочерние типы (колонки, атрибуты, значения) показываются под родителем и здесь не считаются, поэтому total меньше числа из обхода.

Параметры

—

GET/api/v1/connections/{connId}/objects/{typeCode}/{objectName}Объект целиком из источника: { "objectType", "name", "fields" }

Объект целиком из источника: { "objectType", "name", "fields" }. Имена полей в fields — как в модели объекта (Code, CrnName, …). Объекта нет в каталоге — 404.

Параметры

—

Наборы данных: карточка описания

Описание набора данных (holkas-dataset/1) составляется по каталогу базы-подключения. Holkas его нигде не хранит: готовое описание кладут в строку манифеста (PUT …/items/parameter) или передают в definition объекта DAT при создании операции. Нужно право чтения на подключение; подключение должно быть базой, иначе 400 dataset_not_applicable. Описание в теле — JSON-объект или та же JSON-строка, как её отдаёт описатель.

POST/api/v1/connections/{connId}/datasets/buildЧерновик описания с корнем в table: ключ строки (из уникальных ключей каталога, мнемокод первым), части (таблицы с ON DELETE CA…

Черновик описания с корнем в table: ключ строки (из уникальных ключей каталога, мнемокод первым), части (таблицы с ON DELETE CASCADE на корень), ссылки-адреса с вложенными ключами; граница — все строки. Ответ: { "definition", "tables" }; в tables у каждой прочитанной таблицы — role (root, part, target), columns (system, refTable, objectType), keys — кандидаты в ключ, parts — ссылающиеся таблицы (table, by, cascade). С parent — черновик одной части под таблицей parent текущего описания: { "part", "tables" }.

Тело и параметры

{ "table", "name"?, "parent"?, "definition"? }

POST/api/v1/connections/{connId}/datasets/checkПроверка описания по живой базе: { "ok", "unit", "findings": [{ "code", "message", "table", "column", "isError" }] }

Проверка описания по живой базе: { "ok", "unit", "findings": [{ "code", "message", "table", "column", "isError" }] }. Описание, которое не разбирается, — тоже находка (dataset_format).

Тело и параметры

{ "definition" }

POST/api/v1/connections/{connId}/datasets/previewСколько строк корня берёт граница и первые из них, без частей: { "total", "tooMany", "warningThreshold", "rows": [{ "segment", …

Сколько строк корня берёт граница и первые из них, без частей: { "total", "tooMany", "warningThreshold", "rows": [{ "segment", "folder", "cells" }] }; ссылки в cells — адресом A / B. tooMany — больше 10 000 строк. Описание с ошибками проверки — 400 dataset_check.

Тело и параметры

{ "definition", "limit"? (50, не больше 500), "company"? }

GET/api/v1/connections/{connId}/datasets/foldersПапки каталога раздела — для границы { "folder": … }: { "unit", "names" }

Папки каталога раздела — для границы { "folder": … }: { "unit", "names" }. Раздел — unit или единственный раздел таблицы по UNITLIST; иначе 400 dataset_unit_ambiguous.

Тело и параметры

table, unit, company

Точный синтаксис описания и читаемый JSON-пример — в формате набора данных.

Сравнение базы с git

Что разошлось между базой и веткой git: объекты только в базе, только в git, изменённые и совпавшие.

POST/api/v1/change-detectionЗапускает сравнение

Запускает сравнение; { "runId" }. Второй запуск той же тройки, пока идёт первый, — 409 already_running.

Тело и параметры

{ "dbConnectionId", "gitConnectionId", "branch" }

GET/api/v1/change-detection/{runId}Состояние и результат.

Состояние и результат.

Тело и параметры

—

GET/api/v1/change-detection/latestПоследнее завершённое сравнение тройки.

Последнее завершённое сравнение тройки.

Тело и параметры

dbConnId, gitConnId, branch

POST/api/v1/change-detection/{runId}/cancelОстанавливает идущее сравнение.

Останавливает идущее сравнение.

Тело и параметры

—

Нужно право чтения на обоих подключениях. Ответ:

{ "id": 1, "dbConnId": 3, "gitConnId": 5, "branch": "master", "status": "Completed", "error": null,
  "processedObjects": 2, "totalObjects": 2,
  "startedAt": "2026-09-24T13:47:05Z", "finishedAt": "2026-09-24T13:47:12Z",
  "entries": [ { "objectType": "DOM", "objectName": "ZLIVE_A", "status": "Unchanged" },
               { "objectType": "DOM", "objectName": "ACAD_TP", "status": "OnlyDb" } ] }

Статусы записи: OnlyDb, OnlyGit, Modified, Unchanged, Both (объект есть с обеих сторон, но одну не удалось прочитать). Статусы сравнения: Running, Completed, Failed, Cancelled. processedObjects и totalObjects — ход сравнения общей части; сравнение крупной пары занимает десятки минут.

Состав релиза: описатели и манифесты

Описатель сборки — внешний сервис, который по корневым объектам называет состав доработки. Манифест — сохранённый список объектов релиза, который можно выгрузить файлом и загрузить на другом экземпляре. Манифесты видны всем пользователям.

GET/api/v1/describersОписатели: id, name, kind, url, последняя проверка.

Описатели: id, name, kind, url, последняя проверка.

Тело и параметры

—

GET/api/v1/describers/{id}Один описатель.

Один описатель.

Тело и параметры

—

GET/api/v1/describers/kindsВиды описателей: bison-rele.

Виды описателей: bison-rele.

Тело и параметры

—

GET/api/v1/describers/{id}/root-typesТипы, которыми описатель принимает корни.

Типы, которыми описатель принимает корни.

Тело и параметры

—

POST/api/v1/describers/{id}/expandРаскрывает корни в список и сверяет его с каталогом источника.

Раскрывает корни в список и сверяет его с каталогом источника.

Тело и параметры

{ "sourceConnectionId", "roots": [{ "type", "name" }] }

POST/api/v1/describers/{id}/describeТо же без источника: список «как говорит описатель», не сверенный ни с какой базой.

То же без источника: список «как говорит описатель», не сверенный ни с какой базой.

Тело и параметры

{ "roots" }

GET/api/v1/manifestsМанифесты, которые вы видите: id, name, description, itemCount, кто и когда создал, visibility (private — только автор и админи…

Манифесты, которые вы видите: id, name, description, itemCount, кто и когда создал, visibility (private — только автор и администратор, shared — все), canEdit — можете ли вы его менять.

Тело и параметры

—

GET/api/v1/manifests/{id}Манифест со строками: type, name, origin (откуда строка), source, parameter (у набора данных — его описание, иначе null).

Манифест со строками: type, name, origin (откуда строка), source, parameter (у набора данных — его описание, иначе null).

Тело и параметры

—

POST/api/v1/manifestsСоздаёт манифест, при необходимости сразу с составом

Создаёт манифест, при необходимости сразу с составом; по умолчанию private; 201.

Тело и параметры

{ "name", "description"?, "visibility"?, "items"?: [{ "type", "name", "parameter"? }] }

PUT/api/v1/manifests/{id}Меняет имя, описание, видимость.

Меняет имя, описание, видимость.

Тело и параметры

{ "name"?, "description"?, "visibility"? }

POST/api/v1/manifests/{id}/copyКопирует видимый вам манифест в новый ваш, private, с теми же строками и их происхождением

Копирует видимый вам манифест в новый ваш, private, с теми же строками и их происхождением; 201.

Тело и параметры

{ "name", "description"? }

DELETE/api/v1/manifests/{id}Удаляет манифест

Удаляет манифест; 204.

Тело и параметры

confirm, если требует автономия

POST/api/v1/manifests/{id}/items/manualДобавляет строки вручную

Добавляет строки вручную. У набора данных (DAT) parameter — его описание holkas-dataset/1; хранится как передано и проверяется при expand. Параметр у другого типа — 400 parameter_not_applicable. Ответ: { "added", "skipped", "total" }.

Тело и параметры

{ "items": [{ "type", "name", "parameter"? }] }

PUT/api/v1/manifests/{id}/items/parameterЗадаёт описание набора данных в строке DAT (из карточки набора)

Задаёт описание набора данных в строке DAT (из карточки набора); пустое — снимает. Хранится как передано и проверяется при expand. Другой тип — 400 parameter_not_applicable, нет строки — 404. Ответ 204.

Тело и параметры

{ "type", "name", "parameter" }

POST/api/v1/manifests/{id}/items/from-connectionДобавляет строки из каталога подключения (нужно право чтения).

Добавляет строки из каталога подключения (нужно право чтения).

Тело и параметры

{ "connectionId", "items" }

POST/api/v1/manifests/{id}/items/from-describerДобавляет ответ описателя по корням

Добавляет ответ описателя по корням; keep — оставить только эти строки ответа.

Тело и параметры

{ "describerId", "roots", "keep"? }

POST/api/v1/manifests/{id}/items/removeУбирает строки

Убирает строки; 204.

Тело и параметры

{ "items" }

GET/api/v1/manifests/{id}/exportФайл манифеста (manifest-<имя>.json, формат holkas-manifest/2) — то, что переносят на другой экземпляр.

Файл манифеста (manifest-<имя>.json, формат holkas-manifest/2) — то, что переносят на другой экземпляр.

Тело и параметры

—

POST/api/v1/manifests/importЗагружает файл манифеста (тело запроса — сам файл)

Загружает файл манифеста (тело запроса — сам файл); контрольная сумма проверяется до записи; файл прежнего формата holkas-manifest/1 принимается, его версия, кроме «1», дописывается к имени; видимость в файле не едет — по умолчанию private; 201.

Тело и параметры

файл из export; visibility в строке запроса

POST/api/v1/manifests/{id}/expandСверяет манифест с каталогом источника — тот же размеченный список, что у описателя.

Сверяет манифест с каталогом источника — тот же размеченный список, что у описателя.

Тело и параметры

{ "sourceConnectionId" }

Манифест private другого человека для вас не существует: 404. Менять, пополнять и удалять манифест может только его автор или администратор, остальным — 403 access_denied; манифест без записанного автора меняет только администратор.

При создании манифеста можно передать items — выбранный перечень объектов. Манифест и его состав сохраняются вместе: при ошибке записи пустой манифест не остаётся. Строки получают происхождение manual; дубли по типу и имени пропускаются. Если items не передан, создаётся пустой манифест.

Версии у манифеста нет: имя — ключ, номер релиза пишут в имени («Релиз 0.1.22»). Запрос, в котором передан version, отклоняется: 400 version_removed.

Размеченный список (expand, describe):

{ "catalogChecked": true, "okCount": 2, "unsupportedCount": 0, "notInSourceCount": 1, "uncheckedCount": 0,
  "noDefinitionCount": 1,
  "rows": [ { "type": "CLS", "name": "PARUS_DOC", "typeName": "Класс", "status": "ok", "parameter": null, "detail": null },
            { "type": "DOM", "name": "NO_SUCH", "typeName": "Домен", "status": "not_in_source", "parameter": null, "detail": null },
            { "type": "DAT", "name": "Словари", "typeName": "Набор данных", "status": "ok",
              "parameter": "{\"format\":\"holkas-dataset/1\",\"name\":\"Словари\",…}", "detail": null },
            { "type": "DAT", "name": "Маршруты", "typeName": "Набор данных", "status": "no_definition",
              "parameter": null, "detail": "описание набора не задано" } ] }

Статусы строк: ok, not_in_source, unsupported_type, unchecked, no_definition. Строки ok передаются в objects операции; у набора данных — вместе с parameter в поле definition.

Набор данных (DAT) в каталоге базы не перечисляется: его задаёт описание. Описатель отдаёт его в parameter объекта, манифест хранит в строке. При раскрытии описание разбирается и проверяется без базы, имя в нём сверяется с именем строки; нет описания или оно негодно — no_definition, причина в detail. Годное описание сверяется с каталогом источника по корневой таблице (как TBP/JTB): нашлась — ok, нет — not_in_source. Источник, который хранит сам набор (git, пакет), находит его по имени и без описания.

Журнал аудита

Журнал изменений состояния Holkas: подключения, операции, заявки, манифесты, описатели, пользователи, группы, токены, соответствие ролей. Только на добавление; каждая строка подписана. В отличие от журнала конкретной операции, здесь фиксируются действия пользователей и изменения состояния Holkas.

GET/api/v1/auditСтроки журнала, новые сверху.

Строки журнала, новые сверху.

Параметры

entityType, entityId, actor, from, to, beforeId, afterId, limit (100, не больше 500)

[ { "id": 42, "entityType": "operation", "entityId": "ef94b018448b", "action": "apply_started",
    "summary": "Запущено применение плана в «test-db» (3 создать, 0 изменить, 0 удалить).",
    "changesJson": null, "actor": "ci-build", "onBehalfOf": null, "actorSource": "rest",
    "correlationId": "0HN…", "actorTokenId": 7, "actorTokenName": "ci-build-nightly",
    "createdAt": "2026-09-24T13:41:03Z" } ]
  • Администратор видит весь журнал. Остальные — свои действия, историю подключений, которые им доступны на чтение, операций, которые им видны, а также манифесты и описатели.
  • actor — кто действовал, onBehalfOf — за кого действовал агент, actorSource — дверь: web, rest, mcp, background. Фильтр actor находит и прямые действия человека, и действия агента от его имени.
  • actorTokenId и actorTokenName — токен доступа, которым пришёл вызов: какой из ключей агента или какой скрипт действовал. Имя сохраняется на момент действия и остаётся в журнале после отзыва токена. Для входа через браузер, OAuth и фоновой работы — null, как и для записей, сделанных до появления этих полей.
  • Постраничное чтение назад — beforeId = id последней полученной строки; новые с прошлого раза — afterId.
  • Список видов событий пополняется. Незнакомые entityType и action скрипт должен пропускать, а не падать на них.

Администрирование

Подключения: управление

Создавать подключения может администратор и группа с правом connections.create; создатель получает на подключение все права. Править, удалять и раздавать доступ может тот, у кого есть право manage.

POST/api/v1/connectionsСоздаёт подключение

Создаёт подключение; 201 с тем же ответом, что у чтения.

Тело и параметры

{ "name", "transportType", "settingsJson", "environment"? }

PUT/api/v1/connections/{id}Меняет имя и настройки

Меняет имя и настройки. Секреты с маской ******** или без поля остаются прежними.

Тело и параметры

{ "name"?, "settingsJson"? }

PUT/api/v1/connections/{id}/environmentСреда подключения

Среда подключения; null снимает.

Тело и параметры

{ "environment" }

PUT/api/v1/connections/{id}/parametersПараметры сравнения и применения для подключения как приёмника (см

Параметры сравнения и применения для подключения как приёмника (см. раздел о параметрах); переданный объект заменяет их целиком, null у ключа — «по умолчанию». Возвращает подключение; заданное лежит в его parameters.

Тело и параметры

{ "parameters": { "ignoreExtraTargetGrants": true, "ownerMap": { "egiszintegration": "parus" } } }

DELETE/api/v1/connections/{id}Удаляет подключение — с подтверждением

Удаляет подключение — с подтверждением. Ответ говорит, сколько сравнений с git ушло вместе с ним.

Тело и параметры

confirm

GET/api/v1/connections/{id}/delete-previewЧто уйдёт при удалении.

Что уйдёт при удалении.

Тело и параметры

—

GET/api/v1/connections/{id}/usageПоследние сравнения с git, в которых участвует подключение.

Последние сравнения с git, в которых участвует подключение.

Тело и параметры

—

POST/api/v1/connections/{id}/refresh-metaПроверяет связь и запоминает сведения о сервере (версия СУБД и др.).

Проверяет связь и запоминает сведения о сервере (версия СУБД и др.).

Тело и параметры

—

GET/api/v1/connections/{id}/grantsКому выдан доступ к подключению.

Кому выдан доступ к подключению.

Тело и параметры

—

PUT/api/v1/connections/{id}/grantsЗаменяет доступ целиком

Заменяет доступ целиком. У каждой строки ровно один получатель: userId или groupId.

Тело и параметры

{ "grants": [{ "userId"?, "groupId"?, "canRead", "canWrite", "canManage" }] }

settingsJson — строка с JSON настроек транспорта:

transportTypeПоля
DBproviderName (PostgreSQL или Oracle), host, port, database (у Oracle — служба), login, password; либо готовая connectionString. Необязательные: changeNameSchema — переименование схем { "из": "в" }, schemesInitMetaDataParusPostgres — список схем для чтения.
gitremoteUrl, defaultBranch, login, password (пароль или токен доступа хостинга).
S3endpointUrl, bucketName, accessKey, secretKey, region, keyPrefix, forcePathStyle, dbms.
curl -sS -i "${holkas_headers[@]}" -d '{"name":"test-db","transportType":"DB","environment":"test",
  "settingsJson":"{\"providerName\":\"PostgreSQL\",\"host\":\"db.local\",\"port\":\"5432\",\"database\":\"demo\",\"login\":\"parus\",\"password\":\"…\"}"}' \
  "$HOLKAS_API/connections"

Описатели: управление

Требуют права connections.create.

POST/api/v1/describersДобавляет описатель

Добавляет описатель; 201.

Тело и параметры

{ "name", "kind", "url" }

PUT/api/v1/describers/{id}Меняет описатель.

Меняет описатель.

Тело и параметры

{ "name"?, "kind"?, "url"? }

DELETE/api/v1/describers/{id}Удаляет — с подтверждением

Удаляет — с подтверждением; 204.

Тело и параметры

confirm

POST/api/v1/describers/{id}/testПроверяет, отвечает ли сервис: { "ok" }.

Проверяет, отвечает ли сервис: { "ok" }.

Тело и параметры

—

Токены

Список токенов можно читать и токеном; выпускать и отзывать — только в сессии веб-интерфейса (403 token_requires_session).

GET/api/v1/tokensВаши токены: name, purpose (rest, mcp или null), prefix, срок, последнее использование, кто выпустил

Ваши токены: name, purpose (rest, mcp или null), prefix, срок, последнее использование, кто выпустил. Администратор — чужие, с userId.

Тело и параметры

userId

POST/api/v1/tokensВыпускает токен

Выпускает токен; сам токен возвращается один раз, в поле token. Можно выпустить отдельный агентский токен для каждого клиента и отзывать их независимо.

Тело и параметры

{ "name", "purpose"?, "expiresAt"?, "userId"? }

DELETE/api/v1/tokens/{id}Отзывает токен

Отзывает токен; 204.

Тело и параметры

—

Пользователи и группы

Только администратор.

GET/api/v1/usersПользователи: учётная запись, группы, число токенов, источник (local или keycloak), сколько подключений человек видит.

Пользователи: учётная запись, группы, число токенов, источник (local или keycloak), сколько подключений человек видит.

Тело и параметры

—

POST/api/v1/usersСоздаёт человека (нужен password) или служебную учётную запись (isService: true, нужен владелец ownerUserId, пароля нет)

Создаёт человека (нужен password) или служебную учётную запись (isService: true, нужен владелец ownerUserId, пароля нет); 201.

Тело и параметры

{ "username", "displayName", "password"?, "email"?, "isService"?, "ownerUserId"? }

PUT/api/v1/users/{id}Меняет имя, почту, пароль, владельца служебной записи

Меняет имя, почту, пароль, владельца служебной записи; disabled: true отключает вход сразу, вместе с токенами.

Тело и параметры

{ "displayName"?, "password"?, "disabled"?, "email"?, "ownerUserId"? }

DELETE/api/v1/users/{id}Удаляет — с подтверждением, вместе с токенами и личным доступом.

Удаляет — с подтверждением, вместе с токенами и личным доступом.

Тело и параметры

confirm

PUT/api/v1/users/{id}/groupsЗаменяет локальные группы человека

Заменяет локальные группы человека; группы Keycloak управляются в Keycloak.

Тело и параметры

{ "groupIds": [ … ] }

GET/api/v1/users/{id}/effective-accessФактический доступ: каждое подключение, права на него и какая группа или личный грант их дали.

Фактический доступ: каждое подключение, права на него и какая группа или личный грант их дали.

Тело и параметры

—

GET/api/v1/groupsГруппы: участники, системные права, сколько подключений группа видит.

Группы: участники, системные права, сколько подключений группа видит.

Тело и параметры

—

POST/api/v1/groupsСоздаёт группу

Создаёт группу; 201.

Тело и параметры

{ "name", "isAdmin"? }

PUT/api/v1/groups/{id}Меняет имя и признак администратора

Меняет имя и признак администратора. Последнюю админ-группу разжаловать нельзя.

Тело и параметры

{ "name"?, "isAdmin"? }

DELETE/api/v1/groups/{id}Удаляет — с подтверждением.

Удаляет — с подтверждением.

Тело и параметры

confirm

GET/api/v1/groups/permissions-catalogСистемные права: connections.create, users.manage, confirm-floors.set.

Системные права: connections.create, users.manage, confirm-floors.set.

Тело и параметры

—

PUT/api/v1/groups/{id}/permissionsЗаменяет системные права группы.

Заменяет системные права группы.

Тело и параметры

{ "permissions": [ … ] }

GET/api/v1/groups/{id}/connection-grantsДоступ группы к подключениям.

Доступ группы к подключениям.

Тело и параметры

—

PUT/api/v1/groups/{id}/connection-grantsЗаменяет доступ группы целиком.

Заменяет доступ группы целиком.

Тело и параметры

{ "grants": [{ "connectionId", "canRead", "canWrite", "canManage" }] }

Автономия

Какие действия требуют подтверждения человеком — для вас лично. Применение в базу (apply.db) требует его всегда.

GET/api/v1/autonomyДействия: key, label, default, ваша настройка override, итог effective (auto или confirm), alwaysConfirm.

Действия: key, label, default, ваша настройка override, итог effective (auto или confirm), alwaysConfirm.

Тело

—

PUT/api/v1/autonomy/{operationKey}Задаёт auto или confirm

Задаёт auto или confirm; null возвращает значение по умолчанию.

Тело

{ "policy" }

Ключи: connection.create, connection.update, connection.delete, connection.grants, describer.create, describer.update, describer.delete, manifest.create, manifest.update, manifest.import, manifest.delete, operation.reason, user.delete, group.delete, plan.build, apply.db, apply.transport.

Хранение

GET/api/v1/maintenance/retentionПолитика хранения операций (задаётся параметрами запуска), итог прошлой чистки и что подлежит удалению сейчас.

Политика хранения операций (задаётся параметрами запуска), итог прошлой чистки и что подлежит удалению сейчас.

POST/api/v1/maintenance/retention/sweepЧистка по команде — только администратор

Чистка по команде — только администратор. Работает и при выключенной политике.

Обновления

Проверка обновлений доступна всем вошедшим пользователям. CLI использует GUID своего сервера; собственного идентификатора или базы у него нет.

GET/api/v1/updatesСведения из кеша, без обращения в интернет.

Сведения из кеша, без обращения в интернет.

Тело

—

POST/api/v1/updates/checkПроверяет релиз, если кеш устарел

Проверяет релиз, если кеш устарел; сохраняет последнюю переданную версию CLI.

Тело

{ "cliVersion": "1.2.3" } или {}

PUT/api/v1/updates/settingsВключает или выключает автоматическую проверку для всей установки

Включает или выключает автоматическую проверку для всей установки. Только администратор.

Тело

{ "enabled": true }

Ответ содержит enabled, version, cliVersion, latest (version, releaseUrl, publishedAt), updateAvailable, cliUpdateAvailable, lastCheckedAt, error. Если релизы ещё не добавлены, latest равен null. Отказ Aviso возвращает последний известный релиз и текст в error, не превращая проверку в ошибку основной операции.

Кеш хранится в базе состояния и действует сутки. После сбоя повтор возможен через 15 минут. Новая версия сервера или другой адрес Aviso требуют новой проверки. Сборки из исходников с версией 0.0.0 не отправляют статистику.

При обращении в Aviso передаются GUID установки и версии сервера и последнего CLI. Aviso сохраняет внешний IP, первый контакт и дату обновления сведений. Подробности — проверка обновлений.

Коды отказов

Отказ HTTP-запроса и status: "Failed" уже созданной операции обрабатываются отдельно. В первом случае разбирайте error из ответа ниже; во втором — состояние и журнал операции.

HTTPerrorКогда
400invalid_requestТело не читается или не хватает обязательного поля; подробности — в fields.
400invalid, no_objects, ref_not_applicable, input_required, input_taken, output_name_not_applicable, …Запрос понятен, но не выполним по правилам — message говорит, что исправить.
400plan_not_ready, operation_finished, operation_not_finishedОперация не в том состоянии: применять можно только PlanReady, перестраивать остаток — только завершённую.
400plan_empty, no_commands_selected, no_uncoveredПрименять или добавлять нечего.
401unauthorizedТокена нет, он отозван, истёк или неверен.
403access_deniedНет права на подключение или системного права; message называет какого.
403mcp_token_door, rest_token_door, service_account_doorТокен не для этой двери.
403token_requires_sessionТокены выпускаются и отзываются только в веб-интерфейсе.
403forbiddenДействие только для администратора.
404not_found, artifact_not_found, input_not_foundНет такого — или он вам не виден.
409confirmation_invalidНомер заявки не подходит: чужая, отклонённая, использованная или просроченная.
409already_running, duplicate_nameКонфликт с существующим.
428confirmation_requiredНужно подтверждение человеком; в proposal — номер заявки.
502source_error, describer_unreachableИсточник или внешний сервис не ответил как ожидалось.
500internal_errorСбой сервера; подробности — в журнале сервера.

Список кодов может пополняться; скрипт, ветвящийся по error, должен иметь ветку «неизвестный код».

Сводка объектов

Строка сводки плана описывает объект верхнего уровня, а не первую команду его части. Например, новые атрибуты отображаются как изменение класса. Объекты разных типов с одинаковым именем остаются отдельными строками.

В parts находятся элементы состава изменения: kind — код вида, name — подпись, created, updated, deleted — счётчики. Нулевые счётчики могут отсутствовать. Команды параметров метода учитываются как изменение метода; число элементов не равно числу команд. Скриптам, разбиравшим прежние тип и действие строки, нужно учитывать этот контракт.

Время и дни аудита

Даты передаются с указанием UTC. В интерфейсе время операций и дни истории/аудита показываются в часовом поясе читателя.

Гистограмма веб-интерфейса использует служебный маршрут /api/v1/audit/histogram, который не входит в публичный REST-контракт. У него есть необязательный timeZone — имя IANA, например Asia/Almaty. Без него или с неизвестным серверу именем дни считаются по UTC. Ответ возвращает фактически использованный timeZone; days[].day — начало соответствующего местного дня, выраженное в UTC. Сверяйте это поле, если строите собственную диаграмму.