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

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

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

ベース URL

すべての API リクエストは以下のベース URL に対して送信します。

SaaS

https://api.fd.agenticstar.tm.softbank.jp/api

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

認証

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

Authorization: Bearer <access_token>

トークンが無効または未指定の場合、401 Unauthorized が返されます。このページの API で使うスコープは次のとおりです。必要なスコープが不足している場合は 403 Forbidden（insufficient_scope）が返されます。

スコープ	できること
project:read	プロジェクトと、その中のもの（工程・配置・実行・記録 (証跡)・KPI など）、確認依頼、連携先を読む
project:write	プロジェクトを作る・変える、工程と配置を変える
project:delete	プロジェクトを消す
project:run	ワークフローの実行を始める、トリガーを発火する
project:decide	確認依頼を判断する

project:* のスコープは、名前がぴったり合うときだけ使えます。トークンの取得方法・スコープの詳細については、認証ガイド および 認証 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・工程・利用者など）が存在しない・見えないときの扱いは、エンドポイントごとに違います（例: 配置の agentId は 400 Bad Request（agent_not_found）、配置の stepIds は 400 Bad Request（invalid_parameter））。各エンドポイントの説明とエラーレスポンスを参照してください。
• 一覧を絞り込むクエリ（placementId・stepId・runId）に存在しない ID を指定したときは、空の一覧が返ります。
• SSO でログインしていない利用者のトークンでは、プロジェクトと確認依頼の 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）になります。黙って無視すると、変えたつもりで変わらないためです。該当するフィールドは各エンドポイントの説明に書いています。
• レスポンスには x-request-id ヘッダーが付きます。サービス側で採番する値で、リクエストで送った値は使われません。お問い合わせの際はこの値をお知らせください。

書き換えと送り直し

• 書き換える API は、取得で返る digest を baseDigest に入れて送ります。取得した後にほかの変更が入っていると 409 Conflict（stale_base）が返ります。取得し直してから送り直してください。ほぼ同時に届いた 2 つの書き換えは、両方が通ることがあります。
• 応答の digest は書き換えた後の値です。続けて書き換えるときはその値を使えます。
• プロジェクトと工程を作る 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 つの型があります。型は作るときに決め、後から変えられません。

エンドポイント一覧

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

GET/v1/projects

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

クエリパラメータ

パラメータ	型	デフォルト	説明
limit	integer	50	取得件数（1〜100）
cursor	string	—	次ページ取得用カーソル（前回レスポンスの cursor 値）
myRole	string	—	"owner" または "member"。呼び手がその役割のプロジェクトだけを返します

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

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

レスポンスフィールド（200 OK）

フィールド	型	説明
projects	array	プロジェクトオブジェクトの配列
projects[].projectId	string	プロジェクト ID（UUID）
projects[].name	string	プロジェクト名
projects[].type	string	"workflow" または "cycle"
projects[].status	string	プロジェクトの状態。"active" / "paused" / "archived" のいずれか
projects[].tags	array	タグの配列。設定されていない場合は空の配列
projects[].myRole	string	呼び手自身のそのプロジェクトでの役割。"owner" または "member"
projects[].owners	array	そのプロジェクトの現在のオーナーの利用者 ID の配列。オーナー以外の参加者は含みません
hasMore	boolean	次のページが存在するかどうか
cursor	string	次ページ取得用カーソル。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
}

エラーレスポンス

ステータス	説明
400	limit（1〜100 の範囲外）、cursor、または myRole が不正（code は invalid_parameter）
403	project:read スコープが不足（code は insufficient_scope）

GET/v1/projects/shared

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

クエリパラメータ

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

レスポンスフィールド（200 OK）

フィールド	型	説明
projects	array	プロジェクトの配列
projects[].projectId	string	プロジェクト ID（UUID）
projects[].name	string | null	プロジェクト名
projects[].description	string | null	説明
projects[].type	string | null	"workflow" または "cycle"
projects[].status	string | null	"active" / "paused" / "archived" のいずれか
projects[].tags	array	タグの配列
projects[].stepCount	number | null	有効な工程の数
projects[].agentCount	number | null	配置の数
projects[].copyCount	number | null	コピーされた回数
projects[].ownerUserId	string | null	持ち主の利用者 ID
projects[].updatedAt	string | null	最終更新日時（ISO 8601）
hasMore	boolean	次のページが存在するかどうか
cursor	string	次ページ取得用カーソル。hasMore が true の場合のみ含まれます

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

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	limit・cursor・type・tag・q・sort の値が不正
403	insufficient_scope	project:read スコープが不足
403	forbidden	システム連携のトークンで呼び出した
403	sso_required	SSO でログインしていない利用者

GET/v1/projects/organizations

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

レスポンスフィールド（200 OK）

フィールド	型	説明
organizations	array	組織の配列
organizations[].value	string	組織のコード（プロジェクトの organizationCode に指定します）
organizations[].label	string | null	組織の名前
hasMore	boolean	いつも false

エラーレスポンス

ステータス	code	説明
403	insufficient_scope	project:read スコープが不足
403	forbidden	システム連携のトークンで呼び出した
403	sso_required	SSO でログインしていない利用者
503	organization_unavailable	所属している組織を確かめられない（時間をおいて送り直してください）

GET/v1/projects/{projectId}

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

パスパラメータ

パラメータ	型	必須	説明
projectId	string	必須	プロジェクト ID（UUID）

レスポンスフィールド（200 OK）

フィールド	型	説明
project	object	プロジェクト（下の表）
steps	array	工程の配列（並び順）。1 件の項目は「工程の項目」を参照
stepsDigest	string	工程の並びの値。工程を並べ替えるときに baseDigest に送ります
members	array	メンバーの配列
members[].userId	string	利用者 ID
members[].role	string | null	"owner" または "member"
members[].joinedAt	string | null	メンバーになった日時（ISO 8601）
members[].name	string | null	利用者の名前
members[].email	string | null	利用者のメールアドレス
placements	array	配置の配列。1 件の項目は「配置の項目」を参照
triggers	array	トリガーの配列（時刻と Webhook のトリガーだけ）
triggers[].triggerId	string | null	トリガー ID（UUID）。トリガーの発火に使います
triggers[].type	string	"cron"（時刻）または "webhook"
triggers[].name	string | null	名前
triggers[].enabled	boolean | null	有効かどうか
triggers[].lastFiredAt	string | null	最後に発火した日時（ISO 8601）
triggers[].nextFireAt	string | null	次に発火する予定の日時（ISO 8601）
triggers[].createdAt	string | null	作成日時（ISO 8601）
triggers[].cron	string | null	cron 式（"cron" のトリガーだけ）
triggers[].timezone	string | null	タイムゾーン（"cron" のトリガーだけ）
triggers[].startStepId	string | null	始める工程の ID（"cron" のトリガーだけ）
triggers[].placementId	string | null	起動する配置の ID（"webhook" のトリガーだけ）
triggers[].stepId	string | null	起動する工程の ID（"webhook" のトリガーだけ）
notifications	object	通知の設定
notifications.gateReached	boolean | null	確認依頼が届いたときに通知するかどうか
notifications.gateOverdue	boolean | null	確認依頼が期限を過ぎたときに通知するかどうか
connectors	array	このプロジェクトに登録した連携先の配列
connectors[].kind	string | null	"mcp" または "a2a"
connectors[].connectionId	string | null	連携先の ID。連携先の API（GET /v1/connectors/{kind}/{connectionId}）で中身を読めます。管理画面で無効にされた・削除された連携先と、連携先の情報を確かめられなかったときは null
connectors[].name	string | null	連携先の名前
connectors[].ledgerEnabled	boolean | null	台帳として使う連携先かどうか
connectors[].login	string | null	ログインの状態。"connected"（ログイン済み）/ "reauth_required"（ログインし直しが必要）/ "not_connected"（未ログイン）。状態を確かめられないときは null。ログインは画面で行います
connectors[].createdAt	string | null	登録日時（ISO 8601）

project の項目:

フィールド	型	説明
projectId	string	プロジェクト ID（UUID）
name	string | null	プロジェクト名
description	string | null	説明
tags	array	タグの配列
type	string | null	"workflow" または "cycle"
status	string | null	"active"（稼働中）/ "paused"（停止中）/ "archived"（アーカイブ）のいずれか
policy	object | null	実行ルール。画面で設定した値のまま返ります。この API では変えられません
limits	object | null	実行の上限
limits.maxRetriesPerStep	number	1 つの工程で失敗したときにやり直す回数の上限
limits.maxSendBacksPerStep	number	同じ工程へ差し戻せる回数の上限
language	string | null	プロジェクトの言語
flowStructure	object | null	レーンの定義（workflow で、工程を並行して進めるとき）。下の「レーンの定義」を参照
reportTargets	object | null	今は使っていない項目です（値が入っていても使われません）
organizationCode	string | null	組織のコード
organizationName	string | null	組織の名前
isShared	boolean | null	公開しているかどうか
copyCount	number | null	コピーされた回数
ownerUserId	string | null	持ち主の利用者 ID
myRole	string | null	呼んだ利用者の役割。"owner" または "member"。プレビューでは null
createdAt	string | null	作成日時（ISO 8601）
updatedAt	string | null	最終更新日時（ISO 8601）
digest	string	プロジェクトを変えるときに baseDigest に送る値

レーンの定義（flowStructure）:

フィールド	型	説明
lanes	array	レーンの配列
lanes[].id	string | null	レーンの ID
lanes[].name	string | null	レーンの名前
lanes[].parentLaneId	string | null	分かれる前のレーンの ID
lanes[].stepIds	array	このレーンの工程の ID の配列。どのレーンにも属さない工程は "main" のレーンに入ります
forks	array	分かれる所の配列
forks[].id	string | null	分かれる所の ID
forks[].afterStepId	string | null	この工程の後で分かれます
forks[].laneIds	array	分かれた先のレーンの ID の配列
forks[].joinId	string | null	合流する所の ID
joins	array	合流する所の配列
joins[].id	string | null	合流する所の ID
joins[].mode	string | null	"and"（すべてのレーンがそろったら進む）
joins[].laneIds	array	合流するレーンの ID の配列
joins[].nextStepId	string | null	合流した後に進む工程の ID

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

