Правила HTTP API
Передавайте сервисный ключ заголовком Authorization: Bearer …. В примерах ORPHEUS_URL содержит origin сервера, методы начинаются с /api/v1.
Запросы
- Для JSON задавайте
Content-Type: application/json. - Для создания сессии, запуска и уточнения используйте
Idempotency-Key. 202означает приём задачи. Читайте состояние запуска для результата.- Времена передаются в RFC3339, идентификаторы сессий и запусков являются UUID.
- Курсоры непрозрачны. Следуйте
next_cursorиhas_more, где оно предусмотрено. При смене фильтров начинайте с первой страницы.
Ошибки
| HTTP | Что проверить |
|---|---|
| 400 | Формат запроса или курсора |
| 401 | Bearer-ключ или браузерную сессию |
| 403 | Режим доступа, Origin и CSRF при изменении шаблонов |
| 404 | Идентификатор ресурса |
| 409 | Состояние сессии, конфликт ключа или исчерпанный бюджет |
| 413 | Размер запроса |
| 415 | Content-Type |
| 422 | error.details с указанием поля |
| 503 | Ёмкость исполнения или доступность сервиса |
Точный код ошибки находится в error.code. Повторяйте неопределённый сетевой результат с прежним телом и ключом. Не повторяйте некорректный запрос без исправления.
Явный неверный Authorization не заменяется браузерной авторизацией. Пустой PUBLIC_API_KEYS отключает сервисные команды в режимах anonymous и saml.
Полный справочник · Надёжная интеграция
Выбор сервисов
Коды сервисов не зависят от порядка и не должны повторяться. Неизвестный код возвращает 422 unknown_service до принятия запроса. Повтор с прежним ключом идемпотентности и вводом возвращает принятый результат без обращения к текущему каталогу. Ответы содержат неизменяемые снимки сервисов и объединённые имена ENV без значений секретов.
Сохранённый вывод агента
Символы NUL (U+0000) в сохранённых сообщениях агента и JSON-входах и результатах инструментов заменяются на Unicode U+FFFD (�). История остаётся доступной, даже если вывод агента содержит такие символы. Обычный текст с обратной косой чертой и последующим u0000 сохраняется.
Выбор шаблона
Для новой сессии нужно точное имя активной записи каталога. Неизвестное или неактивное имя возвращает 422 unknown_template с template_not_found или template_inactive в error.details. Принятые сессии и идемпотентные повторы сохраняют имя. Продолжение сессии не проверяет каталог повторно.
Список шаблонов возвращает items, next_cursor и prev_cursor. Лимит по умолчанию — 50, максимум — 200. Доступны фильтры active, точное имя name или буквальное вхождение name_contains. Фильтры по имени нельзя совмещать. При переходе по курсору сохраняйте прежние фильтры.