API · MCP

API и MCP «Помощника SA»

Внешнее API платформы «Помощник SA»: проекты, папки и артефакты всех инструментов (DBML, PlantUML, OpenAPI, AsyncAPI, BPMN, XSD, WSDL, XML, JSON Schema, YAML, JSON, Markdown, AsciiDoc) с историей версий.

Адрес APIhttps://helper-sa.ru/api/ext/v1

MCP-серверhttps://helper-sa.ru/api/mcp

Версияv1.0.0

Получить ключ API Подключить ИИ-агентовMCP на GitHub

Начало работы

Доступ. API доступно на тарифах «Про» и выше (в том числе на пробном периоде). Создайте ключ в профиле («Ключи API») и передавайте его в заголовке Authorization: Bearer sah_… (или X-API-Key: sah_…). Права — те же, что у владельца ключа в веб-интерфейсе: лимиты тарифа, доступ к проектам, удаление — автор или владелец проекта.

Версии. Каждое изменение содержимого создаёт версию артефакта, как кнопка «Сохранить» в редакторе. В истории версий указаны автор и источник изменений: WEB, API, MCP или AI. Откат к версии создаёт новую версию; …/diff показывает разницу между версиями (unified diff).

Защита от затирания. Артефакт возвращается с номером текущей версии version. Передайте его как baseVersion при изменении (PUT, …/edit): если с тех пор артефакт сохранил кто-то другой (в редакторе, через API или MCP), правка не применяется — ответ 409 VERSION_CONFLICT. Перечитайте артефакт и повторите.

Точечные правки. POST …/edit заменяет фрагменты текста (oldText → newText) без передачи файла целиком.

Проверка синтаксиса (без ИИ) — POST /validate для текста и GET …/validation для сохранённого артефакта: те же правила, что в редакторах (DBML, PlantUML, OpenAPI, AsyncAPI, JSON Schema, XSD/WSDL со связанными файлами проекта, BPMN, XML, YAML, JSON).

Ошибки — JSON { "code": "…", "message": "…" }: API_KEY_INVALID (401); API_TARIFF_REQUIRED, AUTH_USER_BLOCKED, FORBIDDEN (403 — тариф ниже «Про», пользователь заблокирован, действие доступно только владельцу проекта или автору); NOT_FOUND (404); VALIDATION_FAILED, EDIT_NOT_FOUND / EDIT_AMBIGUOUS (400, точечная правка); VERSION_CONFLICT (409); PROJECT_LIMIT, <TOOL>_DIAGRAM_LIMIT (409, лимиты тарифа), PROJECT_FOLDER_NAME_TAKEN, PROJECT_FOLDER_CYCLE (409, дерево папок).

Одновременная работа. Если артефакт открыт в редакторе у участников проекта, ваша правка через API не потеряется и не затрёт их изменения молча: сохранение в редакторе от устаревшей версии покажет им окно конфликта (затереть, посмотреть текущую версию, сохранить как новый артефакт или отменить).

Для ИИ-агентов тот же набор операций доступен через MCP-сервер /api/mcp.

Первый запрос

curl 'https://helper-sa.ru/api/ext/v1/projects' \
  -H 'Authorization: Bearer sah_ВАШ_КЛЮЧ'

Владелец ключа и доступные инструменты

GET/me

Владелец ключа — логин, имя, тариф и срок его действия

Ответы

200 Пользователь — ExtUser
401 Нет ключа, ключ неизвестен или истёк (`API_KEY_INVALID`)
403 `API_TARIFF_REQUIRED` — тариф владельца ключа ниже «Про»; `AUTH_USER_BLOCKED` — пользователь заблокирован; `FORBIDDEN` — действие доступно не всем участникам (изменить или удалить проект — владелец; удалить артефакт — автор или владелец проекта; перенести артефакт — автор)

curl

curl -X GET 'https://helper-sa.ru/api/ext/v1/me' \
  -H 'Authorization: Bearer sah_ВАШ_КЛЮЧ'

GET/tools

Инструменты, артефакты которых доступны через API

Ответы

200 Коды инструментов — ExtTool[]
401 Нет ключа, ключ неизвестен или истёк (`API_KEY_INVALID`)
403 `API_TARIFF_REQUIRED` — тариф владельца ключа ниже «Про»; `AUTH_USER_BLOCKED` — пользователь заблокирован; `FORBIDDEN` — действие доступно не всем участникам (изменить или удалить проект — владелец; удалить артефакт — автор или владелец проекта; перенести артефакт — автор)

curl

curl -X GET 'https://helper-sa.ru/api/ext/v1/tools' \
  -H 'Authorization: Bearer sah_ВАШ_КЛЮЧ'

Проекты, папки и размещение артефактов

GET/projects

Мои проекты (владелец или участник)

Ответы

200 Проекты — ExtProject[]
401 Нет ключа, ключ неизвестен или истёк (`API_KEY_INVALID`)
403 `API_TARIFF_REQUIRED` — тариф владельца ключа ниже «Про»; `AUTH_USER_BLOCKED` — пользователь заблокирован; `FORBIDDEN` — действие доступно не всем участникам (изменить или удалить проект — владелец; удалить артефакт — автор или владелец проекта; перенести артефакт — автор)