配置の Agent の goal・guardrail・inputFiles（ファイル名）は、assets:read スコープが無くても返ります。

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	projectId が UUID の形式ではない
403	insufficient_scope	project:read スコープが不足
403	forbidden	システム連携のトークンで呼び出した
403	sso_required	SSO でログインしていない利用者
404	project_not_found	プロジェクトが存在しない、またはメンバーではない公開されていないプロジェクト

POST/v1/projects

プロジェクトを作ります。作った利用者がオーナーになり、プロジェクトの実行の主体になります。Agent はライブラリで作ってから、配置を置く API（POST /v1/projects/{projectId}/placements）で置きます。

リクエストボディ

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

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

レスポンス（201 Created）

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

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	name が無い・空白だけ、項目の型や長さ・数・値の誤り（タグの空・重なりを含みます）、工程が 12 個を超える、または trigger・policy・agents・guardrail・templateRef を送った
400	invalid_body	ボディが壊れた JSON、または JSON のオブジェクトではない
400	cycle_disabled	この環境では cycle を使えない
400	cycle_gate_not_allowed	cycle に確認工程（"gate"）を指定した
400	parallel_workflow_only	cycle の工程に placementExecution の "parallel" を指定した
400	parallel_ai_only	"ai" ではない工程に placementExecution の "parallel" を指定した
400	organization_not_member	付けられない組織を指定した
403	insufficient_scope	project:write スコープが不足
403	forbidden	システム連携のトークンで呼び出した
403	sso_required	SSO でログインしていない利用者
403	license_status_unavailable	ライセンスを確かめられない
409	project_limit_reached	プロジェクトの数が上限に達している（数は error.message）
413	body_too_large	ボディが 3 MiB を超える
415	unsupported_media_type	ボディの Content-Type が application/json ではない
503	organization_unavailable	所属している組織を確かめられない

PATCH/v1/projects/{projectId}

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

パスパラメータ

パラメータ	型	必須	説明
projectId	string	必須	プロジェクト ID（UUID）

リクエストボディ

フィールド	型	必須	説明
baseDigest	string	必須	プロジェクトの取得の project.digest
name	string	—	プロジェクト名（255 文字まで。空・空白だけにはできません）
description	string	—	説明（5000 文字まで。空の文字列・空白だけ・null にはできません）
tags	array	—	タグ（作るときと同じ）。送ると全部が置き換わります
status	string	—	"active" / "paused" / "archived"
isShared	boolean	—	公開するかどうか
limits	object	—	実行の上限。送った項目だけを今の値に重ねます
limits.maxRetriesPerStep	integer	—	0〜10
limits.maxSendBacksPerStep	integer	—	1〜10
flowStructure	object | null	—	レーンの定義（取得と同じ形）。送ると全部が置き換わります。null でレーンを無くします
organizationCode	string | null	—	組織のコード（255 文字まで）。組織をまだ付けていないプロジェクトに 1 回だけ付けられます。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" に戻すと、止まっていた間の起動を続きから動かします。

flowStructure を送るときの決まりです。合わないと 400（invalid_flow_structure）が返ります。

• workflow のプロジェクトだけに付けられます。マーケットプレイス版の登録 Agent を置いたプロジェクトには付けられません。
• レーン・分かれる所・合流する所の ID は、英数字と _・- の 64 文字までです。工程の ID は UUID です。レーンの名前は 50 文字までで、空白だけにはできません。"main" のレーンには名前を付けられません（null にするか省きます）。
• "main" のレーンの parentLaneId は null、ほかのレーンの parentLaneId は "main" です（レーンからさらに分かれることはできません）。"main" 以外のレーンは 12 個までです。
• レーンを付けるときは、分かれる所と合流する所を 1 組だけ入れます。分かれる所の laneIds は "main" 以外の全部のレーン（2 個以上）、joinId は合流する所の id です。合流する所の laneIds は分かれる所と同じレーン、mode は "and" です。
• 分かれる所の afterStepId は "main" の工程で、placementExecution が "parallel" の工程は指定できません。合流する所の nextStepId は、それより後ろの "main" の工程です。null のときは、分かれた後の工程を全部どれかのレーンに入れます。
• 分かれてから合流するまでの工程は全部どれかのレーンに入れ、それ以外の工程は "main" に入れます。1 つの工程を 2 つのレーンに入れることはできません。lanes[].stepIds には、このプロジェクトの工程だけを入れられます。レーンにはそれぞれ工程を 1 つ以上入れます。
• 確認工程の行き先・差し戻し先と、onDenied・onDegraded の "goto" の行き先には、同じレーンの工程だけを指定できます。"main" では、分かれる前と合流した後をまたげません。
• "main" 以外のレーンが無く、forks・joins も空なら、null と同じです（レーンを無くします）。

レスポンス（200 OK）

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

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	projectId が UUID の形式ではない、baseDigest が無い・空・文字列ではない、変える項目が無い、name を空・空白だけにした、description を空の文字列・空白だけ・null にした、name・status・tags・isShared・limits に null を送った、項目の型や値の誤り（タグの空・重なりを含みます）、または type・policy・connectSecret を送った
400	invalid_body	ボディが壊れた JSON、または JSON のオブジェクトではない
400	invalid_flow_structure	レーンの定義が、上の決まりに合わない
400	organization_not_member	付けられない組織を指定した
403	insufficient_scope	project:write スコープが不足
403	forbidden	システム連携のトークンで呼び出した
403	owner_only	オーナーではないメンバー
403	sso_required	SSO でログインしていない利用者
404	project_not_found	プロジェクトが存在しない、またはメンバーではない
409	stale_base	取得した後にプロジェクトが変わっている
409	organization_locked	組織はすでに付いている
403	license_status_unavailable	"archived" から戻そうとしたが、ライセンスを確かめられない
409	project_limit_reached	"archived" から戻そうとしたが、プロジェクトの数が上限に達している
413	body_too_large	ボディが 16 KiB を超える
415	unsupported_media_type	ボディの Content-Type が application/json ではない
503	organization_unavailable	所属している組織を確かめられない

DELETE/v1/projects/{projectId}

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

パスパラメータ

パラメータ	型	必須	説明
projectId	string	必須	プロジェクト ID（UUID）

レスポンス（200 OK）

JSON

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

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

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	projectId が UUID の形式ではない
403	insufficient_scope	project:delete スコープが不足
403	forbidden	システム連携のトークンで呼び出した
403	owner_only	オーナーではないメンバー
403	sso_required	SSO でログインしていない利用者
404	project_not_found	プロジェクトが存在しない、メンバーではない、またはすでに消した

GET/v1/projects/{projectId}/control

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

パスパラメータ

パラメータ	型	必須	説明
projectId	string	必須	プロジェクト ID（UUID）

レスポンスフィールド（200 OK）

フィールド	型	説明
tenantProfile	string | null	テナント全体の基本ルール。"open" / "guarded" / "strict"。確かめられないときは null
tenantSource	string | null	tenantProfile の出どころ。"governance_policies"（管理画面で設定）/ "default"（設定が無いので既定）/ "unavailable"（確かめられない）
projectProfile	string | null	このプロジェクトの基本ルール
effectiveProfile	string | null	実際に効く基本ルール（テナント全体とこのプロジェクトのうち厳しい方）。tenantProfile が null のときは null
deny	array	実行ルールで禁止している操作
gates	array	有効な確認工程の配列
gates[].stepId	string	工程の ID
gates[].position	number	工程の位置
gates[].name	string	工程の名前
gates[].gateKind	string	確認の種類。"review"（確認）または "manual"（手作業）
gates[].mode	string	確認方法。"blocking"（担当者の判断を待つ）または "notify_only"（期限後に自動で進める）
gates[].overdueAction	string	期限を過ぎたら。"none"（通知して待ち続ける）/ "proceed"（自動で進める）/ "send_back"（自動で差し戻す）/ "reject"（自動で却下する）
gates[].approverUserIds	array	確認担当者の利用者 ID の配列
gates[].deadlineHours	number | null	確認期限（時間）
operationClasses	null	今は使っていない項目です（いつも null）

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	projectId が UUID の形式ではない
403	insufficient_scope	project:read スコープが不足
403	forbidden	システム連携のトークンで呼び出した
403	sso_required	SSO でログインしていない利用者
404	project_not_found	プロジェクトが存在しない、またはメンバーではない

工程

工程は、プロジェクトの流れの単位です。Agent が実行する工程（defaultZone が "ai"）と、人が判断する確認工程（"gate"）があります。工程は 12 個までです。工程を消して 2 個より少なくすることはできません。

エンドポイント一覧

メソッド	エンドポイント	説明	スコープ (SaaS)
POST	/v1/projects/{projectId}/steps	工程を足す	project:write
PATCH	/v1/projects/{projectId}/steps/{stepId}	工程を変える	project:write
PUT	/v1/projects/{projectId}/steps/order	工程を並べ替える	project:write
DELETE	/v1/projects/{projectId}/steps/{stepId}	工程を消す	project:write

工程の項目

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

フィールド	型	説明
stepId	string	工程の ID（UUID）
position	number | null	工程の位置（1 から）
name	string | null	工程の名前。null のときは画面で既定の名前（「ステップ 1」など）が出ます
description	string | null	説明
enabled	boolean | null	有効かどうか
defaultZone	string | null	"ai"（Agent が実行）または "gate"（確認工程）
reworkToStepId	string | null	差し戻すときの戻り先の工程の ID（確認工程で使います）
gateConfig	object | null	確認工程の設定（下の表）
gateKind	string | null	確認の種類。"review"（確認。Agent の結果を人が判断する）または "manual"（手作業。人が作業してから進める）
schedule	object | null	工程の時刻（workflow だけ）。expression（cron 式）と timezone
scheduleNextFireAt	string | null	工程の時刻で次に動く予定の日時（ISO 8601）
onDenied	string | null	「ルールにより実行できない場合」の扱い。"gate"（確認を求める）/ "closed_failed"（失敗として閉じる）/ "goto"（outcomeRoutes の工程へ進める）
onDegraded	string | null	「Agent の報告による失敗のとき」の扱い。"gate"（確認を求める）/ "proceed"（そのまま進める）/ "goto"（outcomeRoutes の工程へ進める）
outcomeRoutes	object | null	onDenied・onDegraded が "goto" のときの行き先
outcomeRoutes.onDenied.stepId	string	「ルールにより実行できない場合」に進める工程の ID
outcomeRoutes.onDegraded.stepId	string	「Agent の報告による失敗のとき」に進める工程の ID
laneId	string | null	この工程が属するレーンの ID
placementExecution	string | null	"parallel"（この工程に置いた Agent を同時に実行する）。null は置いた順に 1 つずつ実行
digest	string	工程を変えるときに baseDigest に送る値

