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

ユーザー API リファレンス(プロジェクト)

マーケットプレイス版のユーザー向け API のうち、プロジェクトを扱う API のリファレンスです。プロジェクトの作成と設定、登録 Agent の配置、ワークフローの実行の開始、実行の結果と成果物の確認、確認依頼の判断などを、アプリケーション(外部ツールでのログイン)のトークンで行えます。会話・組織の API は ユーザー API リファレンス(会話・組織) を参照してください。API を組み合わせてうまくいかなかった実行を調べて直す流れは、プロジェクト API ガイドにあります。

システム連携のトークンで呼べるプロジェクトの API は、プロジェクト一覧の取得・ワークフローの実行の開始・トリガーの発火・ワークフローの実行の取得の 4 つだけです(システム連携 API リファレンス)。このページのほかの API をシステム連携のトークンで呼ぶと 403 Forbidden(forbidden)が返ります。

ベース URL​

すべての API リクエストは以下のベース URL に対して送信します。<your-domain> は導入した環境のドメインに読み替えてください。

Marketplace
https://<your-domain>/api

本ドキュメントのエンドポイントパスはベース URL からの相対パスで記載しています。

認証​

すべての API リクエストには、Authorization ヘッダーに Bearer トークンを含める必要があります。

Authorization: Bearer <access_token>

トークンが無効または未指定の場合、401 Unauthorized が返されます。マーケットプレイス版ではスコープによる制限はありません。

このページの API は、アプリケーション(外部ツールでのログイン)で得た利用者のトークンで呼びます。外部ツールでのログインは、管理者がその入口を開けた環境でだけ使えます(API 利用準備ガイド)。外部ツールでのログイン以外で得た利用者のトークン(メイン画面にログインしたときのトークンなど)で呼ぶと、どのエンドポイントも 404 Not Found が返ります。トークンの取得方法については、認証ガイド および 認証 API リファレンス を参照してください。

共通の決まり​

このページの API に共通の決まりです。

呼べる人と 404・403​

  • プロジェクトとその中のもの(工程・配置・実行など)を読む API は、プロジェクトのメンバーなら呼べます。プロジェクトを作る API を除き、書き込む API(ワークフローの実行の開始・トリガーの発火を含みます)を呼べるのはプロジェクトのオーナーだけです。確認依頼・キュー・連携先の API の呼べる人は、それぞれの節に書いています。オーナーではないメンバーが呼ぶと 403 Forbidden(owner_only)が返ります。
  • メンバーではないプロジェクトと、存在しないプロジェクトは、どちらも 404 Not Found で、応答から区別できません。ただし、公開されているプロジェクトは、メンバーでなくてもプロジェクトの取得(GET /v1/projects/{projectId})で構造だけを読めます。
  • 404 Not Found の code はエンドポイントごとに 1 つで、パスの最後の資源の名前です(例: 配置の API は placement_not_found、実行の API は execution_not_found)。パスに資源の ID が無いエンドポイントは project_not_found です。プロジェクトが見えないときも、そのエンドポイントの code で返ります。
  • ボディで指定した ID(登録 Agent・工程・利用者など)が存在しない・見えないときの扱いは、エンドポイントごとに違います(例: 配置の marketplaceAgentId は 400 Bad Request(agent_not_found)、配置の stepIds は 400 Bad Request(invalid_parameter))。各エンドポイントの説明とエラーレスポンスを参照してください。
  • 一覧を絞り込むクエリ(placement_id・step_id・run_id)に存在しない ID を指定したときは、空の一覧が返ります。
  • クエリの名前は snake_case です(my_role・placement_id・step_id・run_id・project_id)。前の名前(myRole・placementId・stepId・runId・projectId)でも受け付けます。両方の名前に違う値を指定すると 400 Bad Request(invalid_parameter)です。
  • 本体の利用者の記録が認証サーバーのアカウントと結び付いていない利用者のトークンでは、プロジェクト・確認依頼・キューの API(プロジェクト一覧の取得・ワークフローの実行の開始・トリガーの発火・ワークフローの実行の取得を除きます)で 403 Forbidden(sso_required)が返ります。メイン画面に一度ログインすると結び付きます。

リクエストの扱い​

  • 仕様に無いクエリパラメータとボディのフィールドは無視されます。仕様にあるクエリパラメータの値が不正な場合と、読めない cursor を指定した場合は 400 Bad Request が返ります。
  • ボディは JSON のオブジェクトで送ります。Content-Type: application/json 以外は 415 Unsupported Media Type(unsupported_media_type)、壊れた JSON や JSON のオブジェクトではないボディは 400 Bad Request(invalid_body)です。
  • ボディの上限は 16 KiB です(プロジェクトを作る API と、確認依頼を判断する・期限を延ばす API は 3 MiB)。超えると 413 Payload Too Large(body_too_large)が返ります。
  • この API では受け付けないと決めているフィールドは、送ると 400 Bad Request(invalid_parameter)になります。黙って無視すると、変えたつもりで変わらないためです。該当するフィールドは各エンドポイントの説明に書いています。

書き換えと送り直し​

  • 書き換える API は、取得で返る digest を baseDigest に入れて送ります。取得した後にほかの変更が入っていると 409 Conflict(stale_base)が返ります。取得し直してから送り直してください。ほぼ同時に届いた 2 つの書き換えは、両方が通ることがあります。
  • 応答の digest は書き換えた後の値です。続けて書き換えるときはその値を使えます。
  • 確認依頼の期限の延長と、ワークフローの実行の締め切り・確認担当者の付け替えは、baseDigest を使いません(取得した後の変更とは比べません)。
  • プロジェクトと工程を作る API は、送り直すともう 1 つ作られます。応答が届かなかったときは、送り直す前に、プロジェクトの一覧や取得で作られたかを確かめてください。登録 Agent を置く API は、同じ登録 Agent を同じ担当工程で送り直すと、置いてある配置を返します。
  • ワークフローの実行の開始は Idempotency-Key ヘッダー(必須)、トリガーの発火はボディの eventId、確認依頼の判断と確認担当者の付け替えはボディの commandId で、送り直しを見分けます。同じキーで送り直すと、1 回目の結果が返ります。

人を表す項目​

  • 利用者の名前とメールアドレスを返すのは、プロジェクトの取得(GET /v1/projects/{projectId})のメンバーの一覧(members)だけです。ほかの項目は利用者 ID だけを返します。
  • 資源の持ち主は ownerUserId(配置の Agent の持ち主は agentOwnerUserId)、設定の中の人は approverUserIds・escalateToUserId、確認依頼の依頼者は requesterUserId です。
  • 「誰がしたか」は、…Kind(種類)と …Ref(参照)の組で返します。…Kind が "human" なら …Ref は利用者 ID です。人ではないとき、…Ref はシステム連携なら client:<連携の ID>、それ以外は system:… などの参照です。値が無くても、項目は省かずに null で返します。例外として、ワークフローの実行を始めたものは startedByRef だけで返します(種類の項目はありません。値はワークフローの実行の取得(GET /v1/projects/{projectId}/runs/{runId})の説明を参照)。

ページネーション​

一覧の API は、limit(1〜100。省くと 50)と cursor(前回のレスポンスの値をそのまま送ります)で続きを読みます。hasMore が true のときだけ cursor が返ります。一覧の数(total)は返しません。limit の範囲や既定値が違う一覧、limit の無い一覧、全件を返す一覧と、続きを読めない一覧(hasMore の意味が違う一覧)は、各エンドポイントの説明に書いています。

プロジェクト​

プロジェクトは、工程に Agent を置いて業務を進める単位です。workflow(工程を順に進める)と cycle(配置ごとに巡回で動かし続ける)の 2 つの型があります。型は作るときに決め、後から変えられません。

エンドポイント一覧​

メソッドエンドポイント説明
GET/v1/projects自分が参加しているプロジェクトの一覧を取得
GET/v1/projects/shared公開されているプロジェクトの一覧を取得
GET/v1/projects/organizationsプロジェクトに付けられる組織を取得
GET/v1/projects/{projectId}プロジェクトを取得
POST/v1/projectsプロジェクトを作る
PATCH/v1/projects/{projectId}プロジェクトを変える
DELETE/v1/projects/{projectId}プロジェクトを消す
GET/v1/projects/{projectId}/control統制の設定を取得

GET/v1/projects

アクセスできるプロジェクトの一覧を取得します。カーソルベースのページネーションに対応しています。cycle 型のプロジェクトも一覧に含まれますが、実行開始(POST /v1/projects/{projectId}/runs)の対象にはなりません。

クエリパラメータ​

パラメータ型デフォルト説明
limitinteger50取得件数(1〜100)
cursorstring—次ページ取得用カーソル(前回レスポンスの cursor 値)
my_rolestring—"owner" または "member"。呼び手がその役割のプロジェクトだけを返します(前の名前 myRole でも受け付けます)

上記以外のクエリパラメータは無視されます。 my_role に "owner" / "member" 以外の値を指定した場合、複数指定した場合、および my_role と myRole に違う値を指定した場合は 400 Bad Request が返ります。

cursor は取得位置を表すため、同じカーソルを使い続ける間は my_role を変更しないでください。条件を変えると対象範囲が変わり、項目の重複や取りこぼしが起きます。

レスポンスフィールド(200 OK)​

フィールド型説明
projectsarrayプロジェクトオブジェクトの配列
projects[].projectIdstringプロジェクト ID(UUID)
projects[].namestringプロジェクト名
projects[].typestring"workflow" または "cycle"
projects[].statusstringプロジェクトの状態。"active" / "paused" / "archived" のいずれか
projects[].tagsarrayタグの配列。設定されていない場合は空の配列
projects[].myRolestring呼び手自身のそのプロジェクトでの役割。"owner" または "member"
projects[].ownersarrayそのプロジェクトの現在のオーナーの利用者 ID の配列。オーナー以外の参加者は含みません
hasMoreboolean次のページが存在するかどうか
cursorstring次ページ取得用カーソル。hasMore が true の場合のみ含まれます

レスポンス例​

JSON
{
"projects": [
{
"projectId": "550e8400-e29b-41d4-a716-446655440000",
"name": "受注処理フロー",
"type": "workflow",
"status": "active",
"tags": [],
"myRole": "owner",
"owners": ["bbbe4306-6975-420b-af47-fb4c8f48b4aa"]
},
{
"projectId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "問い合わせ常時対応",
"type": "cycle",
"status": "active",
"tags": [],
"myRole": "member",
"owners": ["90b40fd8-a6b8-42b8-ab61-f3b674169b43", "463e2c25-5a80-4362-b77e-941df96fb1f2"]
}
],
"hasMore": false
}

エラーレスポンス​

ステータス説明
400limit(1〜100 の範囲外)、cursor、または my_role が不正(code は invalid_parameter)

GET/v1/projects/shared

公開されているプロジェクトの一覧を取得します(自分のプロジェクトも、公開していれば含まれます)。カーソルベースのページネーションに対応しています。

クエリパラメータ​

