buildkite-api

Buildkite API

REST API を読み取り専用、GraphQL を書き込み用 API として扱わないでください。ビルド、パイプライン、組織の管理、ホスト型リソース、診断、通知サービスへの書き込みには、デフォルトで REST を使用してください。型付きのネストされた読み取りによって複数のリクエストを避けられる場合や、GraphQL 専用のミューテーションには GraphQL を使用してください。

ターミナルから API 呼び出しを対話的に実行するには、bk api コマンドについて buildkite-cli スキルを参照してください。Buildkite MCP サーバーでは、対応している読み取りとアクションには専用のツールを優先して使用してください。

クイックスタート

REST で軽量なビルドレコードを一覧表示します。

curl -sS -H "Authorization: Bearer $BUILDKITE_API_TOKEN" \
  "https://api.buildkite.com/v2/organizations/my-org/pipelines/my-pipeline/builds?exclude_jobs=true&exclude_pipeline=true&per_page=5" \
  | jq '.[] | {number, state, branch}'

GraphQL で選択したネストされたフィールドをクエリします。

curl -sS -X POST "https://graphql.buildkite.com/v1" \
  -H "Authorization: Bearer $BUILDKITE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ pipeline(slug: \"my-org/my-pipeline\") { builds(first: 5) { edges { node { number state message } } } } }"}' \
  | jq '.data.pipeline.builds.edges[].node'

認証とアクセス

個人用 API アクセストークンをベアラートークンとして渡してください。トークンのスコープは必要な組織に限定し、最小限のスコープを付与してください。HTTP 404 は、リソースが存在しない場合と利用できない場合の両方を意味する可能性があるものとして扱ってください。権限や機能によって制限されるリソースのいくつかは、意図的にその存在を明かしません。

curl -sS -H "Authorization: Bearer $BUILDKITE_API_TOKEN" \
  "https://api.buildkite.com/v2/organizations"

有効期間の短い認証情報を使用する場合、公開鍵 API アクセストークン（プレビュー）で、RS256 署名付き JWT を使った REST API アクセスの認証ができます。アクセストークンの UUID を iss に設定し、iat を現在時刻から 10 秒以内に保ち、exp を iat から 5 分以内に設定してください。JWT はトークンの組織へのアクセス権とスコープを引き継ぎます。

一般的なスコープは次のとおりです。

機能	スコープ
ビルド、パイプライン、アーティファクト	read_builds/write_builds、read_pipelines/write_pipelines、read_artifacts/write_artifacts
ジョブログ、環境、エージェント	read_build_logs/write_build_logs、read_job_env、read_agents/write_agents
組織メンバー	read_organizations/write_organizations
組織の設定	read_organization_settings/write_organization_settings
監査イベント	read_audit_events
リポジトリ接続と検出	read_organization_repository_connections
通知サービス	read_notification_services/write_notification_services
組織への招待	read_organization_invitations/write_organization_invitations
チーム	read_teams/write_teams
ホスト型リソースとクラスターリソース	read_clusters/write_clusters

スコープは必要ですが、それだけで十分とは限りません。403 や権限によって制限される 404 のレスポンスは、別のペイロードやエンドポイントを試すべき根拠ではなく、アクセスまたは利用可能性の境界として扱ってください。確認できる組織の状態や既知の呼び出し元のコンテキストがある場合はそれを使用してください。そうでない場合は、必要なロール、権限、または機能を伝え、管理者に確認を依頼してください。全一覧についてはAPI トークンのスコープを参照してください。

REST API

ベース URL として https://api.buildkite.com/v2 を使用し、JSON リクエストボディには Content-Type: application/json を指定してください。組織スコープのリソースの多くは /organizations/{org.slug} から始まります。ユーザー、組織一覧などのトップレベルリソースは例外です。

ビルドのメタデータとステータスを読み取る場合は、デフォルトで exclude_jobs=true&exclude_pipeline=true を指定してください。ジョブの詳細が必要な場合に限り、Jobs API からジョブを取得してください。

機能マップ

このマップでリソースファミリーを選択し、正確なスキーマとレスポンスの動作についてはリンク先のリファレンスを参照してください。