確認工程の設定（gateConfig）:

フィールド	型	説明
approverUserIds	array	確認担当者の利用者 ID の配列（プロジェクトのメンバーから 20 人まで）
deadlineHours	number | null	確認期限（時間。1〜720）
mode	string | null	確認方法。"blocking"（担当者の判断を待つ）または "notify_only"（期限後に自動で進める）
overdueAction	string | null	期限を過ぎたら。"none"（通知して待ち続ける）/ "proceed"（自動で進める）/ "send_back"（自動で差し戻す）/ "reject"（自動で却下する）
escalateToUserId	string | null	期限超過時の連絡先の利用者 ID（プロジェクトのメンバー）
destinations	array	担当者が進め先として選べる工程（2〜5 個。この工程より後ろの工程）。設定していないときは含まれません
destinations[].id	string	行き先の ID（英数字と _ - の 64 文字まで）
destinations[].label	string	画面に出す名前（100 文字まで）
destinations[].stepId	string	進め先の工程の ID

確認工程の設定が無いとき（gateConfig が null、または項目が無い・null のとき）は、mode は "blocking"、deadlineHours は 24 時間、overdueAction は "none"、期限超過時の連絡先は無しとして動きます。gateKind が null のときは "review" です。

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

工程の項目	workflow	cycle
確認工程（defaultZone の "gate"）と、その設定（gateConfig・gateKind）	付けられる	400（cycle_gate_not_allowed）
onDenied・onDegraded の "gate"	付けられる	400（cycle_gate_not_allowed）
onDenied・onDegraded の "goto" と outcomeRoutes	付けられる	400（cycle_route_not_allowed）
placementExecution の "parallel"	"ai" の工程だけ付けられる	400（parallel_workflow_only）
schedule（工程の時刻）	付けられる	400（invalid_parameter）
reworkToStepId（差し戻し先）	付けられる	400（invalid_parameter）

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

POST/v1/projects/{projectId}/steps

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

パスパラメータ

パラメータ	型	必須	説明
projectId	string	必須	プロジェクト ID（UUID）

リクエストボディ

フィールド	型	必須	説明
name	string | null	—	工程の名前（100 文字まで。空の文字列・null は既定の名前です。空白だけにはできません）
description	string | null	—	説明（2000 文字まで。空の文字列・null は説明なし）
defaultZone	string	—	"ai" または "gate"。省くと "ai"。null・空の文字列は送れません
afterStepId	string	—	この工程の後ろに足す（このプロジェクトの工程の ID）
beforeStepId	string	—	この工程の前に足す（このプロジェクトの工程の ID）。afterStepId と両方を指定すると、この工程の前に足します。どちらも省くと末尾に足します
gateConfig	object | null	—	確認工程の設定（工程の項目の gateConfig と同じ形。destinations は工程を変えるときに設定します）。null は設定なし
placementExecution	string | null	—	"parallel" で同時に実行。null か "serial" は 1 つずつ実行

足した工程は有効です。レーンのあるプロジェクトでは、beforeStepId を指定したときはその工程と、afterStepId だけのときはその工程と同じレーンに入ります。

レスポンス（201 Created）

フィールド	型	説明
step	object	足した工程
steps	array	足した後の全部の工程（並び順）
stepsDigest	string	足した後の工程の並びの値

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	projectId が UUID の形式ではない、afterStepId・beforeStepId がこのプロジェクトの工程ではない、または項目の型や長さ・値の誤り（name の空白だけ、defaultZone の null・空の文字列を含みます）
400	invalid_body	ボディが壊れた JSON、または JSON のオブジェクトではない
400	step_reference_on_create	gateConfig に destinations を送った（null・空の配列を含みます。進め先は、工程を足した後に工程を変える API で設定します）
400	cycle_gate_not_allowed	cycle に確認工程を足そうとした
400	parallel_workflow_only	cycle の工程に "parallel" を指定した
400	parallel_ai_only	確認工程に "parallel" を指定した
400	parallel_not_for_marketplace	マーケットプレイス版の登録 Agent を置いたプロジェクトで "parallel" を指定した
400	approver_not_member	確認担当者にメンバーではない利用者を指定した
400	approvers_required	稼働中の workflow に、確認担当者のいない確認工程を足そうとした
400	escalate_to_not_member	期限超過時の連絡先にメンバーではない利用者を指定した
403	insufficient_scope	project:write スコープが不足
403	forbidden	システム連携のトークンで呼び出した
403	owner_only	オーナーではないメンバー
403	sso_required	SSO でログインしていない利用者
404	project_not_found	プロジェクトが存在しない、またはメンバーではない
409	too_many_steps	工程がすでに 12 個ある
409	flow_structure_conflict	レーンの定義と食い違う
413	body_too_large	ボディが 16 KiB を超える
415	unsupported_media_type	ボディの Content-Type が application/json ではない

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

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

パスパラメータ

パラメータ	型	必須	説明
projectId	string	必須	プロジェクト ID（UUID）
stepId	string	必須	工程の ID（UUID）

リクエストボディ

フィールド	型	必須	説明
baseDigest	string	必須	その工程の digest
name	string | null	—	工程の名前（100 文字まで）。空の文字列・null で既定の名前に戻します。空白だけにはできません
description	string	—	説明（2000 文字まで。空の文字列・空白だけ・null にはできません）
defaultZone	string	—	"ai" または "gate"
enabled	boolean	—	有効かどうか
gateConfig	object | null	—	確認工程の設定。送った項目だけを今の値に重ねます。null で設定を外します
gateKind	string | null	—	"review" または "manual"
reworkToStepId	string | null	—	差し戻し先（この工程より前の工程）。null で外します
onDenied	string | null	—	"gate" / "closed_failed" / "goto"
onDegraded	string | null	—	"gate" / "proceed" / "goto"
outcomeRoutes	object | null	—	"goto" のときの行き先（この工程より後ろの工程）。送ると全部が置き換わります（onDenied だけを変えるときも onDegraded を一緒に送ってください）。null で外します。onDenied・onDegraded のどちらも含まないときは、送らなかったのと同じです
placementExecution	string | null	—	"parallel" で同時に実行。null か "serial" は 1 つずつ実行
schedule	object | null	—	工程の時刻（workflow だけ）。expression（5 項目の cron 式）と timezone（省くと UTC）。null で外します

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

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

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

レスポンス（200 OK）

フィールド	型	説明
step	object	変えた後の工程（新しい digest）

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	projectId・stepId が UUID の形式ではない、baseDigest が無い・空・文字列ではない、変える項目が無い、name を空白だけにした、description を空の文字列・空白だけ・null にした、defaultZone・enabled に null を送った、項目の型や長さ・値の誤り、または cycle に schedule・reworkToStepId を送った
400	invalid_body	ボディが壊れた JSON、または JSON のオブジェクトではない
400	cycle_gate_not_allowed	cycle の工程を確認工程にしようとした、または onDenied・onDegraded に "gate" を指定した
400	cycle_route_not_allowed	cycle の工程に "goto" を指定した
400	parallel_workflow_only	cycle の工程に "parallel" を指定した
400	parallel_ai_only	確認工程に "parallel" を指定した
400	parallel_not_for_marketplace	マーケットプレイス版の登録 Agent を置いたプロジェクトで "parallel" を指定した
400	approver_not_member	確認担当者にメンバーではない利用者を指定した
400	approvers_required	稼働中の workflow で、有効な確認工程の確認担当者がいなくなる
400	escalate_to_not_member	期限超過時の連絡先にメンバーではない利用者を指定した
400	invalid_send_back_step	差し戻し先が、この工程より前の工程ではない
400	invalid_destinations	destinations の形の誤り（2〜5 個ではない、ID・名前・工程の重複 など）
400	destinations_gate_only	確認工程ではない工程に destinations を設定しようとした
400	destinations_notify_only	確認方法が "notify_only" の工程に destinations を設定しようとした
400	invalid_destination_step	destinations の工程が、この工程より後ろの工程ではない
400	invalid_outcome_routes	outcomeRoutes の形の誤り
400	invalid_outcome_route	"goto" の行き先が無い、またはこの工程より後ろの工程ではない
403	insufficient_scope	project:write スコープが不足
403	forbidden	システム連携のトークンで呼び出した
403	owner_only	オーナーではないメンバー
403	sso_required	SSO でログインしていない利用者
404	step_not_found	工程が存在しない、またはメンバーではないプロジェクト
409	stale_base	取得した後に工程が変わっている
409	flow_structure_conflict	レーンの定義と食い違う
413	body_too_large	ボディが 16 KiB を超える
415	unsupported_media_type	ボディの Content-Type が application/json ではない

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

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

パスパラメータ

パラメータ	型	必須	説明
projectId	string	必須	プロジェクト ID（UUID）

リクエストボディ

フィールド	型	必須	説明
baseDigest	string	必須	プロジェクトの取得の stepsDigest
stepIds	array	必須	全部の工程の ID を、新しい並び順で（重複なし）

レスポンス（200 OK）

フィールド	型	説明
steps	array	並べ替えた後の全部の工程
stepsDigest	string	並べ替えた後の工程の並びの値

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	projectId が UUID の形式ではない、baseDigest が無い・空・文字列ではない、または stepIds が全部の工程の並びになっていない
400	invalid_body	ボディが壊れた JSON、または JSON のオブジェクトではない
403	insufficient_scope	project:write スコープが不足
403	forbidden	システム連携のトークンで呼び出した
403	owner_only	オーナーではないメンバー
403	sso_required	SSO でログインしていない利用者
404	project_not_found	プロジェクトが存在しない、またはメンバーではない
409	stale_base	取得した後に工程の並びが変わっている
409	flow_structure_conflict	レーンの定義と食い違う
413	body_too_large	ボディが 16 KiB を超える
415	unsupported_media_type	ボディの Content-Type が application/json ではない

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

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

