# Подпислон АИ-агенты API

> Публичный REST API сервиса Подпислон АИ-агенты: список процессов пространства ключа, ручной запуск и история запусков. Предназначен для интеграции внешних систем с визуальными сценариями автоматизации.

Важно: документация находится на `api.podpislon.ru` (вкладка «Подпислон АИ-агенты»), а сами запросы отправляются на другой хост — базовый URL `https://agents.podpislon.ru/api`. Все пути ниже указаны относительно базового URL.

Авторизация: заголовок `Authorization: Bearer <API-ключ>`. Ключ выпускается в кабинете АИ-агентов, в настройках сервиса на странице «Интеграции», для пространства, выбранного в шапке. Ключ привязан к паре «пользователь + пространство»: в каждом пространстве у пользователя свой ключ, перевыпуск не затрагивает ключи других пространств. Если пользователя исключили из пространства, ключ получает `401`.

Лимиты: 60 запросов в минуту на пространство ключа, общие для всех ключей этого пространства; при превышении — `429`. Неудачные попытки авторизации ограничены 60 в минуту с одного IP-адреса, после чего все запросы с этого адреса, включая запросы с верным ключом, получают `429` в течение минуты.

Передавайте заголовок `Accept: application/json`: без него ответы `429` и `500` могут прийти HTML-страницей вместо JSON.

Версия спецификации — OpenAPI 3.1.0, версия API — 1.0.0.

- [OpenAPI-спецификация (YAML)](https://api.podpislon.ru/podpislon-agents-api.yaml): полное машиночитаемое описание эндпоинтов, схем и кодов ответов
- [Интерактивная документация (Swagger UI)](https://api.podpislon.ru/?api=agents): те же методы с примерами и возможностью выполнить их из браузера
- [Кабинет АИ-агентов](https://agents.podpislon.ru): выпуск API-ключа и редактор процессов

Смежный сервис — API документооборота Подпислон: [llms.txt](https://api.podpislon.ru/llms.txt), базовый URL `https://podpislon.ru/integration`.

## Аккаунт

- [GET /v1/me](https://api.podpislon.ru/?api=agents#/Account/getMe): пользователь и пространство ключа (`workspace.id` — ID как в шапке кабинета; `role_code`: `admin` или `invited`)

## Процессы

Карточка процесса не содержит граф нод (`definition`). Запустить через API можно процесс в статусе `active` (не `draft`) и с нодой «Ручной запуск» — её наличие показывает `has_manual_trigger`. Поле `actions_count` — число связей между нодами; столько экшенов должно быть доступно на тарифе, чтобы запуск прошёл проверку («Нужно: N» в `422`). Фактически списанные экшены — `actions_charged` у запуска, они считаются по выполненным нодам и могут отличаться.

В ответе на список приходит объект `meta`: `current_page`, `per_page`, `total`. Параметры пагинации: `page` (с 1), `per_page` (1–100, по умолчанию 20).

- [GET /v1/workflows](https://api.podpislon.ru/?api=agents#/Workflow/listWorkflows): список процессов пространства ключа
- [GET /v1/workflows/{workflow}](https://api.podpislon.ru/?api=agents#/Workflow/getWorkflow): карточка процесса

## Запуски

Ручной запуск ставится в очередь, ответ — `202`. Логи нод есть только в карточке одного запуска, в списке — `logs_count`. Списанные экшены — `actions_charged`.

Фильтры списка: `status` (`pending`, `running`, `success`, `failed`), `date_from`, `date_to` — даты в формате `YYYY-MM-DD`, сравниваются с `started_at` включительно; `date_to` не может быть раньше `date_from`.

- [GET /v1/workflows/{workflow}/runs](https://api.podpislon.ru/?api=agents#/Workflow-Run/listWorkflowRuns): список запусков процесса
- [POST /v1/workflows/{workflow}/runs](https://api.podpislon.ru/?api=agents#/Workflow-Run/startWorkflowRun): запустить процесс (процесс в статусе `active` и с нодой «Ручной запуск»)
- [GET /v1/workflows/{workflow}/runs/{run}](https://api.podpislon.ru/?api=agents#/Workflow-Run/getWorkflowRun): детали запуска и логи нод

## Коды ответов

- `202` — запуск создан и поставлен в очередь
- `401` — API-ключ не передан, недействителен или у пользователя больше нет доступа к пространству ключа
- `404` — процесс или запуск не найден либо принадлежит другому пространству
- `422` — ошибка валидации: процесс не активирован, нет ноды «Ручной запуск», недостаточно экшенов на тарифе, неверные параметры списка
- `429` — превышен лимит: 60 запросов в минуту на пространство ключа или 60 неудачных попыток авторизации в минуту с одного IP
- `500` — внутренняя ошибка сервиса

## Optional

- [Подпислон АИ-агенты](https://agents.podpislon.ru/): визуальный редактор процессов
- [API Подпислон ЭДО](https://api.podpislon.ru/): документы, контакты, вебхуки документооборота