分類	プロトコルとアクセス	スコープ、権限、またはゲート	主な境界とドキュメント
組織設定	REST 読み取り／書き込み	read_organization_settings/write_organization_settings；組織管理者；フィールドごとのゲート	書き込みの前に読み取ってください。API の許可リストを変更すると、呼び出し元がアクセスできなくなる可能性があります。API 設定とパイプライン設定
監査イベント	REST 読み取り専用	read_audit_events；組織管理者；Enterprise	設定とは独立してカーソルページネーションされます。監査イベント
メンバーと招待	REST 読み取り／書き込み	read_organizations/write_organizations、read_organization_invitations/write_organization_invitations；メンバーの更新とすべての招待操作には組織管理者が必要です	メンバーの PATCH で変更できるのは role と sso_mode のみで、呼び出し元を対象にすることはできません。保留中の招待はメンバーシップではありません。メンバーと招待
チームの有効化	REST は有効化のみ；GraphQL の Organization.isTeamsEnabled で状態を読み取り	write_teams；組織へのアクセス；change_teams_enabled；無効時はプランによるゲート	冪等な POST /organizations/{org.slug}/teams/enable です。チームが存在しない場合、Everyone が作成されることがあります。REST による読み取りや無効化のルートはありません。チーム
リポジトリ接続	REST 読み取り専用	read_organization_repository_connections；組織管理者；プロバイダーのサポート	接続を変更する API はありません。未サポートの検出プロバイダーは 422 を返します。接続と検出
パイプラインのセットアップ	REST 読み取り／書き込み	read_pipelines/write_pipelines；パイプラインへのアクセス	作成時に検証と変更が同時に行われます。REST にドライランはありません。パイプライン
通知サービス	REST 読み取り／書き込みのライフサイクル操作	read_notification_services/write_notification_services；組織管理者または 通知サービスの管理	OAuth を使用する Slack Workspace と Linear では、最初にブラウザーでの認証が必要です。省略されたシークレットは保持してください。通知サービス
受信 GitHub 処理	REST 読み取り／書き込み	read_pipelines/write_pipelines；Full Access；プロバイダーと機能のゲート	処理制御では、リポジトリの Webhook 登録や GitHub App の設定は行われません。パイプライン
ビルドのライフサイクル	REST 読み取り／書き込み	read_builds/write_builds；パイプラインへのアクセス	リビルドでは現在のソース管理の状態を取得せず、元のコンテキストが再現されます。ビルドのキャンセルでは未完了のすべてのジョブが停止し、ジョブのキャンセルでは1つのジョブが停止します。ビルドとジョブ
ホステッドリソース	REST 混合アクセス	read_clusters/write_clusters；クラスター管理権限；ホステッドエージェントとリソースのゲート	クラスターの読み取り／更新で、ホステッド Git ミラーとコンテナーキャッシュの設定を参照できるのはクラスター管理者のみです。イメージの作成は非同期で、更新はできません。キャッシュの削除は明示的に行う必要があります。クラスター、イメージ、ネットワーク範囲、キャッシュボリューム
診断	REST 読み取り専用	read_builds、read_agents	シグナルとエージェントのライフサイクルに関するフィールドは証拠であり、再試行が安全であることを証明するものではありません。ジョブとエージェント
アーティファクト	REST 読み取り／書き込み；削除は GraphQL	REST には read_artifacts/write_artifacts；GraphQL API アクセス；削除にはアーティファクトのパイプラインで ビルド＆読み取り 以上のアクセス権が必要です	ページネーションの前にフィルターし、削除を明示的に確認してください。アーティファクト

ページネーション

ほとんどの REST の一覧レスポンスは、配列と HTTP Link ヘッダーを返します。ページ番号を組み立てるのではなく、rel="next" が指定された URL をたどってください。最初のリクエストではクエリフィルターを維持し、その後はサーバーから提供された次の URL を使用してください。

Jobs API、招待、通知サービス、監査イベントでは、カーソル形式の本文が使用されます。.items からレコードを読み取り、.links.next が null になるまでたどってください。監査イベントでは Link ヘッダーも公開されます。これらの本文形式に対して、配列専用の jq フィルターを実行しないでください。

REST リクエストは、組織単位とユーザー単位の両方のクォータを消費します。429 が返された場合は、対応する RateLimit-Reset または RateLimit-User-Reset の期間が終了するまでリクエストを停止してください。短い間隔で再試行しないでください。リモートの Buildkite MCP サーバーへのリクエストには別のユーザー単位の制限が適用されますが、ローカル MCP サーバーへのリクエストは組織の REST クォータを消費します。

パイプラインの作成

