Перейти к основному содержимому

API

Справочник по API​

Semaphore UI предоставляет документацию API в двух форматах, чтобы вы могли выбрать тот, который лучше подходит для вашего рабочего процесса:

  • Swagger/OpenAPI — идеально, если вы предпочитаете интерактивную работу в браузере.
  • Официальная коллекция Postman — изучайте и тестируйте все эндпоинты в Postman.
  • Встроенная документация API на Swagger — интерактивная документация API на базе Swagger UI. Она доступна прямо на вашем экземпляре.

Все варианты содержат полную документацию по доступным эндпоинтам, параметрам и примерам ответов.

Начало работы с API​

Чтобы начать использовать API Semaphore, необходимо сгенерировать API-токен. Этот токен нужно передавать в заголовке запроса в следующем виде:

Authorization: Bearer YOUR_API_TOKEN

Создание API-токена​

Создать API-токен можно двумя способами:

  • Через веб-интерфейс
  • С помощью HTTP-запроса

Через веб-интерфейс (начиная с 2.14)​

Вы можете создавать свои API-токены и управлять ими через веб-интерфейс Semaphore:

API-токены

С помощью HTTP-запроса​

Вы также можете пройти аутентификацию и сгенерировать токен сессии прямым HTTP-запросом.

Войдите в Semaphore (пароль нужно экранировать, например slashy\\pass вместо slashy\pass):

curl -v -c /tmp/semaphore-cookie -XPOST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{"auth": "YOUR_LOGIN", "password": "YOUR_PASSWORD"}' \
http://localhost:3000/api/auth/login

Сгенерируйте новый токен и получите его:

curl -v -b /tmp/semaphore-cookie -XPOST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
http://localhost:3000/api/user/tokens

Команда должна вернуть что-то похожее на:

{
    "id": "YOUR_ACCESS_TOKEN",
    "created": "2025-05-21T02:35:12Z",
    "expired": false,
    "user_id": 3
}

Использование токена для запросов к API​

Получив API-токен, передавайте его в заголовке Authorization для аутентификации запросов.

Запуск задачи​

Используйте этот токен для запуска задачи или любых других действий:

curl -v -XPOST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-d '{"template_id": 1}' \
http://localhost:3000/api/project/1/tasks

Отзыв API-токена​

Если токен больше не нужен, его следует отозвать, чтобы обезопасить вашу учётную запись.

Чтобы вручную отозвать (сделать просроченным) API-токен, отправьте DELETE-запрос на эндпоинт токена:

curl -v -XDELETE \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
http://localhost:3000/api/user/tokens/YOUR_ACCESS_TOKEN