curl

curl -X GET 'https://helper-sa.ru/api/ext/v1/projects' \
  -H 'Authorization: Bearer sah_ВАШ_КЛЮЧ'

POST/projects

Создать проект

Тело запроса ExtProjectInput

`name`*	string	пример: `Оплата заказа`
`description`	string \| null

Ответы

201 Проект — ExtProject
400 Некорректный запрос (`VALIDATION_FAILED`)
401 Нет ключа, ключ неизвестен или истёк (`API_KEY_INVALID`)
403 `API_TARIFF_REQUIRED` — тариф владельца ключа ниже «Про»; `AUTH_USER_BLOCKED` — пользователь заблокирован; `FORBIDDEN` — действие доступно не всем участникам (изменить или удалить проект — владелец; удалить артефакт — автор или владелец проекта; перенести артефакт — автор)
409 Лимит тарифа (`PROJECT_LIMIT` — проекты, `<TOOL>_DIAGRAM_LIMIT` — артефакты инструмента) или конфликт в дереве папок (`PROJECT_FOLDER_NAME_TAKEN` — папка с таким названием уже есть, `PROJECT_FOLDER_CYCLE` — папку нельзя перенести в саму себя или во вложенную)

curl

curl -X POST 'https://helper-sa.ru/api/ext/v1/projects' \
  -H 'Authorization: Bearer sah_ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Оплата заказа"}'

GET/projects/search

Поиск проектов с фильтрами, сортировкой и страницами

Параметры

`query`	query · string	Подстрока в названии или описании (без учёта регистра)
`role`	query · string any \| owner \| member	Только свои (owner), только чужие, где вы участник (member), или все (any)
`updatedFrom`	query · string(date-time)	Изменены не раньше
`updatedTo`	query · string(date-time)	Изменены не позже
`sort`	query · string updatedAt \| createdAt \| name
`order`	query · string asc \| desc
`page`	query · integer
`size`	query · integer

Ответы

200 Страница проектов — ExtProjectPage
400 Некорректный запрос (`VALIDATION_FAILED`)
401 Нет ключа, ключ неизвестен или истёк (`API_KEY_INVALID`)
403 `API_TARIFF_REQUIRED` — тариф владельца ключа ниже «Про»; `AUTH_USER_BLOCKED` — пользователь заблокирован; `FORBIDDEN` — действие доступно не всем участникам (изменить или удалить проект — владелец; удалить артефакт — автор или владелец проекта; перенести артефакт — автор)

curl

curl -X GET 'https://helper-sa.ru/api/ext/v1/projects/search' \
  -H 'Authorization: Bearer sah_ВАШ_КЛЮЧ'

GET/projects/{projectId}

Проект

Параметры

projectId* path · string(uuid)

Ответы

200 Проект — ExtProject
401 Нет ключа, ключ неизвестен или истёк (`API_KEY_INVALID`)
403 `API_TARIFF_REQUIRED` — тариф владельца ключа ниже «Про»; `AUTH_USER_BLOCKED` — пользователь заблокирован; `FORBIDDEN` — действие доступно не всем участникам (изменить или удалить проект — владелец; удалить артефакт — автор или владелец проекта; перенести артефакт — автор)
404 Не найдено или нет доступа (`NOT_FOUND`)

curl

curl -X GET 'https://helper-sa.ru/api/ext/v1/projects/<projectId>' \
  -H 'Authorization: Bearer sah_ВАШ_КЛЮЧ'

PUT/projects/{projectId}

Изменить название и описание (владелец)

Параметры

projectId* path · string(uuid)

Тело запроса ExtProjectInput

`name`*	string	пример: `Оплата заказа`
`description`	string \| null

Ответы

200 Проект — ExtProject
401 Нет ключа, ключ неизвестен или истёк (`API_KEY_INVALID`)
403 `API_TARIFF_REQUIRED` — тариф владельца ключа ниже «Про»; `AUTH_USER_BLOCKED` — пользователь заблокирован; `FORBIDDEN` — действие доступно не всем участникам (изменить или удалить проект — владелец; удалить артефакт — автор или владелец проекта; перенести артефакт — автор)
404 Не найдено или нет доступа (`NOT_FOUND`)

curl

curl -X PUT 'https://helper-sa.ru/api/ext/v1/projects/<projectId>' \
  -H 'Authorization: Bearer sah_ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Оплата заказа"}'

DELETE/projects/{projectId}

Удалить проект (владелец); артефакты вернутся в личное пространство авторов

Параметры

projectId* path · string(uuid)

Ответы

204 Удалён
401 Нет ключа, ключ неизвестен или истёк (`API_KEY_INVALID`)
403 `API_TARIFF_REQUIRED` — тариф владельца ключа ниже «Про»; `AUTH_USER_BLOCKED` — пользователь заблокирован; `FORBIDDEN` — действие доступно не всем участникам (изменить или удалить проект — владелец; удалить артефакт — автор или владелец проекта; перенести артефакт — автор)
404 Не найдено или нет доступа (`NOT_FOUND`)

curl