REST の configuration 文字列には、パイプライン YAML を使用してください。クラスターが選択されている場合は、cluster_id を含めてください。組織がクラスターに属さないパイプラインを許可している場合は省略できます。許可されていない場合、サーバーは 422 と Cluster must be specified を返します。cluster_id がないことだけを理由に、作成クライアント側でリクエストを拒否しないでください。ユーザーまたは組織のワークフローでテンプレートが選択されている場合は、pipeline_template_uuid を使用してください。公開されている組織フィールドには、作成前にそのモードを確実に識別できるものがないため、既知のレガシーなビジュアルステップのワークフローでのみ、ビジュアル形式の steps 配列を送信してください。

作成リクエストでは、サーバー側の検証と変更が同時に実行されます。必要に応じて、まずローカルで YAML を検証してください。ただし、ローカルでのスキーマ検証を、リポジトリへのアクセス、プロバイダーの設定、権限、サーバー側の作成制約を満たせる証明として説明しないでください。ステップの別のソースを使って暗黙に再試行するのではなく、422 の検証エラーを報告してください。

組織の管理

変更の前に設定を読み取り、管理対象のフィールドのみを比較して、サポートされている最小限の更新を送信してください。不明なフィールドや機能制限付きのフィールドは維持してください。API 設定では、許可リストの変更をロックアウトのリスクがある操作として扱ってください。呼び出し元の送信元アドレスを確認し、ロールバック手段を確保して、設定の同時書き込みを避けてください。

招待とメンバーシップは別の状態として扱ってください。保留中のリクエストを照合するには招待一覧を確認し、招待の状態を確認するには show を使用してください。DELETE は保留中の招待の取り消しにのみ使用してください。一括招待の作成では、ロール、SSO モード、チーム割り当てを指定できますが、リクエスト全体がアトミックに検証されます。失敗した場合、要求された招待は一件も作成されません。

既存のメンバーを更新する場合は、そのメンバーシップを読み取ってから PATCH /organizations/{org.slug}/members/{user.uuid} を実行してください。このリクエストで受け付けられるのは role（admin または member）と sso_mode（optional または required）のみです。また、write_organizations と組織管理者の権限が必要で、呼び出し元自身のメンバーシップは更新できません。変更するフィールドのみを送信してください。まだメンバーではない人には、招待を使用してください。

チームベースの権限が明示的に必要な場合にのみ、Teams を有効にしてください。利用可能かどうかを確認するために、変更操作を使用しないでください。現在の状態を確認する必要がある場合は、GraphQL から Organization.isTeamsEnabled を読み取ってください。Teams が無効な場合は、有効化する前に計画と必要な権限を説明してください。

ホスト型リソース

ホスト型キャッシュの動作を変更する前に、read_clusters でクラスターを読み取ってください。クラスター管理権限を持つ呼び出し元のクラスター詳細レスポンスには、hosted_git_mirror_enabled と hosted_container_cache_enabled が含まれます。この権限がない呼び出し元にはこれらのフィールドが返されないため、フィールドがないことを false と解釈しないでください。いずれかのブール値を更新するには、write_clusters とクラスター管理権限を使用して PUT /organizations/{org.slug}/clusters/{id} を実行してください。いずれかの値を変更できるのはホスト型クラスターに限られます。ホスト型でないクラスターでは 422 が返されます。

Artifact フィルタリング

ビルドレベルとジョブレベルのアーティファクト一覧では、ページネーションの前に state と path を適用します。* を含まないパスは完全一致です。グロブマッチングを意図する場合にのみ * を含めます。単一ページをローカルでフィルタリングせず、パスと状態フィルターを URL エンコードします。

アーティファクト ID を指定してダウンロードする場合は、ダウンロードエンドポイントがリダイレクトするため curl -L を使用します。REST による削除には write_artifacts が必要です。REST と GraphQL のどちらで削除する場合も、アーティファクトのパイプラインに対する Build & Read 以上のアクセス権が必要です。REST では、/organizations/{org.slug}/jobs/{job.id}/artifacts/{id} または完全修飾されたパイプライン／ビルド／ジョブのルートのいずれかで、アーティファクト UUID を指定できます。ビルドレベルのアーティファクト一覧ルートには、対応する削除操作がありません。GraphQL の artifactDelete ではアーティファクトのグローバル ID を指定し、GraphQL API へのアクセスが必要です。どちらの方法でも、必ず明示的な確認を求めてください。また、フィルタリングしたアーティファクトの検出を自動削除ループに変えてはいけません。

