Справочник
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-ответ и результат переноса — разные вещи
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 | Поля |
|---|---|
DB | providerName (PostgreSQL или Oracle), host, port, database (у Oracle — служба), login, password; либо готовая connectionString. Необязательные: changeNameSchema — переименование схем { "из": "в" }, schemesInitMetaDataParusPostgres — список схем для чтения. |
git | remoteUrl, defaultBranch, login, password (пароль или токен доступа хостинга). |
S3 | endpointUrl, 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 из ответа ниже; во втором — состояние и журнал операции.
| HTTP | error | Когда |
|---|---|---|
| 400 | invalid_request | Тело не читается или не хватает обязательного поля; подробности — в fields. |
| 400 | invalid, no_objects, ref_not_applicable, input_required, input_taken, output_name_not_applicable, … | Запрос понятен, но не выполним по правилам — message говорит, что исправить. |
| 400 | plan_not_ready, operation_finished, operation_not_finished | Операция не в том состоянии: применять можно только PlanReady, перестраивать остаток — только завершённую. |
| 400 | plan_empty, no_commands_selected, no_uncovered | Применять или добавлять нечего. |
| 401 | unauthorized | Токена нет, он отозван, истёк или неверен. |
| 403 | access_denied | Нет права на подключение или системного права; message называет какого. |
| 403 | mcp_token_door, rest_token_door, service_account_door | Токен не для этой двери. |
| 403 | token_requires_session | Токены выпускаются и отзываются только в веб-интерфейсе. |
| 403 | forbidden | Действие только для администратора. |
| 404 | not_found, artifact_not_found, input_not_found | Нет такого — или он вам не виден. |
| 409 | confirmation_invalid | Номер заявки не подходит: чужая, отклонённая, использованная или просроченная. |
| 409 | already_running, duplicate_name | Конфликт с существующим. |
| 428 | confirmation_required | Нужно подтверждение человеком; в proposal — номер заявки. |
| 502 | source_error, describer_unreachable | Источник или внешний сервис не ответил как ожидалось. |
| 500 | internal_error | Сбой сервера; подробности — в журнале сервера. |
Список кодов может пополняться; скрипт, ветвящийся по error, должен иметь ветку «неизвестный код».
Сводка объектов
Строка сводки плана описывает объект верхнего уровня, а не первую команду его части. Например, новые атрибуты отображаются как изменение класса. Объекты разных типов с одинаковым именем остаются отдельными строками.
В parts находятся элементы состава изменения: kind — код вида, name — подпись, created, updated, deleted — счётчики. Нулевые счётчики могут отсутствовать. Команды параметров метода учитываются как изменение метода; число элементов не равно числу команд. Скриптам, разбиравшим прежние тип и действие строки, нужно учитывать этот контракт.
Время и дни аудита
Даты передаются с указанием UTC. В интерфейсе время операций и дни истории/аудита показываются в часовом поясе читателя.
Гистограмма веб-интерфейса использует служебный маршрут /api/v1/audit/histogram, который не входит в публичный REST-контракт. У него есть необязательный timeZone — имя IANA, например Asia/Almaty. Без него или с неизвестным серверу именем дни считаются по UTC. Ответ возвращает фактически использованный timeZone; days[].day — начало соответствующего местного дня, выраженное в UTC. Сверяйте это поле, если строите собственную диаграмму.