curl -X DELETE 'https://helper-sa.ru/api/ext/v1/projects/<projectId>' \
  -H 'Authorization: Bearer sah_ВАШ_КЛЮЧ'

GET/projects/{projectId}/tree

Дерево проекта — папки и артефакты с путями

Путь артефакта «папка/подпапка/название» — адрес для ссылок между файлами ($ref, include, schemaLocation).

Параметры

projectId* path · string(uuid)

Ответы

200 Дерево — ExtTree
401 Нет ключа, ключ неизвестен или истёк (`API_KEY_INVALID`)
403 `API_TARIFF_REQUIRED` — тариф владельца ключа ниже «Про»; `AUTH_USER_BLOCKED` — пользователь заблокирован; `FORBIDDEN` — действие доступно не всем участникам (изменить или удалить проект — владелец; удалить артефакт — автор или владелец проекта; перенести артефакт — автор)
404 Не найдено или нет доступа (`NOT_FOUND`)

curl

curl -X GET 'https://helper-sa.ru/api/ext/v1/projects/<projectId>/tree' \
  -H 'Authorization: Bearer sah_ВАШ_КЛЮЧ'

GET/projects/{projectId}/folders

Папки проекта — все или по подстроке в названии

Параметры

`projectId`*	path · string(uuid)
`query`	query · string	Подстрока в названии папки (без учёта регистра); нет — все папки
`parentId`	query · string(uuid)	Только вложенные в эту папку (на любую глубину)

Ответы

200 Папки с путями, по алфавиту путей — ExtFolder[]
401 Нет ключа, ключ неизвестен или истёк (`API_KEY_INVALID`)
403 `API_TARIFF_REQUIRED` — тариф владельца ключа ниже «Про»; `AUTH_USER_BLOCKED` — пользователь заблокирован; `FORBIDDEN` — действие доступно не всем участникам (изменить или удалить проект — владелец; удалить артефакт — автор или владелец проекта; перенести артефакт — автор)
404 Не найдено или нет доступа (`NOT_FOUND`)

curl

curl -X GET 'https://helper-sa.ru/api/ext/v1/projects/<projectId>/folders' \
  -H 'Authorization: Bearer sah_ВАШ_КЛЮЧ'

POST/projects/{projectId}/folders

Создать папку

Параметры

projectId* path · string(uuid)

Тело запроса ExtFolderInput

`name`*	string	пример: `schemas`
`parentId`	string(uuid) \| null	Родительская папка; нет — корень

Ответы

201 Папка — ExtFolder
400 Некорректный запрос (`VALIDATION_FAILED`)
401 Нет ключа, ключ неизвестен или истёк (`API_KEY_INVALID`)
403 `API_TARIFF_REQUIRED` — тариф владельца ключа ниже «Про»; `AUTH_USER_BLOCKED` — пользователь заблокирован; `FORBIDDEN` — действие доступно не всем участникам (изменить или удалить проект — владелец; удалить артефакт — автор или владелец проекта; перенести артефакт — автор)
409 Лимит тарифа (`PROJECT_LIMIT` — проекты, `<TOOL>_DIAGRAM_LIMIT` — артефакты инструмента) или конфликт в дереве папок (`PROJECT_FOLDER_NAME_TAKEN` — папка с таким названием уже есть, `PROJECT_FOLDER_CYCLE` — папку нельзя перенести в саму себя или во вложенную)

curl

curl -X POST 'https://helper-sa.ru/api/ext/v1/projects/<projectId>/folders' \
  -H 'Authorization: Bearer sah_ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{"name":"schemas"}'

GET/projects/{projectId}/folders/{folderId}

Папка с содержимым — вложенные папки и артефакты

Параметры

`projectId`*	path · string(uuid)
`folderId`*	path · string(uuid)
`recursive`	query · boolean	true — всё содержимое на любую глубину; false — только непосредственное

Ответы

200 Папка и её содержимое — ExtFolderContent
401 Нет ключа, ключ неизвестен или истёк (`API_KEY_INVALID`)
403 `API_TARIFF_REQUIRED` — тариф владельца ключа ниже «Про»; `AUTH_USER_BLOCKED` — пользователь заблокирован; `FORBIDDEN` — действие доступно не всем участникам (изменить или удалить проект — владелец; удалить артефакт — автор или владелец проекта; перенести артефакт — автор)
404 Не найдено или нет доступа (`NOT_FOUND`)

curl

curl -X GET 'https://helper-sa.ru/api/ext/v1/projects/<projectId>/folders/<folderId>' \
  -H 'Authorization: Bearer sah_ВАШ_КЛЮЧ'

PUT/projects/{projectId}/folders/{folderId}

Переименовать или перенести папку

Параметры

`projectId`*	path · string(uuid)
`folderId`*	path · string(uuid)

Тело запроса ExtFolderInput

`name`*	string	пример: `schemas`
`parentId`	string(uuid) \| null	Родительская папка; нет — корень

Ответы

200 Папка — ExtFolder
400 Некорректный запрос (`VALIDATION_FAILED`)
401 Нет ключа, ключ неизвестен или истёк (`API_KEY_INVALID`)
403 `API_TARIFF_REQUIRED` — тариф владельца ключа ниже «Про»; `AUTH_USER_BLOCKED` — пользователь заблокирован; `FORBIDDEN` — действие доступно не всем участникам (изменить или удалить проект — владелец; удалить артефакт — автор или владелец проекта; перенести артефакт — автор)
404 Не найдено или нет доступа (`NOT_FOUND`)