組織が顧客管理のアーティファクトストレージを使用している場合、Buildkite アーティファクトを削除しても、基盤となるオブジェクトは削除されません。ストレージバックエンドを推測したり、外部オブジェクトを自動削除したりしないでください。組織のアーティファクトストレージ設定と削除手順書を確認してください。

ジョブとエージェントの診断

ビルド番号が分かったら、ジョブを直接クエリします。すべてのジョブを取得してローカルでフィルタリングするのではなく、サーバー側の state、step_key、group_key フィルターを優先します。ステップキーは、そのステップのすべてのジョブ（並列ジョブを含む）に一致します。グループキーは、そのグループのすべてのジョブに一致します。フィルターがカーソルページ間でも適用され続けるように、各 .links.next URL を返されたとおりにたどります。

signal と signal_reason を使って、シグナルによる終了と通常のゼロ以外の終了コードを区別します。埋め込まれたエージェントの os_id、arch、queue、connected_at、disconnected_at、lost_at、stopped_at を調べ、プラットフォーム、ルーティング、ライフサイクルのタイミングを関連付けます。

この情報は診断の根拠として扱い、再試行しても安全であることの証明とはみなさないでください。再試行する前に、ログ、副作用、再試行履歴、コマンドが冪等かどうかを確認します。エージェントの消失は中断の理由になり得ますが、外部へのデプロイや書き込みが完了していないことを示すものではありません。

ジョブのキャンセル

単一のコマンドジョブをキャンセルするには、PUT /organizations/{org.slug}/jobs/{job.id}/cancel またはネストされた PUT /organizations/{org.slug}/pipelines/{pipeline.slug}/builds/{build.number}/jobs/{job.id}/cancel を使用します。リクエストボディは送信せず、標準のジョブ JSON が返されることを想定します。このエンドポイントには write_builds が必要です。他のジョブが直接キャンセルされることはありませんが、ステップに soft_fail が設定されていない限り、キャンセルされたジョブによってビルドが失敗し、他のステップでファストフェイル（cancel_on_build_failing）が発生する可能性があります。そのため、他のジョブには影響しないと約束してはいけません。未完了のジョブをすべて停止するには、代わりに PUT .../builds/{build.number}/cancel でビルドをキャンセルします。

scheduled、reserved、assigned、accepted、running のコマンドジョブのみキャンセルできます。それ以外のジョブでは、報告すべき理由を含む 422 が返されます。再試行はしないでください。running のジョブは、エージェントが処理を完了するまで canceling になります。REST API には強制オプションがないため、200 を終了済みとみなしてはいけません。最初にジョブ UUID、名前、状態をユーザーに確認してください。コマンドを中断すると外部に部分的な影響が残る可能性があり、復旧のための再試行では新しいジョブが作成されます。ビルドのキャンセルを代用する目的で、ジョブのキャンセルをループしてはいけません。状態、エラー、キャンセルしてポーリングするスクリプトについては、references/patterns.md を参照してください。

GraphQL API

https://graphql.buildkite.com/v1 を使用してください。型付きクエリによってネストした REST の読み取りを複数回行わずに済む場合や、ミューテーションの形式がワークフローに適している場合は、GraphQL を優先してください。GraphQL アクセストークンには、詳細な REST スコープではなく Enable GraphQL API Access 権限を使用します。ミューテーションの入力には、スキーマで明示的に指定されている場合を除き、REST UUID やパイプラインのスラッグではなく、グローバルノード ID を使用してください。

シナリオ	優先する方法	理由
ビルドをトリガーする	REST	シンプルなリクエストボディと識別子
ビルド、ジョブ、またはアーティファクトをフィルタリングする	REST	用途に特化したサーバーフィルターとページネーション
監査イベントを読み取る	REST	読み取り専用の専用監査エンドポイントとカーソルレスポンス
選択したネスト関係を取得する	GraphQL	型付きフィールド選択によって複数回の呼び出しを回避できます
アーティファクトを削除する	REST または GraphQL	REST はアーティファクト UUID を受け付け、artifactDelete はグローバル ID を受け付けます。どちらにも同じ確認事項とストレージに関する注意点が適用されます
その他の GraphQL 専用ミューテーションを使用する	GraphQL	実際のスキーマとミューテーション固有の権限に従ってください

