К содержимому

Правила API Space ​

У Space отдельный контракт и отдельный origin. Для интеграций передавайте Authorization: Bearer <space-key> из PUBLIC_API_KEYS Space. Веб-интерфейс использует свою сессию и CSRF.

Расписание и контекст ​

Cron следует местному времени в указанном часовом поясе. При переходе на летнее время отсутствующий момент пропускается, повторяющийся встречается дважды. После простоя рассматривается только последнее актуальное срабатывание.

Если предыдущий запуск подтверждён как активный, очередное срабатывание получает state=skipped, error_code=previous_run_active. Оно не ждёт своей очереди. Если исход отправки неизвестен или синхронизация статуса не удалась, планирование ждёт восстановления. Периоды, пришедшиеся на фактическое выполнение предыдущего запуска, пропускаются и после его завершения.

При session_mode=reuse действуют правила:

ИзменениеКонтекст следующего запуска
Поручение, название, владелец, cron или часовой поясСохраняется
Профиль, шаблон, модель, коды сервисов, режим сессии, эффективная базовая конфигурацияНовая сессия
Явный сброс контекстаНовая сессия. При активном срабатывании — 409 schedule_busy

Старые сессии остаются в Orpheus. Их namespace — schedule.

Создание и изменения ​

Обязательные поля создания: name, prompt, cron, timezone. По умолчанию status=active, session_mode=new, model=null, services=[]. При пропуске профиля/шаблона берутся настроенные значения по умолчанию. При полном доступе пропуск владельца означает owner_email=null. У обычного пользователя SAML подставляется email сессии. Cron содержит пять полей. Макросы, секунды, год и встроенный TZ не принимаются. Часовой пояс — IANA, например Europe/Moscow, а не Local.

PATCH меняет только переданные поля. null очищает модель или владельца, services: [] — выбор сервисов. Менять и очищать владельца может только вызывающий с полным доступом. Пропущенные поля профиля и шаблона сохраняют выбранные имена. При любом обычном редактировании и возобновлении итоговый шаблон должен существовать и быть активным, даже если поле не изменяется. PATCH ровно с {"status":"paused"} пропускает проверку каталогов. Дополнительные поля делают его обычным редактированием. Отсутствующий или неактивный шаблон возвращает 422 с template_not_found или template_inactive по пути body.template. Пауза убирает ближайшее время. Возобновление и изменение cron/часового пояса выбирают новое будущее время. Прочие правки сохраняют запланированное время.

DELETE скрывает задание из списков. Карточка и история сохраняются, в карточке появляется deleted_at. Повторное удаление возвращает 204.

Повтор создания ​

При создании передавайте UUID в Idempotency-Key. Повтор с тем же нормализованным телом возвращает исходный ответ, даже если задание позже изменили или удалили. Другое тело с тем же ключом возвращает 409. Срока истечения у ключей нет. Поля url и can_edit вычисляются по текущему публичному адресу, владельцу и признаку удаления и при повторном ответе. Права создания проверяются до возврата повтора.

Короткий пример с файлом из examples/space:

python
import json
import os
import uuid
from pathlib import Path
from urllib.request import Request, urlopen

key = str(uuid.uuid4())
print("Idempotency-Key:", key)  # Save and reuse after an uncertain response.
request = Request(
    os.environ["ORPHEUS_SPACE_HOST"] + "/api/v1/schedules",
    data=Path("schedule.json").read_bytes(),
    headers={
        "Authorization": "Bearer " + os.environ["ORPHEUS_SPACE_API_KEY"],
        "Content-Type": "application/json",
        "Idempotency-Key": key,
    },
    method="POST",
)
with urlopen(request, timeout=20) as response:
    print(json.load(response)["id"])

ENV этого примера совпадает с CLI. Если ответ потерян, используйте сохранённый ключ вместо нового UUID и прежнее тело. Не запускайте пример заново с новым ключом для повтора того же запроса.

Ручной запуск ​