curl

curl -X PUT 'https://helper-sa.ru/api/ext/v1/projects/<projectId>/folders/<folderId>' \
  -H 'Authorization: Bearer sah_ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{"name":"schemas"}'

DELETE/projects/{projectId}/folders/{folderId}

Удалить папку (содержимое переходит в родительскую)

Параметры

`projectId`*	path · string(uuid)
`folderId`*	path · string(uuid)

Ответы

204 Удалена
401 Нет ключа, ключ неизвестен или истёк (`API_KEY_INVALID`)
403 `API_TARIFF_REQUIRED` — тариф владельца ключа ниже «Про»; `AUTH_USER_BLOCKED` — пользователь заблокирован; `FORBIDDEN` — действие доступно не всем участникам (изменить или удалить проект — владелец; удалить артефакт — автор или владелец проекта; перенести артефакт — автор)
404 Не найдено или нет доступа (`NOT_FOUND`)

curl

curl -X DELETE 'https://helper-sa.ru/api/ext/v1/projects/<projectId>/folders/<folderId>' \
  -H 'Authorization: Bearer sah_ВАШ_КЛЮЧ'

PUT/projects/{projectId}/placements

Положить артефакт проекта в папку (folderId = null — в корень)

Параметры

projectId* path · string(uuid)

Тело запроса ExtPlacement

`tool`*	string	пример: `xsd`
`artifactId`*	string(uuid)
`folderId`	string(uuid) \| null

Ответы

204 Размещён
401 Нет ключа, ключ неизвестен или истёк (`API_KEY_INVALID`)
403 `API_TARIFF_REQUIRED` — тариф владельца ключа ниже «Про»; `AUTH_USER_BLOCKED` — пользователь заблокирован; `FORBIDDEN` — действие доступно не всем участникам (изменить или удалить проект — владелец; удалить артефакт — автор или владелец проекта; перенести артефакт — автор)
404 Не найдено или нет доступа (`NOT_FOUND`)

curl

curl -X PUT 'https://helper-sa.ru/api/ext/v1/projects/<projectId>/placements' \
  -H 'Authorization: Bearer sah_ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{"tool":"xsd","artifactId":"…"}'

Артефакты инструментов и их версии

GET/artifacts

Артефакты — личные или проекта

Параметры

`projectId`	query · string(uuid)	Проект; не задан — личные артефакты
`tool`	query · string	Только артефакты этого инструмента

Ответы

200 Артефакты (без содержимого) — ExtArtifactMeta[]
401 Нет ключа, ключ неизвестен или истёк (`API_KEY_INVALID`)
403 `API_TARIFF_REQUIRED` — тариф владельца ключа ниже «Про»; `AUTH_USER_BLOCKED` — пользователь заблокирован; `FORBIDDEN` — действие доступно не всем участникам (изменить или удалить проект — владелец; удалить артефакт — автор или владелец проекта; перенести артефакт — автор)
404 Не найдено или нет доступа (`NOT_FOUND`)

curl

curl -X GET 'https://helper-sa.ru/api/ext/v1/artifacts' \
  -H 'Authorization: Bearer sah_ВАШ_КЛЮЧ'

POST/artifacts

Создать артефакт (версия 1)

Тело запроса ExtArtifactCreate

`tool`*	string	пример: `openapi`
`name`*	string	пример: `orders.yaml`
`source`*	string
`projectId`	string(uuid) \| null	Проект; нет — личный артефакт
`folderId`	string(uuid) \| null	Папка проекта

Ответы

201 Артефакт — ExtArtifact
400 Некорректный запрос (`VALIDATION_FAILED`)
401 Нет ключа, ключ неизвестен или истёк (`API_KEY_INVALID`)
403 `API_TARIFF_REQUIRED` — тариф владельца ключа ниже «Про»; `AUTH_USER_BLOCKED` — пользователь заблокирован; `FORBIDDEN` — действие доступно не всем участникам (изменить или удалить проект — владелец; удалить артефакт — автор или владелец проекта; перенести артефакт — автор)
409 Лимит тарифа (`PROJECT_LIMIT` — проекты, `<TOOL>_DIAGRAM_LIMIT` — артефакты инструмента) или конфликт в дереве папок (`PROJECT_FOLDER_NAME_TAKEN` — папка с таким названием уже есть, `PROJECT_FOLDER_CYCLE` — папку нельзя перенести в саму себя или во вложенную)

curl

curl -X POST 'https://helper-sa.ru/api/ext/v1/artifacts' \
  -H 'Authorization: Bearer sah_ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{"tool":"openapi","name":"orders.yaml","source":"…"}'

GET/artifacts/search

Поиск артефактов по названию и содержимому

Без projectId ищет в личных артефактах и во всех ваших проектах. inContent=true — искать подстроку и в тексте артефактов; в ответе — найденные строки с номерами.

Параметры

