メインコンテンツまでスキップ

API

API リファレンス​

Semaphore UI は 2 種類の形式で API ドキュメントを提供しているため、ワークフローに最も合うものを選べます:

  • Swagger/OpenAPI — ブラウザ上で対話的に操作したい場合に最適です。
  • 公式 Postman コレクション — Postman ですべてのエンドポイントを探索・テストできます。
  • 組み込みの Swagger API ドキュメント — Swagger UI による対話型の API ドキュメントです。自身のインスタンス上でアクセスできます。

いずれの形式にも、利用可能なエンドポイント、パラメーター、レスポンス例の完全なドキュメントが含まれています。

API の利用を始める​

Semaphore API を使い始めるには、API トークンを生成する必要があります。 このトークンは、次のようにリクエストヘッダーに含める必要があります:

Authorization: Bearer YOUR_API_TOKEN

API トークンの作成​

API トークンを作成する方法は 2 つあります:

  • Web インターフェースから作成する
  • HTTP リクエストを使用する

Web インターフェースから作成する (2.14 以降)​

Semaphore の Web UI から API トークンを作成・管理できます:

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