HTTP のトップレベルの失敗と GraphQL の errors 配列の両方を確認してください。200 レスポンスでも、操作エラーや部分的なデータが含まれている場合があります。ページネーション、グローバル ID、アーティファクトの削除については、references/graphql-reference.md を参照してください。

Webhooks

送信通知と受信ソース管理イベントの処理を分けてください。

• 組織の通知サービス REST ライフサイクルを通じて、送信 Webhook を通知サービスとして作成・管理します。
• パイプラインの github-webhooks REST リソースを使って、Buildkite による受信 GitHub イベントの処理を有効または無効にします。
• 対象となる GitHub App パイプラインに SCM Webhook を登録するには、POST /pipelines/{slug}/webhook を使用します。これにより Buildkite がプロバイダー側の配信を作成します。これは処理の有効・無効を切り替える設定とは別です。
• 組織の GitHub App 接続の設定は、ブラウザーを使用する別個の組織管理ワークフローです。

送信ハンドラーでは、X-Buildkite-Event またはペイロードの event に基づいて処理を分岐してください。すべてのイベントで、ビルド、ジョブ、パイプライン、送信者のオブジェクトが同じ形式で含まれると想定しないでください。すばやく応答し、冪等に処理し、選択したイベントと最新の認証フィールドについてはWebhooks リファレンスを参照してください。

通知サービスのライフサイクルと受信 GitHub 配信の診断については、references/webhooks.md を参照してください。

よくある間違い

間違い	発生すること	対処法
cluster_id が常に必須、または常に任意だと思い込む	有効なクラスターなしの作成がクライアント側で拒否されるか、クラスターが必須の作成で 422 が返されます	選択したクラスターを含めてください。そうでない場合は、組織がクラスターなしのパイプラインを許可するかどうかをサーバーに判定させてください
有効なステップソースなしで REST パイプラインを作成する	作成時に 422 が返されます	該当する場合は、YAML の configuration、従来のビジュアル形式の steps、または pipeline_template_uuid を使用してください。作成時の検証は変更を伴う操作として扱ってください
先に読み取らずに設定を更新する	機能制限のあるフィールドが上書きされるか、IP 許可リストによって自動化が締め出されます	読み取り、管理対象フィールドを比較し、検証済みのロールバック手段を確保してください
招待を有効なメンバーシップとして扱う	承認やプロビジョニングの前にアクセスできると自動化が想定します	保留中の招待はメンバーと分けて追跡してください
リポジトリ接続に CRUD エンドポイントがあると思い込む	自動化がサポートされていない変更を試みます	リスト表示、詳細表示、リポジトリの検出のみを使用してください
GET でシークレットが返されないため通知シークレットを置き換える	動作中の認証情報が不必要にローテーションされます	プロバイダー固有のシークレット応答の挙動を考慮し、省略されたシークレットを保持してください
アウトバウンド通知 Webhook とインバウンドの GitHub 処理を混同する	間違ったエンドポイントが変更され、リポジトリへの配信が引き続き機能しません	通知サービス、処理の切り替え、リポジトリ登録、アプリ接続をそれぞれ特定してください
1 ページを読み取った後にアーティファクトをフィルタリングする	後続ページにある一致するアーティファクトが見つかりません	ページネーションの前に、API リクエストで state と path を適用してください
1 つのジョブを停止するためにビルドをキャンセルする、またはビルドを停止するためにジョブのキャンセルを繰り返す	関係のないジョブが停止するか、呼び出しの間に作成されたジョブが実行され続けます	確認済みの単一ジョブにはジョブのキャンセルルートを、ビルド全体にはビルドのキャンセルルートを使用してください
シグナルやエージェントのタイミングから中断を推測し、それだけを根拠に再試行する	冪等でない外部処理が二重に実行される可能性があります	再試行する前にログ、副作用、再試行履歴を確認してください

追加リソース

リファレンスファイル

• references/graphql-reference.md — GraphQL のページネーション、グローバル ID、一般的なクエリ、安全なアーティファクト削除
• references/webhooks.md — 通知サービスのライフサイクルと、アウトバウンド／インバウンド Webhook の概念の境界
• references/patterns.md — 監査インベントリ、リポジトリからパイプラインを設定する手順、通知の調整、単一ジョブのキャンセル、診断のためのコピー＆ペースト可能な REST ワークフロー

関連資料

• Buildkite REST API リファレンス
• Buildkite GraphQL API ドキュメント
• Buildkite Webhook イベント
• API 認証とトークン管理
• LLM 向け Buildkite ドキュメント