`query`	query · string	Подстрока (без учёта регистра); нет — все артефакты по остальным фильтрам
`inContent`	query · boolean	Искать также в исходном тексте артефактов
`projectId`	query · string(uuid)
`personal`	query · boolean	true — только личные артефакты (вне проектов)
`folderId`	query · string(uuid)	Только в этой папке и вложенных (нужен projectId)
`tool`	query · string
`updatedFrom`	query · string(date-time)	Изменены не раньше
`updatedTo`	query · string(date-time)	Изменены не позже
`sort`	query · string updatedAt \| createdAt \| name \| path
`order`	query · string asc \| desc
`page`	query · integer
`size`	query · integer

Ответы

200 Страница найденных артефактов — ExtArtifactSearchPage
400 Некорректный запрос (`VALIDATION_FAILED`)
401 Нет ключа, ключ неизвестен или истёк (`API_KEY_INVALID`)
403 `API_TARIFF_REQUIRED` — тариф владельца ключа ниже «Про»; `AUTH_USER_BLOCKED` — пользователь заблокирован; `FORBIDDEN` — действие доступно не всем участникам (изменить или удалить проект — владелец; удалить артефакт — автор или владелец проекта; перенести артефакт — автор)
404 Не найдено или нет доступа (`NOT_FOUND`)

curl

curl -X GET 'https://helper-sa.ru/api/ext/v1/artifacts/search' \
  -H 'Authorization: Bearer sah_ВАШ_КЛЮЧ'

GET/artifacts/{tool}/{artifactId}

Артефакт с содержимым

Параметры

`tool`*	path · string	Код инструмента (`GET /tools`), например `openapi`
`artifactId`*	path · string(uuid)

Ответы

200 Артефакт — ExtArtifact
401 Нет ключа, ключ неизвестен или истёк (`API_KEY_INVALID`)
403 `API_TARIFF_REQUIRED` — тариф владельца ключа ниже «Про»; `AUTH_USER_BLOCKED` — пользователь заблокирован; `FORBIDDEN` — действие доступно не всем участникам (изменить или удалить проект — владелец; удалить артефакт — автор или владелец проекта; перенести артефакт — автор)
404 Не найдено или нет доступа (`NOT_FOUND`)

curl

curl -X GET 'https://helper-sa.ru/api/ext/v1/artifacts/openapi/<artifactId>' \
  -H 'Authorization: Bearer sah_ВАШ_КЛЮЧ'

PUT/artifacts/{tool}/{artifactId}

Изменить название и/или содержимое — при изменениях создаётся версия

Параметры

`tool`*	path · string	Код инструмента (`GET /tools`), например `openapi`
`artifactId`*	path · string(uuid)

Тело запроса ExtArtifactUpdate

`name`	string
`source`	string
`baseVersion`	integer	Версия, от которой сделана правка; если артефакт с тех пор изменён — 409 VERSION_CONFLICT

Ответы

200 Артефакт — ExtArtifact
400 Некорректный запрос (`VALIDATION_FAILED`)
401 Нет ключа, ключ неизвестен или истёк (`API_KEY_INVALID`)
403 `API_TARIFF_REQUIRED` — тариф владельца ключа ниже «Про»; `AUTH_USER_BLOCKED` — пользователь заблокирован; `FORBIDDEN` — действие доступно не всем участникам (изменить или удалить проект — владелец; удалить артефакт — автор или владелец проекта; перенести артефакт — автор)
404 Не найдено или нет доступа (`NOT_FOUND`)
409 `VERSION_CONFLICT` — артефакт изменён после версии `baseVersion`; правка не применена. Перечитайте артефакт (номер текущей версии — `version`) и повторите правку.

curl

curl -X PUT 'https://helper-sa.ru/api/ext/v1/artifacts/openapi/<artifactId>' \
  -H 'Authorization: Bearer sah_ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{}'

DELETE/artifacts/{tool}/{artifactId}

Удалить артефакт (автор или владелец проекта)

Параметры

`tool`*	path · string	Код инструмента (`GET /tools`), например `openapi`
`artifactId`*	path · string(uuid)

Ответы

204 Удалён
401 Нет ключа, ключ неизвестен или истёк (`API_KEY_INVALID`)
403 `API_TARIFF_REQUIRED` — тариф владельца ключа ниже «Про»; `AUTH_USER_BLOCKED` — пользователь заблокирован; `FORBIDDEN` — действие доступно не всем участникам (изменить или удалить проект — владелец; удалить артефакт — автор или владелец проекта; перенести артефакт — автор)
404 Не найдено или нет доступа (`NOT_FOUND`)

curl

curl -X DELETE 'https://helper-sa.ru/api/ext/v1/artifacts/openapi/<artifactId>' \
  -H 'Authorization: Bearer sah_ВАШ_КЛЮЧ'

POST/artifacts/{tool}/{artifactId}/edit

Точечные правки — замена фрагментов текста (при изменениях создаётся версия)

Правки применяются по порядку, к результату предыдущей. oldText должен встречаться в тексте ровно один раз (иначе EDIT_NOT_FOUND или EDIT_AMBIGUOUS — добавьте окружающие строки); replaceAll: true заменяет все вхождения. Если хотя бы одна правка не применяется, артефакт не меняется. В ответе — номер новой версии и результат проверки синтаксиса.