パスパラメータ

パラメータ	型	必須	説明
projectId	string	必須	プロジェクト ID（UUID）
stepId	string	必須	工程の ID（UUID）

レスポンス（200 OK）

フィールド	型	説明
stepId	string	消した工程の ID
deleted	boolean	いつも true
historyKept	boolean	記録のために工程を残したかどうか
steps	array	消した後の全部の工程
stepsDigest	string	消した後の工程の並びの値

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	projectId・stepId が UUID の形式ではない
403	insufficient_scope	project:write スコープが不足
403	forbidden	システム連携のトークンで呼び出した
403	owner_only	オーナーではないメンバー
403	sso_required	SSO でログインしていない利用者
404	step_not_found	工程が存在しない、またはメンバーではないプロジェクト
409	min_steps	工程が 2 つしかない
409	flow_structure_conflict	レーンの定義と食い違う（分かれる所・合流した後の工程や、レーンの最後の工程は、先にレーンの定義を直してから消します）

配置

配置は、ライブラリの Agent をプロジェクトの工程に置いたものです。1 つのプロジェクトに同じ Agent を置けるのは 1 つの配置だけで、1 つの配置は複数の工程（担当工程）を持てます。cycle では、Agent を動かす周期（巡回）を配置と工程の組ごとに決めます。

エンドポイント一覧

メソッド	エンドポイント	説明	スコープ (SaaS)
GET	/v1/projects/{projectId}/placements	配置の一覧を取得	project:read
GET	/v1/projects/{projectId}/placements/{placementId}	配置を取得	project:read
POST	/v1/projects/{projectId}/placements	配置を置く	project:write
DELETE	/v1/projects/{projectId}/placements/{placementId}	配置を外す	project:write
PUT	/v1/projects/{projectId}/placements/{placementId}/steps	配置の担当工程を変える	project:write
GET	/v1/projects/{projectId}/memory-candidates	配置の記憶の候補を取得	project:read
PATCH	/v1/projects/{projectId}/placements/{placementId}/memory	配置の記憶を変える	project:write
PATCH	/v1/projects/{projectId}/placements/{placementId}/schedule	巡回を止める・再開する・周期を変える（cycle だけ）	project:write

配置の項目

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

フィールド	型	説明
placementId	string	配置の ID（UUID）
agentId	string | null	置いた Agent の ID（ライブラリの Agent の ID）
displayOrder	number | null	表示の順
name	string | null	Agent の名前
description	string | null	Agent の説明
goal	string | null	Agent のゴール（指示）
guardrail	string | null	Agent のガードレール
skills	array	Agent が使うスキル（skillId・name）
skillCount	number | null	スキルの数
playbookId	string | null	Agent が使うプレイブックの ID
playbookName	string | null	プレイブックの名前
inputFiles	array	Agent の入力ファイル（filename だけ）
stepIds	array	担当工程の ID の配列
sweeps	array	巡回の設定（cycle）。担当工程ごとに stepId・cron・timezone・enabled
runtimeConfigs	array	工程ごとの実行の設定（stepId・runtimeConfig）。runtimeConfig の中身は保存した形のまま返ります
memoryOrgId	string | null	配置の記憶の組織
memoryJobId	string | null	配置の記憶の職種
agentOwnerUserId	string | null	置いた Agent の持ち主の利用者 ID
isShared	boolean | null	置いた Agent を公開しているかどうか
runtimeKind	string | null	Agent の実行環境の種類
marketplaceAgentId	string | null	マーケットプレイス版の登録 Agent の ID。それ以外は null
exclusiveToThisProject	boolean | null	この Agent を置いているのがこのプロジェクトだけかどうか
digest	string	配置を変える API（担当工程・記憶・巡回）で baseDigest に送る値。担当工程・記憶・実行の設定・巡回から作られ、Agent の中身を変えても変わりません

GET/v1/projects/{projectId}/placements

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

レスポンスフィールド（200 OK）

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

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	projectId が UUID の形式ではない
403	insufficient_scope	project:read スコープが不足
403	forbidden	システム連携のトークンで呼び出した
403	sso_required	SSO でログインしていない利用者
404	project_not_found	プロジェクトが存在しない、またはメンバーではない

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

配置を 1 件取得します。

レスポンスフィールド（200 OK）

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

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	projectId・placementId が UUID の形式ではない
403	insufficient_scope	project:read スコープが不足
403	forbidden	システム連携のトークンで呼び出した
403	sso_required	SSO でログインしていない利用者
404	placement_not_found	配置が存在しない、ほかのプロジェクトの配置、またはメンバーではないプロジェクト

POST/v1/projects/{projectId}/placements

ライブラリの Agent を、プロジェクトの工程に置きます。オーナーだけが呼べます。置けるのは、自分の Agent だけです（公開されている Agent はライブラリでコピーしてから置きます）。

リクエストボディ

フィールド	型	必須	説明
agentId	string	必須	置く Agent の ID（UUID）
stepIds	array	—	担当工程の ID の配列（このプロジェクトの工程を 12 個まで）。省くと担当工程なしで置きます

• 同じ Agent がすでに置いてあるときは 409 Conflict（placement_already_exists）です。担当工程まで同じときは、送り直しとして、置いてある配置を返します。担当工程を変えるときは、配置の担当工程を変える API を使います。
• Agent の入力ファイルのうち、実行のときに渡るのはプロジェクトを作った利用者のファイルだけです。
• 新しく置いた配置は、配置の並び（displayOrder）の最後に入ります。ただし、前に外した配置（過去のワークフローの実行が使っていたため残っている配置）と同じ Agent を置くと、その配置が元の ID と並びの位置で戻ります。同じ工程の配置を 1 つずつ実行するときは、この並びの順に動きます。配置を並べ替える API はありません。

レスポンス（201 Created）

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

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	projectId・agentId が UUID の形式ではない、または stepIds の誤り（12 個を超える、このプロジェクトの工程ではない、同じ工程を重ねた など）
400	invalid_body	ボディが壊れた JSON、または JSON のオブジェクトではない
400	agent_not_found	agentId の Agent が存在しない、または見えない
400	agent_not_owned	自分の Agent ではない
403	insufficient_scope	project:write スコープが不足
403	forbidden	システム連携のトークンで呼び出した
403	owner_only	オーナーではないメンバー
403	sso_required	SSO でログインしていない利用者
404	project_not_found	プロジェクトが存在しない、またはメンバーではない
409	placement_already_exists	同じ Agent がすでに置いてある（担当工程が違う）
409	unsupported_runtime	この API では置けない Agent（マーケットプレイス版の登録 Agent など）
413	body_too_large	ボディが 16 KiB を超える
415	unsupported_media_type	ボディの Content-Type が application/json ではない

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

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

レスポンス（200 OK）

フィールド	型	説明
placementId	string	外した配置の ID
deleted	boolean	いつも true
historyKept	boolean	記録のために配置を残したかどうか

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	projectId・placementId が UUID の形式ではない
403	insufficient_scope	project:write スコープが不足
403	forbidden	システム連携のトークンで呼び出した
403	owner_only	オーナーではないメンバー
403	sso_required	SSO でログインしていない利用者
404	placement_not_found	配置が存在しない、ほかのプロジェクトの配置、またはメンバーではないプロジェクト

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

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

リクエストボディ

フィールド	型	必須	説明
baseDigest	string	必須	その配置の digest
stepIds	array	必須	担当工程の ID の配列（このプロジェクトの工程を 12 個まで）

レスポンス（200 OK）

フィールド	型	説明
placement	object	変えた後の配置（新しい digest）

エラーレスポンス

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

GET/v1/projects/{projectId}/memory-candidates

配置の記憶に選べる組織と職種の候補を取得します。候補は、プロジェクトのメンバーの組織と職種です。

レスポンスフィールド（200 OK）

フィールド	型	説明
organizations	array	組織の候補（orgId・label）
jobs	array	職種の候補（jobId・label）
unresolved	number | null	組織と職種を確かめられなかったメンバーの数

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	projectId が UUID の形式ではない
403	insufficient_scope	project:read スコープが不足
403	forbidden	システム連携のトークンで呼び出した
403	sso_required	SSO でログインしていない利用者
404	project_not_found	プロジェクトが存在しない、またはメンバーではない

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

配置の記憶（Agent が業務で読む組織・職種の記憶）を変えます。送った項目だけを変えます。オーナーだけが呼べます。

リクエストボディ

フィールド	型	必須	説明
baseDigest	string	必須	その配置の digest
orgId	string | null	—	組織。新しく選べるのは記憶の候補にある値だけ。null か空の文字列で外します
jobId	string | null	—	職種。新しく選べるのは記憶の候補にある値だけ。null か空の文字列で外します

orgId・jobId のうち、少なくとも 1 つを送ってください。

レスポンス（200 OK）

フィールド	型	説明
placement	object	変えた後の配置（新しい digest）

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	projectId・placementId が UUID の形式ではない、baseDigest が無い・空・文字列ではない、変える項目が無い、または orgId・jobId が文字列でも null でもない
400	invalid_body	ボディが壊れた JSON、または JSON のオブジェクトではない
400	memory_not_candidate	記憶の候補に無い値を指定した
403	insufficient_scope	project:write スコープが不足
403	forbidden	システム連携のトークンで呼び出した
403	owner_only	オーナーではないメンバー
403	sso_required	SSO でログインしていない利用者
404	placement_not_found	配置が存在しない、ほかのプロジェクトの配置、またはメンバーではないプロジェクト
409	stale_base	取得した後に配置が変わっている
413	body_too_large	ボディが 16 KiB を超える
415	unsupported_media_type	ボディの Content-Type が application/json ではない
503	memory_candidates_unavailable	メンバーの組織・職種を確かめられない（時間をおいて送り直してください）

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

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

リクエストボディ

フィールド	型	必須	説明
baseDigest	string	必須	その配置の digest
stepId	string	—	巡回の工程の ID（配置の担当工程）。担当工程が 1 つの配置では省けます
enabled	boolean	—	true で再開、false で停止
cron	string	—	周期（5 項目の cron 式。100 文字まで）
timezone	string	—	タイムゾーン（IANA のタイムゾーン名。64 文字まで。例: "Asia/Tokyo"）

