公開APIとは
公開APIは、ベースマキナのリソースを外部システムから操作するためのREST APIです。環境の一覧取得や、アクションの一覧取得・詳細取得・実行を、HTTPリクエストで行なえます。
主なユースケースは以下の通りです。
- 外部システムからベースマキナのアクションを実行する
- CI/CDのジョブからアクションを呼び出して定型作業を自動化する
- 自社のスクリプトやツールに、ベースマキナのアクションを組み込む
- AIエージェント（Claude Codeなど）からアクションをツールとして実行する
対応する操作
現状、公開APIで提供しているのは環境の一覧取得と、アクションの一覧取得・詳細取得・実行です。環境一覧では有効化されている環境のみを返します。アクションやデータソースなどの設定変更（作成・編集・削除）は提供していません。設定の作成・編集・削除はベースマキナの管理画面、またはコード管理から行なってください。
ベースURL・各エンドポイントの詳細（リクエスト・レスポンス・パラメーター・エラーコードなど）はAPIリファレンスを参照してください。
アクションの識別子
公開APIではアクションをアクションID、または識別子で参照します。管理画面やコード管理で識別子を設定している場合は識別子を、未設定の場合は自動生成されたアクションIDを使います。アクション一覧・詳細のレスポンスに含まれるidを、そのまま実行時のaction_idに指定してください。
アクションの実行権限
公開APIでのアクション実行は、認証に使ったトークンの主体が持つ権限で行なわれます。主体は認証方式によって決まります。
アクションに実行権限が設定されている場合、実行権限を持たない主体は403 forbiddenになります。サービスアカウントで実行する場合は、所属グループに対象アクションの実行権限を付与してください。実行権限は所属グループ単位で決まります。サービスアカウントごとに個別の権限は付与できません。
レビュー設定でレビューが必須のアクションは、公開APIから直接実行できず403 forbiddenを返します。
公開APIから実行できないアクション
次のアクションはアクション実行画面からは実行できますが、公開APIからは実行できず422 argument_invalidを返します。
| 種別 |
|---|
| ファイルパラメーターを持つアクション |
| (旧)JavaScriptアクション |
| ストレージ（Amazon S3 / Google Cloud Storage）のダウンロード操作のアクション |
| 実行結果にファイル（バイナリデータ）が含まれるアクション |
公開APIはJSON形式で表現できる結果のみを返せます。HTTP APIアクションが画像やPDFなどのバイナリを返した場合や、JavaScriptアクションがファイルを返した場合は実行できません。公開APIでストレージのファイルを取得したい場合は、署名付きURL発行操作のアクションを使用してください。
また、次の状態のアクションは公開APIに限らず実行できず404 not_foundを返します。状態を解消してから実行してください。
| 状態 | 対処 |
|---|---|
| アクションが無効化されている | アクションを有効化する |
| データソースが現在の環境に接続されていない | データソースの接続先設定で現在の環境を有効にする |
認証
公開APIのエンドポイント（トークン交換エンドポイント/tokenを除く）はBearerトークン認証（Authorization: Bearer <token>）で保護されています。ローカル端末からはbm loginで取得したJWTを、CI/CDやクラウドからは外部OIDC IdPが発行したID Tokenをトークン交換エンドポイントでアクセストークンに交換して利用します。シナリオ別の取得手順と呼び出し例は認証して呼び出すを参照してください。
利用までの流れ
- ベースマキナの管理画面でサービスアカウントを用意し、CI/CDやクラウドから呼び出す場合はOIDC信頼ポリシーを設定する
- 認証して呼び出すを参考に、ローカルからは
bm loginで、CI/CDやクラウドからは外部OIDC ID Tokenをアクセストークンに交換して、呼び出し用のトークンを用意する - プロジェクトIDと環境IDを確認し、URLパスの
project_id・environment_idに指定する - APIリファレンスのエンドポイント定義に従って環境一覧・アクション一覧・詳細・実行を呼び出す
OpenAPI仕様
公開APIのインターフェースはOpenAPI仕様（YAML形式）として公開しています。仕様ファイルは次のURLから取得できます。
https://docs.basemachina.com/openapi/public_api.yaml (opens in a new tab)
OpenAPI対応のツールへ仕様ファイルを取り込めば、APIクライアントの生成やリクエストの動作確認に活用できます。
エラーコード
エラーレスポンスはRFC 9457 Problem Details (opens in a new tab)形式（Content-Type: application/problem+json）で返ります。codeフィールドで分類されます。各コードの発生条件・レスポンス例はAPIリファレンスの各エンドポイントのレスポンス定義を参照してください。
トークン交換エンドポイント/tokenのエラーレスポンスのみ、RFC 8693 (opens in a new tab) /
RFC 6749 §5.2 (opens in a new tab)準拠の{ error, error_description }形式（Content-Type: application/json）で返ります。詳細は認証して呼び出すを参照してください。
unauthorized
401。Bearerトークンが欠落・期限切れ・検証失敗。
bad_request
400。URLパスやリクエストの文法レベルの不正。
forbidden
403。対象プロジェクト・アクションへの権限不足、またはサービスアカウントから実行できない操作の呼び出し。
not_found
404。アクション・環境などのリソースが存在しない、または無効化されている。
method_not_allowed
405。許可されていないHTTPメソッドの利用。
state_conflict
409。アクションの状態不整合。
payload_too_large
413。リクエストボディのサイズ超過。
unsupported_media_type
415。Content-Typeがapplication/json以外。
argument_invalid
422。引数・クエリパラメーターのバリデーション違反、または公開APIから実行できないアクションの呼び出し。
javascript_action_error
422。JavaScriptアクションのコードが投げた業務エラー。
data_source_error
422。データソースなど接続先のエラー。接続先のHTTPステータスを取得できた場合はdata_source.statusに格納される。
internal_error
500。ベースマキナ側で予期しないエラーが発生した。
service_unavailable
503。ベースマキナ側の一時障害。Retry-Afterヘッダーに従ってリトライ可能。