Параметры

`tool`*	path · string	Код инструмента (`GET /tools`), например `openapi`
`artifactId`*	path · string(uuid)

Тело запроса ExtArtifactEdit

`edits`*	ExtEdit[]
`baseVersion`	integer	Версия, от которой сделана правка; если артефакт с тех пор изменён — 409 VERSION_CONFLICT

Ответы

200 Результат — ExtEditResult
400 Некорректный запрос (`VALIDATION_FAILED`)
401 Нет ключа, ключ неизвестен или истёк (`API_KEY_INVALID`)
403 `API_TARIFF_REQUIRED` — тариф владельца ключа ниже «Про»; `AUTH_USER_BLOCKED` — пользователь заблокирован; `FORBIDDEN` — действие доступно не всем участникам (изменить или удалить проект — владелец; удалить артефакт — автор или владелец проекта; перенести артефакт — автор)
404 Не найдено или нет доступа (`NOT_FOUND`)
409 `VERSION_CONFLICT` — артефакт изменён после версии `baseVersion`; правка не применена. Перечитайте артефакт (номер текущей версии — `version`) и повторите правку.

curl

curl -X POST 'https://helper-sa.ru/api/ext/v1/artifacts/openapi/<artifactId>/edit' \
  -H 'Authorization: Bearer sah_ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{"edits":null}'

GET/artifacts/{tool}/{artifactId}/diff

Разница между версиями (unified diff)

Номера версий: to — по умолчанию текущая, from — по умолчанию предыдущая перед to (без параметров — что изменило последнее сохранение). Сервер хранит ограниченное число последних версий; для более старой — 404.

Параметры

`tool`*	path · string	Код инструмента (`GET /tools`), например `openapi`
`artifactId`*	path · string(uuid)
`from`	query · integer	Номер версии «было» (0 — пустой текст)
`to`	query · integer	Номер версии «стало»
`context`	query · integer	Сколько неизменённых строк показывать вокруг изменений

Ответы

200 Разница — ExtDiff
400 Некорректный запрос (`VALIDATION_FAILED`)
401 Нет ключа, ключ неизвестен или истёк (`API_KEY_INVALID`)
403 `API_TARIFF_REQUIRED` — тариф владельца ключа ниже «Про»; `AUTH_USER_BLOCKED` — пользователь заблокирован; `FORBIDDEN` — действие доступно не всем участникам (изменить или удалить проект — владелец; удалить артефакт — автор или владелец проекта; перенести артефакт — автор)
404 Не найдено или нет доступа (`NOT_FOUND`)

curl

curl -X GET 'https://helper-sa.ru/api/ext/v1/artifacts/openapi/<artifactId>/diff' \
  -H 'Authorization: Bearer sah_ВАШ_КЛЮЧ'

PUT/artifacts/{tool}/{artifactId}/project

Перенести в проект или в личное пространство (автор)

Параметры

`tool`*	path · string	Код инструмента (`GET /tools`), например `openapi`
`artifactId`*	path · string(uuid)

Тело запроса ExtArtifactMove

projectId string(uuid) | null Проект; null — личное пространство

Ответы

200 Артефакт — ExtArtifact
401 Нет ключа, ключ неизвестен или истёк (`API_KEY_INVALID`)
403 `API_TARIFF_REQUIRED` — тариф владельца ключа ниже «Про»; `AUTH_USER_BLOCKED` — пользователь заблокирован; `FORBIDDEN` — действие доступно не всем участникам (изменить или удалить проект — владелец; удалить артефакт — автор или владелец проекта; перенести артефакт — автор)
404 Не найдено или нет доступа (`NOT_FOUND`)

curl

curl -X PUT 'https://helper-sa.ru/api/ext/v1/artifacts/openapi/<artifactId>/project' \
  -H 'Authorization: Bearer sah_ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{}'

GET/artifacts/{tool}/{artifactId}/versions

История версий (новые сверху)

Параметры

`tool`*	path · string	Код инструмента (`GET /tools`), например `openapi`
`artifactId`*	path · string(uuid)

Ответы

200 Версии без содержимого — ExtVersion[]
401 Нет ключа, ключ неизвестен или истёк (`API_KEY_INVALID`)
403 `API_TARIFF_REQUIRED` — тариф владельца ключа ниже «Про»; `AUTH_USER_BLOCKED` — пользователь заблокирован; `FORBIDDEN` — действие доступно не всем участникам (изменить или удалить проект — владелец; удалить артефакт — автор или владелец проекта; перенести артефакт — автор)
404 Не найдено или нет доступа (`NOT_FOUND`)

curl

curl -X GET 'https://helper-sa.ru/api/ext/v1/artifacts/openapi/<artifactId>/versions' \
  -H 'Authorization: Bearer sah_ВАШ_КЛЮЧ'

GET/artifacts/{tool}/{artifactId}/versions/{versionId}

Версия с содержимым

Параметры

`tool`*	path · string	Код инструмента (`GET /tools`), например `openapi`
`artifactId`*	path · string(uuid)
`versionId`*	path · string(uuid)

Ответы

