Разработчикам

Интеграция с API

Базовый адрес, авторизация, основные маршруты API и восстановление принятого задания.

Подключение

Базовый адрес: https://siharness.dev. API интеграций использует Bearer-ключ и заголовки области доступа. Идентификаторы организации, проекта и окружения предоставляет администратор.

Заголовок	Значение
`Authorization`	`Bearer <ключ>`
`X-AI-Organization-ID`	Идентификатор организации
`X-AI-Project-ID`	Идентификатор проекта
`X-AI-Environment-ID`	Разрешённое окружение

Ключ и заголовки должны соответствовать друг другу. Доступ к маршрутам определяется ролью сервисной учётной записи.

Пример чтения

Пример запрашивает каталог решений и не создаёт запуск. Переменные заполняются значениями вашей учётной записи. Для этого маршрута нужны права чтения каталога.

curl --fail-with-body 'https://siharness.dev/v1/solutions' \
  -H "Authorization: Bearer $HARNESS_API_KEY" \
  -H "X-AI-Organization-ID: $HARNESS_ORGANIZATION_ID" \
  -H "X-AI-Project-ID: $HARNESS_PROJECT_ID" \
  -H "X-AI-Environment-ID: $HARNESS_ENVIRONMENT_ID"

Интеграционный ключ отдельного продукта может не иметь доступа к общему каталогу. Используйте разрешённые ему продуктовые маршруты.

Основные маршруты

Маршрут	Назначение
`GET /v1/solutions`	Каталог доступных решений
`POST /v1/tasks/quote`	Предварительные условия запуска и бюджет
`POST /v1/tasks`	Создание задания решения
`GET /v1/tasks/{taskID}`	Состояние принятого задания
`GET /v1/tasks/{taskID}/result`	Сохранённый результат
`GET /v1/tasks/{taskID}/finance`	Учтённые расходы и полнота стоимости
`GET /v1/runs/{runID}/events`	События исполнения агента
`GET /v1/runs/{runID}/usage`	Учёт физических попыток

Специализированные интеграции используют выделенные маршруты API. Администратор предоставляет разрешённые маршруты и параметры подключения; операции и результаты доступны владельцу интеграции.

Повторы и восстановление

Для создания задания передавайте стабильный Idempotency-Key длиной от 16 до 128 символов. Если ответ потерян, сначала найдите принятое задание по этому ключу: GET /v1/tasks/by-idempotency-key?solutionId=<solutionId> с тем же заголовком и областью доступа.

Повтор с тем же ключом и тем же содержимым возвращает принятую операцию. Другое содержимое под тем же ключом вызывает конфликт. Не меняйте ключ при транспортном повторе: новый ключ может означать новую оплачиваемую работу.

Что появится дальше

Python и TypeScript SDK, клиентский CLI, webhooks и локальный запуск описаны в плане развития. Сейчас эта инструкция относится к HTTP API.