POST /api/v1/schedules/{id}/run сохраняет команду выполнения активного задания или задания на паузе. Передайте ненулевой UUID в Idempotency-Key, без тела и параметров запроса. Нужны права на изменение задания. Ответ 202 содержит сохранённое срабатывание, но не подтверждает начало работы агента. Приём команды синхронно не обращается к Orpheus и не проверяет его каталоги.

Worker использует сохранённые настройки при подготовке срабатывания. Изменения до подготовки попадут в этот запуск. После подготовки запрос фиксируется для следующих попыток отправки. Следите за ходом выполнения через методы срабатывания и результата.

Ключ действует в пределах одного задания и не истекает. Повтор с ним возвращает то же срабатывание в текущем состоянии, в том числе после завершения или удаления задания. Права по текущему владельцу проверяются заново. Новый ключ запрашивает новое срабатывание. Другое незавершённое срабатывание, включая неизвестный исход отправки, возвращает 409 schedule_busy. Новая команда для удалённого задания возвращает 409 schedule_deleted.

Ручная команда не меняет активность, cron, ближайшее время или контекст продолжаемой сессии. В истории у неё trigger=manual, а scheduled_at — время принятия команды. Она не повторяет отчётный период прежней ошибки и не сбрасывает контекст после сбоя. Успешный ручной запуск учитывается в last_successful_run. Для пересекающихся периодов cron действуют обычные правила пропуска.

Пауза отменяет ожидающие срабатывания по расписанию, но сохраняет ожидающие ручные команды. Удаление задания отменяет ожидающие срабатывания обоих видов. Подготовленные к отправке запросы и принятые запуски сохраняют правила уточнения исхода после обоих действий.

Фильтры и курсоры ​

owner_email можно повторить до 100 различных адресов. Фильтры объединяются через ИЛИ. Адреса нормализуются: удаляются пробелы по краям, регистр приводится к нижнему. Алиасы почтового провайдера не объединяются. unowned=true выбирает только общие задания и несовместим с email-фильтрами.

Список упорядочен от новых заданий к старым. limit по умолчанию 50, максимум 200. Передавайте next_cursor как cursor с теми же фильтрами. В начатый обход не попадают новые задания, но изменения и удаления отражают текущее состояние. История также использует курсор.

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

Список, карточка, история и настройки читаются из Space. Каталоги сервисов, профилей, шаблонов и result синхронно обращаются к Orpheus. Время получения результата fetched_at не заменяет время наблюдения статуса observed_at в истории.

Неначавшийся запуск даёт 409, отсутствующий результат — 404, недоступный Orpheus — 503. Диагностика.

Ошибки имеют вид error: {code, message, phase, details}. В details путь вроде ["body", "name"] или ["query", "limit"] указывает поле. Коды включают required, invalid_type, unknown_field, invalid_value. Схема ошибки. Ответы API не кешируются.

Поля истории ​

Срабатывание — запись о выполнении по расписанию или ручной команде. Оно может быть пропущено или не дойти до Orpheus, поэтому ID запуска и его статус допускают null. Полная схема.

ПолеЗначение
id, schedule_idID срабатывания и задания
triggerscheduled для cron, manual для ручной команды
scheduled_atПлановое время cron или время принятия ручной команды
created_at, updated_atСоздание и последнее изменение записи Space
stateОтправка: pending, dispatching, accepted, skipped, failed, cancelled
session_id, run_idID сессии и запуска, принятого Orpheus
run_statusПоследнее успешно прочитанное состояние выполнения Orpheus
observed_atВремя успешного наблюдения этого статуса
execution_started_at, finished_atФактическое начало и завершение исполнения
error_codeОшибка отправки или причина пропуска
run_error_codeОшибка выполнения агента
sync_error_codeОшибка чтения статуса. Предыдущее наблюдение сохраняется
attempts, next_attempt_atЧисло попыток отправки и время следующей попытки отправки или синхронизации

Коды ошибок API ​

Основные значения error.code в API заданий:

HTTPКодПричина
401unauthorizedНет действительных учётных данных
403csrf_failedНеверный Origin или CSRF-заголовок
403schedule_forbiddenСессия не может создать задание на этого владельца или изменить это задание
404schedule_not_found, occurrence_not_found, not_foundЗадание, срабатывание или маршрут не найдены
404run_result_not_foundЗапись результата не найдена в Orpheus
409run_not_startedOrpheus ещё не принял запуск
409schedule_busyРучной запуск или сброс контекста при незавершённом срабатывании, включая неизвестный исход отправки
409schedule_deletedИзменение удалённого задания или запрос нового ручного запуска для него
409idempotency_conflictКлюч создания уже использован с другим телом
413request_too_largeПревышен размер тела
415unsupported_media_typeТребуется JSON
422validation_error, invalid_cursorНекорректные поля или курсор
503core_unavailable, storage_unavailableНедоступны Orpheus или хранилище Space

Это ошибки HTTP-запроса. Ошибки сохранённого срабатывания, например previous_run_active, относятся к полям истории, а не к коду ответа API. Диагностика.

Браузерная авторизация ​

Для браузерной записи нужны точный Origin, совпадающий с ORPHEUS_PUBLIC_URL, и заголовок X-Orpheus-CSRF: 1. Space Web отправляет их автоматически. SAML callback вместо этих заголовков проверяет подписанный ответ IdP и начатый в браузере вход. Запросы с валидным Bearer-ключом не требуют этих заголовков. Неверный Authorization возвращает 401, даже если браузерная сессия действительна.

Все авторизованные пользователи могут читать задания и результаты. Настроенные администраторы имеют полный доступ. Остальные пользователи SAML создают только на email своей сессии и меняют только свои задания. Явный null или чужой владелец при создании дают 403 schedule_forbidden. Через PATCH нельзя передать, очистить или присвоить владельца. Сессия без email разрешает только просмотр. Bearer-ключи и anonymous сохраняют полный доступ.

Ответ сессии содержит write_access и can_manage_all. У каждого задания есть can_edit, который после удаления равен false. Эти поля описывают права и не принимаются в запросах записи.

Каталоги сервисов ​

Корневой метод сервисов читает Orpheus и возвращает {items: [...]}. Каталог шаблонов возвращает items, next_cursor и prev_cursor. Он включает активные и неактивные записи и принимает active, точное имя name с учётом регистра, буквальное вхождение name_contains без учёта регистра, limit (1–200, по умолчанию 50) и cursor. Фильтры по имени взаимоисключающие. Сохраняйте фильтры при использовании любого из полученных курсоров. Проверяйте сохранённый выбор и default_template из настроек через name без фильтра активности. Сервисы выбираются явно, без значений по умолчанию. Каталог одинаков для всех пользователей с правом чтения. Неизвестный код возвращает 422, недоступный обязательный каталог — 503 core_unavailable. Сохранение прежнего выбора и очистка сервисов не требуют каталога сервисов. Возобновление проверяет весь выбор. Изменение состава сервиса под прежним кодом требует сброса продолжаемого контекста. Подготовленные запросы выполнения сохраняют принятую конфигурацию.

Каталог профилей тоже возвращает items, next_cursor и prev_cursor. Он принимает available, name, name_contains, limit и cursor. available=true требует активности профиля и его аккаунта. Проверяйте сохранённое имя и default_profile из настроек без этого фильтра. Имя профиля чувствительно к регистру и неизменяемо. Перенос профиля на другой аккаунт не сбрасывает продолжаемый контекст. Сбросьте его явно, чтобы следующее выполнение использовало текущий профиль.

Создание, обычное редактирование и возобновление требуют существующего активного профиля и аккаунта, даже если profile отсутствует в PATCH. При отказе возвращается 422 с profile_not_found, profile_inactive или account_inactive в body.profile. Только {"status":"paused"} и удаление пропускают эту проверку. Приём ручного запуска и идемпотентный повтор сохраняют свои правила.