• enabled・cron・timezone のうち、少なくとも 1 つを送ってください。送らなかった項目は今の値のままです。
• その工程にまだ巡回が無いとき（初めて設定するとき）は cron が必須です。enabled を省くと止めたまま、timezone を省くと UTC になります。

レスポンス（200 OK）

フィールド	型	説明
placement	object	変えた後の配置（新しい digest）

エラーレスポンス

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

トリガー

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

エンドポイント一覧

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

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

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

定期実行の設定はそのまま維持されます。発火による実行は、定期実行とは別に追加されるものです。ただし、先の発火がまだ動き始めていない場合、あとの発火はその実行にまとまることがあります。まとまったときは jobId に先の発火と同じ値が返るため、発火の回数と実行の回数は必ずしも一致しません。

パスパラメータ

パラメータ	型	必須	説明
projectId	string	必須	プロジェクトの ID（UUID）
triggerId	string	必須	発火するトリガーの ID（UUID）

リクエストボディ

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

レスポンスフィールド（202 Accepted）

フィールド	型	説明
result	string	"accepted"（新しく受け付けた）または "duplicate"（同じ eventId で受付済み）
jobId	string	受付先のジョブ 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	説明
400	invalid_event_id	eventId が無い、または形式が不正
400	invalid_parameter	projectId または triggerId が UUID の形式ではない
400	invalid_body	リクエストボディが壊れた JSON、または JSON のオブジェクトではない
415	unsupported_media_type	リクエストボディがあるのに、Content-Type が application/json ではない
403	insufficient_scope	project:run スコープが不足
403	owner_only	プロジェクトのメンバーだが、オーナーではない
404	trigger_not_found	プロジェクト・トリガーが存在しない、アクセス権が無い、Webhook ではないトリガーを指定した、または workflow 型のプロジェクトを指定した
409	trigger_disabled	トリガーが無効化されている
409	project_not_active	プロジェクトが実行可能な状態にない
409	placement_unavailable	発火対象のエージェント配置が存在しない、または実行主体が未設定
409	event_conflict	同じ eventId で payload が異なる
413	body_too_large	リクエストボディが 16 KiB を超過

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

実行履歴（GET /v1/projects/{projectId}/executions）は、発火の応答の jobId では絞り込めません。次の手順で見分けます。

1. 実行履歴を、トリガーの配置（placementId）と、発火した時刻（from）で絞り込みます。
2. 候補の実行の結果（GET /v1/projects/{projectId}/executions/{executionId}）の jobId を、発火の応答の jobId と照らします。

まだ動き始めていない実行にまとめられた発火は、同じ jobId の 1 つの実行になります。

ワークフローの実行（run）

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

エンドポイント一覧

メソッド	エンドポイント	説明	スコープ (SaaS)
POST	/v1/projects/{projectId}/runs	ワークフローの実行を開始	project:run
GET	/v1/projects/{projectId}/runs/{runId}	ワークフローの実行を取得	project:read
GET	/v1/projects/{projectId}/runs	ワークフローの実行の一覧を取得	project:read
GET	/v1/projects/{projectId}/runs/{runId}/config	ワークフローの実行を始めたときの設定を取得	project:read

POST/v1/projects/{projectId}/runs

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

リクエストヘッダー

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

パスパラメータ

パラメータ	型	必須	説明
projectId	string	必須	プロジェクトの ID（UUID）

リクエストボディ

ボディは不要です。送信する場合は JSON のオブジェクトにしてください。含めたフィールドは無視されます。

レスポンスフィールド（201 Created / 200 OK）

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

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

リクエスト例

curl

curl -X POST https://api.fd.agenticstar.tm.softbank.jp/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 '{}'

レスポンス例

JSON