200 Версия — ExtVersion
401 Нет ключа, ключ неизвестен или истёк (`API_KEY_INVALID`)
403 `API_TARIFF_REQUIRED` — тариф владельца ключа ниже «Про»; `AUTH_USER_BLOCKED` — пользователь заблокирован; `FORBIDDEN` — действие доступно не всем участникам (изменить или удалить проект — владелец; удалить артефакт — автор или владелец проекта; перенести артефакт — автор)
404 Не найдено или нет доступа (`NOT_FOUND`)

curl

curl -X GET 'https://helper-sa.ru/api/ext/v1/artifacts/openapi/<artifactId>/versions/<versionId>' \
  -H 'Authorization: Bearer sah_ВАШ_КЛЮЧ'

POST/artifacts/{tool}/{artifactId}/versions/{versionId}/restore

Откатить к версии — создаётся новая версия с её содержимым

Параметры

`tool`*	path · string	Код инструмента (`GET /tools`), например `openapi`
`artifactId`*	path · string(uuid)
`versionId`*	path · string(uuid)

Ответы

200 Артефакт после отката — ExtArtifact
401 Нет ключа, ключ неизвестен или истёк (`API_KEY_INVALID`)
403 `API_TARIFF_REQUIRED` — тариф владельца ключа ниже «Про»; `AUTH_USER_BLOCKED` — пользователь заблокирован; `FORBIDDEN` — действие доступно не всем участникам (изменить или удалить проект — владелец; удалить артефакт — автор или владелец проекта; перенести артефакт — автор)
404 Не найдено или нет доступа (`NOT_FOUND`)

curl

curl -X POST 'https://helper-sa.ru/api/ext/v1/artifacts/openapi/<artifactId>/versions/<versionId>/restore' \
  -H 'Authorization: Bearer sah_ВАШ_КЛЮЧ'

Проверка синтаксиса без ИИ

GET/artifacts/{tool}/{artifactId}/validation

Проверка синтаксиса сохранённого артефакта (без ИИ; связанные файлы — из проекта)

Параметры

`tool`*	path · string	Код инструмента (`GET /tools`), например `openapi`
`artifactId`*	path · string(uuid)

Ответы

200 Результат проверки — ExtValidation
401 Нет ключа, ключ неизвестен или истёк (`API_KEY_INVALID`)
403 `API_TARIFF_REQUIRED` — тариф владельца ключа ниже «Про»; `AUTH_USER_BLOCKED` — пользователь заблокирован; `FORBIDDEN` — действие доступно не всем участникам (изменить или удалить проект — владелец; удалить артефакт — автор или владелец проекта; перенести артефакт — автор)
404 Не найдено или нет доступа (`NOT_FOUND`)

curl

curl -X GET 'https://helper-sa.ru/api/ext/v1/artifacts/openapi/<artifactId>/validation' \
  -H 'Authorization: Bearer sah_ВАШ_КЛЮЧ'

POST/validate

Проверка синтаксиса текста (без ИИ и без сохранения)

С projectId и path ссылки на другие файлы (xs:include/import в XSD, схемы WSDL, $ref в JSON Schema) ищутся в дереве этого проекта относительно path.

Тело запроса ExtValidateRequest

`tool`*	string	пример: `dbml`
`source`*	string
`projectId`	string(uuid)	Проект для поиска связанных файлов
`path`	string	Путь файла в проекте («папка/файл») — от него разрешаются ссылки

Ответы

200 Результат проверки — ExtValidation
400 Некорректный запрос (`VALIDATION_FAILED`)
401 Нет ключа, ключ неизвестен или истёк (`API_KEY_INVALID`)
403 `API_TARIFF_REQUIRED` — тариф владельца ключа ниже «Про»; `AUTH_USER_BLOCKED` — пользователь заблокирован; `FORBIDDEN` — действие доступно не всем участникам (изменить или удалить проект — владелец; удалить артефакт — автор или владелец проекта; перенести артефакт — автор)
404 Не найдено или нет доступа (`NOT_FOUND`)

curl

curl -X POST 'https://helper-sa.ru/api/ext/v1/validate' \
  -H 'Authorization: Bearer sah_ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{"tool":"dbml","source":"…"}'

Схемы данных

`ExtError`

`code`*	string	пример: `NOT_FOUND`
`message`*	string

`ExtUser`

`id`*	string(uuid)
`login`*	string	пример: `ivan.petrov`
`name`*	string	пример: `Иван Петров`
`email`	string \| null
`tariff`*	string	пример: `pro`
`tariffExpiresAt`*	string(date-time) \| null	До какого момента действует тариф, в том числе пробный период (null — бессрочно) пример: `2026-12-31T23:59:59Z`

`ExtTool`

code* string пример: openapi

`ExtProjectInput`

`name`*	string	пример: `Оплата заказа`
`description`	string \| null

`ExtProject`

`id`*	string(uuid)
`name`*	string
`description`	string \| null
`owner`*	boolean	Вы — владелец проекта
`createdAt`*	string(date-time)
`updatedAt`*	string(date-time)

`ExtProjectPage`

`items`*	ExtProject[]
`page`*	integer
`size`*	integer
`total`*	integer(int64)

