APIリファレンス

Build APIは、アプリケーション、設定、プラットフォームリソースへのプログラム的なアクセスを提供します。CI/CDパイプラインへのBuildの統合、デプロイの自動化、カスタムツールの構築に使用してください。

インタラクティブドキュメント

詳細なリクエストとレスポンスのスキーマについては、Swaggerドキュメントを使用してエンドポイントをインタラクティブに試すことができます：

https://app.build.io/api-docs/index.html

When promoted by basic HTTP authentication, the username is “build” and the password is “best”.

ベースURL

すべてのAPIリクエストは以下のURLに送信してください：

https://app.build.io/api/v1

認証

APIはいくつかの認証方法をサポートしています。ほとんどのユースケースでは、Bearerトークンが最もシンプルなアプローチです。

Authorizationヘッダーにトークンを含めてください：

Authorization: Bearer your-token-here

APIはユーザーの代わりに動作するアプリケーション向けにOAuth 2.0もサポートしています。認証とトークンのエンドポイントは以下の通りです：

Authorization: https://app.build.io/oauth/authorize

Token: https://app.build.io/oauth/token

利用可能なOAuthスコープは “read” と “write” です。

リクエストとレスポンスのフォーマット

APIはJSONを受け付け、返します。リクエストボディを送信する場合はContent-Typeヘッダーを含めてください：

Content-Type: application/json

単一のリソースを返すエンドポイントはJSONオブジェクトで応答します。複数のリソースを返すエンドポイントはJSON配列で応答します。

エラー

リクエストが失敗した場合、APIはマシン読み取り可能なコードと人間が読めるメッセージを含むエラーレスポンスを返します：

{
  "code": "not_found",
  "message": "The requested resource was not found"
}

リソースの概要

APIは以下のリソースを中心に構成されています：

アプリ

アプリはBuildの中核リソースです。各アプリはデプロイされたアプリケーションを表します。

GET /apps — アクセス可能なすべてのアプリを一覧表示します。team_idクエリパラメータを使用してチームでフィルタリングできます。

GET /apps/{app_id_or_name} — フォーメーション、ビルドパック、リージョン、現在のデプロイ状態を含む特定のアプリの詳細を取得します。

POST /apps — 新しいアプリを作成します。nameが必須で、team_idとregionはオプションです。

ビルド

アプリの新しいビルドをトリガーします。

POST /apps/{app_id_or_name}/builds — ビルドを開始します。ブランチ、コミットish、または説明をオプションで指定できます。

設定変数

アプリの環境変数を管理します。

GET /apps/{app_id_or_name}/config-vars — すべての設定変数をキーと値のペアで一覧表示します。

PATCH /apps/{app_id_or_name}/config-vars — 設定変数を設定または更新します。設定したいキーと値を持つJSONオブジェクトを送信します。

DELETE /apps/{app_id_or_name}/config-vars/{key} — 特定の設定変数を削除します。

ドメイン

カスタムドメインとSSL証明書を管理します。

GET /apps/{app_id_or_name}/domains — プラットフォームドメインとカスタムドメインを含む、アプリのすべてのドメインを一覧表示します。

POST /apps/{app_id_or_name}/domains — カスタムドメインを追加します。hostnameが必須で、certはオプションです。

GET /apps/{app_id_or_name}/domains/{domain_id} — SSLステータスを含む特定のドメインの詳細を取得します。

PATCH /apps/{app_id_or_name}/domains/{domain_id} — ドメインのSSL証明書を更新します。

DELETE /apps/{app_id_or_name}/domains/{domain_id} — カスタムドメインを削除します。

DELETE /apps/{app_id_or_name}/domains — アプリからすべてのカスタムドメインを削除します。

ダイノ

実行中のプロセスを確認・管理します。

GET /apps/{app_id_or_name}/dynos/list — すべてのダイノとその現在のステータスを一覧表示します。

DELETE /apps/{app_id_or_name}/dynos — アプリのすべてのダイノを再起動します。

DELETE /apps/{app_id_or_name}/dynos/{dyno} — 特定のダイノを再起動します。

POST /apps/{app_id_or_name}/dynos/{dyno}/exec — 実行中のダイノ内でコマンドを実行します。コマンドは文字列の配列として提供する必要があります（例：[“/bin/sh”, “-c”, “rails console”]）。

ネームスペース

ネームスペースはアプリのグループに対して独立した環境を提供します。

GET /namespaces — アクセス可能なすべてのネームスペースを一覧表示します。

POST /namespaces — 新しいネームスペースを作成します。nameが必須で、team_id、description、regionはオプションです。

GET /namespaces/{namespace_id_or_name} — 特定のネームスペースの詳細を取得します。

DELETE /namespaces/{namespace_id_or_name} — ネームスペースを削除します。

パイプライン

パイプラインは開発ステージ（レビューアプリ、CI、ステージング、本番環境）にわたってアプリを接続します。

GET /pipelines — アクセス可能なすべてのパイプラインを一覧表示します。

GET /pipelines/{pipeline_id_or_name} — 環境とレビューアプリの設定を含む特定のパイプラインの詳細を取得します。

GET /pipelines/{pipeline_id_or_name}/apps — パイプライン内のすべてのアプリを一覧表示します。

環境

パイプライン環境（レビューアプリのデフォルトなど）の設定変数を管理します。

GET /environments/{id} — 環境の設定変数を一覧表示します。

PATCH /environments/{id} — 環境の設定変数を設定または更新します。キーをnullに設定すると削除されます。

DELETE /environments/{id}/{key} — 環境から特定の設定変数を削除します。

チーム

チームはユーザーとリソースをグループ化します。

GET /teams — 所属するすべてのチームを一覧表示します。

GET /teams/{id} — 特定のチームの詳細を取得します。

アイデンティティ

GET /me — 現在認証されているユーザーのメールアドレスを返します。認証情報の確認に便利です。

OIDCログイン

GET /oidc-login — Buildクラスターとの認証に使用するKubernetes ExecCredentialを返します。regionクエリパラメータが必要です。主にCLIによるクラスターアクセスに使用されます。