{
  "runId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Idempotency-Key の扱い

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

エラーレスポンス

ステータス	code	説明
400	idempotency_key_required	Idempotency-Key ヘッダーが無い
400	idempotency_key_invalid	Idempotency-Key の長さまたは文字種が不正
400	invalid_parameter	projectId が UUID の形式ではない
400	invalid_body	リクエストボディが壊れた JSON、または JSON のオブジェクトではない
413	body_too_large	リクエストボディが 16 KiB を超過
415	unsupported_media_type	リクエストボディがあるのに、Content-Type が application/json ではない
403	insufficient_scope	project:run スコープが不足
403	owner_only	プロジェクトのメンバーだが、オーナーではない
404	project_not_found	プロジェクトが存在しない、またはアクセス権が無い
400	approvers_required	有効な確認工程に確認担当者が設定されていない
409	unsupported_project_type	cycle 型のプロジェクトを指定した
409	project_inactive	プロジェクトが有効な状態ではない（一時停止中、またはアーカイブ済み）
409	unsupported_runtime	プロジェクト内のエージェントの実行環境が混在しているなど、実行できない構成
429	too_many_active_runs	同じプロジェクトで、実行中と確認待ちの実行が合わせて上限（3 件）に達している

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

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

パスパラメータ

パラメータ	型	必須	説明
projectId	string	必須	プロジェクトの ID（UUID）
runId	string	必須	実行の ID（UUID）

レスポンスフィールド（200 OK）

フィールド	型	説明
runId	string	実行の ID（UUID）
status	string	実行の状態。"running"（実行中）/ "waiting_gate"（確認待ち）/ "closed_done"（完了）/ "closed_rejected"（却下で終了）/ "closed_failed"（失敗で終了）/ "cancelled"（中断）のいずれか。"running" と "waiting_gate" 以外は、実行が終わったことを表します
originType	string | null	実行の始まり方。"manual"（画面から開始）/ "api"（API で開始）/ "mail"（メールで開始）/ "cron"（定期実行）のいずれか
originRef	string | null	始まり方ごとの参照値。API で開始した実行では、開始したときの Idempotency-Key の値
currentStepId	string | null	進んでいる工程の ID（UUID）。レーンに分かれて進んでいる間は、分岐する前の工程の ID。完了した実行では null。ほかの理由で終わった実行では、終わったときの工程の ID が残る場合があります
startedByRef	string | null	実行を始めたもの。値は下の「実行を始めたもの」の表のとおり
actorLabel	string | null	利用者ではない起動者の表示名（システム連携の名前、またはメールの送信元のアドレス）。それ以外は null
startedAt	string | null	開始日時（ISO 8601）。開始前は null
endedAt	string | null	終了日時（ISO 8601）。終了前は null
summary	string | null	完了した実行で、出力が記録された最後の完了した工程の出力（先頭 2,000 文字）。そうした工程が無い場合と、完了していない実行では null
runtimeKind	string | null	実行環境の種類（"autonomous"）。古い実行では null の場合があります
cancelRequestedAt	string | null	中断が求められた日時（ISO 8601）。求められていなければ null
configRevision	number | null	案件設定の版（Marketplace 版の実行だけ）。SaaS 版の実行では null
steps	array	工程ごとの実行の記録。記録した順
steps[].runStepId	string	工程の実行の ID（"rs:" で始まる）
steps[].stepId	string | null	工程の ID（UUID）
steps[].placementId	string | null	その工程を担当した配置の ID（UUID）。Agent を動かさない行（確認の工程など）では null
steps[].executionId	string | null	Agent の実行の ID。Agent を動かし始めると付きます
steps[].conversationId	string | null	Agent の実行の会話の ID。Agent を動かし始めると付きます
steps[].status	string	"pending"（実行待ち）/ "running"（実行中）/ "waiting_gate"（確認待ち）/ "done"（完了）/ "failed"（失敗）/ "skipped"（実行を省略）のいずれか
steps[].attempt	number | null	同じ回の中での再試行の回数（1 から）
steps[].lane	string | null	工程が属するレーンの ID。レーンに分かれていない工程は "main"
steps[].scheduledAt	string | null	工程に時刻が設定されているとき、その時刻まで待つ行の予定日時（ISO 8601）。動き始めると null
steps[].startedAt	string | null	開始日時（ISO 8601）
steps[].endedAt	string | null	終了日時（ISO 8601）
steps[].outputSummary	string | null	工程の出力の要約
steps[].outcome	string | null	Agent の実行の結果。"completed" / "incomplete" / "failed" / "timeout" / "stopped" / "denied" / "skipped" のいずれか。結果の無い行では null
steps[].reasonCode	string | null	結果の理由コード
steps[].held	boolean	プロジェクトの一時停止で止めていて、再開を待っているか
steps[].visit	number | null	この工程に来た何回目か（差し戻しで増えます）。記録の無い行では null
steps[].reworkReason	string | null	差し戻しの理由
steps[].gateFor	string | null	この確認の行が、どの工程の実行（runStepId）のために立ったか
steps[].routedFrom	string | null	行き先を決めて工程を飛ばしたとき、行き先を決めた工程の実行（runStepId）
steps[].late	string | null	結果が遅れて届き、進行に使わなかった理由
steps[].gate	object | null	確認の工程の要約。確認の工程ではない行では null
steps[].gate.decision	string | null	"proceed"（進める）/ "send_back"（差し戻す）/ "reject"（却下）のいずれか。決まっていなければ null
steps[].gate.waitSource	string | null	何を待つ確認か。"human"（人の判断）/ "external"（外部の条件）
plannedPlacements	array	開始したときの設定で、動く予定の工程と配置の並び
plannedPlacements[].stepId	string | null	工程の ID（UUID）
plannedPlacements[].placementId	string | null	配置の ID（UUID）。確認の工程と Agent の無い工程では null
lanes	array	分岐した後の、レーンごとの状況。分岐する前と、レーンを使わない実行では空の配列
lanes[].laneId	string	レーンの ID
lanes[].name	string | null	レーンの名前
lanes[].position	number | null	レーンの並び（1 から）
lanes[].state	string	"running"（実行中）/ "waiting_gate"（確認待ち）/ "arrived"（合流待ち）/ "closed"（終了）のいずれか
lanes[].currentStepId	string | null	そのレーンで進んでいる工程の ID（UUID）。合流待ちのレーンでは null。終わったレーンでは、最後の工程の ID が残る場合があります
lanes[].arrived	boolean	合流する地点に着いたか

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

実行を始めたもの

始めたもの	startedByRef	actorLabel
利用者（画面・API、またはメンバーのアドレスから送ったメール）	利用者 ID	null
システム連携	"client:" に続くシステム連携の Client ID。Client ID が分からない場合は "system:federation-api"	システム連携の名前（分からない場合は null）
メンバーではないアドレスから送ったメール	"mail:" に続く送信元のハッシュ	送信元のアドレス
定期実行	null	null

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": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "actorLabel": null,
  "startedAt": "2026-09-17T01:30:00.000Z",
  "endedAt": null,
  "summary": null,
  "runtimeKind": "autonomous",
  "cancelRequestedAt": null,
  "configRevision": null,
  "steps": [
    {
      "runStepId": "rs:1042",
      "stepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
      "placementId": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8",
      "executionId": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
      "conversationId": "9c8b7a6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
      "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
    }
  ],
  "plannedPlacements": [
    { "stepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f", "placementId": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8" },
    { "stepId": "c2f1a8e4-6b3d-4e7a-9c15-8d2e4f6a7b90", "placementId": null }
  ],
  "lanes": []
}

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	projectId または runId が UUID の形式ではない
403	insufficient_scope	project:read スコープが不足
404	run_not_found	実行が存在しない、別のプロジェクトの実行を指定した、またはアクセス権が無い

GET/v1/projects/{projectId}/runs

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

クエリパラメータ

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

レスポンスフィールド（200 OK）

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

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

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	projectId・placementId が UUID の形式ではない、または limit が 1-100 の整数でない
403	insufficient_scope	project:read スコープが不足
403	forbidden	システム連携のトークンで呼び出した
403	sso_required	SSO でログインしていない利用者
404	project_not_found	プロジェクトが存在しない、またはメンバーではない

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

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

レスポンスフィールド（200 OK）

フィールド	型	説明
runId	string	ワークフローの実行の ID
takenAt	string | null	設定を写した日時（ISO 8601）
steps	array | null	当時の工程。項目は「工程の項目」と同じです（digest を除きます。写しに無い項目は null）
lanes	array | null	当時のレーン（id・name・parentLaneId・stepIds）。レーンを持たない形の写しでは、"main" の 1 本に全部の工程が入り、name は null
forks	array | null	当時の分かれる所（id・afterStepId・laneIds・joinId）
joins	array | null	当時の合流する所（id・mode・laneIds・nextStepId）
placements	array | null	当時の配置（placementId・agentId・name・goal・guardrail・skills・playbookId・playbookName・runtimeConfigs・sweeps・stepIds）。goal・guardrail・skills・playbookId は始めたときの値
connectors	array | null	当時の連携先（kind・connectionId・name・ledgerEnabled）。name は始めたときの名前。connectionId は今の連携先の情報から求めます（管理画面で無効にされた・削除された、または確かめられなかったときは null）
sendBackLimit	number | null	差し戻せる回数の上限

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

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	projectId・runId が UUID の形式ではない
403	insufficient_scope	project:read スコープが不足
403	forbidden	システム連携のトークンで呼び出した
403	sso_required	SSO でログインしていない利用者
404	run_not_found	ワークフローの実行が存在しない、ほかのプロジェクトのもの、cycle のプロジェクト、またはメンバーではないプロジェクト

実行

実行は、Agent の 1 回の処理です。画面の実行履歴に 1 行ずつ並び、開くと実行記録になります。workflow の工程の実行（kind が "run_step"。executionId は rs:<数値> の形）と、cycle の巡回の実行（"sweep"。executionId は UUID）があります。

エンドポイント一覧

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

結果の値

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

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

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

GET/v1/projects/{projectId}/executions

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

クエリパラメータ

パラメータ	型	デフォルト	説明
from	string	—	この日時以降に始まった実行に絞り込み（ISO 8601）
to	string	—	この日時以前に始まった実行に絞り込み（ISO 8601）
placementId	string	—	この配置の実行に絞り込み（UUID）
stepId	string	—	この工程の実行に絞り込み（UUID）
runId	string	—	このワークフローの実行の工程の実行に絞り込み（UUID）
outcome	string	"all"	結果で絞り込み。結果の値のほか、"all"（すべて）/ "success"（completed）/ "problems"（incomplete・failed・timeout・stopped・denied）/ "running"（実行中）/ "missing"（記録不足）/ "unmeasured"（完遂を測っていない終わり方）
q	string	—	Agent 名・実行の UUID・会話 ID の一部で絞り込み（200 文字まで）。cycle の実行は executionId で探せます。workflow の工程の実行は rs:<数値> では探せないので、ワークフローの実行の steps[].executionId（UUID）で探します
limit	integer	50	1 ページの取得件数（1-100）
cursor	string	—	次ページ取得用カーソル（前回レスポンスの cursor 値）

レスポンスフィールド（200 OK）

フィールド	型	説明
executions	array	実行の配列
executions[].executionId	string	実行の ID。workflow は rs:<数値>、cycle は UUID
executions[].kind	string | null	"run_step"（workflow の工程）または "sweep"（cycle の巡回）
executions[].runId	string | null	ワークフローの実行の ID。cycle は null
executions[].stepId	string | null	工程の ID
executions[].stepName	string | null	工程の名前
executions[].stepPosition	number | null	工程の位置
executions[].placementId	string | null	配置の ID
executions[].agentName	string | null	Agent の名前
executions[].attempt	number | null	試行の回数（基盤の失敗でやり直すと増えます）
executions[].lane	string | null	レーンの ID（workflow。レーンが無いときは "main"）
executions[].outcome	string | null	結果（上の「結果の値」）
executions[].reasonCode	string | null	結果の理由。cycle は実行の終わり方の理由（例: "guardrail_blocked"）、workflow は工程の報告の理由
executions[].resultState	string | null	"terminal"（結果あり）/ "running"（実行中）/ "missing"（記録不足）/ "unmeasured"（完遂を測っていない）/ "not_applicable"（確認工程など、Agent の実行ではない行）
executions[].terminal	boolean | null	終わっているかどうか
executions[].startedAt	string | null	開始日時（ISO 8601）
executions[].endedAt	string | null	終了日時（ISO 8601）
executions[].summary	string | null	workflow の工程の最終応答（2000 文字まで）。cycle は null（実行の結果で読みます）
executions[].errorMessage	string | null	エラーのメッセージ（cycle）
executions[].originType	string | null	始まり方。workflow はワークフローの実行の始まり方（"manual" / "api" / "mail" / "cron"）、cycle は "cron"（巡回、または「メールで起動」）または "webhook"（トリガーの発火）
executions[].actorLabel	string | null	利用者ではない起動者の表示名（システム連携の名前、またはメールの送信元のアドレス）
executions[].gateDecision	string | null	確認工程の決定
executions[].conversationId	string | null	実行の会話の ID（実行の会話を読むときに使います）
hasMore	boolean	次のページが存在するかどうか
cursor	string	次ページ取得用カーソル。hasMore が true の場合のみ含まれます

結果の理由（reasonCode）では絞り込めません。

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	projectId・placementId・stepId・runId が UUID の形式ではない、from・to が ISO 8601 の日時ではない、outcome が上の値ではない、q が 200 文字を超える、limit・cursor が不正
403	insufficient_scope	project:read スコープが不足
403	forbidden	システム連携のトークンで呼び出した
403	sso_required	SSO でログインしていない利用者
404	project_not_found	プロジェクトが存在しない、またはメンバーではない

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

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

パスパラメータ

パラメータ	型	必須	説明
projectId	string	必須	プロジェクト ID（UUID）
executionId	string	必須	実行の ID（rs:<数値> または UUID）

レスポンスフィールド（200 OK）

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

フィールド	型	説明
envelope	object | null	実行の要約
envelope.counts	object	ツールの呼び出しの数（toolCalls・readCalls・mutatingSuccess・mutatingFailed・unknownCalls・opaqueCalls・workspaceWrites・mcpCalls・mcpFailed）
envelope.completionReport	object | null	Agent の完了の報告（completed・reasonCode・fixTarget・comment・truncated）
envelope.completionReport.fixTarget	string | null	直す先。"goal" / "skill" / "handoff" / "not_assigned" / "connection" / "rule" / "guardrail" / "external" / "unknown"。無いときは null
envelope.completionReport.comment	string | null	Agent のコメント（2 KB まで。切ったときは truncated が true）
envelope.platformFailure	string | null	基盤側の失敗の種類（結果が failed・timeout のとき）。"cancelled" / "signal_cancelled" / "kill_timeout" / "exception" / "invalid_output" / "model_refusal" / "content_filter" / "max_turns" / "loop_limit"。無いときは null
envelope.tools	array	呼んだツールの名前
usedSettings	object	使った設定
usedSettings.manifest	object | null	配ったスキル（スキル ID と版 ID）・プレイブック・ガードレールなど。実行の時系列の context.manifest の meta と同じで、項目名は記録のまま返ります
usedSettings.mcp	object | null	MCP の接続（設定・接続・失敗の数と名前など）。実行の時系列の runtime.mcp.connected の meta と同じ。MCP を使わない実行では null
questions	array	Agent からの質問（eventId・at・kind・optionsCount・optionsTruncated・answer）
questions[].answer	object | null	回答（at・eventType・actorKind・actorRef・digest・answerKind・optionIndex）。回答の記録が無ければ null
gates	array	確認依頼（workItemId・title・status・gateDecision・decidedAt・gateMode・decidedByKind・decidedByRef・waitSource・decisionReason・destinationLabel）
artifacts	array	成果物（artifactId・name・path・format・sha256・size。本文は含みません）
files	array	ファイル（filename・filepath・source・isPrimary・createdAt。分かるときは mimeType・size）。会話の API の deliverables と同じ形
configuration	object	実行の設定（policyVersion・policyDigest・policyProfile・model・mcpConfigVersion）
request	object	依頼。workflow は originType・originRef・triggerId・scheduledAt・runStartedAt・reworkReason、cycle は cron・timezone・jobName・originKind
jobId	string | null	ジョブの ID。トリガーの発火の応答の jobId と照らせます
gateFor	string | null	この確認がどの失敗した工程の実行のために作られたか（rs:<数値>）
routedFrom	string | null	行き先を決めた工程の実行（rs:<数値>）
late	string | null	結果が遅れて届き、進行に使わなかった理由
inputs	array	前の工程から受け取ったファイル（filename だけ）

• questions と gates の …Kind が "human" なら、…Ref は利用者 ID です。人ではないときは …Ref が null です。
• questions は、実行の記録の新しい方から 200 行の中にある質問だけです。それより古い質問は、実行の時系列（section が "confirmation" の行）で読みます。
• files は 20 件までです。
• ツールの呼び出しの 1 回ずつは、ツールの呼び出しの一覧で読みます。

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	projectId が UUID の形式ではない、または executionId が rs:<数値> でも UUID でもない
403	insufficient_scope	project:read スコープが不足
403	forbidden	システム連携のトークンで呼び出した
403	sso_required	SSO でログインしていない利用者
404	execution_not_found	実行が存在しない、ほかのプロジェクトの実行、またはメンバーではないプロジェクト

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

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

クエリパラメータ

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

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

レスポンスフィールド（200 OK）

フィールド	型	説明
operations	array	呼び出しの配列
operations[].operationId	string | null	呼び出しの ID
operations[].kind	string | null	行の種類。"access" はファイルを読む前の検査
operations[].resource	string | null	ツール（MCP は mcp:<サーバー名>:<ツール名>）
operations[].action	string | null	操作
operations[].path	string | null	読んだファイルのパス
operations[].mcpServer	string | null	MCP サーバーの名前
operations[].connectionId	string | null	連携先の ID（連携先の API の connectionId）
operations[].connectionKind	string | null	連携先の種類（"mcp" / "a2a"）
operations[].attempted	boolean	呼び出したかどうか
operations[].effect	string | null	呼び出しの結果
operations[].denied	string | null	止められたときの理由
operations[].durationMs	number | null	かかった時間（ミリ秒）
operations[].reason	string | null	検査の理由（kind が "access" の行だけ。例: "granted"・"path_not_found"）。ほかの行は null
hasMore	boolean	続きがあるかどうか
cursor	string	次ページ取得用カーソル。hasMore が true の場合のみ含まれます

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

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	projectId・executionId の形式の誤り、または cursor が不正
400	invalid_cursor	cursor を読めない
403	insufficient_scope	project:read スコープが不足
403	forbidden	システム連携のトークンで呼び出した
403	sso_required	SSO でログインしていない利用者
404	execution_not_found	実行が存在しない、ほかのプロジェクトの実行、またはメンバーではないプロジェクト

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

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

クエリパラメータ

パラメータ	型	デフォルト	説明
limit	integer	—	1 ページの行の数（1-100）。省くと 200 行
cursor	string	—	次ページ取得用カーソル（前回レスポンスの cursor 値）

レスポンスフィールド（200 OK）

フィールド	型	説明
rootExecutionId	string	実行の ID
origin	string | null	実行の始まり
owner	object | null	実行の主体
executions	object	実行の要約（items）。結果・設定・ツールの呼び出しの数など
timeline	object	記録の行（items）
timeline.items[].at	string	記録の日時
timeline.items[].key	number	記録の ID。"tool.access" の行は、ツールの呼び出しの一覧の operationId（row:<key>）と同じ
timeline.items[].section	string	"request"（依頼）/ "evidence"（根拠）/ "action"（実行したこと）/ "confirmation"（確認）/ "result"（結果）/ "other"
timeline.items[].eventType	string	記録の種類（例: "context.manifest"・"runtime.mcp.connected"・"tool.invoked"・"guardrail.blocked"）
timeline.items[].meta	object	記録ごとの中身。項目名は記録のまま返ります
deleted	object	消された会話・リソース
hasMore	boolean	続きがあるかどうか
cursor	string	次ページ取得用カーソル。hasMore が true の場合のみ含まれます
snapshotAt	string | null	記録を読んだ日時

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

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	projectId・executionId の形式の誤り、limit が 1-100 の整数でない、または cursor が不正
400	invalid_cursor	cursor を読めない
403	insufficient_scope	project:read スコープが不足
403	forbidden	システム連携のトークンで呼び出した
403	sso_required	SSO でログインしていない利用者
404	execution_not_found	実行が存在しない、ほかのプロジェクトの実行、またはメンバーではないプロジェクト
413	trace_too_large	記録が大きすぎて読めない
502	trace_unreachable	記録を読めなかった（時間をおいて送り直してください）
503	trace_unavailable	記録を読む機能が使えない

記録 (証跡)

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

エンドポイント一覧

メソッド	エンドポイント	説明	スコープ (SaaS)
GET	/v1/projects/{projectId}/audit	記録 (証跡) を取得	project:read

GET/v1/projects/{projectId}/audit

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

クエリパラメータ

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

レスポンスフィールド（200 OK）

フィールド	型	説明
events	array	記録の配列
events[].eventId	number	記録の ID
events[].occurredAt	string | null	日時（ISO 8601）
events[].eventType	string | null	記録の種類
events[].actorKind	string | null	記録者の種類。"agent" / "human" / "system" / "human_external" / "mail_external" / "unknown"
events[].actorRef	string | null	記録者。actorKind が "human" なら利用者 ID、それ以外は参照（システム連携は client:<連携の ID>、外部の送信者のメールは mail:<ハッシュ> など）
events[].decision	string | null	決定・結果
events[].reason	string | null	理由
events[].executionId	string | null	実行の ID
events[].runId	string | null	ワークフローの実行の ID
events[].stepName	string | null	工程の名前
events[].metadata	object	記録ごとの中身。項目名は記録のまま返ります。中身の無い記録は {}
hasMore	boolean	次のページが存在するかどうか
cursor	string	次ページ取得用カーソル。hasMore が true の場合のみ含まれます

• システム連携の行は、actorRef の client:<連携の ID> で見分けます。連携の表示名は、実行履歴・実行の結果の actorLabel で読みます。
• 実行の途中の記録の一部（context.manifest・runtime.* など）は含まれません。実行の時系列で読みます。

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	projectId・runId が UUID の形式ではない、kind が記録の種類の形ではない、q が 100 文字を超える、limit・cursor が不正
403	insufficient_scope	project:read スコープが不足
403	forbidden	システム連携のトークンで呼び出した
403	sso_required	SSO でログインしていない利用者
404	project_not_found	プロジェクトが存在しない、またはメンバーではない

KPI

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

エンドポイント一覧

メソッド	エンドポイント	説明	スコープ (SaaS)
GET	/v1/projects/{projectId}/kpi	KPI を取得	project:read

GET/v1/projects/{projectId}/kpi

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

クエリパラメータ

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

レスポンスフィールド（200 OK）

フィールド	型	説明
days	number	期間（日）
successRate	number | null	Agentの完遂率（0〜1。正常完了 ÷ 終了）。終了が 0 件なら null
successRateStatus	string	"ok"（確定）/ "incomplete"（記録不足があり暫定値）/ "none"（記録不足が無く、終了が 0 件）
succeeded	number	正常完了の数
denominator	number	終了の数（正常完了と「失敗・要対応」の合計）
executions	number	denominator と同じ値
outcomes	object	結果ごとの数（completed・incomplete・failed・timeout・stopped・denied・skipped）
excluded	object	集計外の数（skipped・running・missing・unmeasured）
durationP95Minutes	number | null	処理時間の目安（p95。分）
runs	object	ワークフローの実行の数（total・closedDone・closedFailed・closedRejected・cancelled）と p95Minutes
gates	array	確認工程ごとの実績（stepId・position・name・mode・total・approvalRate・sendBackRate）
human	object	確認対応の状況（reviewsPerRun・gateWaitMedianMinutes・interventions）
workSteps	object	請求のステップと同じ数え方の数（executions・billableExecutions・excludedExecutions・toolCalls・steps・stepsUnknown・formulaVersion）

Agentの完遂率・runs・gates・human は、期間に始まった実行・ワークフローの実行・確認依頼を数えます。workSteps は、期間に終わった実行を数えます。数える実行が違うため、executions と workSteps.executions は一致するとは限りません。

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	projectId が UUID の形式ではない、または days が 7・30・90 ではない
403	insufficient_scope	project:read スコープが不足
403	forbidden	システム連携のトークンで呼び出した
403	sso_required	SSO でログインしていない利用者
404	project_not_found	プロジェクトが存在しない、またはメンバーではない

確認依頼

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

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

エンドポイント一覧

メソッド	エンドポイント	説明	スコープ (SaaS)
GET	/v1/workitems	確認依頼の一覧を取得	project:read
GET	/v1/workitems/{workItemId}	確認依頼を取得	project:read
POST	/v1/workitems/{workItemId}/decision	確認依頼を判断	project:decide

GET/v1/workitems

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

クエリパラメータ

パラメータ	型	デフォルト	説明
status	string	—	状態で絞り込み。"assigned"（確認待ち）/ "done"（進めた・差し戻した）/ "cancelled"（却下した、またはワークフローの実行が止まって取り消された）
projectId	string	—	このプロジェクトの確認依頼に絞り込み（UUID）
limit	integer	50	1 ページの件数（1〜100）
cursor	string	—	次のページのカーソル（前のレスポンスの cursor の値）

レスポンスフィールド（200 OK）

フィールド	型	説明
workitems	array	確認依頼の配列
workitems[].workItemId	string	確認依頼の ID（UUID）
workitems[].title	string | null	件名
workitems[].status	string | null	"assigned" / "done" / "cancelled"
workitems[].projectId	string | null	プロジェクト ID
workitems[].decision	string | null	判断。"proceed"（進める）/ "send_back"（差し戻す）/ "reject"（却下する）。決まる前は null
workitems[].requesterUserId	string | null	依頼者の利用者 ID
workitems[].expiresAt	string | null	確認期限（ISO 8601）
workitems[].gateMode	string | null	確認方法。"blocking"（担当者の判断を待つ）または "notify_only"（期限後に自動で進める）
workitems[].overdue	boolean | null	期限を過ぎたかどうか
workitems[].decidedAt	string | null	判断した日時（ISO 8601）
workitems[].createdAt	string | null	作成日時（ISO 8601）
workitems[].updatedAt	string | null	更新日時（ISO 8601）
workitems[].canDecide	boolean	自分が判断できるかどうか（確認担当者なら true）
hasMore	boolean	次のページがあるかどうか
cursor	string	次のページのカーソル。hasMore が true のときだけ含まれます

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	status が上の値ではない、projectId が UUID の形式ではない、または limit・cursor の誤り
403	insufficient_scope	project:read スコープが不足
403	forbidden	システム連携のトークンで呼び出した
403	sso_required	SSO でログインしていない利用者

GET/v1/workitems/{workItemId}

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

パスパラメータ

パラメータ	型	必須	説明
workItemId	string	必須	確認依頼の ID（UUID）

レスポンスフィールド（200 OK）

フィールド	型	説明
workitem	object	確認依頼。一覧の 1 件の項目（workItemId・title・status・projectId・decision・requesterUserId・expiresAt・gateMode・overdue・decidedAt・createdAt・updatedAt・canDecide）と、次の項目
workitem.description	string | null	説明
workitem.runId	string | null	ワークフローの実行の ID
workitem.runStepId	string | null	確認を求めた工程の実行の ID（rs:<数値>。実行履歴の executionId と同じ形）
workitem.stepId	string | null	確認を求めた工程の ID（確認工程、または結果によって確認を求めた Agent の工程）
workitem.approverUserIds	array	確認担当者の利用者 ID の配列（確認依頼ができたときの担当者）
workitem.overdueAction	string | null	期限を過ぎたら。"none" / "proceed" / "send_back" / "reject"
workitem.evidence	object | null	確認の材料（下の表）
workitem.decidedByKind	string | null	判断したものの種類（"human" など）。決まる前は null
workitem.decidedByRef	string | null	判断したもの。decidedByKind が "human" なら利用者 ID。期限後の自動の判断などは system:… の参照。決まる前は null
workitem.decisionReason	string | null	判断の理由
workitem.sendBackToStepId	string | null	差し戻し先の工程の ID
workitem.decisionResult	object | null	判断の結果（decision・at・completesRun・sendBackToStepId・destinationId・destinationStepId）。completesRun は、進めたときにワークフローの実行が終わったかどうか
activities	array	経緯（新しい順に 100 件まで）
activities[].activityId	number | null	経緯の ID
activities[].eventType	string | null	記録の種類
activities[].decision	string | null	判断
activities[].actorKind	string | null	記録したものの種類
activities[].actorRef	string | null	記録したもの。actorKind が "human" なら利用者 ID、それ以外は system:… などの参照
activities[].reasonCode	string | null	理由
activities[].conversationId	string | null	会話の ID
activities[].metadata	object	記録ごとの中身。項目名は記録のまま返ります（利用者 ID が入ることがあります）
activities[].occurredAt	string | null	日時（ISO 8601）
gate	object | null	判断に使う情報（下の表）

確認の材料（workitem.evidence）:

フィールド	型	説明
summary	string | null	確認の材料の文。ふつうは確認する工程の Agent の出力で、Agent の工程の結果によって確認を求めたときは、結果とその理由の要約
conversationId	string | null	確認する工程の実行の会話の ID
files	array	確認する工程のファイル（会話 API の deliverables と同じ形）
gateKind	string | null	確認の種類。"review"（確認）または "manual"（手作業）
stepName	string | null	確認を求めた工程の名前
outcome	string | null	確認する工程の実行の結果（実行の「結果の値」）
executionId	string | null	確認する工程の実行の ID（実行の結果を取得する API で読めます）
reasonCode	string | null	結果の理由（Agent の工程の結果によって確認を求めたとき）
escalateToUserId	string | null	期限超過時の連絡先の利用者 ID（確認依頼ができたときにメンバーだった人）
destinations	array	進め先として選べる工程（destinationId・label・stepId）。設定していなければ空の配列

判断に使う情報（gate）:

フィールド	型	説明
projectName	string | null	プロジェクト名
projectType	string | null	プロジェクトの型
stepId	string | null	確認を求めた工程の ID
stepName	string | null	確認を求めた工程の名前
stepPosition	number | null	確認を求めた工程の位置
nextStep	object | null	進めたときの次の工程（stepId・name・position）。次の工程が無ければ null
sendBackDefaultStepId	string | null	差し戻し先を指定しないときの戻り先の工程の ID
sendBackCandidates	array	差し戻し先に指定できる工程（stepId・name・position・sendBacks）。sendBacks はその工程へ差し戻した回数
sendBackLimit	number | null	1 つの工程へ差し戻せる回数の上限
destinations	array	進め先として選べる工程（destinationId・label・stepId・stepName・stepPosition）
lane	object | null	確認を求めた工程のレーン（laneId・name・position）。レーンが無ければ null

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	workItemId が UUID の形式ではない
403	insufficient_scope	project:read スコープが不足
403	forbidden	システム連携のトークンで呼び出した
403	sso_required	SSO でログインしていない利用者
404	workitem_not_found	確認依頼が存在しない、または読めない

POST/v1/workitems/{workItemId}/decision

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

リクエストボディ

フィールド	型	必須	説明
decision	string	必須	"proceed"（進める）/ "send_back"（差し戻す）/ "reject"（却下する）
reason	string	—	理由（10000 文字まで）。"send_back"・"reject" のときは必須
sendBackToStepId	string	—	差し戻し先の工程の ID（"send_back" のとき。gate の sendBackCandidates の工程）。省くと sendBackDefaultStepId の工程に戻します
destinationId	string	—	進め先（"proceed" のとき。gate の destinations の destinationId。64 文字まで）。進め先のある確認依頼を進めるときは必須
commandId	string	—	送り直しを見分ける値（128 文字まで）

• 同じ commandId で同じ内容を送り直すと、1 回目の結果（{ "decision": …, "alreadyDecided": true }）が返ります。同じ commandId で違う内容を送ると 409 Conflict（command_conflict）です。
• すでに判断されている確認依頼に、違う commandId（または commandId なし）で送ると 409 Conflict（already_decided）です。確認依頼を取得し直して、今の判断を読んでください。
• 差し戻しは、1 つの工程へ差し戻せる回数の上限（gate.sendBackLimit）までです。

レスポンスフィールド（200 OK）

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

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	workItemId・sendBackToStepId が UUID の形式ではない、decision が無い・上の値ではない、commandId・destinationId が空白だけ、または項目の型や長さの誤り
400	invalid_body	ボディが壊れた JSON、または JSON のオブジェクトではない
400	reason_required	"send_back"・"reject" で reason が無い
400	invalid_send_back_step	sendBackToStepId が、差し戻し先に指定できる工程ではない
400	destination_required	進め先のある確認依頼を、destinationId なしで進めようとした
400	invalid_destination	destinationId が進め先に無い、または "proceed" 以外で destinationId を送った
403	insufficient_scope	project:decide スコープが不足
403	forbidden	システム連携のトークンで呼び出した
403	sso_required	SSO でログインしていない利用者
403	not_gate_owner	プロジェクトのメンバーだが、確認担当者ではない
404	workitem_not_found	確認依頼が存在しない、または読めない
409	already_decided	すでに判断されている
409	command_conflict	同じ commandId で違う内容を送った
409	invalid_state	確認待ちではない（取り消されたなど）
409	send_back_limit_exceeded	差し戻せる回数の上限に達している
413	body_too_large	ボディが 3 MiB を超える
415	unsupported_media_type	ボディの Content-Type が application/json ではない

連携先

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

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

エンドポイント一覧

メソッド	エンドポイント	説明	スコープ (SaaS)
GET	/v1/connectors/mcp/{connectionId}	MCP の連携先を取得	project:read
GET	/v1/connectors/a2a/{connectionId}	A2A の連携先を取得	project:read

GET/v1/connectors/mcp/{connectionId}

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

パスパラメータ

パラメータ	型	必須	説明
connectionId	string	必須	連携先の ID（16 桁までの正の整数）

レスポンスフィールド（200 OK）

フィールド	型	説明
kind	string	"mcp"
connectionId	string	連携先の ID
name	string | null	連携先の名前
requiresLogin	boolean	プロジェクトの画面でログインしてから使う連携先かどうか
tools	array	ツールの配列
tools[].name	string | null	ツールの名前
tools[].displayName	string | null	表示名
tools[].description	string | null	説明
tools[].presentInLastFetch	boolean | null	最後に取得したときにもあったかどうか（false は、MCP サーバーから無くなったツール）
toolsFetchedAt	string | null	ツールの一覧を最後に取得した日時（ISO 8601）。保存されたツールが無ければ null

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	connectionId が 16 桁までの正の整数ではない
403	insufficient_scope	project:read スコープが不足
403	forbidden	システム連携のトークンで呼び出した
404	connector_not_found	連携先が存在しない、または無効

GET/v1/connectors/a2a/{connectionId}

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

パスパラメータ

パラメータ	型	必須	説明
connectionId	string	必須	連携先の ID（16 桁までの正の整数）

レスポンスフィールド（200 OK）

フィールド	型	説明
kind	string	"a2a"
connectionId	string	連携先の ID
name	string | null	連携先の名前
requiresLogin	boolean	プロジェクトの画面でログインしてから使う連携先かどうか
agentCard	object	エージェントカード
agentCard.description	string | null	説明
agentCard.version	string | null	版
agentCard.provider	object | null	提供者
agentCard.skills	array	スキル
agentCard.capabilities	object | null	対応している機能
agentCard.defaultInputModes	array	受け取る形式
agentCard.defaultOutputModes	array	返す形式
agentCard.supportedInterfaces	array	対応している接続方式
agentCard.documentationUrl	string | null	説明書の URL
agentCard.iconUrl	string | null	アイコンの URL

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

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	connectionId が 16 桁までの正の整数ではない
403	insufficient_scope	project:read スコープが不足
403	forbidden	システム連携のトークンで呼び出した
404	connector_not_found	連携先が存在しない、または無効

実行の会話

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

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

エラーレスポンス

HTTP ステータスコード

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

ステータス	説明
400 Bad Request	リクエストパラメータが不正
401 Unauthorized	トークンが無効または未指定
403 Forbidden	リソースへのアクセス権限なし
404 Not Found	リソースが存在しない
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.type	string	エラーの分類。"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.message	string	人間が読めるエラーメッセージ
error.code	string	機械的に処理可能なエラーコード（例: "missing_parameter"、"invalid_parameter"、"invalid_token"）
error.param	string	エラーの原因となったパラメータ名。バリデーションエラー時のみ含まれます
error.suggested_action	string	推奨される対処方法。一部のエラーでのみ含まれます

JSON

{
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid parameter: limit",
    "code": "invalid_parameter",
    "param": "limit",
    "suggested_action": "limit must be between 1 and 100"
  }
}