`ExtFolderContent`

`folder`*	ExtFolder
`folders`*	ExtFolder[]	Вложенные папки (с recursive — на любую глубину)
`artifacts`*	ExtArtifactMeta[]	Артефакты папки (с recursive — и вложенных папок)

`ExtMatch`

`line`*	integer	Номер строки (с 1)
`text`*	string	Строка с найденной подстрокой (до 200 символов)

`ExtArtifactHit`

`id`*	string(uuid)
`tool`*	string
`name`*	string
`projectId`	string(uuid) \| null
`projectName`	string \| null
`folderId`	string(uuid) \| null
`path`	string \| null	Путь в дереве проекта «папка/название»
`createdAt`*	string(date-time)
`updatedAt`*	string(date-time)
`matches`	ExtMatch[]	Найденные строки содержимого (при inContent, до 5)

`ExtArtifactSearchPage`

`items`*	ExtArtifactHit[]
`page`*	integer
`size`*	integer
`total`*	integer(int64)

`ExtFolderInput`

`name`*	string	пример: `schemas`
`parentId`	string(uuid) \| null	Родительская папка; нет — корень

`ExtFolder`

`id`*	string(uuid)
`name`*	string
`parentId`	string(uuid) \| null
`path`*	string	пример: `api/schemas`

`ExtPlacement`

`tool`*	string	пример: `xsd`
`artifactId`*	string(uuid)
`folderId`	string(uuid) \| null

`ExtTree`

`folders`*	ExtFolder[]
`artifacts`*	ExtArtifactMeta[]

`ExtArtifactMeta`

`id`*	string(uuid)
`tool`*	string	пример: `openapi`
`name`*	string	пример: `orders.yaml`
`projectId`	string(uuid) \| null
`folderId`	string(uuid) \| null
`path`	string \| null	Путь в дереве проекта «папка/название»
`createdAt`*	string(date-time)
`updatedAt`*	string(date-time)

`ExtArtifact`

`id`*	string(uuid)
`tool`*	string
`name`*	string
`source`*	string	Исходный текст артефакта
`version`*	integer	Номер текущей версии — передайте как baseVersion при изменении
`projectId`	string(uuid) \| null
`createdAt`*	string(date-time)
`updatedAt`*	string(date-time)

`ExtArtifactCreate`

`tool`*	string	пример: `openapi`
`name`*	string	пример: `orders.yaml`
`source`*	string
`projectId`	string(uuid) \| null	Проект; нет — личный артефакт
`folderId`	string(uuid) \| null	Папка проекта

`ExtArtifactUpdate`

`name`	string
`source`	string
`baseVersion`	integer	Версия, от которой сделана правка; если артефакт с тех пор изменён — 409 VERSION_CONFLICT

`ExtArtifactEdit`

`edits`*	ExtEdit[]
`baseVersion`	integer	Версия, от которой сделана правка; если артефакт с тех пор изменён — 409 VERSION_CONFLICT

`ExtEdit`

`oldText`*	string	Заменяемый фрагмент — точно как в тексте, с отступами
`newText`*	string	Новый фрагмент (пустая строка — удалить)
`replaceAll`	boolean	Заменить все вхождения

`ExtEditResult`

`id`*	string(uuid)
`tool`*	string
`name`*	string
`projectId`	string(uuid) \| null
`version`*	integer	Номер текущей версии после правки
`changed`*	boolean	Текст изменился (создана новая версия)
`replacements`	integer	Сколько фрагментов заменено
`updatedAt`*	string(date-time)
`validation`*	ExtValidation

`ExtValidateRequest`

`tool`*	string	пример: `dbml`
`source`*	string
`projectId`	string(uuid)	Проект для поиска связанных файлов
`path`	string	Путь файла в проекте («папка/файл») — от него разрешаются ссылки

`ExtValidation`

`tool`*	string
`valid`*	boolean	Ошибок нет (предупреждения допускаются)
`checked`*	boolean	Проверка выполнена (false — для инструмента нет проверки синтаксиса или она недоступна)
`problems`*	ExtProblem[]

`ExtProblem`

`line`*	integer	Строка (с 1)
`column`*	integer	Столбец (с 1)
`endLine`	integer
`endColumn`	integer
`severity`*	string error \| warning
`message`*	string
`path`	string \| null	Связанный файл с ошибкой (нет — проверяемый документ)

`ExtDiff`

`from`*	integer	Номер версии «было» (0 — пустой текст)
`to`*	integer	Номер версии «стало»
`identical`*	boolean
`added`*	integer	Добавлено строк
`removed`*	integer	Удалено строк
`diff`*	string	Unified diff (строки «+» и «-», заголовки «@@»)

`ExtArtifactMove`

projectId string(uuid) | null Проект; null — личное пространство

`ExtVersion`

`id`*	string(uuid)
`number`*	integer
`name`*	string
`changeSource`*	string WEB \| API \| MCP \| AI	Источник изменений
`restoredFrom`	integer \| null	Откат к версии с этим номером
`authorName`	string	Кто сохранил версию («—» — пользователь удалён)
`createdAt`*	string(date-time)
`source`	string \| null	Содержимое (только при запросе конкретной версии)