パラメータ型デフォルト説明
limitinteger501 ページの取得件数(1-100)
cursorstring—次ページ取得用カーソル(前回レスポンスの cursor 値)
typestring—"cycle" または "workflow" で絞り込み
tagstring—このタグを持つプロジェクトに絞り込み(前後の空白と先頭の # を除いて 30 文字まで。大文字と小文字は区別しません)
qstring—名前か説明の一部で絞り込み(100 文字まで)
sortstring"popular"並び順。"popular" はコピーされた回数の多い順(同数なら更新日時の新しい順)、"new" は更新日時の新しい順

レスポンスフィールド(200 OK)​

フィールド型説明
projectsarrayプロジェクトの配列
projects[].projectIdstringプロジェクト ID(UUID)
projects[].namestring | nullプロジェクト名
projects[].descriptionstring | null説明
projects[].typestring | null"workflow" または "cycle"
projects[].statusstring | null"active" / "paused" / "archived" のいずれか
projects[].tagsarrayタグの配列
projects[].stepCountnumber | null有効な工程の数
projects[].agentCountnumber | null配置の数
projects[].copyCountnumber | nullコピーされた回数
projects[].connectorCountnumber | null連携先の数
projects[].ownerUserIdstring | null持ち主の利用者 ID
projects[].updatedAtstring | null最終更新日時(ISO 8601)
hasMoreboolean次のページが存在するかどうか
cursorstring次ページ取得用カーソル。hasMore が true の場合のみ含まれます

自分がメンバーのプロジェクトでも、myRole・owners は含まれません。

エラーレスポンス​

ステータスcode説明
400invalid_parameterlimit・cursor・type・tag・q・sort の値が不正
403forbiddenシステム連携のトークンで呼び出した
403sso_required認証サーバーのアカウントと結び付いていない利用者

GET/v1/projects/organizations

プロジェクトを作るときに付けられる組織を取得します。付けられるのは、呼んだ利用者が今所属している組織だけです(0 件か 1 件)。すべての組織を返す GET /v1/organizations とは違います。

レスポンスフィールド(200 OK)​

フィールド型説明
organizationsarray組織の配列
organizations[].valuestring組織のコード(プロジェクトの organizationCode に指定します)
organizations[].labelstring | null組織の名前
hasMorebooleanいつも false

エラーレスポンス​

ステータスcode説明
403forbiddenシステム連携のトークンで呼び出した
403sso_required認証サーバーのアカウントと結び付いていない利用者
503organization_unavailable所属している組織を確かめられない(時間をおいて送り直してください)

GET/v1/projects/{projectId}

プロジェクトを、工程・メンバー・配置・トリガー・通知・連携先と合わせて取得します。メンバーではない利用者が公開されているプロジェクトを指定すると、構造だけ(プレビュー)を返します。

パスパラメータ​

パラメータ型必須説明
projectIdstring必須プロジェクト ID(UUID)

レスポンスフィールド(200 OK)​

フィールド型説明
projectobjectプロジェクト(下の表)
stepsarray工程の配列(並び順)。1 件の項目は「工程の項目」を参照
stepsDigeststring工程の並びの値。工程を並べ替えるときに baseDigest に送ります
membersarrayメンバーの配列
members[].userIdstring利用者 ID
members[].rolestring | null"owner" または "member"
members[].joinedAtstring | nullメンバーになった日時(ISO 8601)
members[].namestring | null利用者の名前
members[].emailstring | null利用者のメールアドレス
placementsarray配置の配列。1 件の項目は「配置の項目」を参照
triggersarrayトリガーの配列(時刻と Webhook のトリガーだけ)
triggers[].triggerIdstring | nullトリガー ID(UUID)。トリガーの発火に使います
triggers[].typestring"cron"(時刻)または "webhook"
triggers[].namestring | null名前
triggers[].enabledboolean | null有効かどうか
triggers[].lastFiredAtstring | null最後に発火した日時(ISO 8601)
triggers[].nextFireAtstring | null次に発火する予定の日時(ISO 8601)
triggers[].createdAtstring | null作成日時(ISO 8601)
triggers[].cronstring | nullcron 式("cron" のトリガーだけ)
triggers[].timezonestring | nullタイムゾーン("cron" のトリガーだけ)
triggers[].startStepIdstring | null始める工程の ID("cron" のトリガーだけ)
triggers[].placementIdstring | null起動する配置の ID("webhook" のトリガーだけ)
triggers[].stepIdstring | null起動する工程の ID("webhook" のトリガーだけ)
triggers[].startFailureobject | null開始の失敗("cron" のトリガーだけ)。開始できなかったときだけ入り、ほかは null。下の「開始の失敗の読み方」を参照
triggers[].startFailure.reasonstring | null開始できなかった理由のコード
triggers[].startFailure.sincestring | nullその理由で開始できなくなった日時(ISO 8601)
stepStartFailuresarray先頭の工程に付けた時刻で開始する形の、開始の失敗の配列。開始できなかった工程だけが入ります。下の「開始の失敗の読み方」を参照
stepStartFailures[].stepIdstring | null工程の ID
stepStartFailures[].reasonstring | null開始できなかった理由のコード
stepStartFailures[].sincestring | nullその理由で開始できなくなった日時(ISO 8601)
notificationsobject通知の設定
notifications.gateReachedboolean | null確認依頼が届いたときに通知するかどうか
notifications.gateOverdueboolean | null確認依頼が期限を過ぎたときに通知するかどうか
notifications.runDeadlineOverdueboolean | nullワークフローの実行が締め切りを過ぎたときに通知するかどうか
notifications.runStalledboolean | nullワークフローの実行が停滞したとき(limits.stallHours のあいだ進まないとき)に通知するかどうか
connectorsarrayこのプロジェクトに登録した連携先の配列
connectors[].kindstring | null"mcp" または "a2a"
connectors[].connectionIdstring | null連携先の ID。連携先の API(GET /v1/connectors/{kind}/{connectionId})で中身を読めます。管理画面で無効にされた・削除された連携先と、連携先の情報を確かめられなかったときは null
connectors[].namestring | null連携先の名前
connectors[].ledgerEnabledboolean | null台帳として使う連携先かどうか
connectors[].confirmModestring | nullこの連携先を使う前に、人の確認を求めるかの設定。"none" / "first_per_execution" / "always" のどれか。画面で設定します
connectors[].confirmWaitMinutesnumber | nullその確認を待つ時間の上限(分)
connectors[].loginstring | nullログインの状態。"connected"(ログイン済み)/ "reauth_required"(ログインし直しが必要)/ "not_connected"(未ログイン)。状態を確かめられないときは null。ログインは画面で行います
connectors[].createdAtstring | null登録日時(ISO 8601)

project の項目:

フィールド型説明
projectIdstringプロジェクト ID(UUID)
namestring | nullプロジェクト名
descriptionstring | null説明
tagsarrayタグの配列
typestring | null"workflow" または "cycle"
statusstring | null"active"(稼働中)/ "paused"(停止中)/ "archived"(アーカイブ)のいずれか
policyobject | null実行ルール。画面で設定した値のまま返ります。この API では変えられません
limitsobject | null実行の上限
limits.maxRetriesPerStepnumber1 つの工程で失敗したときにやり直す回数の上限
limits.maxSendBacksPerStepnumber同じ工程へ差し戻せる回数の上限
limits.runDeadlineHoursnumber | nullワークフローの実行の締め切りの既定(開始からの時間)。null または無ければ締め切りを付けません
limits.stallHoursnumber進まないまま、この時間が過ぎると停滞とみなす時間(無ければ 24 時間)
limits.maxMinutesPerRunnumber | null1 回の実行の長さの上限(分)。5・15・30・60・90・120 のどれか。無いとき・null のときは、この上限を付けていません
languagestring | nullプロジェクトの言語
flowStructureobject | nullいつも null
reportTargetsobject | null今は使っていない項目です(値が入っていても使われません)
escalateToUserIdstring | nullプロジェクトの既定の連絡先の利用者 ID(期限を過ぎた確認依頼の連絡先。このエンドポイントでは変えられません)
organizationCodestring | null組織のコード
organizationNamestring | null組織の名前
isSharedboolean | null公開しているかどうか
copyCountnumber | nullコピーされた回数
ownerUserIdstring | null持ち主の利用者 ID
myRolestring | null呼んだ利用者の役割。"owner" または "member"。プレビューでは null
createdAtstring | null作成日時(ISO 8601)
updatedAtstring | null最終更新日時(ISO 8601)
digeststringプロジェクトを変えるときに baseDigest に送る値

開始の失敗の読み方(triggers[].startFailure・stepStartFailures):

時刻でワークフローの実行を始められなかったときの記録です。時間トリガー("cron")と、先頭の工程に付けた時刻(工程の schedule)の 2 つがあります。

  • 直近 90 日の、そのトリガー(工程)の最後の開始の記録が失敗のときだけ入ります。開始できた後と、まだ一度も時刻が来ていないときは、startFailure は null で、stepStartFailures には入りません。
  • 同じ理由が続くあいだは、最初の 1 回だけを記録します。since は、その理由で開始できなくなった日時です。理由が変わると新しくなります。同じ理由で 90 日より長く開始できていないときは、記録が 90 日より前になるので、null(入らない)になります。
  • プロジェクトの停止中や、同時に動かせる実行の上限に達していたときなど、記録しない理由で開始しなかった回では、値は変わりません(前の記録が失敗なら失敗のまま、開始できていれば null のまま)。
  • 先頭の工程に付けた時刻で開始するのは、有効な時間トリガーが無いときだけです。有効な時間トリガーがあるあいだの stepStartFailures は前の記録です。消した工程の ID が入ることもあります。

reason の主な値です。このほかの値が返ることもあります。

値意味
approvers_required人の確認の工程に、今もメンバーの確認担当者がいない
unsupported_runtimeこのサービスで動かせない種類の Agent が置かれている
unexpected_error予期しない失敗

メンバーではない利用者が公開されているプロジェクトを読むとき(プレビュー)は、project(organizationName と digest を除きます。myRole は null)・steps(各工程の digest を除きます)・placements(placementId・agentId・name・description・goal・stepIds・skillCount だけ)を返します。stepsDigest・members・triggers・stepStartFailures・notifications・connectors は返しません。

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId が UUID の形式ではない
403forbiddenシステム連携のトークンで呼び出した
403sso_required認証サーバーのアカウントと結び付いていない利用者
404project_not_foundプロジェクトが存在しない、またはメンバーではない公開されていないプロジェクト

POST/v1/projects

プロジェクトを作ります。作った利用者がオーナーになり、プロジェクトの実行の主体になります。Agent は、置ける Agent の候補(GET /v1/projects/agent-candidates)から選んで、配置を置く API(POST /v1/projects/{projectId}/placements)で置きます。

リクエストボディ​

フィールド型必須説明
namestring必須プロジェクト名(255 文字まで。空白だけにはできません)
descriptionstring—説明(5000 文字まで)
tagsarray—タグ(1 つ 30 文字までの文字列を 10 個まで。前後の空白と先頭の # を除き、小文字にして保存します。そうして空になるタグと、同じになるタグは送れません)
typestring—"cycle" または "workflow"。省くと "cycle"(cycle を使えない環境では "workflow")
organizationCodestring | null—組織のコード(255 文字まで)。付けられるのは GET /v1/projects/organizations で返る組織だけ。null・空の文字列・空白だけは、付けないのと同じです
stepsarray—工程の並び(12 個まで)。省くか空の配列のときは、既定の工程で作ります(workflow は Agent が実行する工程・確認工程・Agent が実行する工程の 3 つ、cycle は Agent が実行する工程 2 つ)
steps[].namestring | null—工程の名前(100 文字まで。空の文字列・null は既定の名前です。空白だけにはできません)
steps[].descriptionstring | null—工程の説明(空の文字列・null は説明なし)
steps[].enabledboolean—有効かどうか(true または false)。省くと有効です
steps[].zonestring—"ai"(Agent が実行)または "gate"(確認工程)。省くと "ai"。cycle では "ai" だけ。null は送れません

trigger・policy・agents・guardrail・templateRef は受け付けません(送ると 400、invalid_parameter)。トリガーと実行ルールは画面で設定します。cycle の巡回の周期は、Agent を置いた後に巡回を変える API(PATCH /v1/projects/{projectId}/placements/{placementId}/schedule)で設定します。

レスポンス(201 Created)​

フィールド型説明
projectobject作ったプロジェクト。プロジェクトの取得の project と同じ項目です(organizationName を除きます。myRole は "owner")
stepsarray作った工程の配列。1 件の項目は「工程の項目」を参照

エラーレスポンス​

ステータスcode説明
400invalid_parametername が無い・空白だけ、項目の型や長さ・数・値の誤り(タグの空・重なりを含みます)、工程が 12 個を超える、または trigger・policy・agents・guardrail・templateRef を送った
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
400cycle_disabledこの環境では cycle を使えない
400cycle_gate_not_allowedcycle に確認工程("gate")を指定した
400organization_not_member付けられない組織を指定した
403forbiddenシステム連携のトークンで呼び出した
403sso_required認証サーバーのアカウントと結び付いていない利用者
409project_limit_reachedプロジェクトの数が上限に達している(マーケットプレイス版は 1 つの環境で 5 件まで。アーカイブしたプロジェクトは数えません。数は error.message)
413body_too_largeボディが 3 MiB を超える
415unsupported_media_typeボディの Content-Type が application/json ではない
503organization_unavailable所属している組織を確かめられない

PATCH/v1/projects/{projectId}

プロジェクトを変えます。送った項目だけを変えます。オーナーだけが呼べます。

パスパラメータ​

パラメータ型必須説明
projectIdstring必須プロジェクト ID(UUID)

リクエストボディ​

フィールド型必須説明
baseDigeststring必須プロジェクトの取得の project.digest
namestring—プロジェクト名(255 文字まで。空・空白だけにはできません)
descriptionstring—説明(5000 文字まで。空の文字列・空白だけ・null にはできません)
tagsarray—タグ(作るときと同じ)。送ると全部が置き換わります
statusstring—"active" / "paused" / "archived"
isSharedboolean—公開するかどうか
limitsobject—実行の上限。送った項目だけを今の値に重ねます
limits.maxRetriesPerStepinteger—0〜10
limits.maxSendBacksPerStepinteger—1〜10
limits.runDeadlineHoursinteger | null—1〜2160。null は締め切りを付けない
limits.stallHoursinteger—1〜720
limits.maxMinutesPerRuninteger | null—1 回の実行の長さの上限(分)。5・15・30・60・90・120 のどれか。null は上限を付けない
organizationCodestring | null—組織のコード(255 文字まで)。組織をまだ付けていないプロジェクトに 1 回だけ付けられます。今の値と同じ値は何も変えません(取得の値をそのまま送り返せます)。組織が付いているプロジェクトに違う値を送ると 409(organization_locked)です。null は、組織がまだ付いていなければ何も変えず、付いていれば 409(organization_locked)です

baseDigest のほかに、少なくとも 1 つの項目を送ってください。type・policy・connectSecret は受け付けません(送ると 400、invalid_parameter)。型は作るときに決め、実行ルールは画面で変えます。

status を "paused"・"archived" にすると、新しい実行が始まらなくなります。巡回と時刻による開始が止まり、ワークフローの実行の開始とトリガーの発火は 409 Conflict で断られます(ワークフローの実行の開始を、前に受け付けたのと同じ Idempotency-Key で送り直したときは、1 回目の結果が返ります)。動いている実行は止まりません。動いているワークフローの実行は、次の工程を始めずに待ちます(status は "running"・"waiting_gate" のままです)。止める前に受け付けた発火は、止めた後でも動くことがあります。"active" に戻すと、止まっていた間の起動を続きから動かします。

レスポンス(200 OK)​

フィールド型説明
projectobject変えた後のプロジェクト。プロジェクトの取得の project と同じ項目です(organizationName を除きます)

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId が UUID の形式ではない、baseDigest が無い・空・文字列ではない、変える項目が無い、name を空・空白だけにした、description を空の文字列・空白だけ・null にした、name・status・tags・isShared・limits に null を送った、項目の型や値の誤り(タグの空・重なりを含みます)、または type・policy・connectSecret を送った
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
400organization_not_member付けられない組織を指定した
403forbiddenシステム連携のトークンで呼び出した
403owner_onlyオーナーではないメンバー
403sso_required認証サーバーのアカウントと結び付いていない利用者
404project_not_foundプロジェクトが存在しない、またはメンバーではない
409stale_base取得した後にプロジェクトが変わっている
409organization_locked組織はすでに付いている(違う値、または null を送った)
409project_limit_reached"archived" から戻そうとしたが、プロジェクトの数が上限に達している(マーケットプレイス版は 1 つの環境で 5 件まで。数は error.message)
413body_too_largeボディが 16 KiB を超える
415unsupported_media_typeボディの Content-Type が application/json ではない
503organization_unavailable所属している組織を確かめられない

DELETE/v1/projects/{projectId}

プロジェクトを消します。オーナーだけが呼べます。動いているもの(巡回・実行中のワークフローの実行・確認待ちの確認依頼・トリガー)は止まります。実行や確認の記録は消えません。プロジェクトの連携先のログインも外そうとしますが、外せなくてもプロジェクトの削除は成功として返ります。

パスパラメータ​

パラメータ型必須説明
projectIdstring必須プロジェクト ID(UUID)

レスポンス(200 OK)​

JSON
{
"projectId": "6addd341-cd6d-4061-b8dc-4e9a6669a720",
"deleted": true
}

もう一度呼ぶと 404 Not Found が返ります。

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId が UUID の形式ではない
403forbiddenシステム連携のトークンで呼び出した
403owner_onlyオーナーではないメンバー
403sso_required認証サーバーのアカウントと結び付いていない利用者
404project_not_foundプロジェクトが存在しない、メンバーではない、またはすでに消した

GET/v1/projects/{projectId}/control

プロジェクトの統制の設定(実行ルールの強さと、確認工程の設定)を取得します。

パスパラメータ​

パラメータ型必須説明
projectIdstring必須プロジェクト ID(UUID)

レスポンスフィールド(200 OK)​

フィールド型説明
tenantProfilestring | nullテナント全体の基本ルール。"open" / "guarded" / "strict"。確かめられないときは null
tenantSourcestring | nulltenantProfile の出どころ。"governance_policies"(管理画面で設定)/ "default"(設定が無いので既定)/ "unavailable"(確かめられない)
projectProfilestring | nullこのプロジェクトの基本ルール
effectiveProfilestring | null実際に効く基本ルール(テナント全体とこのプロジェクトのうち厳しい方)。tenantProfile が null のときは null
denyarray実行ルールで禁止している操作
gatesarray有効な確認工程の配列
gates[].stepIdstring工程の ID
gates[].positionnumber工程の位置
gates[].namestring工程の名前
gates[].gateKindstring確認の種類。"review"(確認)または "manual"(手作業)
gates[].modestring"blocking"(担当者の判断を待つ)。前の版で保存した "notify_only" が返ることがありますが、ワークフローの実行では値によらず担当者の判断を待ちます
gates[].overdueActionstring"none"(期限を過ぎても自動では決まらず、通知して待ち続けます)。前の版で保存した値が返ることがありますが、ワークフローの実行では値によらず、期限を過ぎても自動では決まらず通知して待ち続けます
gates[].approverUserIdsarray確認担当者の利用者 ID の配列
gates[].deadlineHoursnumber | null確認期限(時間)
operationClassesnull今は使っていない項目です(いつも null)

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId が UUID の形式ではない
403forbiddenシステム連携のトークンで呼び出した
403sso_required認証サーバーのアカウントと結び付いていない利用者
404project_not_foundプロジェクトが存在しない、またはメンバーではない

工程​

工程は、プロジェクトの流れの単位です。Agent が実行する工程(defaultZone が "ai")と、人が判断する確認工程("gate")があります。工程は 12 個までです。工程を消して下限(ワークフローは 2 個、サイクルは 1 個)より少なくすることはできません。

エンドポイント一覧​

メソッドエンドポイント説明
POST/v1/projects/{projectId}/steps工程を足す
PATCH/v1/projects/{projectId}/steps/{stepId}工程を変える
PUT/v1/projects/{projectId}/steps/order工程を並べ替える
DELETE/v1/projects/{projectId}/steps/{stepId}工程を消す

工程の項目​

プロジェクトの取得の steps と、工程の API の応答の工程の 1 件の項目です。

フィールド型説明
stepIdstring工程の ID(UUID)
positionnumber | null工程の位置(1 から)
namestring | null工程の名前。null のときは画面で既定の名前(「工程1」など)が出ます
descriptionstring | null説明
enabledboolean | null有効かどうか
defaultZonestring | null"ai"(Agent が実行)または "gate"(確認工程)
reworkToStepIdstring | null差し戻すときの戻り先の工程の ID(確認工程で使います)
gateConfigobject | null確認工程の設定(下の表)
gateKindstring | null確認の種類。"review"(確認。Agent の結果を人が判断する)または "manual"(手作業。人が作業してから進める)
scheduleobject | null工程の時刻(workflow だけ)。expression(cron 式)と timezone
scheduleNextFireAtstring | null工程の時刻で次に動く予定の日時(ISO 8601)
onDeniedstring | null「ルールにより実行できない場合」の扱い。"gate"(確認を求める)/ "closed_failed"(失敗として閉じる)
onDegradedstring | null「Agent の報告による失敗のとき」の扱い。"gate"(確認を求める)/ "proceed"(そのまま進める)
outcomeRoutesobject | nullいつも null(マーケットプレイス版では、結果ごとの行き先を設定できません)
laneIdstring | nullいつも null
placementExecutionstring | nullいつも null(置いた順に 1 つずつ実行)
digeststring工程を変えるときに baseDigest に送る値

確認工程の設定(gateConfig):

フィールド型説明
approverUserIdsarray確認担当者の利用者 ID の配列(プロジェクトのメンバーから 20 人まで)
deadlineHoursnumber | null確認期限(時間。1〜720)
modestring | null確認方法。送れるのは "blocking"(担当者の判断を待つ)だけです("notify_only" は 400 structure_not_for_marketplace)。前の版で保存した "notify_only" が返ることがありますが、ワークフローの実行では値によらず担当者の判断を待ちます
overdueActionstring | null期限を過ぎたとき。送れるのは "none"(期限を過ぎても自動では決まらず、通知して待ち続けます)か null("none" として動きます)です("proceed"・"send_back"・"reject" は 400 structure_not_for_marketplace)。前の版で保存した値が返ることがありますが、ワークフローの実行では値によらず、期限を過ぎても自動では決まらず通知して待ち続けます
escalateToUserIdstring | null期限超過時の連絡先の利用者 ID(プロジェクトのメンバー)
destinationsarrayいつも含まれません(マーケットプレイス版では、進め先を設定できません)

確認工程の設定が無いとき(gateConfig が null、または項目が無いとき)は、mode は "blocking"、deadlineHours は 24 時間、overdueAction は "none"、期限超過時の連絡先は無しとして動きます。deadlineHours・overdueAction・escalateToUserId は、null を送っても同じです(mode に null を送ると 400 Bad Request(invalid_parameter)です)。gateKind が null のときは "review" です。

プロジェクトの型によって、工程に付けられないものがあります。

工程の項目workflowcycle
確認工程(defaultZone の "gate")と、その設定(gateConfig・gateKind)付けられる400(cycle_gate_not_allowed)
onDenied・onDegraded の "gate"付けられる400(cycle_gate_not_allowed)
schedule(工程の時刻)付けられる400(invalid_parameter)
reworkToStepId(差し戻し先)付けられる400(invalid_parameter)

cycle で断る schedule・reworkToStepId は、null 以外の値を送ったときだけです(取得した工程をそのまま送り返せるように、null は受け付けます)。cycle の Agent を動かす周期は、工程ではなく配置の巡回で決めます。

POST/v1/projects/{projectId}/steps

工程を足します。オーナーだけが呼べます。

パスパラメータ​

パラメータ型必須説明
projectIdstring必須プロジェクト ID(UUID)

リクエストボディ​

フィールド型必須説明
namestring | null—工程の名前(100 文字まで。空の文字列・null は既定の名前です。空白だけにはできません)
descriptionstring | null—説明(2000 文字まで。空の文字列・null は説明なし)
defaultZonestring—"ai" または "gate"。省くと "ai"。null・空の文字列は送れません
afterStepIdstring—この工程の後ろに足す(このプロジェクトの工程の ID)
beforeStepIdstring—この工程の前に足す(このプロジェクトの工程の ID)。afterStepId と両方を指定すると、この工程の前に足します。どちらも省くと末尾に足します
gateConfigobject | null—確認工程の設定(工程の項目の gateConfig と同じ形)。null は設定なし

レスポンス(201 Created)​

フィールド型説明
stepobject足した工程
stepsarray足した後の全部の工程(並び順)
stepsDigeststring足した後の工程の並びの値

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId が UUID の形式ではない、afterStepId・beforeStepId がこのプロジェクトの工程ではない、項目の型や長さ・値の誤り(name の空白だけ、defaultZone の null・空の文字列を含みます)、または gateConfig に approvers・escalateToRef を送った(approverUserIds・escalateToUserId を使います)
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
400structure_not_for_marketplaceマーケットプレイス版に無い確認工程の設定("notify_only"・期限後の自動処理)を送った
400step_reference_on_creategateConfig に destinations を送った(null・空の配列を含みます。マーケットプレイス版では進め先を設定できません)
400cycle_gate_not_allowedcycle に確認工程を足そうとした
400approver_not_member確認担当者にメンバーではない利用者を指定した
400approvers_required稼働中の workflow に、確認担当者のいない確認工程を足そうとした
400escalate_to_not_member期限超過時の連絡先にメンバーではない利用者を指定した
403forbiddenシステム連携のトークンで呼び出した
403owner_onlyオーナーではないメンバー
403sso_required認証サーバーのアカウントと結び付いていない利用者
404project_not_foundプロジェクトが存在しない、またはメンバーではない
409too_many_steps工程がすでに 12 個ある
413body_too_largeボディが 16 KiB を超える
415unsupported_media_typeボディの Content-Type が application/json ではない

PATCH/v1/projects/{projectId}/steps/{stepId}

工程を変えます。送った項目だけを変えます。オーナーだけが呼べます。

パスパラメータ​

パラメータ型必須説明
projectIdstring必須プロジェクト ID(UUID)
stepIdstring必須工程の ID(UUID)

リクエストボディ​

フィールド型必須説明
baseDigeststring必須その工程の digest
namestring | null—工程の名前(100 文字まで)。空の文字列・null で既定の名前に戻します。空白だけにはできません
descriptionstring—説明(2000 文字まで。空の文字列・空白だけ・null にはできません)
defaultZonestring—"ai" または "gate"
enabledboolean—有効かどうか
gateConfigobject | null—確認工程の設定。送った項目だけを今の値に重ねます。null で設定を外します。前の版で "notify_only" や期限後の自動処理を保存した工程では、ほかの項目だけを送っても 400(structure_not_for_marketplace)になります。そのときは mode に "blocking"、overdueAction に "none" を一緒に送ってください
gateKindstring | null—"review" または "manual"
reworkToStepIdstring | null—差し戻し先(この工程より前の工程)。null で外します
onDeniedstring | null—"gate" / "closed_failed"
onDegradedstring | null—"gate" / "proceed"
scheduleobject | null—工程の時刻(workflow だけ)。expression(5 項目の cron 式)と timezone(省くと UTC)。null で外します

baseDigest のほかに、少なくとも 1 つの項目を送ってください。

工程の時刻は、先頭の工程ではプロジェクトに有効な時刻のトリガーが無いときだけ、その時刻にワークフローの実行を始めます。ほかの工程では、ワークフローの実行の中でその時刻まで待ちます。

確認担当者(approverUserIds)と確認方法(mode)を変えると、記録 (証跡) に残ります。

レスポンス(200 OK)​

フィールド型説明
stepobject変えた後の工程(新しい digest)

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId・stepId が UUID の形式ではない、baseDigest が無い・空・文字列ではない、変える項目が無い、name を空白だけにした、description を空の文字列・空白だけ・null にした、defaultZone・enabled に null を送った、項目の型や長さ・値の誤り、cycle に schedule・reworkToStepId を送った、または gateConfig に approvers・escalateToRef を送った(approverUserIds・escalateToUserId を使います)
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
400structure_not_for_marketplaceマーケットプレイス版に無い工程の構造(結果ごとの行き先・進め先・"notify_only"・期限後の自動処理など)を送った
400cycle_gate_not_allowedcycle の工程を確認工程にしようとした、または onDenied・onDegraded に "gate" を指定した
400cycle_route_not_allowedcycle の工程に "goto" を指定した
400approver_not_member確認担当者にメンバーではない利用者を指定した
400approvers_required稼働中の workflow で、有効な確認工程の確認担当者がいなくなる
400escalate_to_not_member期限超過時の連絡先にメンバーではない利用者を指定した
400invalid_send_back_step差し戻し先が、この工程より前の工程ではない
400invalid_outcome_route"goto" を指定した(マーケットプレイス版では行き先を設定できないので、"goto" は使えません)
403forbiddenシステム連携のトークンで呼び出した
403owner_onlyオーナーではないメンバー
403sso_required認証サーバーのアカウントと結び付いていない利用者
404step_not_found工程が存在しない、またはメンバーではないプロジェクト
409stale_base取得した後に工程が変わっている
413body_too_largeボディが 16 KiB を超える
415unsupported_media_typeボディの Content-Type が application/json ではない

PUT/v1/projects/{projectId}/steps/order

工程を並べ替えます。オーナーだけが呼べます。

パスパラメータ​

パラメータ型必須説明
projectIdstring必須プロジェクト ID(UUID)

リクエストボディ​

フィールド型必須説明
baseDigeststring必須プロジェクトの取得の stepsDigest
stepIdsarray必須全部の工程の ID を、新しい並び順で(重複なし)

レスポンス(200 OK)​

フィールド型説明
stepsarray並べ替えた後の全部の工程
stepsDigeststring並べ替えた後の工程の並びの値

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId が UUID の形式ではない、baseDigest が無い・空・文字列ではない、または stepIds が全部の工程の並びになっていない
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
403forbiddenシステム連携のトークンで呼び出した
403owner_onlyオーナーではないメンバー
403sso_required認証サーバーのアカウントと結び付いていない利用者
404project_not_foundプロジェクトが存在しない、またはメンバーではない
409stale_base取得した後に工程の並びが変わっている
413body_too_largeボディが 16 KiB を超える
415unsupported_media_typeボディの Content-Type が application/json ではない

DELETE/v1/projects/{projectId}/steps/{stepId}

工程を消します。オーナーだけが呼べます。その工程を指す差し戻し先・行き先・トリガーの開始工程は外れ、その工程の配置と巡回も外れます。過去のワークフローの実行や確認依頼が使った工程は、記録のために残ります(historyKept が true)。

パスパラメータ​

パラメータ型必須説明
projectIdstring必須プロジェクト ID(UUID)
stepIdstring必須工程の ID(UUID)

レスポンス(200 OK)​

フィールド型説明
stepIdstring消した工程の ID
deletedbooleanいつも true
historyKeptboolean記録のために工程を残したかどうか
stepsarray消した後の全部の工程
stepsDigeststring消した後の工程の並びの値

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId・stepId が UUID の形式ではない
403forbiddenシステム連携のトークンで呼び出した
403owner_onlyオーナーではないメンバー
403sso_required認証サーバーのアカウントと結び付いていない利用者
404step_not_found工程が存在しない、またはメンバーではないプロジェクト
409min_steps工程が下限の数しかない(ワークフローは 2 つ、サイクルは 1 つ)

配置​

配置は、登録 Agent(管理者が登録した Agent)をプロジェクトの工程に置いたものです。1 つのプロジェクトに同じ Agent を置けるのは 1 つの配置だけで、1 つの配置は複数の工程(担当工程)を持てます。cycle では、Agent を動かす周期(巡回)を配置と工程の組ごとに決めます。

エンドポイント一覧​

メソッドエンドポイント説明
GET/v1/projects/{projectId}/placements配置の一覧を取得
GET/v1/projects/{projectId}/placements/{placementId}配置を取得
GET/v1/projects/agent-candidates置ける登録 Agent の一覧を取得
POST/v1/projects/{projectId}/placements配置を置く
DELETE/v1/projects/{projectId}/placements/{placementId}配置を外す
PUT/v1/projects/{projectId}/placements/{placementId}/steps配置の担当工程を変える
PATCH/v1/projects/{projectId}/placements/{placementId}/schedule巡回を止める・再開する・周期を変える(cycle だけ)

配置の項目​

プロジェクトの取得の placements と、配置の API の応答の配置の 1 件の項目です。

フィールド型説明
placementIdstring配置の ID(UUID)
agentIdstring | null置いた Agent の ID
displayOrdernumber | null表示の順
namestring | nullAgent の名前
descriptionstring | nullAgent の説明
goalstring | nullいつも null
guardrailstring | nullいつも null
skillsarrayいつも空の配列
skillCountnumber | nullいつも 0
playbookIdstring | nullいつも null
playbookNamestring | nullいつも null
inputFilesarrayいつも空の配列
stepIdsarray担当工程の ID の配列
sweepsarray巡回の設定(cycle)。担当工程ごとに stepId・cron・timezone・enabled
runtimeConfigsarray工程ごとの実行の設定(stepId・runtimeConfig)。runtimeConfig の中身は保存した形のまま返ります
libraryBindingsarrayいつも空の配列
memoryOrgIdstring | nullいつも null
memoryJobIdstring | nullいつも null
agentOwnerUserIdstring | null置いた Agent の持ち主の利用者 ID
isSharedboolean | null置いた Agent を公開しているかどうか
runtimeKindstring | nullAgent の実行環境の種類
marketplaceAgentIdstring | nullマーケットプレイス版の登録 Agent の ID。それ以外は null
exclusiveToThisProjectboolean | nullこの Agent を置いているのがこのプロジェクトだけかどうか
digeststring配置を変える API(担当工程・巡回)で baseDigest に送る値。担当工程・実行の設定・巡回から作られ、Agent の中身を変えても変わりません

GET/v1/projects/{projectId}/placements

プロジェクトの配置をすべて取得します。

レスポンスフィールド(200 OK)​

フィールド型説明
placementsarray配置の配列。1 件の項目は「配置の項目」を参照
hasMorebooleanいつも false

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId が UUID の形式ではない
403forbiddenシステム連携のトークンで呼び出した
403sso_required認証サーバーのアカウントと結び付いていない利用者
404project_not_foundプロジェクトが存在しない、またはメンバーではない

GET/v1/projects/{projectId}/placements/{placementId}

配置を 1 件取得します。

レスポンスフィールド(200 OK)​

フィールド型説明
placementobject配置。項目は「配置の項目」を参照

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId・placementId が UUID の形式ではない
403forbiddenシステム連携のトークンで呼び出した
403sso_required認証サーバーのアカウントと結び付いていない利用者
404placement_not_found配置が存在しない、ほかのプロジェクトの配置、またはメンバーではないプロジェクト

GET/v1/projects/agent-candidates

工程に置ける登録 Agent の一覧を取得します。返る marketplaceAgentId を、配置を置く API(POST /v1/projects/{projectId}/placements)に指定します。有効な登録 Agent を、表示名の順に全件返します。

  • project_type が "workflow" のときは、ワークフローの定義を持つ登録 Agent が返ります。workflow のプロジェクトに置けるのは、certified が true の登録 Agent だけです。
  • project_type が "cycle" のときは、有効な登録 Agent が全部返ります(certified・certificationProblem は null)。

クエリパラメータ​

パラメータ型デフォルト説明
project_typestring"workflow"置くプロジェクトの型。"workflow" または "cycle"

レスポンスフィールド(200 OK)​

フィールド型説明
candidatesarray置ける登録 Agent の配列
candidates[].marketplaceAgentIdstring | null登録 Agent の ID。配置を置く API に指定します
candidates[].displayNamestring | null表示名
candidates[].descriptionstring | null説明
candidates[].iconUrlstring | nullアイコンの URL
candidates[].tagsarrayタグの配列
candidates[].certifiedboolean | nullワークフローで使うための認定があるかどうか("workflow" のときだけ)
candidates[].certificationProblemstring | null認定が無い理由のコード。認定があるときと、"cycle" のときは null

エラーレスポンス​

ステータスcode説明
400invalid_parameterproject_type が "workflow"・"cycle" のどちらでもない
403forbiddenシステム連携のトークンで呼び出した
403sso_required認証サーバーのアカウントと結び付いていない利用者

POST/v1/projects/{projectId}/placements

登録 Agent を、プロジェクトの工程に置きます。オーナーだけが呼べます。置く登録 Agent は、置ける Agent の候補(GET /v1/projects/agent-candidates)の marketplaceAgentId で指定します。

リクエストボディ​

フィールド型必須説明
marketplaceAgentIdstring必須置く登録 Agent の ID(置ける Agent の候補の marketplaceAgentId。1〜100 文字。前後の空白は除きます)
stepIdsarray—担当工程の ID の配列(このプロジェクトの工程を 12 個まで)。省くと担当工程なしで置きます
  • 同じ Agent がすでに置いてあるときは 409 Conflict(placement_already_exists)です。担当工程まで同じときは、送り直しとして、置いてある配置を返します。担当工程を変えるときは、配置の担当工程を変える API を使います。
  • agentId は送れません(送ると 400 Bad Request(invalid_parameter))。
  • 新しく置いた配置は、配置の並び(displayOrder)の最後に入ります。ただし、前に外した配置(過去のワークフローの実行が使っていたため残っている配置)と同じ Agent を置くと、その配置が元の ID と並びの位置で戻ります。同じ工程の配置を 1 つずつ実行するときは、この並びの順に動きます。配置を並べ替える API はありません。

レスポンス(201 Created)​

フィールド型説明
placementobject置いた配置。項目は「配置の項目」を参照

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId が UUID の形式ではない、marketplaceAgentId が無い・空・100 文字を超える、agentId を送った、または stepIds の誤り(12 個を超える、このプロジェクトの工程ではない、同じ工程を重ねた など)
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
400agent_not_foundmarketplaceAgentId の登録 Agent が存在しない、または有効ではない
400agent_not_certifiedworkflow のプロジェクトに、ワークフローで使うための認定が無い登録 Agent を指定した
400lanes_not_for_marketplaceレーンのあるプロジェクトに登録 Agent を置こうとした
403forbiddenシステム連携のトークンで呼び出した
403owner_onlyオーナーではないメンバー
403sso_required認証サーバーのアカウントと結び付いていない利用者
404project_not_foundプロジェクトが存在しない、またはメンバーではない
409placement_already_exists同じ Agent がすでに置いてある(担当工程が違う)
413body_too_largeボディが 16 KiB を超える
415unsupported_media_typeボディの Content-Type が application/json ではない

DELETE/v1/projects/{projectId}/placements/{placementId}

配置を外します。オーナーだけが呼べます。過去のワークフローの実行が使った配置は、記録のために残ります(historyKept が true)。外した配置の過去の実行は、実行履歴に元の配置の ID(placementId)のまま残ります。

レスポンス(200 OK)​

フィールド型説明
placementIdstring外した配置の ID
deletedbooleanいつも true
historyKeptboolean記録のために配置を残したかどうか

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId・placementId が UUID の形式ではない
403forbiddenシステム連携のトークンで呼び出した
403owner_onlyオーナーではないメンバー
403sso_required認証サーバーのアカウントと結び付いていない利用者
404placement_not_found配置が存在しない、ほかのプロジェクトの配置、またはメンバーではないプロジェクト

PUT/v1/projects/{projectId}/placements/{placementId}/steps

配置の担当工程を、送った工程で置き換えます。オーナーだけが呼べます。外れた工程の巡回は止まります。空の配列も送れます(配置はプロジェクトに残りますが、どの工程も担当しないので動きません)。

リクエストボディ​

フィールド型必須説明
baseDigeststring必須その配置の digest
stepIdsarray必須担当工程の ID の配列(このプロジェクトの工程を 12 個まで)

レスポンス(200 OK)​

フィールド型説明
placementobject変えた後の配置(新しい digest)

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId・placementId が UUID の形式ではない、baseDigest が無い・空・文字列ではない、または stepIds の誤り(12 個を超える、このプロジェクトの工程ではない、同じ工程を重ねた など)
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
403forbiddenシステム連携のトークンで呼び出した
403owner_onlyオーナーではないメンバー
403sso_required認証サーバーのアカウントと結び付いていない利用者
404placement_not_found配置が存在しない、ほかのプロジェクトの配置、またはメンバーではないプロジェクト
409stale_base取得した後に配置が変わっている
413body_too_largeボディが 16 KiB を超える
415unsupported_media_typeボディの Content-Type が application/json ではない

PATCH/v1/projects/{projectId}/placements/{placementId}/schedule

cycle のプロジェクトで、配置の巡回を止める・再開する・周期を変えます。送った項目だけを変えます。オーナーだけが呼べます。

リクエストボディ​

フィールド型必須説明
baseDigeststring必須その配置の digest
stepIdstring—巡回の工程の ID(配置の担当工程)。担当工程が 1 つの配置では省けます
enabledboolean—true で再開、false で停止
cronstring—周期(5 項目の cron 式。100 文字まで)
timezonestring—タイムゾーン(IANA のタイムゾーン名。64 文字まで。例: "Asia/Tokyo")
  • enabled・cron・timezone のうち、少なくとも 1 つを送ってください。送らなかった項目は今の値のままです。
  • その工程にまだ巡回が無いとき(初めて設定するとき)は cron が必須です。enabled を省くと止めたまま、timezone を省くと UTC になります。

レスポンス(200 OK)​

フィールド型説明
placementobject変えた後の配置(新しい digest)

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId・placementId・stepId が UUID の形式ではない、baseDigest が無い・空・文字列ではない、変える項目が無い、enabled・cron・timezone の型の誤り、cron が cron 式として正しくないか 100 文字を超える、timezone が空白だけ・タイムゾーンとして正しくない・64 文字を超える、workflow のプロジェクト、stepId が必要なのに無い、または初めて設定するのに cron が無い
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
400step_not_foundstepId が、この配置の担当工程ではない
403forbiddenシステム連携のトークンで呼び出した
403owner_onlyオーナーではないメンバー
403sso_required認証サーバーのアカウントと結び付いていない利用者
404placement_not_found配置が存在しない、ほかのプロジェクトの配置、またはメンバーではないプロジェクト
409stale_base取得した後に配置が変わっている
409principalプロジェクトの実行の主体(作った利用者)を確かめられない
409not_marketplace登録 Agent の配置ではない(周期を持てるのは登録 Agent の配置だけ)
413body_too_largeボディが 16 KiB を超える
415unsupported_media_typeボディの Content-Type が application/json ではない

トリガー​

cycle のプロジェクトで、Webhook のトリガーを発火すると、トリガーに結び付いた配置を臨時に 1 回動かします。トリガーの ID は、プロジェクトの取得の triggers で読めます。トリガーを足す・変える・消すのは画面で行います。

エンドポイント一覧​

メソッドエンドポイント説明
POST/v1/projects/{projectId}/triggers/{triggerId}/fireトリガーを発火して臨時に 1 回実行

POST/v1/projects/{projectId}/triggers/{triggerId}/fire

cycle 型のプロジェクトに設定された Webhook トリガーを発火し、対象のエージェントを臨時に 1 回だけ実行します。workflow 型に対して呼び出すと 404 Not Found が返ります。

定期実行の設定はそのまま維持されます。発火による実行は、定期実行とは別に追加されるものです。発火は 1 件ずつ別に受け付けられ、先の発火にまとまることはありません。同じエージェント配置の同じ工程への発火は、受け付けた順に 1 件ずつ処理されます。

パスパラメータ​

パラメータ型必須説明
projectIdstring必須プロジェクトの ID(UUID)
triggerIdstring必須発火するトリガーの ID(UUID)

リクエストボディ​

パラメータ型必須説明
eventIdstring必須送信側が採番する一意な ID。同じ ID の再送は重複として扱われます。1〜160 文字で、使用できる文字は半角英数字と _ . : @ + - です
payloadany—エージェントへ渡す任意の JSON。JSON の文字列にして、エージェントへの依頼に添えて渡されます。文字列にしたときに 8,000 文字を超える部分は省略されます

レスポンスフィールド(202 Accepted)​

フィールド型説明
resultstring"accepted"(新しく受け付けた)または "duplicate"(同じ eventId で受付済み)
jobIdstring受付先のジョブ ID。エージェント配置と工程の組み合わせごとに決まり、同じ組み合わせへの発火では同じ値になります(発火ごとには変わりません)。実行状況の取得(GET /v1/projects/{projectId}/runs/{runId})には使えません

レスポンス例​

JSON
{
"result": "accepted",
"jobId": "9b2e4c61-0f3a-4a9b-9c1d-2f7e5a8b3c40"
}
202 の意味

ここでの 202 Accepted は、受付を記録したことだけを表します。実行はこの後に行われ、その成否はこの応答に含まれません。実行の結果は含まないため、202 を業務上の成功として扱わないでください。

再送​

冪等性はプロジェクト・トリガー・eventId の組み合わせで判定されます。同じ内容で再送すると 202 と result: "duplicate" が返ります。同じ eventId で payload が異なる場合は 409 Conflict(event_conflict)が返ります。

エラーレスポンス​

ステータスcode説明
400invalid_event_ideventId が無い、または形式が不正
400invalid_parameterprojectId または triggerId が UUID の形式ではない
400invalid_bodyリクエストボディが壊れた JSON、または JSON のオブジェクトではない
415unsupported_media_typeリクエストボディがあるのに、Content-Type が application/json ではない
403owner_onlyプロジェクトのメンバーだが、オーナーではない
404trigger_not_foundプロジェクト・トリガーが存在しない、アクセス権が無い、Webhook ではないトリガーを指定した、または workflow 型のプロジェクトを指定した
409trigger_disabledトリガーが無効化されている
409project_not_activeプロジェクトが実行可能な状態にない
409placement_unavailable発火対象のエージェント配置が存在しない、または実行できる状態にない
409event_conflict同じ eventId で payload が異なる
413body_too_largeリクエストボディが 16 KiB を超過
429queue_full同じエージェント配置の同じ工程で実行を待っている発火が上限(20 件)に達している

発火で動いた実行の見分け方​

実行履歴(GET /v1/projects/{projectId}/executions)は、発火の応答の jobId では絞り込めません。jobId は配置と工程の組み合わせごとに同じ値なので、実行の見分けにも使えません。発火は 1 回ごとに別の実行になり、同じ配置では 1 つずつ動きます。実行履歴を、トリガーの配置(placementId)と、発火した時刻(from)で絞り込んで見分けます。

ワークフローの実行(run)​

ワークフローの実行(run)は、workflow のプロジェクトで工程を順に進める 1 件です。cycle のプロジェクトはワークフローの実行を作りません(cycle の実行は実行履歴で読みます)。

エンドポイント一覧​

メソッドエンドポイント説明
POST/v1/projects/{projectId}/runsワークフローの実行を開始
GET/v1/projects/{projectId}/runs/{runId}ワークフローの実行を取得
GET/v1/projects/{projectId}/runsワークフローの実行の一覧を取得
GET/v1/projects/{projectId}/runs/{runId}/configワークフローの実行を始めたときの設定を取得
PATCH/v1/projects/{projectId}/runs/{runId}ワークフローの実行の締め切りを決める・外す
PUT/v1/projects/{projectId}/runs/{runId}/approversワークフローの実行の確認担当者を付け替える
GET/v1/projects/{projectId}/artifactsワークフローの実行の成果物の一覧を取得
GET/v1/projects/{projectId}/artifacts/{artifactId}/content成果物の中身を取得

POST/v1/projects/{projectId}/runs

workflow 型のプロジェクトの実行を開始します。cycle 型に対して呼び出すと 409 Conflict(unsupported_project_type)が返ります。

リクエストヘッダー​

ヘッダー必須説明
Idempotency-Key必須呼び出し側が採番する重複実行の防止キー。8〜128 文字で、使用できる文字は半角英数字と _ . : - です

パスパラメータ​

パラメータ型必須説明
projectIdstring必須プロジェクトの ID(UUID)

リクエストボディ​

ボディは省けます。送信する場合は JSON のオブジェクトにしてください。下のフィールドのほかは無視されます。

パラメータ型必須説明
payloadany—実行の依頼。JSON の値(オブジェクト・配列・文字列など)を、中身を変えずに受け取ります。最初の工程のエージェントが context.start_input で受け取ります(マーケットプレイスのワークフローガイドの「外から始めた run の依頼」を参照)。依頼の中にファイルの ID を入れても、ファイルは添付されません。省略・null は依頼なし。JSON の文字列にして 8,000 文字まで

上限は 2 つあります。payload を JSON の文字列にした長さが 8,000 文字を超えると 400 Bad Request(payload_too_large)、ボディ全体が 16 KiB を超えると 413 Payload Too Large(body_too_large)が返ります。

レスポンスフィールド(201 Created / 200 OK)​

フィールド型説明
runIdstring実行の ID(UUID)。実行状況の取得に使用します
existingboolean?同じ Idempotency-Key での再送により既存の実行を返した場合に true。初回は含まれません

初回の呼び出しは 201 Created、同じ Idempotency-Key での再送は 200 OK が返ります。

リクエスト例​

curl
curl -X POST https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/runs \
-H "Authorization: Bearer <access_token>" \
-H "Idempotency-Key: nightly-batch-20260917" \
-H "Content-Type: application/json" \
-d '{"payload": {"ticketId": "INC-1024", "summary": "ログインできない利用者がいる"}}'

レスポンス例​

JSON
{
"runId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
Idempotency-Key の扱い
  • キーはプロジェクト単位で照合されます。有効期限はありません。
  • 同じキーで再送すると、プロジェクトが停止した後・同時実行の上限に達した後・その実行が終了した後であっても、同じ実行が返ります。
  • タイムアウトなどで成否が分からなくなった場合は、同じキーでそのまま再送してください。二重に実行されることはありません。
  • 別の実行を開始したい場合は、必ず新しいキーを採番してください。

同じキーで、違う payload を付けて再送すると 409 Conflict(origin_conflict)が返ります。

エラーレスポンス​

ステータスcode説明
400idempotency_key_requiredIdempotency-Key ヘッダーが無い
400idempotency_key_invalidIdempotency-Key の長さまたは文字種が不正
400invalid_parameterprojectId が UUID の形式ではない
400payload_too_largepayload を JSON の文字列にした長さが 8,000 文字を超える
400invalid_bodyリクエストボディが壊れた JSON、または JSON のオブジェクトではない
413body_too_largeリクエストボディが 16 KiB を超過
415unsupported_media_typeリクエストボディがあるのに、Content-Type が application/json ではない
403owner_onlyプロジェクトのメンバーだが、オーナーではない
404project_not_foundプロジェクトが存在しない、またはアクセス権が無い
400approvers_required有効な確認工程に確認担当者が設定されていない
409unsupported_project_typecycle 型のプロジェクトを指定した
409project_inactiveプロジェクトが有効な状態ではない(一時停止中、またはアーカイブ済み)
409mixed_runtime登録した Agent と、それ以外のエージェントが同じプロジェクトに置かれている
409agent_not_certified置いた登録 Agent に、ワークフローで使うための認定が無い
409lanes_not_for_marketplaceプロジェクトの流れにレーンがある(登録 Agent のプロジェクトはレーンで進められません)
400invalid_parameter開始の入力の値が正しくない
400missing_input工程が必要とする入力ファイルが無い(前の工程が出していない、または指定していない)
400duplicate_target_path同じ置き先のパスに、2 つ以上の入力ファイルを置こうとしている
400mp_placement_not_in_snapshot工程の登録 Agent が、実行を始めたときの構成に含まれていない
400connection_version_missing接続のバージョンが保存されていない
400invalid_runtime_config配置の実行の設定が、登録 Agent の定義に合わない
400input_binding_cycle入力の受け渡しが循環している
400input_binding_forward_referenceまだ動いていない後の工程の出力を、入力に指定している
400input_binding_unknown_output入力に指定した出力が、元の登録 Agent に無い
400artifact_format_mismatch入力に指定した成果物の形式が、求める形式と違う
400artifact_digest_missing入力に指定した成果物に digest が無い
400invalid_config設定が、登録 Agent の定義に合わない
409artifact_not_ready入力に指定した成果物が、まだ使える状態ではない(または確認した内容と違う)
409origin_conflict同じ Idempotency-Key で、違う payload を送った(同じ起点が、違う中身で使われている)
409connection_version_unavailable接続のバージョンを確かめられない(承認した後に、接続の対象または権限が変わった)
429too_many_active_runs同じプロジェクトで、実行中と確認待ちの実行が合わせて上限(3 件)に達している

GET/v1/projects/{projectId}/runs/{runId}

実行の状況を取得します。API(POST /v1/projects/{projectId}/runs)で開始した実行のほか、画面・定期実行で始まった実行も取得できます。cycle 型のプロジェクトは実行(run)を作らないため、このエンドポイントの対象外です。

パスパラメータ​

パラメータ型必須説明
projectIdstring必須プロジェクトの ID(UUID)
runIdstring必須実行の ID(UUID)

レスポンスフィールド(200 OK)​

フィールド型説明
runIdstring実行の ID(UUID)
statusstring実行の状態。"running"(実行中)/ "waiting_gate"(確認待ち)/ "closed_done"(完了)/ "closed_rejected"(却下で終了)/ "closed_failed"(失敗で終了)/ "cancelled"(中断)のいずれか。"running" と "waiting_gate" 以外は、実行が終わったことを表します
originTypestring | null実行の始まり方。"manual"(画面から開始)/ "api"(API で開始)/ "cron"(定期実行)のいずれか
originRefstring | null始まり方ごとの参照値。API で開始した実行では、開始したときの Idempotency-Key の値
currentStepIdstring | null進んでいる工程の ID(UUID)。完了した実行では null。ほかの理由で終わった実行では、終わったときの工程の ID が残る場合があります
startedByRefstring | null実行を始めたもの。値は下の「実行を始めたもの」の表のとおり
actorLabelstring | null利用者ではない起動者の表示名(サービスアカウントの名前)。分からない場合と、それ以外は null
startedAtstring | null開始日時(ISO 8601)。開始前は null
endedAtstring | null終了日時(ISO 8601)。終了前は null
summarystring | null完了した実行で、出力が記録された最後の完了した工程の出力(先頭 2,000 文字)。そうした工程が無い場合と、完了していない実行では null
runtimeKindstring | null実行環境の種類。"marketplace"(登録した Agent で動く実行)または "autonomous"。古い実行では null の場合があります
cancelRequestedAtstring | null中断が求められた日時(ISO 8601)。求められていなければ null
deadlineAtstring | nullワークフローの実行の締め切り(ISO 8601)。締め切りが無ければ null
configRevisionnumber | null案件設定のバージョン。登録した Agent で動く実行で使い、それ以外の実行では null
stepsarray工程ごとの実行の記録。記録した順
steps[].runStepIdstring工程の実行の ID("rs:" で始まる)
steps[].stepIdstring | null工程の ID(UUID)
steps[].placementIdstring | nullその工程を担当した配置の ID(UUID)。Agent を動かさない行(確認の工程など)では null
steps[].executionIdstring | nullAgent の実行の ID。Agent を動かし始めると付きます
steps[].conversationIdstring | nullAgent の実行の会話の ID。登録した Agent で動く実行では null
steps[].statusstring"pending"(実行待ち)/ "running"(実行中)/ "waiting_gate"(確認待ち)/ "done"(完了)/ "failed"(失敗)/ "skipped"(実行を省略)のいずれか
steps[].attemptnumber | null同じ回の中での再試行の回数(1 から)
steps[].lanestring | nullいつも "main"
steps[].scheduledAtstring | null工程に時刻が設定されているとき、その時刻まで待つ行の予定日時(ISO 8601)。動き始めると null
steps[].startedAtstring | null開始日時(ISO 8601)
steps[].endedAtstring | null終了日時(ISO 8601)
steps[].outputSummarystring | null工程の出力の要約
steps[].outcomestring | nullAgent の実行の結果。"completed" / "incomplete" / "failed" / "timeout" / "stopped" / "denied" / "skipped" のいずれか。結果の無い行では null
steps[].reasonCodestring | null結果の理由コード
steps[].heldbooleanプロジェクトの一時停止で止めていて、再開を待っているか
steps[].visitnumber | nullこの工程に来た何回目か(差し戻しで増えます)。記録の無い行では null
steps[].reworkReasonstring | null差し戻しの理由
steps[].gateForstring | nullこの確認の行が、どの工程の実行(runStepId)のために立ったか
steps[].routedFromstring | null行き先を決めて工程を飛ばしたとき、行き先を決めた工程の実行(runStepId)
steps[].latestring | null結果が遅れて届き、進行に使わなかった理由
steps[].gateobject | null確認の要約。確認の工程の行に付きます。それ以外の行では null
steps[].gate.decisionstring | null"proceed"(進める)/ "send_back"(差し戻す)/ "reject"(却下)のいずれか。決まっていなければ null
steps[].gate.waitSourcestring | null何を待つ確認か。"human"(人の判断)/ "external"(外部の条件)
steps[].resumeCommandIdstring | nullいつも null
steps[].resumeReasonstring | nullいつも null
steps[].supersededBystring | nullいつも null
steps[].gateKindstring | nullいつも null
steps[].connectionConfirmOfstring | nullいつも null
plannedPlacementsarray開始したときの設定で、動く予定の工程と配置の並び
plannedPlacements[].stepIdstring | null工程の ID(UUID)
plannedPlacements[].placementIdstring | null配置の ID(UUID)。確認の工程と Agent の無い工程では null
lanesarrayいつも空の配列

項目は、呼び出しに使ったトークン(アプリケーションかシステム連携か)によらず同じです。

実行を始めたもの​
始めたものstartedByRefactorLabel
利用者(画面・API から開始)利用者 IDnull
サービスアカウント"client:" に続くサービスアカウントのクライアント IDサービスアカウントの名前(分からない場合は null)
定期実行nullnull

2026-09-25 より前にサービスアカウントが始めた実行では、startedByRef は null です。

レスポンス例​

JSON
{
"runId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "running",
"originType": "api",
"originRef": "nightly-batch-20260917",
"currentStepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
"startedByRef": "client:order-batch",
"actorLabel": null,
"startedAt": "2026-09-17T01:30:00.000Z",
"endedAt": null,
"summary": null,
"runtimeKind": "marketplace",
"cancelRequestedAt": null,
"deadlineAt": null,
"configRevision": 1,
"steps": [
{
"runStepId": "rs:1042",
"stepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
"placementId": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8",
"executionId": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
"conversationId": null,
"status": "running",
"attempt": 1,
"lane": "main",
"scheduledAt": null,
"startedAt": "2026-09-17T01:30:01.000Z",
"endedAt": null,
"outputSummary": null,
"outcome": null,
"reasonCode": null,
"held": false,
"visit": 1,
"reworkReason": null,
"gateFor": null,
"routedFrom": null,
"late": null,
"gate": null,
"resumeCommandId": null,
"resumeReason": null,
"supersededBy": null,
"gateKind": null,
"connectionConfirmOf": null
}
],
"plannedPlacements": [
{ "stepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f", "placementId": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8" },
{ "stepId": "c2f1a8e4-6b3d-4e7a-9c15-8d2e4f6a7b90", "placementId": null }
],
"lanes": []
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId または runId が UUID の形式ではない
404run_not_found実行が存在しない、別のプロジェクトの実行を指定した、またはアクセス権が無い

GET/v1/projects/{projectId}/runs

ワークフローの実行の一覧を、開始の新しい順に取得します。新しい方から 100 件までで、続き(cursor)は読めません。cycle のプロジェクトでは空の一覧です。

クエリパラメータ​

パラメータ型デフォルト説明
limitinteger50取得件数(1-100)
placement_idstring—この配置が担当した工程のあるワークフローの実行に絞り込み(UUID)

レスポンスフィールド(200 OK)​

フィールド型説明
runsarrayワークフローの実行の配列。1 件の項目は、ワークフローの実行の取得(GET /v1/projects/{projectId}/runs/{runId})と同じです
hasMorebooleanlimit が 99 以下のときは、ほかにもあるかどうか。limit が 100 のときは、100 件そろえば true(ほかにもあるとは限りません)

100 件より古いワークフローの実行は、この一覧では読めません。実行履歴(GET /v1/projects/{projectId}/executions。続きを読めます)で runId を知り、ワークフローの実行の取得(GET /v1/projects/{projectId}/runs/{runId})で読みます。実行履歴には、始まっていない工程と確認待ちの工程は出ないため、どの工程も始まっていない古いワークフローの実行は見つけられません。

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId・placement_id が UUID の形式ではない、placement_id と placementId に違う値を指定した、または limit が 1-100 の整数でない
403forbiddenシステム連携のトークンで呼び出した
403sso_required認証サーバーのアカウントと結び付いていない利用者
404project_not_foundプロジェクトが存在しない、またはメンバーではない

GET/v1/projects/{projectId}/runs/{runId}/config

ワークフローの実行を始めたときの設定(工程・配置・連携先)を取得します。その後にプロジェクトの設定を変えても、この内容は変わりません(連携先の connectionId だけは、今の連携先の情報から求めます)。

レスポンスフィールド(200 OK)​

フィールド型説明
runIdstringワークフローの実行の ID
takenAtstring | null設定を写した日時(ISO 8601)
stepsarray | null当時の工程。項目は「工程の項目」と同じです(digest を除きます。写しに無い項目は null)
lanesarray | null"main" の 1 本に全部の工程が入ります(name は null)
forksarray | nullいつも空の配列
joinsarray | nullいつも空の配列
placementsarray | null当時の配置(placementId・agentId・name・goal・guardrail・skills・playbookId・playbookName・runtimeConfigs・libraryBindings・sweeps・stepIds)。runtimeConfigs・libraryBindings は配置の項目と同じ形。goal・guardrail・skills・playbookId は始めたときの値。libraryBindings はいつも空の配列。goal・guardrail・playbookId・playbookName はいつも null、skills はいつも空の配列
connectorsarray | null当時の連携先(kind・connectionId・name・ledgerEnabled)。name は始めたときの名前。connectionId は今の連携先の情報から求めます(管理画面で無効にされた・削除された、または確かめられなかったときは null)
sendBackLimitnumber | null差し戻せる回数の上限

設定の写しが無いワークフローの実行と、写しを読めないワークフローの実行では、runId 以外が null です。

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId・runId が UUID の形式ではない
403forbiddenシステム連携のトークンで呼び出した
403sso_required認証サーバーのアカウントと結び付いていない利用者
404run_not_foundワークフローの実行が存在しない、ほかのプロジェクトのもの、cycle のプロジェクト、またはメンバーではないプロジェクト

PATCH/v1/projects/{projectId}/runs/{runId}

ワークフローの実行の締め切りを決める、または外します。締め切りを過ぎると、キューに締め切りを過ぎたワークフローの実行の行(run_deadline_overdue)が出ます。オーナーだけが呼べます。変えられるのは、終わっていないワークフローの実行(status が "running"・"waiting_gate")だけです。

パスパラメータ​

パラメータ型必須説明
projectIdstring必須プロジェクト ID(UUID)
runIdstring必須ワークフローの実行の ID(UUID)

リクエストボディ​

フィールド型必須説明
deadlineAtstring | null必須締め切り(ISO 8601 の日時。今より後)。null で締め切りを外します

同じ値で送り直すと、同じ結果になります。

レスポンスフィールド(200 OK)​

変えた後のワークフローの実行です。項目は、ワークフローの実行の取得(GET /v1/projects/{projectId}/runs/{runId})と同じです。

締め切りを変えた後の読み直しに失敗すると、502 Bad Gateway(upstream_connection_error)が返ります。締め切りは変わっていることがあるので、送り直す前に、ワークフローの実行の取得で deadlineAt を確かめてください。

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId・runId が UUID の形式ではない、または deadlineAt が無い・ISO 8601 の日時ではない・今より後ではない
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
403forbiddenシステム連携のトークンで呼び出した
403owner_onlyオーナーではないメンバー
403sso_required認証サーバーのアカウントと結び付いていない利用者
404run_not_foundワークフローの実行が存在しない、ほかのプロジェクトのもの、cycle のプロジェクト、またはメンバーではないプロジェクト
409invalid_stateワークフローの実行が終わっている
413body_too_largeボディが 16 KiB を超える
415unsupported_media_typeボディの Content-Type が application/json ではない
502upstream_connection_error締め切りを変えた後の読み直しに失敗した(送り直す前に、ワークフローの実行の取得で確かめてください)

PUT/v1/projects/{projectId}/runs/{runId}/approvers

ワークフローの実行の、まだ判断されていない確認依頼の確認担当者を、まとめて置き換えます。オーナーだけが呼べます。変えられるのは、終わっていないワークフローの実行だけです。確認依頼の通知は、新しく担当になった人にだけ届きます。

パスパラメータ​

パラメータ型必須説明
projectIdstring必須プロジェクト ID(UUID)
runIdstring必須ワークフローの実行の ID(UUID)

リクエストボディ​

フィールド型必須説明
approverUserIdsarray必須新しい確認担当者の利用者 ID の配列(1〜50 人。今のプロジェクトのメンバーだけ。1 つは 128 文字まで。同じ人は 1 度だけ)
commandIdstring必須送り直しを見分ける値(英数字と _ . : - の 8〜128 文字)
  • 同じ commandId で同じ確認担当者を送り直すと、1 回目と同じ結果が返ります。同じ commandId で違う確認担当者を送ると 409 Conflict(command_conflict)です。
  • 確認担当者か対象の確認依頼がとても多い付け替え(例: 確認担当者 50 人)では、同じ commandId で送り直したときに確認担当者を比べられず、1 回目の結果として 200 が返り、workItemIds が空になることがあります。結果は、ワークフローの実行の取得と確認依頼の取得で確かめてください。

レスポンスフィールド(200 OK)​

フィールド型説明
runIdstringワークフローの実行の ID
approverUserIdsarray置き換えた後の確認担当者の利用者 ID(送った値)
workItemIdsarray確認担当者を置き換えた確認依頼の ID

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId・runId が UUID の形式ではない、approverUserIds が 1〜50 個の利用者 ID の配列ではない(空の ID・128 文字を超える ID を含む)・同じ人を 2 度含む、または commandId が無い・形の誤り
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
400approver_not_memberapproverUserIds に、今のプロジェクトのメンバーではない人がいる
403forbiddenシステム連携のトークンで呼び出した
403owner_onlyオーナーではないメンバー
403sso_required認証サーバーのアカウントと結び付いていない利用者
404run_not_foundワークフローの実行が存在しない、ほかのプロジェクトのもの、cycle のプロジェクト、またはメンバーではないプロジェクト
409invalid_stateワークフローの実行が終わっている
409command_conflict同じ commandId で違う確認担当者を送った
413body_too_largeボディが 16 KiB を超える
415unsupported_media_typeボディの Content-Type が application/json ではない

GET/v1/projects/{projectId}/artifacts

ワークフローの実行の工程が作った成果物の一覧を、作られた順に全件取得します。中身は、成果物の中身の取得(GET /v1/projects/{projectId}/artifacts/{artifactId}/content)で読みます。プロジェクトのメンバーだけが読めます。

パスパラメータ​

パラメータ型必須説明
projectIdstring必須プロジェクト ID(UUID)

クエリパラメータ​

パラメータ型デフォルト説明
run_idstring—必須。ワークフローの実行の ID(UUID)

レスポンスフィールド(200 OK)​

フィールド型説明
artifactsarray成果物の配列
artifacts[].artifactIdstring | null成果物の ID(UUID)
artifacts[].runIdstring | nullワークフローの実行の ID
artifacts[].namestring | null成果物の名前
artifacts[].mimeTypestring | null成果物の MIME タイプ
artifacts[].sizenumber | null大きさ(バイト)
artifacts[].statusstring | null"ready"(読める)または "uploading"(書き終わっていない)
artifacts[].createdAtstring | null作られた日時(ISO 8601)

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId が UUID の形式ではない、または run_id が無い・UUID の形式ではない
403forbiddenシステム連携のトークンで呼び出した
403sso_required認証サーバーのアカウントと結び付いていない利用者
404project_not_foundプロジェクトが存在しない、またはメンバーではない
404run_not_foundワークフローの実行が存在しない、またはほかのプロジェクトのもの

GET/v1/projects/{projectId}/artifacts/{artifactId}/content

成果物の中身を取得します。HEAD でも呼べます。本文を除いて同じヘッダーが返るので、先に大きさを確かめられます。GET で読むと、記録 (証跡) に閲覧(forensic.viewed)が残ります(HEAD では残りません)。

パスパラメータ​

パラメータ型必須説明
projectIdstring必須プロジェクト ID(UUID)
artifactIdstring必須成果物の ID(UUID)。成果物の一覧の artifactId

レスポンス(200 OK)​

成果物の中身が、そのまま返ります。

レスポンスヘッダー説明
Content-Type成果物の MIME タイプ
Content-Length大きさ(バイト)
X-Content-Type-Options"nosniff"
Content-Disposition"attachment"(ダウンロードとして返します)

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId・artifactId が UUID の形式ではない
403forbiddenシステム連携のトークンで呼び出した
403sso_required認証サーバーのアカウントと結び付いていない利用者
404project_not_foundプロジェクトが存在しない、またはメンバーではない
404artifact_not_found成果物が存在しない、ほかのプロジェクトのもの、またはワークフローの実行の成果物ではない
409artifact_not_ready成果物がまだ書き終わっていない

実行​

実行は、Agent の 1 回の処理です。画面の実行履歴に並び、開くと実行記録になります(何も変わらなかった巡回が続くと、画面では 1 行にまとめて出ます。この API はまとめずに 1 件ずつ返します)。workflow の工程の実行(kind が "run_step"。executionId は rs:<数値> の形)と、cycle の巡回の実行("sweep"。executionId は UUID)があります。

エンドポイント一覧​

メソッドエンドポイント説明
GET/v1/projects/{projectId}/executions実行履歴を取得
GET/v1/projects/{projectId}/executions/{executionId}実行の結果を取得
GET/v1/projects/{projectId}/executions/{executionId}/operationsツールの呼び出しの一覧を取得
GET/v1/projects/{projectId}/executions/{executionId}/timeline実行の時系列を取得

結果の値​

outcome(結果)の値です。画面の表示は結果リファレンスを参照してください。

値画面の表示
completed完了
incomplete失敗 (Agent の報告)
failed失敗
timeout時間切れ
stopped失敗 (停止)
deniedルールにより実行不可
skipped対象なし

まだ終わっていない実行と、終わったのに結果が記録されていない実行(記録不足)は、outcome が null です。

GET/v1/projects/{projectId}/executions

実行履歴を、開始時刻の新しい順に取得します。カーソルベースのページネーションに対応しています。始まっていない工程と、確認待ちの工程は含まれません。

クエリパラメータ​

パラメータ型デフォルト説明
fromstring—この日時以降に始まった実行に絞り込み(ISO 8601)
tostring—この日時以前に始まった実行に絞り込み(ISO 8601)
placement_idstring—この配置の実行に絞り込み(UUID)
step_idstring—この工程の実行に絞り込み(UUID)
run_idstring—このワークフローの実行の工程の実行に絞り込み(UUID)
outcomestring"all"結果で絞り込み。結果の値のほか、"all"(すべて)/ "success"(completed)/ "problems"(incomplete・failed・timeout・stopped・denied)/ "running"(実行中)/ "missing"(記録不足)/ "unmeasured"(完遂を測っていない終わり方)
fix_targetstring—直す先で絞り込み。"goal" / "skill" / "handoff" / "not_assigned" / "connection" / "rule" / "guardrail" / "external" / "unknown"(実行の結果の envelope.completionReport.fixTarget の値)、または "platform"(基盤側の失敗のある実行)
reason_codestring—結果の理由(executions[].reasonCode)が一致する実行に絞り込み。大文字と小文字を区別します。英字で始まり、英数字と _ . : - の 64 文字まで(前後の空白は除きます。空なら絞り込みません)
qstring—Agent 名・実行の UUID・会話 ID の一部で絞り込み(200 文字まで)。cycle の実行は executionId で探せます。workflow の工程の実行は rs:<数値> では探せないので、ワークフローの実行の steps[].executionId(UUID)で探します
limitinteger501 ページの取得件数(1-100)
cursorstring—次ページ取得用カーソル(前回レスポンスの cursor 値)

レスポンスフィールド(200 OK)​

フィールド型説明
executionsarray実行の配列
executions[].executionIdstring実行の ID。workflow は rs:<数値>、cycle は UUID
executions[].kindstring | null"run_step"(workflow の工程)または "sweep"(cycle の巡回)
executions[].runIdstring | nullワークフローの実行の ID。cycle は null
executions[].stepIdstring | null工程の ID
executions[].stepNamestring | null工程の名前
executions[].stepPositionnumber | null工程の位置
executions[].placementIdstring | null配置の ID
executions[].agentNamestring | nullAgent の名前
executions[].attemptnumber | null試行の回数(基盤の失敗でやり直すと増えます。cycle は起動し直すと新しい実行になり、増えません)
executions[].lanestring | nullレーンの ID(workflow。レーンが無いときは "main")
executions[].outcomestring | null結果(上の「結果の値」)
executions[].reasonCodestring | null結果の理由。cycle は実行の終わり方の理由(例: "guardrail_blocked")、workflow は工程の報告の理由
executions[].resultStatestring | null"terminal"(結果あり)/ "running"(実行中)/ "missing"(記録不足)/ "unmeasured"(完遂を測っていない)/ "not_applicable"(確認工程など、Agent の実行ではない行)
executions[].terminalboolean | null終わっているかどうか
executions[].startedAtstring | null開始日時(ISO 8601)
executions[].endedAtstring | null終了日時(ISO 8601)
executions[].summarystring | nullworkflow の工程の最終応答(2000 文字まで)。cycle は null(実行の結果で読みます)
executions[].errorMessagestring | nullエラーのメッセージ(cycle)
executions[].originTypestring | null始まり方。workflow はワークフローの実行の始まり方("manual" / "api" / "cron")、cycle は "cron"(巡回)または "webhook"(トリガーの発火)
executions[].actorLabelstring | null利用者ではない起動者の表示名(サービスアカウントの名前)
executions[].gateDecisionstring | null確認工程の決定
executions[].conversationIdstring | null実行の会話の ID(実行の会話を読むときに使います)
executions[].fixTargetstring | null直す先(実行の結果の envelope.completionReport.fixTarget と同じ値)。無いときは null
executions[].platformFailurestring | null基盤側の失敗の種類(実行の結果の envelope.platformFailure と同じ値)。無いときは null
executions[].rerunOfstring | nullいつも null
hasMoreboolean次のページが存在するかどうか
cursorstring次ページ取得用カーソル。hasMore が true の場合のみ含まれます

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId・placement_id・step_id・run_id が UUID の形式ではない、snake_case と前の名前に違う値を指定した、from・to が ISO 8601 の日時ではない、outcome・fix_target が上の値ではない、reason_code が理由の形ではない・2 回以上指定した、q が 200 文字を超える、limit・cursor が不正
403forbiddenシステム連携のトークンで呼び出した
403sso_required認証サーバーのアカウントと結び付いていない利用者
404project_not_foundプロジェクトが存在しない、またはメンバーではない

GET/v1/projects/{projectId}/executions/{executionId}

実行の結果(実行記録)を取得します。workflow の工程の実行は、実行履歴の rs:<数値> のほか、ワークフローの実行の steps[].executionId(UUID)でも読めます。応答の executionId は rs:<数値> です。

パスパラメータ​

パラメータ型必須説明
projectIdstring必須プロジェクト ID(UUID)
executionIdstring必須実行の ID(rs:<数値> または UUID)

レスポンスフィールド(200 OK)​

実行履歴の 1 件の項目に加えて、次の項目を返します。summary は、workflow は 2000 文字まで、cycle は会話の最後の本文をそのまま返します。

フィールド型説明
connectionConfirmOfstring | nullいつも null
envelopeobject | null実行の要約
envelope.countsobjectツールの呼び出しの数(toolCalls・readCalls・mutatingSuccess・mutatingFailed・unknownCalls・opaqueCalls・workspaceWrites・mcpCalls・mcpFailed)
envelope.completionReportobject | nullAgent の完了の報告(completed・reasonCode・fixTarget・comment・truncated)
envelope.completionReport.fixTargetstring | null直す先。"goal" / "skill" / "handoff" / "not_assigned" / "connection" / "rule" / "guardrail" / "external" / "unknown"。無いときは null
envelope.completionReport.commentstring | nullAgent のコメント(2 KB まで。切ったときは truncated が true)
envelope.platformFailurestring | null基盤側の失敗の種類(結果が failed・timeout のとき)。"cancelled" / "signal_cancelled" / "kill_timeout" / "exception" / "invalid_output" / "model_refusal" / "content_filter" / "max_turns" / "loop_limit"。無いときは null
envelope.toolsarray呼んだツールの名前
usedSettingsobject使った設定
usedSettings.manifestobject | null配ったスキル(スキル ID とバージョン ID)・プレイブック・ガードレールなど。実行の時系列の context.manifest の meta と同じで、項目名は記録のまま返ります
usedSettings.mcpobject | nullMCP の接続(設定・接続・失敗の数と名前など)。実行の時系列の runtime.mcp.connected の meta と同じ。MCP を使わない実行では null
questionsarrayAgent からの質問(eventId・at・kind・optionsCount・optionsTruncated・answer)
questions[].answerobject | null回答(at・eventType・actorKind・actorRef・digest・answerKind・optionIndex)。回答の記録が無ければ null
gatesarray確認依頼(workItemId・title・status・gateDecision・decidedAt・gateMode・decidedByKind・decidedByRef・waitSource・decisionReason・destinationLabel)
artifactsarray成果物(artifactId・name・path・format・sha256・size。本文は含みません)
filesarrayファイル(filename・filepath・source・isPrimary・createdAt・mimeType(分からないときは application/octet-stream)。分かるときは size)。会話の API の deliverables と同じ形。中身はファイルの中身の取得(GET /v1/projects/{projectId}/files/content)に filepath を path で渡して取る
configurationobject実行の設定(policyVersion・policyDigest・policyProfile・model・mcpConfigVersion)
requestobject依頼。workflow は originType・originRef・triggerId・scheduledAt・runStartedAt・reworkReason、cycle は cron・timezone・jobName・originKind
jobIdstring | nullジョブの ID。トリガーの発火の応答の jobId と照らせます
gateForstring | nullこの確認がどの失敗した工程の実行のために作られたか(rs:<数値>)
routedFromstring | null行き先を決めた工程の実行(rs:<数値>)
latestring | null結果が遅れて届き、進行に使わなかった理由
inputsarray入力ファイル(Agent に登録した入力ファイルと、前の工程から受け取ったファイル)。filename と handoff(前の工程から受け取ったものなら true)
libraryobjectプロジェクトのライブラリの記録。inputs・writes はいつも空の配列
  • questions と gates の …Kind が "human" なら、…Ref は利用者 ID です。人ではないときは …Ref が null です。
  • questions は、実行の記録の新しい方から 200 行の中にある質問だけです。それより古い質問は、実行の時系列(section が "confirmation" の行)で読みます。
  • files は 20 件までです。
  • library の inputs・writes は、いつも空の配列です。
  • ツールの呼び出しの 1 回ずつは、ツールの呼び出しの一覧で読みます。

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId が UUID の形式ではない、または executionId が rs:<数値> でも UUID でもない
403forbiddenシステム連携のトークンで呼び出した
403sso_required認証サーバーのアカウントと結び付いていない利用者
404execution_not_found実行が存在しない、ほかのプロジェクトの実行、またはメンバーではないプロジェクト

GET/v1/projects/{projectId}/executions/{executionId}/operations

実行の中のツールの呼び出しの一覧を、新しい記録のページから古い記録のページへ順に取得します。1 ページの中の operations は古い順に並びます。最後まで読むと、その実行のすべての呼び出しがそろいます。引数と応答は含みません。

クエリパラメータ​

パラメータ型デフォルト説明
cursorstring—次ページ取得用カーソル(前回レスポンスの cursor 値)

1 ページの件数は決まっていないため、limit はありません。

レスポンスフィールド(200 OK)​

フィールド型説明
operationsarray呼び出しの配列
operations[].operationIdstring | null呼び出しの ID
operations[].kindstring | null行の種類。"access" はファイルを読む前の検査
operations[].resourcestring | nullツール(MCP は mcp:<サーバー名>:<ツール名>)
operations[].actionstring | null操作
operations[].pathstring | null読んだファイルのパス
operations[].mcpServerstring | nullMCP サーバーの名前
operations[].connectionIdstring | null連携先の ID(連携先の API の connectionId)
operations[].connectionKindstring | null連携先の種類("mcp" / "a2a")
operations[].attemptedboolean呼び出したかどうか
operations[].effectstring | null呼び出しの結果
operations[].deniedstring | null止められたときの理由
operations[].durationMsnumber | nullかかった時間(ミリ秒)
operations[].reasonstring | null検査の理由(kind が "access" の行だけ。例: "granted"・"path_not_found")。ほかの行は null
hasMoreboolean続きがあるかどうか
cursorstring次ページ取得用カーソル。hasMore が true の場合のみ含まれます

1 回の呼び出しの記録がページの境目で分かれると、同じ operationId の行が両方のページに出ます。同じ operationId は 1 つにまとめて読んでください。

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId・executionId の形式の誤り、または cursor が不正
400invalid_cursorcursor を読めない
403forbiddenシステム連携のトークンで呼び出した
403sso_required認証サーバーのアカウントと結び付いていない利用者
404execution_not_found実行が存在しない、ほかのプロジェクトの実行、またはメンバーではないプロジェクト

GET/v1/projects/{projectId}/executions/{executionId}/timeline

実行の時系列(実行の記録)を取得します。依頼・根拠・実行したこと・確認・結果の記録が、古い方から並びます。

クエリパラメータ​

パラメータ型デフォルト説明
limitinteger501 ページの行の数(1-100)
cursorstring—次ページ取得用カーソル(前回レスポンスの cursor 値)

レスポンスフィールド(200 OK)​

フィールド型説明
rootExecutionIdstring実行の ID
originstring | null実行の始まり
ownerobject | null実行の主体
executionsobject実行の要約(items)。結果・設定・ツールの呼び出しの数など
timelineobject記録の行(items)
timeline.items[].atstring記録の日時
timeline.items[].keynumber記録の ID。"tool.access" の行は、ツールの呼び出しの一覧の operationId(row:<key>)と同じ
timeline.items[].sectionstring"request"(依頼)/ "evidence"(根拠)/ "action"(実行したこと)/ "confirmation"(確認)/ "result"(結果)/ "other"
timeline.items[].eventTypestring記録の種類(例: "context.manifest"・"runtime.mcp.connected"・"tool.invoked"・"guardrail.blocked")
timeline.items[].metaobject記録ごとの中身。項目名は記録のまま返ります
deletedobject消された会話・リソース
hasMoreboolean続きがあるかどうか
cursorstring次ページ取得用カーソル。hasMore が true の場合のみ含まれます
snapshotAtstring | null記録を読んだ日時

timeline.items[] には、ほかに writer・actor・resource・action・decision・reason・ref・available があります。meta の中身は記録の種類ごとに違い、項目名は記録のまま(snake_case)返ります。1 ページは 64 KiB までです。

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId・executionId の形式の誤り、limit が 1-100 の整数でない、または cursor が不正
400invalid_cursorcursor を読めない
403forbiddenシステム連携のトークンで呼び出した
403sso_required認証サーバーのアカウントと結び付いていない利用者
404execution_not_found実行が存在しない、ほかのプロジェクトの実行、またはメンバーではないプロジェクト
413trace_too_large記録が大きすぎて読めない
502trace_unreachable記録を読めなかった(時間をおいて送り直してください)
503trace_unavailable記録を読む機能が使えない

ファイル​

プロジェクトの中で見つけたファイル(実行の結果の files[]、確認依頼の材料の evidence.files[])の中身を取得します。どれも、応答の filepath をそのまま path に渡します。

エンドポイント一覧​

メソッドエンドポイント説明
GET/v1/projects/{projectId}/files/contentファイルの中身を取得

GET/v1/projects/{projectId}/files/content

ファイルの中身を取得します。プロジェクトのメンバーだけが読めます(公開されているプロジェクトでも、メンバーでなければ 404)。HEAD でも呼べます。本文を除いて同じヘッダーが返るので、先に大きさを確かめられます。MCP で使うトークンでも呼べるので、MCP のツールが返したファイルの URL を、同じトークンで取れます。

パスパラメータ​

パラメータ型必須説明
projectIdstring必須プロジェクト ID(UUID)

クエリパラメータ​

パラメータ型デフォルト説明
pathstring—必須。ファイルのパス(実行の結果の files[].filepath、または確認依頼の evidence.files[].filepath)
version_idstring—バージョンの ID。省くと今のバージョン

実行の結果のファイルで読めるバージョンは、今のバージョンと、プロジェクトがそのファイルを最初に記録した実行が始まった後に書かれたバージョンだけです。

レスポンス(200 OK)​

ファイルの中身が、そのまま返ります。

レスポンスヘッダー説明
Content-Typeファイルの MIME タイプ
Content-Lengthファイルサイズ(バイト)
X-Content-Type-Options"nosniff"
Content-DispositionHTML・SVG・XML のファイルでは "attachment"(ダウンロードとして返します)

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId が UUID の形式ではない、または path が無い
400file_not_foundpath で指定したファイルが読めない
400version_not_foundversion_id で指定したバージョンが無い(ファイルは読める)
403forbiddenシステム連携のトークンで呼び出した
403sso_required認証サーバーのアカウントと結び付いていない利用者
404project_not_foundプロジェクトが存在しない、またはメンバーではない

保存先の失敗(500・502・503)は、成果物取得(GET /v1/files/proxy)と同じです。

記録 (証跡)​

プロジェクトの中の決まった操作や出来事(確認の決定、実行ルールやメンバーの変更、実行の中のツールの記録など)の一覧です。設定の変更で残るのは、実行ルール・確認担当者・確認方法・メンバーの変更です(画面から変えたものも残ります)。そのほかの工程・配置・巡回・トリガー・連携先・通知の変更は残りません。

エンドポイント一覧​

メソッドエンドポイント説明
GET/v1/projects/{projectId}/audit記録 (証跡) を取得

GET/v1/projects/{projectId}/audit

記録 (証跡) を新しい順に取得します。カーソルベースのページネーションに対応しています。

クエリパラメータ​

パラメータ型デフォルト説明
kindstring—記録の種類で絞り込み(例: "policy.changed"・"improvement.applied"・"tool.invoked")
run_idstring—このワークフローの実行の記録に絞り込み(UUID)
qstring—文字列で絞り込み(100 文字まで)
limitinteger501 ページの取得件数(1-100)
cursorstring—次ページ取得用カーソル(前回レスポンスの cursor 値)

レスポンスフィールド(200 OK)​

フィールド型説明
eventsarray記録の配列
events[].eventIdnumber記録の ID
events[].occurredAtstring | null日時(ISO 8601)
events[].eventTypestring | null記録の種類
events[].actorKindstring | null記録者の種類。"agent" / "human" / "system" / "human_external" / "mail_external" / "unknown"
events[].actorRefstring | null記録者。actorKind が "human" なら利用者 ID、それ以外は参照(システム連携は client:<クライアント ID> など)
events[].decisionstring | null決定・結果
events[].reasonstring | null理由
events[].executionIdstring | null実行の ID
events[].runIdstring | nullワークフローの実行の ID
events[].stepNamestring | null工程の名前
events[].metadataobject記録ごとの中身。項目名は記録のまま返ります。中身の無い記録は {}
hasMoreboolean次のページが存在するかどうか
cursorstring次ページ取得用カーソル。hasMore が true の場合のみ含まれます
  • システム連携の行は、actorRef の client:<連携の ID> で見分けます。連携の表示名は、実行履歴・実行の結果の actorLabel で読みます。
  • 実行の途中の記録の一部(context.manifest・runtime.* など)は含まれません。実行の時系列で読みます。

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId・run_id が UUID の形式ではない、run_id と runId に違う値を指定した、kind が記録の種類の形ではない、q が 100 文字を超える、limit・cursor が不正
403forbiddenシステム連携のトークンで呼び出した
403sso_required認証サーバーのアカウントと結び付いていない利用者
404project_not_foundプロジェクトが存在しない、またはメンバーではない

KPI​

画面の概要の「KPI」と同じ値を取得します。数え方は結果リファレンスを参照してください。

エンドポイント一覧​

メソッドエンドポイント説明
GET/v1/projects/{projectId}/kpiKPI を取得

GET/v1/projects/{projectId}/kpi

プロジェクトの KPI を取得します。プロジェクトのメンバーだけが読めます(公開されているプロジェクトでも、メンバーでなければ 404)。

クエリパラメータ​

パラメータ型デフォルト説明
daysinteger30期間(直近の日数)。7・30・90 のどれか

レスポンスフィールド(200 OK)​

フィールド型説明
daysnumber期間(日)
successRatenumber | nullAgentの完遂率(0〜1。正常完了 ÷ 終了)。終了が 0 件なら null
successRateStatusstring"ok"(確定)/ "incomplete"(記録不足があり暫定値)/ "none"(記録不足が無く、終了が 0 件)
succeedednumber正常完了の数
denominatornumber終了の数(正常完了と「失敗・要対応」の合計。変化なしで終わった実行は入れません)
executionsnumber終わった実行の数(denominator と noChange の合計)
noChangenumber変化なしで終わった実行の数(結果は completed で、理由が "no_change")。終了・正常完了には入れません
outcomesobject結果ごとの数(completed・incomplete・failed・timeout・stopped・denied・skipped)。completed には、変化なしで終わった実行も入ります
excludedobject集計外の数(skipped・running・missing・unmeasured・connectionConfirm)。connectionConfirm はいつも 0
durationP95Minutesnumber | null処理時間の目安(p95。分)
runsobjectワークフローの実行の数(total・closedDone・closedFailed・closedRejected・cancelled)と p95Minutes
gatesarray確認工程ごとの実績(stepId・position・name・mode・total・approvalRate・sendBackRate)
humanobject確認対応の状況(reviewsPerRun・gateWaitMedianMinutes・interventions)

Agentの完遂率・runs・gates・human は、期間に始まった実行・ワークフローの実行・確認依頼を数えます。

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId が UUID の形式ではない、または days が 7・30・90 ではない
403forbiddenシステム連携のトークンで呼び出した
403sso_required認証サーバーのアカウントと結び付いていない利用者
404project_not_foundプロジェクトが存在しない、またはメンバーではない

確認依頼​

確認依頼は、ワークフローが確認工程に入ったとき、または Agent の工程の結果が「ルールにより実行不可」「失敗 (Agent の報告)」になり、その工程が確認を求める設定のときにできます。確認担当者が、進める・差し戻す・却下するを決めます。画面の確認依頼と同じものです。

  • 読めるのは、確認担当者(確認依頼ができたときの担当者で、今もプロジェクトのメンバーの人)と、プロジェクトのオーナーです。それ以外の利用者には 404 Not Found(workitem_not_found)が返ります。
  • 判断と期限の延長ができるのは確認担当者だけです。オーナーでも、確認担当者でなければできません(403 Forbidden、not_gate_owner)。

エンドポイント一覧​

メソッドエンドポイント説明
GET/v1/workitems確認依頼の一覧を取得
GET/v1/workitems/{workItemId}確認依頼を取得
POST/v1/workitems/{workItemId}/decision確認依頼を判断
PATCH/v1/workitems/{workItemId}確認依頼の期限を延ばす

GET/v1/workitems

自分が読める確認依頼を、更新の新しい順に取得します。プロジェクトをまたいで返します。カーソルベースのページネーションに対応しています。

クエリパラメータ​

パラメータ型デフォルト説明
statusstring—状態で絞り込み。"assigned"(確認待ち)/ "done"(進めた・差し戻した)/ "cancelled"(却下した、またはワークフローの実行が止まって取り消された)
statestring—"open"(割り当て中で、まだ決定していない)/ "closed"(それ以外)で絞り込み
project_idstring—このプロジェクトの確認依頼に絞り込み(UUID)
limitinteger501 ページの件数(1〜100)
cursorstring—次のページのカーソル(前のレスポンスの cursor の値)

レスポンスフィールド(200 OK)​

フィールド型説明
workitemsarray確認依頼の配列
workitems[].workItemIdstring確認依頼の ID(UUID)
workitems[].titlestring | null件名
workitems[].statusstring | null"assigned" / "done" / "cancelled"
workitems[].projectIdstring | nullプロジェクト ID
workitems[].projectNamestring | nullプロジェクト名
workitems[].decisionstring | null判断。"proceed"(進める)/ "send_back"(差し戻す)/ "reject"(却下する)。決まる前は null
workitems[].requesterUserIdstring | null依頼者の利用者 ID
workitems[].expiresAtstring | null確認期限(ISO 8601)
workitems[].gateModestring | nullいつも "blocking"(担当者の判断を待つ)
workitems[].overdueboolean | null期限を過ぎたかどうか
workitems[].decidedAtstring | null判断した日時(ISO 8601)
workitems[].createdAtstring | null作成日時(ISO 8601)
workitems[].updatedAtstring | null更新日時(ISO 8601)
workitems[].canDecideboolean自分が判断できるかどうか(確認担当者なら true)
hasMoreboolean次のページがあるかどうか
cursorstring次のページのカーソル。hasMore が true のときだけ含まれます

エラーレスポンス​

ステータスcode説明
400invalid_parameterstatus・state が上の値ではない、project_id が UUID の形式ではない、project_id と projectId に違う値を指定した、または limit・cursor の誤り
403forbiddenシステム連携のトークンで呼び出した
403sso_required認証サーバーのアカウントと結び付いていない利用者

GET/v1/workitems/{workItemId}

確認依頼を、確認の材料・経緯・判断できる行き先と一緒に取得します。

パスパラメータ​

パラメータ型必須説明
workItemIdstring必須確認依頼の ID(UUID)

レスポンスフィールド(200 OK)​

フィールド型説明
workitemobject確認依頼。一覧の 1 件の項目(workItemId・title・status・projectId・decision・requesterUserId・expiresAt・gateMode・overdue・decidedAt・createdAt・updatedAt・canDecide)と、次の項目
workitem.descriptionstring | null説明
workitem.runIdstring | nullワークフローの実行の ID
workitem.runStepIdstring | null確認を求めた工程の実行の ID(rs:<数値>。実行履歴の executionId と同じ形)
workitem.stepIdstring | null確認を求めた工程の ID(確認工程、または結果によって確認を求めた Agent の工程)
workitem.approverUserIdsarray確認担当者の利用者 ID の配列(確認依頼ができたときの担当者)
workitem.overdueActionstring | nullいつも "none"(期限を過ぎても自動では決まらず、通知して待ち続けます)
workitem.evidenceobject | null確認の材料(下の表)
workitem.decidedByKindstring | null判断したものの種類("human" など)。決まる前は null
workitem.decidedByRefstring | null判断したもの。decidedByKind が "human" なら利用者 ID。期限後の自動の判断などは system:… の参照。決まる前は null
workitem.decisionReasonstring | null判断の理由
workitem.sendBackToStepIdstring | null差し戻し先の工程の ID
workitem.decisionResultobject | null判断の結果(decision・at・completesRun・sendBackToStepId・destinationId・destinationStepId)。completesRun は、進めたときにワークフローの実行が終わったかどうか
activitiesarray経緯(新しい順に 100 件まで)
activities[].activityIdnumber | null経緯の ID
activities[].eventTypestring | null記録の種類
activities[].decisionstring | null判断
activities[].actorKindstring | null記録したものの種類
activities[].actorRefstring | null記録したもの。actorKind が "human" なら利用者 ID、それ以外は system:… などの参照
activities[].reasonCodestring | null理由
activities[].conversationIdstring | null会話の ID
activities[].metadataobject記録ごとの中身。項目名は記録のまま返ります(利用者 ID が入ることがあります)
activities[].occurredAtstring | null日時(ISO 8601)
gateobject | null判断に使う情報(下の表)

確認の材料(workitem.evidence):

フィールド型説明
summarystring | null確認の材料の文。ふつうは確認する工程の Agent の出力で、Agent の工程の結果によって確認を求めたときは、結果とその理由の要約
conversationIdstring | null確認する工程の実行の会話の ID
filesarray確認する工程のファイル(会話 API の deliverables と同じ形。中身はファイルの中身の取得(GET /v1/projects/{projectId}/files/content)に filepath を path で渡して取る)
gateKindstring | null確認の種類。"review"(確認)/ "manual"(手作業)
stepNamestring | null確認を求めた工程の名前
outcomestring | null確認する工程の実行の結果(実行の「結果の値」)
executionIdstring | null確認する工程の実行の ID(実行の結果を取得する API で読めます)
reasonCodestring | null結果の理由(Agent の工程の結果によって確認を求めたとき)
escalateToUserIdstring | null期限超過時の連絡先の利用者 ID(確認依頼ができたときにメンバーだった人)
destinationsarrayいつも空の配列(マーケットプレイス版では、進め先を設定できません)
connectorobject | nullいつも null
servicestring | nullいつも null
modestring | nullいつも null
toolstring | nullいつも null
waitMinutesnumber | nullいつも null

判断に使う情報(gate):

フィールド型説明
contextVersionnumber確認依頼のバージョン(1 以上)。バージョン付きの確認(ワークフローの確認)のときだけ含まれます。判断の contextVersion にそのまま送ります
basisDigeststring | null確認の材料の digest(64 文字の 16 進)。contextVersion と同じときだけ含まれます。判断の basisDigest にそのまま送ります
projectNamestring | nullプロジェクト名
projectTypestring | nullプロジェクトの型
stepIdstring | null確認を求めた工程の ID
stepNamestring | null確認を求めた工程の名前
stepPositionnumber | null確認を求めた工程の位置
nextStepobject | null進めたときの次の工程(stepId・name・position)。次の工程が無ければ null
sendBackDefaultStepIdstring | null差し戻し先を指定しないときの戻り先の工程の ID
sendBackCandidatesarray差し戻し先に指定できる工程(stepId・name・position・sendBacks)。sendBacks はその工程へ差し戻した回数
sendBackLimitnumber | null1 つの工程へ差し戻せる回数の上限
destinationsarrayいつも空の配列(マーケットプレイス版では、進め先を設定できません)
laneobject | null確認を求めた工程のレーン(laneId・name・position)。レーンが無ければ null

エラーレスポンス​

ステータスcode説明
400invalid_parameterworkItemId が UUID の形式ではない
403forbiddenシステム連携のトークンで呼び出した
403sso_required認証サーバーのアカウントと結び付いていない利用者
404workitem_not_found確認依頼が存在しない、または読めない

POST/v1/workitems/{workItemId}/decision

確認依頼を判断します。確認担当者だけが呼べます。

リクエストボディ​

フィールド型必須説明
decisionstring必須"proceed"(進める)/ "send_back"(差し戻す)/ "reject"(却下する)
reasonstring—理由(10000 文字まで)。"send_back"・"reject" のときは必須
sendBackToStepIdstring—差し戻し先の工程の ID("send_back" のとき。gate の sendBackCandidates の工程)。省くと sendBackDefaultStepId の工程に戻します
commandIdstring—送り直しを見分ける値(128 文字まで)
contextVersioninteger—判断する前に読んだ確認依頼の gate.contextVersion(1 以上の整数)。gate に含まれるときは必須
basisDigeststring—判断する前に読んだ確認依頼の gate.basisDigest(64 文字の小文字の 16 進)。gate に含まれるときは必須
  • 同じ commandId で同じ内容を送り直すと、1 回目の結果({ "decision": …, "alreadyDecided": true })が返ります。同じ commandId で違う内容を送ると 409 Conflict(command_conflict)です。
  • すでに判断されている確認依頼に、違う commandId(または commandId なし)で送ると 409 Conflict(already_decided)です。確認依頼を取得し直して、今の判断を読んでください。
  • 差し戻しは、1 つの工程へ差し戻せる回数の上限(gate.sendBackLimit)までです。

バージョン付きの確認では、確認依頼を読んだ後に確認依頼が変わっていると 409 Conflict(stale_context)です。確認依頼を取得し直し、新しい gate.contextVersion・gate.basisDigest で送り直してください。

レスポンスフィールド(200 OK)​

フィールド型説明
decisionstring判断
channelstring | null判断の経路(API から判断したときは "api")。送り直しの応答には含まれません
alreadyDecidedboolean同じ commandId の送り直しで、1 回目の結果を返したときだけ true で含まれます

エラーレスポンス​

ステータスcode説明
400invalid_parameterworkItemId・sendBackToStepId が UUID の形式ではない、decision が無い・上の値ではない、commandId・destinationId が空白だけ、contextVersion が 1 以上の整数ではない、basisDigest が 64 文字の小文字の 16 進ではない、または項目の型や長さの誤り
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
400reason_required"send_back"・"reject" で reason が無い
400invalid_send_back_stepsendBackToStepId が、差し戻し先に指定できる工程ではない
400invalid_destinationdestinationId を送った(マーケットプレイス版の確認依頼には進め先がありません)
400basis_requiredバージョン付きの確認で、contextVersion・basisDigest を送らなかった
403forbiddenシステム連携のトークンで呼び出した
403sso_required認証サーバーのアカウントと結び付いていない利用者
403not_gate_ownerプロジェクトのメンバーだが、確認担当者ではない
404workitem_not_found確認依頼が存在しない、または読めない
409already_decidedすでに判断されている
409command_conflict同じ commandId で違う内容を送った
409invalid_state確認待ちではない(取り消されたなど)
409send_back_limit_exceeded差し戻せる回数の上限に達している
409stale_context確認依頼を読んだ後に、確認依頼が変わっている(送ったバージョンと今のバージョンが違う)
413body_too_largeボディが 3 MiB を超える
415unsupported_media_typeボディの Content-Type が application/json ではない

PATCH/v1/workitems/{workItemId}

確認依頼の期限(expiresAt)を延ばします。確認担当者だけが呼べます。延ばすと、期限超過の印(overdue)も外れます。

パスパラメータ​

パラメータ型必須説明
workItemIdstring必須確認依頼の ID(UUID)

リクエストボディ​

フィールド型必須説明
expiresAtstring必須新しい期限(ISO 8601 の日時。今より後)

同じ値で送り直すと、同じ結果になります。

レスポンスフィールド(200 OK)​

フィールド型説明
workitemobject延ばした後の確認依頼。項目は、確認依頼の取得の workitem と同じです

期限を延ばした後の読み直しに失敗すると、502 Bad Gateway(upstream_connection_error)が返ります。期限は延びていることがあるので、送り直す前に、確認依頼の取得で expiresAt を確かめてください。

エラーレスポンス​

ステータスcode説明
400invalid_parameterworkItemId が UUID の形式ではない、または expiresAt が無い・ISO 8601 の日時ではない・今より後ではない
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
403forbiddenシステム連携のトークンで呼び出した
403sso_required認証サーバーのアカウントと結び付いていない利用者
403not_gate_ownerプロジェクトのメンバーだが、確認担当者ではない
404workitem_not_found確認依頼が存在しない、または読めない
409already_decidedすでに判断されている
409invalid_state確認待ちではない(取り消されたなど)
413body_too_largeボディが 3 MiB を超える
415unsupported_media_typeボディの Content-Type が application/json ではない
502upstream_connection_error期限を延ばした後の読み直しに失敗した(送り直す前に、確認依頼の取得で確かめてください)

キュー​

キューは、人の手が要るもの(期限を過ぎた確認依頼・確認待ち・外部の待ちの観測の失敗・ワークフローの実行の締め切りの超過と停滞・失敗した工程・差し戻し待ち・失敗した巡回)を、1 件 1 行で優先度の順に並べた一覧です。画面のキューと同じものです。

  • プロジェクトのキュー(GET /v1/projects/{projectId}/queue)は、そのプロジェクトの全部の行を返します。プロジェクトのメンバーなら読めます。
  • 自分のキュー(GET /v1/queue)は、参加しているプロジェクトのうち、自分が担当の行を返します。
  • 行への操作は、次の API に行の ID を渡して行います。
することAPI使う ID
確認依頼を進める・差し戻す・却下するPOST /v1/workitems/{workItemId}/decisionworkItemId
確認依頼の期限を延ばすPATCH /v1/workitems/{workItemId}workItemId
ワークフローの実行の締め切りを変えるPATCH /v1/projects/{projectId}/runs/{runId}runId
ワークフローの実行の確認担当者を付け替えるPUT /v1/projects/{projectId}/runs/{runId}/approversrunId

エンドポイント一覧​

メソッドエンドポイント説明
GET/v1/projects/{projectId}/queueプロジェクトのキューを取得
GET/v1/queue自分が担当のキューを取得

行の種類​

kind(行の種類)の値です。

値画面の表示中身
gate_overdue期限超過期限を過ぎた確認依頼
run_deadline_overdue締め切り超過(実行)締め切りを過ぎたワークフローの実行
external_wait_blocked外部待ち外部の待ちの観測が失敗している確認依頼
gate_pending確認待ち確認待ちの確認依頼
run_stalled停滞止まったままのワークフローの実行
execution_failed失敗失敗した工程
send_back_pending差し戻し待ち差し戻されて待っている工程
sweep_failed巡回の失敗失敗した巡回

GET/v1/projects/{projectId}/queue

プロジェクトのキューを、優先度の順に取得します。並びは、優先度 → 期限 → 経過の起点 → 行の ID の順で、変えられません。カーソルベースのページネーションに対応しています。

パスパラメータ​

パラメータ型必須説明
projectIdstring必須プロジェクト ID(UUID)

クエリパラメータ​

パラメータ型デフォルト説明
kindstring—行の種類で絞り込み(上の「行の種類」の値)
limitinteger501 ページの取得件数(1-100)
cursorstring—次ページ取得用カーソル(前回レスポンスの cursor 値)

レスポンスフィールド(200 OK)​

フィールド型説明
queueItemsarrayキューの行の配列
queueItems[].queueItemIdstring行の ID(<種類>:<ID> の形)
queueItems[].kindstring行の種類(上の「行の種類」)
queueItems[].prioritynumber | null優先度(1〜4。1 が高い)
queueItems[].projectIdstring | nullプロジェクトの ID
queueItems[].projectNamestring | nullプロジェクトの名前
queueItems[].workItemIdstring | null確認依頼の ID。確認依頼の行(gate_overdue・external_wait_blocked・gate_pending)だけで、それ以外は null。確認依頼の API でそのまま使えます
queueItems[].runIdstring | nullワークフローの実行の ID。無ければ null
queueItems[].stepIdstring | null工程の ID。無ければ null
queueItems[].placementIdstring | null配置の ID。無ければ null
queueItems[].executionIdstring | null実行の ID。実行の結果の取得でそのまま使えます。失敗した工程(execution_failed)は rs:<数値>、失敗した巡回(sweep_failed)は巡回の実行の UUID、確認依頼の行は確認の材料(evidence.executionId)と同じ値。それ以外は null
queueItems[].stepNamestring | null工程の名前
queueItems[].agentNamestring | nullAgent の名前
queueItems[].titlestring | null確認依頼の題。確認依頼の行だけで、それ以外は null
queueItems[].dueAtstring | null期限(ISO 8601)。確認依頼の期限か、ワークフローの実行の締め切り。それ以外は null
queueItems[].elapsedFromstring | null経過を数える起点(ISO 8601)。確認依頼の行は、確認依頼ができた日時
queueItems[].assigneeUserIdsarray担当者の利用者 ID。確認依頼の行はその確認担当者、差し戻し待ちは差し戻した確認の確認担当者(どちらも今もメンバーの人)。失敗した工程・失敗した巡回・締め切りの超過・停滞は、プロジェクトのオーナー
queueItems[].escalateToUserIdstring | null期限超過時の連絡先の利用者 ID。確認依頼の行だけで、それ以外は null
queueItems[].causeobject | null失敗から来た行の、結果(outcome)と理由(reasonCode)。それ以外は null
queueItems[].gateKindstring | null確認の種類(確認の材料の gateKind と同じ値)
queueItems[].observationErrorCodestring | null外部の待ちの観測が失敗した理由
queueItems[].sendBackLimitReachedboolean | null差し戻せる回数の上限に達したかどうか
hasMoreboolean次のページが存在するかどうか
cursorstring次ページ取得用カーソル。hasMore が true の場合のみ含まれます

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId が UUID の形式ではない、kind が上の値ではない、または limit・cursor が不正
403forbiddenシステム連携のトークンで呼び出した
403sso_required認証サーバーのアカウントと結び付いていない利用者
404project_not_foundプロジェクトが存在しない、またはメンバーではない

GET/v1/queue

参加しているプロジェクトのうち、自分が担当の行を、優先度の順に取得します。プロジェクトをまたいで返します。クエリパラメータ・レスポンスフィールド・並びは、プロジェクトのキューと同じです。

エラーレスポンス​

ステータスcode説明
400invalid_parameterkind が上の値ではない、または limit・cursor が不正
403forbiddenシステム連携のトークンで呼び出した
403sso_required認証サーバーのアカウントと結び付いていない利用者

連携先​

プロジェクトの実行で使う MCP サーバーと A2A のエージェントの中身を読みます。返すのは、相手が公開している情報(ツールの名前と説明、エージェントカード)だけです。接続先の URL や資格情報は返しません。

  • 連携先の ID(connectionId)は、プロジェクトの取得の connectors[].connectionId と、ツールの呼び出しの一覧の operations[].connectionId で分かります。
  • テナントの利用者なら、どの連携先も読めます(プロジェクトのメンバーでなくても読めます)。管理画面で無効にされた・削除された連携先は 404 Not Found(connector_not_found)です。
  • 連携先へのログインは、プロジェクトの画面で行います。

エンドポイント一覧​

メソッドエンドポイント説明
GET/v1/connectors/mcp/{connectionId}MCP の連携先を取得
GET/v1/connectors/a2a/{connectionId}A2A の連携先を取得

GET/v1/connectors/mcp/{connectionId}

MCP の連携先と、そのツールの一覧を取得します。ツールの一覧は、管理画面で MCP サーバーから取得して保存したものです。

パスパラメータ​

パラメータ型必須説明
connectionIdstring必須連携先の ID(16 桁までの正の整数)

レスポンスフィールド(200 OK)​

フィールド型説明
kindstring"mcp"
connectionIdstring連携先の ID
namestring | null連携先の名前
requiresLoginbooleanプロジェクトの画面でログインしてから使う連携先かどうか
toolsarrayツールの配列
tools[].namestring | nullツールの名前
tools[].displayNamestring | null表示名
tools[].descriptionstring | null説明
tools[].inputSchemaobject | nullツールの入力のスキーマ(MCP サーバーが申告した形のまま)。管理画面でツールの一覧を取り直すまでは null
tools[].outputSchemaobject | nullツールの出力のスキーマ(MCP サーバーが申告した形のまま)。申告が無ければ null
tools[].declaredAnnotationsobject | nullツールの注釈(readOnlyHint など。MCP サーバーの自己申告のまま)。本製品はこの申告を確かめておらず、実行の制御にも使っていません
tools[].presentInLastFetchboolean | null最後に取得したときにもあったかどうか(false は、MCP サーバーから無くなったツール)
toolsFetchedAtstring | nullツールの一覧を最後に取得した日時(ISO 8601)。ツールが 0 件の取得でも、取得した日時が入ります。一度も取得していなければ null

エラーレスポンス​

ステータスcode説明
400invalid_parameterconnectionId が 16 桁までの正の整数ではない
403forbiddenシステム連携のトークンで呼び出した
404connector_not_found連携先が存在しない、または無効

GET/v1/connectors/a2a/{connectionId}

A2A の連携先と、そのエージェントカードを取得します。エージェントカードは、管理画面に保存された内容です。

パスパラメータ​

パラメータ型必須説明
connectionIdstring必須連携先の ID(16 桁までの正の整数)

レスポンスフィールド(200 OK)​

フィールド型説明
kindstring"a2a"
connectionIdstring連携先の ID
namestring | null連携先の名前
requiresLoginbooleanプロジェクトの画面でログインしてから使う連携先かどうか
agentCardobjectエージェントカード
agentCard.descriptionstring | null説明
agentCard.versionstring | null版
agentCard.providerobject | null提供者
agentCard.skillsarrayスキル
agentCard.capabilitiesobject | null対応している機能
agentCard.defaultInputModesarray受け取る形式
agentCard.defaultOutputModesarray返す形式
agentCard.supportedInterfacesarray対応している接続方式
agentCard.documentationUrlstring | null説明書の URL
agentCard.iconUrlstring | nullアイコンの URL
agentCard.securitySchemesobject | null相手への認証の方法(相手が公開した形のまま)
agentCard.securityRequirementsarray認証の要件(相手が公開した形のまま)

agentCard の provider・skills・capabilities・supportedInterfaces の中身は、相手のエージェントが公開している形のままです。

エラーレスポンス​

ステータスcode説明
400invalid_parameterconnectionId が 16 桁までの正の整数ではない
403forbiddenシステム連携のトークンで呼び出した
404connector_not_found連携先が存在しない、または無効

実行の会話​

実行の中で Agent とやりとりした会話(Agent への依頼の文、途中の説明、最終応答など)は、会話 API の GET /v1/conversations/{conversationId}/messagesで読みます。詳しくはユーザー API リファレンス(会話・組織)の会話管理を参照してください。

  • conversationId は、実行履歴・実行の結果の conversationId で分かります。
  • 読めるのは、プロジェクトを作った人(コピーして作ったプロジェクトなら、コピーした人)だけです。プロジェクトの実行は、作った人の名前で動くためです(誰が何を決められるかを参照)。ほかのオーナーとメンバーには 404 Not Found が返ります。システム連携からは読めません。
  • 登録 Agent で動く workflow の工程の実行には、会話がありません(conversationId は null)。cycle の周期の巡回は、配置と工程ごとの 1 つの会話に、回ごとのメッセージが足されていきます。会話 API はメッセージと実行を結び付けないので、実行の開始時刻(startedAt)の頃の、sender が "User" のメッセージ(その回の Agent への依頼)で見分けてください。

エラーレスポンス​

HTTP ステータスコード​

すべてのエンドポイントで返される可能性のある HTTP ステータスコードです。

ステータス説明
400 Bad Requestリクエストパラメータが不正
401 Unauthorizedトークンが無効または未指定
403 Forbiddenリソースへのアクセス権限なし
404 Not Foundリソースが存在しない、または未定義のパス・メソッド(405 は返しません)
409 Conflictリソースが現在処理中など、操作が競合
413 Payload Too Largeリクエストボディがサイズ上限を超過
415 Unsupported Media Typeリクエストボディの形式(Content-Type)に対応していない
429 Too Many Requestsレート制限または同時実行の上限を超過。error.type は rate_limit_error で、error.code はエンドポイントにより異なります(例: 月間上限は monthly_quota_exceeded、プロジェクトの同時実行は too_many_active_runs)。時間をおいて再試行してください
500 Internal Server Errorサーバー内部エラー
502 Bad Gateway上流サービス(認証基盤・チャット基盤等)との通信エラー
503 Service Unavailableサービス一時利用不可
504 Gateway Timeout上流サービスの応答タイムアウト

エラーレスポンス形式​

すべてのエラーレスポンスは以下の共通構造で返されます。

フィールド型説明
error.typestringエラーの分類。"invalid_request_error"、"authentication_error"、"insufficient_scope_error"、"forbidden_error"、"not_found_error"、"conflict_error"、"payload_too_large_error"、"rate_limit_error"、"server_error"、"upstream_error" のいずれか
error.messagestring人間が読めるエラーメッセージ
error.codestring機械的に処理可能なエラーコード(例: "missing_parameter"、"invalid_parameter"、"invalid_token")
error.paramstringエラーの原因となったパラメータ名。バリデーションエラー時のみ含まれます
error.suggested_actionstring推奨される対処方法。一部のエラーでのみ含まれます
JSON
{
"error": {
"type": "invalid_request_error",
"message": "Invalid parameter: limit",
"code": "invalid_parameter",
"param": "limit",
"suggested_action": "limit must be between 1 and 100"
}
}