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

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

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

システム連携のトークンで呼べるプロジェクトの API は、プロジェクト一覧の取得・ワークフローの実行の開始・トリガーの発火・ワークフローの実行の取得・成果物の一覧の取得・成果物の中身の取得・ワークフローの実行の中断・サイクルの巡回の実行の停止・実行の結果の取得(状態の項目だけ)の 9 つだけです(システム連携 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​

呼べるかどうかは、プロジェクトでの役割で決まります(○ は呼べる、× は呼べない)。

操作オーナー運用担当メンバー組織の運用の役割 ※1呼べない人への断り
プロジェクトとその中のもの(工程・配置・実行など)を読む○○○一部 ※2—
ワークフローの実行の開始・トリガーの発火・入力ファイルの下書きの上げ○○○○—
ほかの運転の操作 ※3○○×(ワークフローの実行の中断は、その実行を始めた本人なら ○)○403 Forbidden(operator_only)
Webhook の API(一覧と配送の結果を含む)○×××403 Forbidden(owner_only)。参加していない組織の運用の役割の人は 409 Conflict(forbidden_role)
ほかの書き込む API(プロジェクトを作る API を除く)○×××403 Forbidden(owner_only)。参加していない組織の運用の役割の人は 409 Conflict(forbidden_role)
  • ※1 プロジェクトの所属組織で、組織の運用の役割(管理コンソールの「管理の役割」で付ける「運用」の役割)を持つ人です。プロジェクトに参加していなくても、表で ○ の操作を呼べます。参加している人がこの役割も持つときは、参加の役割に加えて運転の操作を呼べます。
  • ※2 参加していない組織の運用の役割の人には、成果物の一覧と中身の取得、定義の承認待ちの取得は 409 Conflict(forbidden_role)、プロジェクトのファイルの中身は 400 Bad Request(file_not_found)です。ワークフローの実行と実行の、Agent の文とファイルの項目は null か空で返ります。
  • ※3 ワークフローの実行の締め切り・確認担当者の付け替え・ワークフローの実行の中断・サイクルの巡回の実行の停止・プロジェクトの一時停止と再開です。
  • 確認依頼・キュー・連携先の API の呼べる人は、それぞれの節に書いています。
場面返るもの
メンバーでも、プロジェクトの所属組織で組織の運用の役割を持つ人でもないプロジェクトと、存在しないプロジェクトどちらも 404 Not Found で、応答から区別できません。ただし、公開されているプロジェクトは、メンバーでなくてもプロジェクトの取得(GET /v1/projects/{projectId})で構造だけを読めます
404 Not Found の codeエンドポイントごとに 1 つで、パスの最後の資源の名前です(例: 配置の API は placement_not_found、実行の API は execution_not_found)。パスに資源の ID が無いエンドポイントは project_not_found です。配置の下の工程の設定を書き込む API(runtime-config)は、パスの最後が工程の ID でも placement_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 を指定した空の一覧が返ります
本体の利用者の記録が認証サーバーのアカウントと結び付いていない利用者のトークンプロジェクト・確認依頼・キューの API で 403 Forbidden(sso_required)が返ります(プロジェクト一覧の取得・ワークフローの実行の開始・トリガーの発火・ワークフローの実行の取得を除きます)。メイン画面に一度ログインすると結び付きます

この頁の誤りの表の 404 の「メンバーではない」は、メンバーでも、プロジェクトの所属組織で組織の運用の役割を持つ人でもないことを指します。

リクエストの扱い​

ボディは JSON のオブジェクトで送ります(入力ファイルを上げる APIは multipart/form-data)。

送ったもの扱い
仕様に無いクエリパラメータとボディのフィールド無視されます
仕様にあるクエリパラメータの不正な値、読めない cursor400 Bad Request
パスパラメータの値の不正な URL エンコード(% の並び)400 Bad Request(invalid_parameter)
Content-Type: application/json 以外のボディ、対応していない文字コード(charset)のボディ415 Unsupported Media Type(unsupported_media_type)
壊れた JSON、JSON のオブジェクトではないボディ400 Bad Request(invalid_body)
この API では受け付けないと決めているフィールド400 Bad Request(invalid_parameter)。黙って無視すると、変えたつもりで変わらないためです。該当するフィールドは各エンドポイントの説明に書いています
クエリの名前snake_case です(my_role・placement_id・step_id・run_id・project_id)。前の名前(myRole・placementId・stepId・runId・projectId)でも受け付けます。両方の名前に違う値を指定すると 400 Bad Request(invalid_parameter)です

ボディの上限は次のとおりです。超えると 413 Payload Too Large(body_too_large)が返ります。

APIボディの上限
プロジェクトを作る・定義を取り込む、確認依頼を判断する・期限を延ばす3 MiB
工程を足す・変える32 KiB
確認待ちのワークフローの実行の案件設定を置き換える787,456 バイト
入力ファイルを上げるその API の説明を参照してください
ほかの API16 KiB

書き換えと送り直し​

書き換える API は、取得で返る digest を baseDigest に入れて送ります。取得した後にほかの変更が入っていると 409 Conflict(stale_base)が返ります。取得し直してから送り直してください。

  • 応答の digest は書き換えた後の値です。続けて書き換えるときはその値を使えます。
  • ほぼ同時に届いた 2 つの書き換えは、両方が通ることがあります。
  • 確認依頼の期限の延長と、ワークフローの実行の締め切り・確認担当者の付け替えは、baseDigest を使いません(取得した後の変更とは比べません)。確認待ちのワークフローの実行の案件設定の置き換えは、baseDigest ではなく、案件設定の取得で読んだ revision を expectedRevision に入れて送ります。
  • 定義の変更に承認が要るテナントでは、書き換えが届いたかを definition=pending を付けた取得で確かめてください(承認待ちの変更は、既定の取得には出ません)。

送り直したときの扱いは次のとおりです。

API送り直しを見分けるもの同じもので送り直すと
ワークフローの実行の開始Idempotency-Key ヘッダー(必須)1 回目の結果が返ります
トリガーの発火ボディの eventId1 回目の結果が返ります
確認依頼の判断・確認担当者の付け替え・ワークフローの実行の中断・確認待ちのワークフローの実行の案件設定の置き換えボディの commandId1 回目の結果が返ります(返り方は各エンドポイントの説明を参照してください)
入力ファイルを上げるIdempotency-Key ヘッダー(任意)1 回目の結果が返ります
登録 Agent を置く同じ 登録 Agent と同じ担当工程置いてある配置が返ります
プロジェクトを作る・工程を作る—もう 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})の説明を参照)。

ページネーション​

パラメータ型説明
limitinteger1ページあたりの取得件数(1-100)。デフォルトは 50 件です
cursorstring次のページを取得するためのカーソル値。前回のレスポンスに含まれる 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/{projectId}/definitionプロジェクトの定義を書き出す
POST/v1/projects/import書き出した定義からプロジェクトを作る(取り込み)
DELETE/v1/projects/{projectId}/relink取り込んだ定義の、必要に応じて再度設定する項目を消す
GET/v1/projects/{projectId}/definition-approval定義の承認待ちを取得
DELETE/v1/projects/{projectId}/definition-approval定義の承認待ちを取り消す

GET/v1/projects

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

クエリパラメータ​

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

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

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

リクエスト例​

List projects
1curl "https://<your-domain>/api/v1/projects?limit=20" \
2-H "Authorization: Bearer <access_token>"

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

フィールド型説明
projectsarrayプロジェクトオブジェクトの配列
projects[].projectIdstringプロジェクト ID(UUID)
projects[].namestringプロジェクト名
projects[].typestring"workflow" または "cycle"
projects[].statusstringプロジェクトの状態。"active" / "paused" / "archived" / "admin_stopped"(管理者が停止)のいずれか
projects[].tagsarrayタグの配列。設定されていない場合は空の配列
projects[].myRolestring呼び手自身のそのプロジェクトでの役割。"owner"(オーナー)・"operator"(運用担当)・"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" は更新日時の新しい順

リクエスト例​

List shared projects
1curl "https://<your-domain>/api/v1/projects/shared?type=workflow&limit=20" \
2-H "Authorization: Bearer <access_token>"

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

フィールド型説明
projectsarrayプロジェクトの配列
projects[].projectIdstringプロジェクト ID(UUID)
projects[].namestring | nullプロジェクト名
projects[].descriptionstring | null説明
projects[].typestring | null"workflow" または "cycle"
projects[].statusstring | null"active" / "paused" / "archived" / "admin_stopped"(管理者が停止)のいずれか
projects[].tagsarrayタグの配列
projects[].shareScopestring | null公開の範囲。"all"(全員)または "organizations"(shareOrganizations の組織の利用者だけ)
projects[].shareOrganizationsarray | null公開先の組織のコードの配列。shareScope が "organizations" のときに使います
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 は含まれません。

レスポンス例​

JSON
{
"projects": [
{
"projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
"name": "請求書の突合",
"description": "請求書の金額と明細を照合し、差異を確認依頼にします",
"type": "workflow",
"status": "active",
"tags": [
"経理"
],
"shareScope": "all",
"shareOrganizations": null,
"stepCount": 3,
"agentCount": 2,
"copyCount": 5,
"connectorCount": 0,
"ownerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"updatedAt": "2026-11-18T01:00:00.000Z"
}
],
"hasMore": false
}

エラーレスポンス​

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

GET/v1/projects/organizations

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

リクエスト例​

Get project organizations
1curl https://<your-domain>/api/v1/projects/organizations \
2-H "Authorization: Bearer <access_token>"

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

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

レスポンス例​

JSON
{
"organizations": [
{
"value": "eng",
"label": "エンジニアリング部門"
}
],
"hasMore": false
}

エラーレスポンス​

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

GET/v1/projects/{projectId}

プロジェクトを、工程・メンバー・配置・トリガー・通知・連携先と合わせて取得します。メンバーではない利用者が公開されているプロジェクトを指定すると、構造だけ(プレビュー)を返します。プロジェクトの所属組織で組織の運用の役割を持つ人は、参加していなくても、プレビューではなく全部を読めます(myRole は null、orgOperator は true)。

パスパラメータ​

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

クエリパラメータ​

パラメータ型必須説明
definitionstring—"pending" を付けると、定義の変更の承認待ちを重ねた見え方で返します(承認待ちが無ければ、承認された定義)。付けないときは、承認された定義を返します

リクエスト例​

Get project
1curl https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31 \
2-H "Authorization: Bearer <access_token>"

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

フィールド型説明
projectobjectプロジェクト(下の表)
stepsarray工程の配列(並び順)。1 件の項目は「工程の項目」を参照
stepsDigeststring工程の並びの値。工程を並べ替えるときに baseDigest に送ります
membersarrayメンバーの配列
members[].userIdstring利用者 ID
members[].rolestring | null"owner"・"operator"・"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)
triggers[].digeststringトリガーを変えるときに baseDigest に送る値
stepStartFailuresarray先頭の工程に付けた時刻で開始する形の、開始の失敗の配列。開始できなかった工程だけが入ります。下の「開始の失敗の読み方」を参照
stepStartFailures[].stepIdstring | null工程の ID
stepStartFailures[].reasonstring | null開始できなかった理由のコード
stepStartFailures[].sincestring | nullその理由で開始できなくなった日時(ISO 8601)
notificationsobject通知の設定
notifications.gateReachedboolean | null確認依頼が届いたときに通知するかどうか
notifications.gateDueSoonboolean | null確認依頼の期限が近づいたときに催促を通知するかどうか(前の版の本体では 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)
definitionViewstring | nulldefinition=pending を付けたときだけ。"pending"(承認待ちを重ねた見え方)か "active"(承認待ちが無い)。組織の運用の役割を持ち、プロジェクトに参加していない人には null
relinkobject | null書き出した定義から取り込んだプロジェクトで、この環境で見つからず、つなぎ直しが要る参照。無ければ null
relink.itemsarrayつなぎ直しが要る参照の配列
relink.items[].kindstring参照の種類。"connector"(見つからない連携先)と "agent"(見つからない登録 Agent)は、つなぎ直すまで実行の開始・再開を断ります。"connection"・"playbook_version"・"automation_destination"・"approvers"・"branch_target"・"external_wait"・"trigger"・"library"・"input_files"・"placement_env"・"lanes"・"connection_binding"・"input_binding" は必要に応じて再度設定する項目で、実行は断りません。"branch_target" は、条件分岐のレーンの工程が見つからず、レーンと条件を外したことを表します。"unavailable" は、この環境の版で使えない物と、cycle の定義の時刻のトリガー(what が "cron_trigger")を外したことを表します
relink.items[].blockingbooleantrue のとき、実行の開始・再開を断ります。kind が "unavailable" の行には入りません
relink.items[].*—行の種類に応じて、手がかりの項目(agent・name・step・what・from・to・type・count・names・agents)が入ります。名前・版・数だけで、ID・URL は入りません。names は環境変数の名前だけで、値は入りません

メンバー(member)も、ワークフローの実行の開始・Webhook トリガーの発火・入力ファイルの下書きの上げと、自分が始めたワークフローの実行の中断ができます。運用担当(operator)は、それに加えて、ほかの人が始めたワークフローの実行の中断・ワークフローの実行の締め切り・確認担当者の付け替え、プロジェクトの一時停止・再開(status だけの変更)ができます。プロジェクトの設定・工程・Agent の配置・トリガー・Webhook・公開・削除・工程の設定はオーナーだけです(開始の config で、その案件だけの設定値・接続先・入力ファイルを渡すのは、メンバーもできます)。組織の運用の役割の人も、参加していなくても、運用担当の操作を呼べます。組織の運用の役割も持たないメンバーが運用担当の操作を呼ぶと 403 Forbidden(operator_only)が返ります。

project の項目:

フィールド型説明
projectIdstringプロジェクト ID(UUID)
namestring | nullプロジェクト名
descriptionstring | null説明
tagsarrayタグの配列
typestring | null"workflow" または "cycle"
statusstring | null"active"(稼働中)/ "paused"(停止中)/ "archived"(アーカイブ)/ "admin_stopped"(管理者が停止)のいずれか
adminStopobject | null管理者が止めているときの、停止元・理由・時刻。止めていなければ null。プロジェクトの取得だけで返ります
adminStop.sourcestring | null停止元。"aster"(AGENTIC STAR の管理者)、または連携先の "agent365"・"aws"
adminStop.reasonCodestring | null理由の種類。"admin"(管理者が止めた)・"remote_stopped"(連携先で止められた)・"remote_unreachable"(連携先に届かない)
adminStop.reasonstring | null理由の文。無ければ null
adminStop.stoppedAtstring | null止めた時刻(ISO 8601)
policyobject | null実行ルール。画面で設定した値のまま返ります。この API では変えられません
limitsobject | null実行の上限
limits.maxRetriesPerStepnumber1 つの工程で失敗したときにやり直す回数の上限
limits.maxSendBacksPerStepnumber同じ工程へ差し戻せる回数の上限
limits.runDeadlineHoursnumber | nullワークフローの実行の締め切りの既定(開始からの時間)。null または無ければ締め切りを付けません
limits.stallHoursnumber進まないまま、この時間が過ぎると停滞とみなす時間(無ければ 24 時間)
languagestring | nullプロジェクトの言語
flowStructureobject | nullいつも null
reportTargetsobject | null今は使っていない項目です(値が入っていても使われません)
escalateToUserIdstring | nullプロジェクトの既定の連絡先の利用者 ID(期限を過ぎた確認依頼の連絡先。このエンドポイントでは変えられません)
organizationCodestring | null組織のコード
organizationNamestring | null組織の名前
isSharedboolean | null公開しているかどうか
shareScopestring | null公開の範囲。"all"(全員)または "organizations"(shareOrganizations の組織の利用者だけ)
shareOrganizationsarray | null公開先の組織のコードの配列。shareScope が "organizations" のときに使います
copyCountnumber | nullコピーされた回数
ownerUserIdstring | null持ち主の利用者 ID
myRolestring | null呼んだ利用者の役割。"owner"・"operator"・"member" のどれか。プレビューと、参加していない組織の運用の役割の人では null
orgOperatorboolean呼んだ利用者が、プロジェクトの所属組織で組織の運用の役割を持つか。プロジェクトの取得だけで返ります(一覧には無い)
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・adminStop を除きます。myRole は null)・steps(各工程の digest を除きます)・placements(placementId・agentId・name・description・goal・stepIds・skillCount だけ)を返します。stepsDigest・members・triggers・stepStartFailures・notifications・connectors・relink は返しません。

レスポンス例​

JSON
{
"project": {
"projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
"name": "請求書の突合",
"description": "請求書の金額と明細を照合し、差異を確認依頼にします",
"tags": [
"経理"
],
"type": "workflow",
"status": "active",
"policy": {
"profile": "open",
"deny": []
},
"limits": {
"maxRetriesPerStep": 2,
"maxSendBacksPerStep": 3,
"runDeadlineHours": null,
"stallHours": 24
},
"language": "ja",
"flowStructure": null,
"reportTargets": {
"app": true
},
"escalateToUserId": null,
"organizationCode": "eng",
"isShared": false,
"shareScope": null,
"shareOrganizations": null,
"copyCount": 0,
"ownerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"myRole": "owner",
"createdAt": "2026-11-10T09:00:00.000Z",
"updatedAt": "2026-11-18T01:00:00.000Z",
"organizationName": "エンジニアリング部門",
"digest": "qHnScSdRAclmcFJVVCjKUrMsl5SELfkKS5UPAVidUJk",
"adminStop": null,
"orgOperator": false,
"relink": null
},
"steps": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"position": 1,
"name": "金額の確認",
"description": "請求書の金額と明細を照合します",
"enabled": true,
"defaultZone": "ai",
"branchConfig": null,
"reworkToStepId": null,
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null,
"digest": "jZ38OtGgLnS14QCvjZdg5PdyrGEHPK0EhxgDZzEnE2Y"
},
{
"stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"position": 2,
"name": "差異の確認",
"description": null,
"enabled": true,
"defaultZone": "gate",
"branchConfig": null,
"reworkToStepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null,
"digest": "27bA5P1PM8JFDwEEZhLP5DDn77Q8MFWq-YcGa6q8Sso"
},
{
"stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"position": 3,
"name": "差異の報告",
"description": null,
"enabled": true,
"defaultZone": "ai",
"branchConfig": null,
"reworkToStepId": null,
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null,
"digest": "idyMTCSnJ2toCfD4Y8F_cqLwFwZ-cyJpByz-v1nxscE"
}
],
"stepsDigest": "6r94LWhMkQ54T1GkU_ntdq-ZfgpGyeGFyu4Gt32V9H0",
"members": [
{
"userId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"role": "owner",
"joinedAt": "2026-11-10T09:00:00.000Z",
"name": "田中太郎",
"email": "tanaka@example.com"
}
],
"placements": [
{
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"agentId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
"displayOrder": 0,
"name": "請求書チェック",
"description": "請求書の金額と明細を照合します",
"goal": null,
"guardrail": null,
"skills": [],
"skillCount": 0,
"playbookId": null,
"playbookName": null,
"inputFiles": [],
"stepIds": [
"5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"
],
"sweeps": [],
"runtimeConfigs": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"runtimeConfig": null
}
],
"libraryBindings": [],
"memoryOrgId": null,
"memoryJobId": null,
"agentOwnerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"isShared": false,
"runtimeKind": "marketplace",
"marketplaceAgentId": "invoice-checker",
"exclusiveToThisProject": true,
"agentStopped": false,
"relink": null,
"digest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU"
}
],
"triggers": [],
"stepStartFailures": [],
"notifications": {
"gateReached": true,
"gateDueSoon": true,
"gateOverdue": true,
"runDeadlineOverdue": true,
"runStalled": true
},
"connectors": []
}

エラーレスポンス​

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

GET/v1/projects/{projectId}/definition

プロジェクトの確定している定義(承認された定義)を、画面の「定義を書き出す」と同じ JSON で返します。オーナーだけが呼べます。返した definition は、そのまま取り込み(POST /v1/projects/import)の本文に使えます。システム連携のトークンでは呼べません。

  • definition は製品の書き出しの形のまま返します(format は "agentic-star.project-definition" で、形の版が付きます)。項目の名前は camelCase に読み替えません。
  • 確認担当者・報告先のアドレス・接続・環境変数の値などは入りません。ただし、Agent の agentConfig、実行ルールの接続の ID、利用者が書いた文はそのまま入ります。agentConfig に秘密を入れていれば、書き出しにも入ります。別の環境では、同じ接続の ID が別の物を指すことがあります。この応答には Cache-Control: no-store が付きます。

パスパラメータ​

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

リクエスト例​

Export project definition
1curl https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/definition \
2-H "Authorization: Bearer <access_token>"

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

フィールド型説明
definitionobjectプロジェクトの定義(製品の書き出しの形のまま)

エラーレスポンス​

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

POST/v1/projects/import

書き出した定義(GET /v1/projects/{projectId}/definition の definition)から、プロジェクトを作ります。画面の「ファイルから取り込む」と同じです。プロジェクトを作れる人が呼べます(作った人がオーナーになります)。システム連携のトークンでは呼べません。Idempotency-Key は受け付けません。

  • 作ったプロジェクトは一時停止(status が "paused")で、時刻のトリガーと巡回は無効です。確かめてから再開します。
  • この環境で見つからない参照(連携先・Agent・プレイブック・スキルなど)は持ち込まれず、答えの relink に出ます。起動を断る参照が残っている間は、実行を始められません(409、relink_required)。
  • 答えの project は作った直後の形です。取り込んだプロジェクトを書き換えるときは、プロジェクトの取得(GET /v1/projects/{projectId})で読み直し、その digest を baseDigest に送ってください。
  • 答えが返らなかったとき(時間切れ・途中で切れた)は、プロジェクトが作られたかもしれません。プロジェクトの一覧(GET /v1/projects)で確かめてから送り直してください。

リクエストボディ​

フィールド型必須説明
definitionobject必須書き出した定義(書き出しの答えの definition をそのまま)
organizationCodestring | null—組織のコード。プロジェクトを作る API の organizationCode と同じです

レスポンス(201 Created)​

フィールド型説明
projectobject作ったプロジェクト。プロジェクトを作る API の答えの project と同じ項目です
relinkobjectつなぎ直しが要る参照
relink.itemsarrayつなぎ直しが要る参照の配列。1 行の項目は、プロジェクトの取得の relink.items と同じです
relink.agentsarray置いた Agent ごとの、見つからなかったプレイブック・スキル
relink.agents[].agentstringAgent の名前
relink.agents[].playbookobject | null見つからなかったプレイブック(name・versionNo)
relink.agents[].skillsarray見つからなかったスキル(name・versionNo)の配列
definitionApprovalobject | nullテナントで定義の変更に承認が要るとき、作ったプロジェクトの最初の定義は承認待ちになり、ここに承認待ちの様子が入ります(項目は定義の承認の項目)。承認が要らないときは null

レスポンス例​

JSON
{
"project": {
"projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
"name": "請求書の突合",
"description": "請求書の金額と明細を照合し、差異を確認依頼にします",
"tags": [
"経理"
],
"type": "workflow",
"status": "paused",
"policy": {
"profile": "open",
"deny": []
},
"limits": {
"maxRetriesPerStep": 2,
"maxSendBacksPerStep": 3,
"runDeadlineHours": null,
"stallHours": 24
},
"language": "ja",
"flowStructure": null,
"reportTargets": {
"app": true
},
"escalateToUserId": null,
"organizationCode": "eng",
"isShared": false,
"shareScope": null,
"shareOrganizations": null,
"copyCount": 0,
"ownerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"myRole": "owner",
"createdAt": "2026-11-10T09:00:00.000Z",
"updatedAt": "2026-11-18T01:00:00.000Z",
"digest": "qcbI-0P5vLMOx2fZNU6E4w_O8csDygptMUne-emVENo"
},
"relink": {
"items": [],
"agents": []
},
"definitionApproval": null
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterdefinition がオブジェクトではない、または organizationCode の型・長さの誤り
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
400invalid_definition_file定義の形が正しくない
400unsupported_definition_version定義の形の版が、この環境では扱えない。書き出した環境と取り込む環境の版をそろえてください
400definition_too_large定義が大きすぎる(作る操作が 200 を超える)。定義を小さくしてください
400organization_not_member付けられない組織を指定した
400import_failed作る途中の書き込みが断られた。どの操作が、なぜ断られたかが error.message に入ります(元の失敗が 5xx のときは、同じ 5xx が返ります)
403forbiddenシステム連携のトークンで呼び出した
403sso_required認証サーバーのアカウントと結び付いていない利用者
403feature_not_permitted定義にトリガーか、時刻を入れた工程(どの工程でも)があるが、管理者が定期実行の作成を許可していない(取り込みでは巡回はいつも無効なので、巡回では断りません)。作る前に断るので、作りかけのプロジェクトは残りません
409project_limit_reachedプロジェクトの数が上限に達している(数は error.message)
413body_too_largeボディが 3 MiB を超える
415unsupported_media_typeボディの Content-Type が application/json ではない
503feature_permissions_unavailable機能の許可を確かめられない。時間をおいて送り直してください
503approval_setting_unavailable定義の承認の設定を確かめられない。時間をおいて送り直してください

取り込んだプロジェクトの relink から、起動を断らない、必要に応じて再度設定する項目(blocking が false の行)だけを消します(画面の「確認済みにする」と同じ)。オーナーだけが呼べます。起動を断る参照(blocking が true の行)と、配置の relink(置いた Agent が指す、見つからなかったプレイブック・スキル)は残ります。これを消すだけでは、実行を始められるようにはなりません。システム連携のトークンでは呼べません。

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

リクエスト例​

Dismiss project relink
1curl -X DELETE https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/relink \
2-H "Authorization: Bearer <access_token>"
JSON
{
"projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
"dismissed": true
}
ステータスcode説明
400invalid_parameterprojectId が UUID の形式ではない
403forbiddenシステム連携のトークンで呼び出した
403owner_onlyオーナーではないメンバー
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"
organizationCodestring | null—組織のコード(255 文字まで)。付けられるのは GET /v1/projects/organizations で返る組織だけ。null・空の文字列・空白だけは、付けないのと同じです
stepsarray—工程の並び(12 個まで)。空でない配列を渡すときは、workflow は 2 つ以上、cycle は 1 つ以上です。省くか空の配列のときは、既定の工程で作ります(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 は送れません
steps[].outputConfig——送れません(null 以外は 400 output_config_invalid。null は送らないのと同じです)

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

リクエスト例​

Create project
1curl -X POST https://<your-domain>/api/v1/projects \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "name": "請求書の突合",
6 "description": "請求書の金額と明細を照合し、差異を確認依頼にします",
7 "tags": [
8 "経理"
9 ],
10 "type": "workflow",
11 "organizationCode": "eng"
12}'

レスポンス(201 Created)​

フィールド型説明
projectobject作ったプロジェクト。プロジェクトの取得の project と同じ項目です(organizationName と adminStop を除きます。myRole は "owner")
stepsarray作った工程の配列。1 件の項目は「工程の項目」を参照
definitionApprovalobject | nullテナントで定義の変更に承認が要るとき、作ったプロジェクトの最初の定義は承認待ちになり、ここに承認待ちの様子が入ります(status が "pending"。項目は定義の承認の項目)。承認されるまで、実行を始められません。承認が要らず、すぐ反映したときは null

レスポンス例​

JSON
{
"project": {
"projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
"name": "請求書の突合",
"description": "請求書の金額と明細を照合し、差異を確認依頼にします",
"tags": [
"経理"
],
"type": "workflow",
"status": "active",
"policy": {
"profile": "open",
"deny": []
},
"limits": {
"maxRetriesPerStep": 2,
"maxSendBacksPerStep": 3,
"runDeadlineHours": null,
"stallHours": 24
},
"language": "ja",
"flowStructure": null,
"reportTargets": {
"app": true
},
"escalateToUserId": null,
"organizationCode": "eng",
"isShared": false,
"shareScope": null,
"shareOrganizations": null,
"copyCount": 0,
"ownerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"myRole": "owner",
"createdAt": "2026-11-18T05:00:00.000Z",
"updatedAt": "2026-11-18T05:00:00.000Z",
"digest": "qHnScSdRAclmcFJVVCjKUrMsl5SELfkKS5UPAVidUJk"
},
"steps": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"position": 1,
"name": null,
"description": null,
"enabled": true,
"defaultZone": "ai",
"branchConfig": null,
"reworkToStepId": null,
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null,
"digest": "klTw4jQoxuF17jBz4GL9aYU5DcFDjcv24zXfBEWTMtw"
},
{
"stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"position": 2,
"name": null,
"description": null,
"enabled": true,
"defaultZone": "gate",
"branchConfig": null,
"reworkToStepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null,
"digest": "rBZ_uP64l5OjdSlPVOdAoWThVePY0Rqei1BltLAcvQg"
},
{
"stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"position": 3,
"name": null,
"description": null,
"enabled": true,
"defaultZone": "ai",
"branchConfig": null,
"reworkToStepId": null,
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null,
"digest": "klTw4jQoxuF17jBz4GL9aYU5DcFDjcv24zXfBEWTMtw"
}
],
"definitionApproval": null
}

エラーレスポンス​

ステータスcode説明
400invalid_parametername が無い・空白だけ、項目の型や長さ・数・値の誤り(タグの空・重なりを含みます)、工程が 12 個を超える・空でない工程の配列が下限(workflow は 2 つ、cycle は 1 つ)より少ない、または trigger・policy・agents・guardrail・templateRef を送った
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
400cycle_gate_not_allowedcycle に確認工程("gate")を指定した
400output_config_invalidsteps[].outputConfig を送った(マーケットプレイス版では使えません。null は送らないのと同じです)。error.param は steps[N].outputConfig
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所属している組織を確かめられない
503approval_setting_unavailable定義の承認の設定を確かめられない。時間をおいて送り直してください

PATCH/v1/projects/{projectId}

プロジェクトを変えます。送った項目だけを変えます。オーナーだけが呼べます。ただし、baseDigest と status("active"・"paused")だけを送る一時停止・再開は、運用担当と組織の運用の役割の人も呼べます。

パスパラメータ​

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

リクエストボディ​

フィールド型必須説明
baseDigeststring必須プロジェクトの取得の project.digest
namestring—プロジェクト名(255 文字まで。空・空白だけにはできません)
descriptionstring—説明(5000 文字まで。空の文字列・空白だけ・null にはできません)
tagsarray—タグ(作るときと同じ)。送ると全部が置き換わります
statusstring—"active" / "paused" / "archived"
isSharedboolean—公開するかどうか
shareScopestring—公開の範囲。"all"(全員)または "organizations"(shareOrganizations の組織の利用者だけ)
shareOrganizationsarray—公開先の組織のコード(20 件まで。1 件 255 文字まで。前後の空白を除き、同じ値は 1 つにします)。送ると全部が置き換わります。公開していて範囲が "organizations" のときと、shareScope の "organizations" と一緒に送るときは、1 件以上が要ります
limitsobject—実行の上限。送った項目だけを今の値に重ねます
limits.maxRetriesPerStepinteger—0〜10
limits.maxSendBacksPerStepinteger—1〜10
limits.runDeadlineHoursinteger | null—1〜2160。null は締め切りを付けない
limits.stallHoursinteger—1〜720
organizationCodestring | null—組織のコード(255 文字まで)。組織をまだ付けていないプロジェクトに 1 回だけ付けられます。今の値と同じ値は何も変えません(取得の値をそのまま送り返せます)。組織が付いているプロジェクトに違う値を送ると 409(organization_locked)です。null は、組織がまだ付いていなければ何も変えず、付いていれば 409(organization_locked)です

baseDigest のほかに、少なくとも 1 つの項目を送ってください。type・policy・connectSecret と、null 以外の limits.maxMinutesPerRun は受け付けません(送ると 400、invalid_parameter)。1 つの Agent の作業の長さは、プロジェクトでは変えられません。型は作るときに決め、実行ルールは画面で変えます。

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

管理者がプロジェクトを止めているとき(status が "admin_stopped")は、status を送る変更と、プロジェクトの削除は 409 Conflict(admin_stopped)で断られます。名前などのほかの項目は変えられます。再開は管理者が行います。

リクエスト例​

Update project
1curl -X PATCH https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31 \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "baseDigest": "qHnScSdRAclmcFJVVCjKUrMsl5SELfkKS5UPAVidUJk",
6 "status": "paused"
7}'

レスポンス(200 OK)​

フィールド型説明
projectobject変えた後のプロジェクト。プロジェクトの取得の project と同じ項目です(organizationName と adminStop を除きます)
definitionApprovalobject | nullテナントで定義の変更に承認が要るとき、この変更は承認待ちになり、ここに承認待ちの様子が入ります(status が "pending"。項目は定義の承認の項目)。承認されるまで、実行は前の定義で動きます。承認が要らず、すぐ反映したときは null

レスポンス例​

JSON
{
"project": {
"projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
"name": "請求書の突合",
"description": "請求書の金額と明細を照合し、差異を確認依頼にします",
"tags": [
"経理"
],
"type": "workflow",
"status": "paused",
"policy": {
"profile": "open",
"deny": []
},
"limits": {
"maxRetriesPerStep": 2,
"maxSendBacksPerStep": 3,
"runDeadlineHours": null,
"stallHours": 24
},
"language": "ja",
"flowStructure": null,
"reportTargets": {
"app": true
},
"escalateToUserId": null,
"organizationCode": "eng",
"isShared": false,
"shareScope": null,
"shareOrganizations": null,
"copyCount": 0,
"ownerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"myRole": "owner",
"createdAt": "2026-11-10T09:00:00.000Z",
"updatedAt": "2026-11-18T05:30:00.000Z",
"digest": "qcbI-0P5vLMOx2fZNU6E4w_O8csDygptMUne-emVENo"
},
"definitionApproval": null
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId が UUID の形式ではない、baseDigest が無い・空・文字列ではない、変える項目が無い、name を空・空白だけにした、description を空の文字列・空白だけ・null にした、name・status・tags・isShared・limits に null を送った、項目の型や値の誤り(タグの空・重なりを含みます)、または type・policy・connectSecret・limits.maxMinutesPerRun(null 以外)を送った
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
400invalid_share_scopeshareScope が "all"・"organizations" ではない
400invalid_share_organizationsshareOrganizations が配列ではない、21 件以上、または文字列でない・空・空白だけ・256 文字以上の値がある
400share_organizations_requiredshareScope に "organizations" と空の shareOrganizations を送った、または公開している(送った値か今の値の isShared が true)のに、範囲が "organizations" で組織が 1 件も無い(送った値と今の値を合わせて見ます)
400organization_not_member付けられない組織を指定した
403forbiddenシステム連携のトークンで呼び出した
403owner_onlystatus を "archived" にする変更か、status のほかの変えられる項目(上のリクエストボディの表の項目)を含む変更を、オーナーではないメンバーが送った
403operator_only一時停止・再開だけの変更を、オーナーでも運用担当でもなく、組織の運用の役割も持たないメンバーが送った
403sso_required認証サーバーのアカウントと結び付いていない利用者
404project_not_foundプロジェクトが存在しない、またはメンバーではない
409stale_base取得した後にプロジェクトが変わっている。承認待ちがあるときは、既定の取得の digest では合いません。definition=pending で読み直し、その digest を baseDigest に送ってください
409definition_invalid承認待ちの変更に重ねると定義が成り立たない(理由の種類は error.reason)。definition=pending で読み直し、重ねた形を見て直してください
409relink_required取り込みで見つからなかった参照をつなぎ直すまで、一時停止から再開できない(status を "active" にした)。直し方は、ワークフローの実行の開始の誤りの表の relink_required を参照してください
409admin_stopped管理者がプロジェクトを止めている(status の変更はできない)
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所属している組織を確かめられない
503approval_setting_unavailable定義の承認の設定を確かめられない。時間をおいて送り直してください
503definition_busy同じ定義の変更が処理中。時間をおいて送り直してください

DELETE/v1/projects/{projectId}

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

パスパラメータ​

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

リクエスト例​

Delete project
1curl -X DELETE https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31 \
2-H "Authorization: Bearer <access_token>"

レスポンス(200 OK)​

JSON
{
"projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
"deleted": true
}

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

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId が UUID の形式ではない
403forbiddenシステム連携のトークンで呼び出した
403owner_onlyオーナーではないメンバー
403sso_required認証サーバーのアカウントと結び付いていない利用者
404project_not_foundプロジェクトが存在しない、メンバーではない、またはすでに消した
409legal_hold保全中のプロジェクト。管理者が保全を解除するまで削除できません
409admin_stopped管理者がプロジェクトを止めている。管理者が再開するまで削除できません

GET/v1/projects/{projectId}/control

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

パスパラメータ​

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

クエリパラメータ​

パラメータ型必須説明
definitionstring—"pending" を付けると、定義の変更の承認待ちを重ねた見え方で返します。付けないときは、承認された定義を返します

リクエスト例​

Get project control
1curl https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/control \
2-H "Authorization: Bearer <access_token>"

レスポンスフィールド(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)
definitionViewstring | nulldefinition=pending を付けたときだけ。"pending"(承認待ちを重ねた見え方)か "active"(承認待ちが無い)。組織の運用の役割を持ち、プロジェクトに参加していない人には null

レスポンス例​

JSON
{
"tenantProfile": "guarded",
"tenantSource": "default",
"projectProfile": "guarded",
"effectiveProfile": "guarded",
"deny": [],
"gates": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"position": 2,
"name": "金額の確認",
"gateKind": "review",
"mode": "blocking",
"overdueAction": "none",
"approverUserIds": [
"f47ac10b-58cc-4372-a567-0e02b2c3d479"
],
"deadlineHours": 24
}
],
"operationClasses": null
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId が UUID の形式ではない
403forbiddenシステム連携のトークンで呼び出した
403sso_required認証サーバーのアカウントと結び付いていない利用者
404project_not_foundプロジェクトが存在しない、またはメンバーではない
409definition_invaliddefinition=pending で、承認待ちの変更に重ねると定義が成り立たない(理由の種類は error.reason)
503definition_busydefinition=pending で、同じ定義の変更が処理中。時間をおいて送り直してください

GET/v1/projects/{projectId}/definition-approval

定義の変更の承認待ちの要約を取得します。メンバーが呼べます。テナントで定義の変更に承認が要るとき、書く API(プロジェクト・工程・配置・トリガー・ライブラリの対応づけ)の変更は承認待ちになり、承認されるまで実行は前の定義で動きます。承認・差し戻しは、承認する人が製品の画面で行います(API では決められません)。

パスパラメータ​

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

リクエスト例​

Get definition approval
1curl https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/definition-approval \
2-H "Authorization: Bearer <access_token>"

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

フィールド型説明
requiredbooleanテナントで定義の変更に承認が要るかどうか
activeVersionnumber | null承認された(実行に使う)定義の版の番号
pendingobject | null承認待ちの変更。無ければ null。項目は下の定義の承認の項目の pending と同じで、createdAt と changes が加わります
pending.createdAtstring | null承認待ちができた日時(ISO 8601)
pending.changesarray承認された定義から変わる所の配列
pending.changes[].sectionstring変わる所の種類。"project"・"steps"・"placements"・"triggers"・"notifications"・"connectors"
pending.changes[].keystring | nullその種類の中のどれか(工程・配置・トリガーの ID、連携先の ID、通知の種類と経路)。"project" のときは null
pending.changes[].changestring"added"(足す)・"removed"(外す)・"updated"(変える)
pending.changes[].fieldsarray変わった欄の手がかりの名前。この要約だけの名前で、取得の答えの項目の名前とは一致しません。中身は definition=pending の読みで確かめます
lastRejectionobject | null最後に差し戻された変更(その後に承認された変更があれば null)
lastRejection.versionnumber差し戻された版の番号
lastRejection.reviewedByUserIdstring | null差し戻した利用者 ID
lastRejection.reviewedAtstring | null差し戻した日時(ISO 8601)
lastRejection.reasonstring | null差し戻しの理由
approverRulestring承認できる人の決まり(下の定義の承認の項目と同じ)
approversobject承認できる人
approvers.ownerUserIdsarray承認できるオーナーの利用者 ID の配列(申請した人を除きます)
approvers.orgAdminCountnumber承認できる組織の管理者の数
approvers.availableboolean承認できる人がいるかどうか
canApproveboolean呼んだ人が承認できるかどうか(承認は製品の画面で行います)
canWithdrawboolean呼んだ人が承認待ちを取り消せるかどうか(オーナー)

定義の承認の項目​

書く API の答えの definitionApproval と、承認待ちを取り消す API の答えの項目です。

フィールド型説明
requiredboolean | nullテナントで定義の変更に承認が要るかどうか。承認待ちを取り消した答えで、設定を確かめられなかったときは null
statusstring"pending"(承認待ちがある)または "none"(無い)
activeVersionnumber | null承認された(実行に使う)定義の版の番号。まだ無ければ null
pendingobject | null承認待ちの変更。無ければ null
pending.versionnumber承認待ちの版の番号
pending.digeststring承認待ちの変更の値。承認待ちを取り消すときに pendingDigest に送ります(プロジェクトの取得の digest とは別の値です)
pending.baseVersionnumber | null承認待ちの変更の元になった版の番号
pending.initialboolean作ったプロジェクトの最初の定義の承認待ちかどうか。true の間は、実行を始められません
pending.requestedByUserIdsarray変更を申請した利用者 ID の配列(承認待ちに変更を重ねた人を含みます)
pending.updatedAtstring | null承認待ちが最後に変わった日時(ISO 8601)
pending.workItemIdstring | null承認する人に届いている承認の依頼の ID(受信トレイの行の ID。確認依頼の API では読めません)
approverRulestring承認できる人の決まり。"owner_or_org_admin_not_requester"(申請した人ではない、プロジェクトのオーナーか組織の管理者)
approversAvailableboolean承認できる人がいるかどうか

レスポンス例​

JSON
{
"required": true,
"activeVersion": 2,
"pending": null,
"lastRejection": null,
"approverRule": "owner_or_org_admin_not_requester",
"approvers": {
"ownerUserIds": [
"f47ac10b-58cc-4372-a567-0e02b2c3d479"
],
"orgAdminCount": 1,
"available": true
},
"canApprove": false,
"canWithdraw": false
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId が UUID の形式ではない
403forbiddenシステム連携のトークンで呼び出した
403sso_required認証サーバーのアカウントと結び付いていない利用者
404project_not_foundプロジェクトが存在しない、またはメンバーではない
409forbidden_roleプロジェクトに参加していない組織の運用の役割の人が呼んだ
503approval_setting_unavailable定義の承認の設定を確かめられない。時間をおいて送り直してください

DELETE/v1/projects/{projectId}/definition-approval

定義の変更の承認待ちを取り消します。オーナーが呼べます。取り消すと、承認待ちの変更は捨てられ、承認された定義のままになります。

パスパラメータ​

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

クエリパラメータ​

パラメータ型必須説明
pendingDigeststring必須取り消す承認待ちの値(書く API の答えか、この要約の pending.digest)。プロジェクトの取得の digest とは別の値です

リクエスト例​

Withdraw definition approval
1curl -X DELETE "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/definition-approval?pendingDigest=c3d7b0e6e1840e4008c84b6e53e66bfc500453c3ff3a2a543d70374dc38b82d1" \
2-H "Authorization: Bearer <access_token>"

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

フィールド型説明
definitionApprovalobject取り消した後の様子(項目は定義の承認の項目)

レスポンス例​

JSON
{
"definitionApproval": {
"required": true,
"status": "none",
"activeVersion": 2,
"pending": null,
"approverRule": "owner_or_org_admin_not_requester",
"approversAvailable": true
}
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId が UUID の形式ではない、または pendingDigest が無い・形の誤り
403forbiddenシステム連携のトークンで呼び出した
403owner_onlyオーナーではないメンバー
403sso_required認証サーバーのアカウントと結び付いていない利用者
404project_not_foundプロジェクトが存在しない、またはメンバーではない
409no_pending承認待ちが無い。承認待ちの要約を読み直してから決めてください
409approval_stalependingDigest が今の承認待ちと違う(承認待ちに変更が重なった)。承認待ちの要約を読み直してから決めてください
503definition_busy同じ定義の変更が処理中。時間をおいて送り直してください

工程​

工程は、プロジェクトの流れの単位です。Agent が実行する工程(defaultZone が "ai")と、人が判断する確認工程("gate")があります。前の工程の結果で進むレーンを選ぶ条件分岐の工程("branch"。Agent を置きません)もあります。工程は 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"(確認工程)・"branch"(条件分岐)のどれか
branchConfigobject | null条件分岐の設定(defaultZone が "branch" の工程だけ。ほかの工程と、まだ設定していない条件分岐の工程は null)。公開されているプロジェクトのプレビューでも返します
branchConfig.lanes[]object[]レーン。id・name(名前の無いレーンは null。変えるときは省けます)・stepIds(そのレーンの工程の ID。上から順に実行)
branchConfig.rules[]object[]条件。id・kind(判定対象と規則の種類)と規則ごとの値・to(当てはまったときの進む先)
branchConfig.otherwiseobjectどの条件にも当てはまらないときの進む先
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"(失敗として閉じる)。前の版で保存した "goto" が返ることがありますが、ワークフローの実行では "gate" と同じく確認を求めます
onDegradedstring | null「Agent の報告による失敗のとき」の扱い。"gate"(確認を求める)。前の版で保存した "proceed"・"goto" が返ることがありますが、ワークフローの実行では "gate" と同じく確認を求めます
outcomeRoutesobject | nullいつも null(マーケットプレイス版では、結果ごとの次の工程を設定できません)
laneIdstring | nullいつも null
placementExecutionstring | nullいつも null(置いた順に 1 つずつ実行)
digeststring工程を変えるときに baseDigest に送る値

branchConfig の決まり: branchConfig は、条件分岐の工程を足した後に、工程を変える API で付けます(足す API では送れません)。先に、レーンにする工程を条件分岐のすぐ後ろに、レーンごとに続けて並べてください。lanes は 1〜12 本(工程は条件分岐を含めて全部で 12 までなので、実際は 11 本まで)で、どのレーンにも工程を 1 つ以上入れます(同じ工程を 2 つのレーンには入れられません。name は 50 文字まで)。rules は上から順に確かめ、最初に当てはまった条件の to へ進みます(8 件まで。0 件なら、いつも otherwise)。to は {"kind": "lane", "laneId": …} か {"kind": "merge"}(何もせずに合流)、otherwise はそのどちらか、または {"kind": "ask"}(人に選択してもらう)で、省くと merge です。lanes[].id と rules[].id は英数字と _・- の 64 文字までで、同じ設定の中で重ねられません。stepIds は工程の ID(UUID)です。レーンの中に条件分岐は置けず、条件分岐とそのレーンは並列のレーンの外に置きます。

規則の種類(rules[].kind):

kind値当たるとき
text_containsvalue(200 文字まで。空白だけにはできません)・negate前の工程の結果の文に value を含む(negate が true なら、含まない)
json_fieldpath(ドット区切りの項目の名前。200 文字まで)・op("eq"・"ne"・"gte"・"lte"・"exists")・value(op が "exists" のほか。200 文字までの文字列か数)前の工程の結果の JSON の項目が value と同じ・違う・以上・以下("exists" は項目がある)
files_existnegate成果物がある(negate が true なら、ない)
files_countop("gte"・"lte")・value(0 以上の整数)成果物の数が value 以上・以下
file_typefileType("pdf"・"excel"・"word"・"powerpoint"・"image")その種類の成果物がある
file_name_containsvalue(200 文字まで。空白だけにはできません)名前に value を含む成果物がある
duration_minutesop("gte"・"lte")・value(分。0 以上の整数)前の工程の処理時間が value 分以上・以下
send_backsop("gte")・value(0 以上の整数)この工程に戻された回数が value 回以上
mutatingnegate前の工程で書き込み操作があった(negate が true なら、なかった)
no_change_reported—Agent が「変更は要らなかった」と報告した

工程を変える API の本文の例(レーン 2 本。PDF の成果物があれば「請求書」へ、結果の文に「対象外」を含めば何もせずに合流し、どちらでもなければ「そのほか」へ):

JSON
{
"baseDigest": "<その工程の digest>",
"branchConfig": {
"lanes": [
{ "id": "lane-invoice", "name": "請求書", "stepIds": ["3f6c1d2e-8b4a-4c1e-9f0a-1b2c3d4e5f60"] },
{ "id": "lane-other", "name": "そのほか", "stepIds": ["7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d"] }
],
"rules": [
{ "id": "row-pdf", "kind": "file_type", "fileType": "pdf", "to": { "kind": "lane", "laneId": "lane-invoice" } },
{ "id": "row-skip", "kind": "text_contains", "value": "対象外", "to": { "kind": "merge" } }
],
"otherwise": { "kind": "lane", "laneId": "lane-other" }
}
}

確認工程の設定(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)
条件分岐の工程(defaultZone の "branch")と branchConfig付けられる400(cycle_branch_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"・"branch" のどれか。省くと "ai"。null・空の文字列は送れません
branchConfig——送れません(400 step_reference_on_create)。工程を足した後、レーンの工程を後ろに置いてから、工程を変える API で付けます
outputConfig——送れません(null 以外は 400 output_config_invalid。null は送らないのと同じです)
afterStepIdstring—この工程の後ろに足す(このプロジェクトの工程の ID)
beforeStepIdstring—この工程の前に足す(このプロジェクトの工程の ID)。afterStepId と両方を指定すると、この工程の前に足します。どちらも省くと末尾に足します
gateConfigobject | null—確認工程の設定(工程の項目の gateConfig と同じ形)。null は設定なし

リクエスト例​

Create step
1curl -X POST https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "name": "差異の報告",
6 "description": null,
7 "defaultZone": "ai",
8 "afterStepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
9}'

レスポンス(201 Created)​

フィールド型説明
stepobject足した工程
stepsarray足した後の全部の工程(並び順)
stepsDigeststring足した後の工程の並びの値
definitionApprovalobject | nullテナントで定義の変更に承認が要るとき、この変更は承認待ちになり、ここに承認待ちの様子が入ります(status が "pending"。項目は定義の承認の項目)。承認されるまで、実行は前の定義で動きます。承認が要らず、すぐ反映したときは null

レスポンス例​

JSON
{
"step": {
"stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"position": 3,
"name": "差異の報告",
"description": null,
"enabled": true,
"defaultZone": "ai",
"branchConfig": null,
"reworkToStepId": null,
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null,
"digest": "idyMTCSnJ2toCfD4Y8F_cqLwFwZ-cyJpByz-v1nxscE"
},
"steps": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"position": 1,
"name": "金額の確認",
"description": "請求書の金額と明細を照合します",
"enabled": true,
"defaultZone": "ai",
"branchConfig": null,
"reworkToStepId": null,
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null,
"digest": "jZ38OtGgLnS14QCvjZdg5PdyrGEHPK0EhxgDZzEnE2Y"
},
{
"stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"position": 2,
"name": "差異の確認",
"description": null,
"enabled": true,
"defaultZone": "gate",
"branchConfig": null,
"reworkToStepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null,
"digest": "27bA5P1PM8JFDwEEZhLP5DDn77Q8MFWq-YcGa6q8Sso"
},
{
"stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"position": 3,
"name": "差異の報告",
"description": null,
"enabled": true,
"defaultZone": "ai",
"branchConfig": null,
"reworkToStepId": null,
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null,
"digest": "idyMTCSnJ2toCfD4Y8F_cqLwFwZ-cyJpByz-v1nxscE"
}
],
"stepsDigest": "6r94LWhMkQ54T1GkU_ntdq-ZfgpGyeGFyu4Gt32V9H0",
"definitionApproval": null
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId が UUID の形式ではない、afterStepId・beforeStepId がこのプロジェクトの工程ではない、項目の型や長さ・値の誤り(name の空白だけ、defaultZone の null・空の文字列を含みます)、または gateConfig に approvers・escalateToRef を送った(approverUserIds・escalateToUserId を使います)
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
400structure_not_for_marketplaceマーケットプレイス版に無い確認工程の設定("notify_only"・期限後の自動処理)を送った。error.param に、断られた項目の名前(gateConfig.mode など)が入ります
400step_reference_on_creategateConfig に destinations を送った(null・空の配列を含みます。マーケットプレイス版では進め先を設定できません)、または branchConfig を送った(error.param は branchConfig。工程を足した後、レーンの工程を後ろに置いてから、工程を変える API で付けてください)
400cycle_gate_not_allowedcycle に確認工程を足そうとした
400cycle_branch_not_allowedcycle に条件分岐の工程("branch")を足そうとした
400branch_step_settings条件分岐の工程では使えない項目を送った。その項目を送らないでください(error.param にその項目の名前)
400output_config_invalidoutputConfig を送った(マーケットプレイス版では使えません。null は送らないのと同じです)。error.param は outputConfig
400approver_not_member確認担当者にメンバーではない利用者を指定した
400approvers_required稼働中の workflow に、確認担当者のいない確認工程を足そうとした
400escalate_to_not_member期限超過時の連絡先にメンバーではない利用者を指定した
403forbiddenシステム連携のトークンで呼び出した
403owner_onlyオーナーではないメンバー
403sso_required認証サーバーのアカウントと結び付いていない利用者
404project_not_foundプロジェクトが存在しない、またはメンバーではない
409too_many_steps工程がすでに 12 個ある
409flow_structure_conflict条件分岐の置き方と食い違う(理由は error.reason。工程を並べ替える API の誤りの表の下)
413body_too_largeボディが 32 KiB を超える
415unsupported_media_typeボディの Content-Type が application/json ではない
409definition_invalid承認待ちの変更に重ねると定義が成り立たない(理由の種類は error.reason)。definition=pending で読み直し、重ねた形を見て直してください
503approval_setting_unavailable定義の承認の設定を確かめられない。時間をおいて送り直してください
503definition_busy同じ定義の変更が処理中。時間をおいて送り直してください

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

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

パスパラメータ​

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

リクエストボディ​

フィールド型必須説明
baseDigeststring必須その工程の digest
namestring | null—工程の名前(100 文字まで)。空の文字列・null で既定の名前に戻します。空白だけにはできません
descriptionstring—説明(2000 文字まで。空の文字列・空白だけ・null にはできません)
defaultZonestring—"ai"・"gate"・"branch" のどれか
branchConfigobject | null—条件分岐の設定(defaultZone が "branch" の工程だけ。形は工程の項目の branchConfig と下の決まり)。送ると丸ごと置き換え、null で外します
outputConfig——送れません(null 以外は 400 output_config_invalid。null は送らないのと同じで、null だけでは変える項目が無い 400 invalid_parameter です)
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"("goto" は 400 structure_not_for_marketplace)。前の版で保存した値の工程でも、onDenied を送らなければ断られません。取得した値をそのまま送り返すと 400 です
onDegradedstring | null—"gate"("proceed"・"goto" は 400 structure_not_for_marketplace)。前の版で保存した値の工程でも、onDegraded を送らなければ断られません。取得した値をそのまま送り返すと 400 です
scheduleobject | null—工程の時刻(workflow だけ)。expression(5 項目の cron 式)と timezone(省くと UTC)。null で外します

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

条件分岐の工程にすると、確認・時刻・次の工程の候補・結果の扱い・差し戻し先・同時に実行の設定が外れます。Agent を置いた工程は、条件分岐の工程にできません。

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

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

リクエスト例​

Update step
1curl -X PATCH https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps/5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819 \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "baseDigest": "jZ38OtGgLnS14QCvjZdg5PdyrGEHPK0EhxgDZzEnE2Y",
6 "name": "金額の確認(税込)"
7}'

レスポンス(200 OK)​

フィールド型説明
stepobject変えた後の工程(新しい digest)
definitionApprovalobject | nullテナントで定義の変更に承認が要るとき、この変更は承認待ちになり、ここに承認待ちの様子が入ります(status が "pending"。項目は定義の承認の項目)。承認されるまで、実行は前の定義で動きます。承認が要らず、すぐ反映したときは null

レスポンス例​

JSON
{
"step": {
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"position": 1,
"name": "金額の確認(税込)",
"description": "請求書の金額と明細を照合します",
"enabled": true,
"defaultZone": "ai",
"branchConfig": null,
"reworkToStepId": null,
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null,
"digest": "DnfITwsv5MlLFs8OPquzCBg2dGQCDhScmxK22X7Siv0"
},
"definitionApproval": null
}

エラーレスポンス​

ステータス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マーケットプレイス版に無い工程の構造(結果ごとの次の工程・進め先・onDenied の "goto"・onDegraded の "proceed"・"goto"・"notify_only"・期限後の自動処理など)を送った。error.param に、断られた項目の名前(onDenied・onDegraded・gateConfig.mode など)が入ります
400cycle_gate_not_allowedcycle の工程を確認工程にしようとした、または onDenied・onDegraded に "gate" を指定した
400cycle_route_not_allowedcycle の工程に "goto" を指定した
400cycle_branch_not_allowedcycle の工程を条件分岐の工程("branch")にしようとした、または cycle の工程に branchConfig を送った
400branch_step_settings条件分岐の工程では使えない項目を送った。その項目を送らないでください(error.param にその項目の名前)
400output_config_invalidoutputConfig を送った(マーケットプレイス版では使えません。null は送らないのと同じです)。error.param は outputConfig
400invalid_branch_configbranchConfig の形・値の誤り(レーンは 1〜12 本で各レーンに工程が 1 つ以上・条件は 8 件まで・id の形・規則の値など。上の決まり)。外すときは null を送ってください
400branch_config_not_alloweddefaultZone が "branch" でない工程に branchConfig を送った(外すときは null)
400invalid_branch_lanesbranchConfig.lanes の工程が、条件分岐のすぐ後ろに lanes の順でレーンごとに続けて並んでいない(間にほかの工程がある)。先に工程を並べ替えてから送り直してください
400branch_nestedほかの条件分岐のレーンの工程を、この条件分岐やそのレーンにしようとした。先にほかの条件分岐のレーンから外すか、レーンの外の工程を使ってください
409branch_step_has_agentsAgent を置いた工程を、条件分岐の工程にしようとした。先に配置を外してください
409branch_ai_not_supportedkind が "ai" の規則を送った(マーケットプレイス版では使えません)。ほかの種類の規則を使ってください
400approver_not_member確認担当者にメンバーではない利用者を指定した
400approvers_required稼働中の workflow で、有効な確認工程の確認担当者がいなくなる
400escalate_to_not_member期限超過時の連絡先にメンバーではない利用者を指定した
400invalid_send_back_step差し戻し先が、この工程より前の工程ではない
403forbiddenシステム連携のトークンで呼び出した
403owner_onlyオーナーではないメンバー
403sso_required認証サーバーのアカウントと結び付いていない利用者
403feature_not_permittedschedule を保存済みの値から変えようとしたが、管理者が定期実行の作成を許可していない。schedule を送らない・同じ値を送る・null で外す変更は通ります
404step_not_found工程が存在しない、またはメンバーではないプロジェクト
409stale_base取得した後に工程が変わっている。承認待ちがあるときは、既定の取得の digest では合いません。definition=pending で読み直し、その digest を baseDigest に送ってください
409flow_structure_conflict条件分岐の置き方と食い違う(理由は error.reason。工程を並べ替える API の誤りの表の下)
413body_too_largeボディが 32 KiB を超える
415unsupported_media_typeボディの Content-Type が application/json ではない
409definition_invalid承認待ちの変更に重ねると定義が成り立たない(理由の種類は error.reason)。definition=pending で読み直し、重ねた形を見て直してください
503feature_permissions_unavailable機能の許可を確かめられない。時間をおいて送り直してください
503approval_setting_unavailable定義の承認の設定を確かめられない。時間をおいて送り直してください
503definition_busy同じ定義の変更が処理中。時間をおいて送り直してください

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

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

パスパラメータ​

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

リクエストボディ​

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

リクエスト例​

Reorder steps
1curl -X PUT https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps/order \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "baseDigest": "6r94LWhMkQ54T1GkU_ntdq-ZfgpGyeGFyu4Gt32V9H0",
6 "stepIds": [
7 "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
8 "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
9 "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
10 ]
11}'

レスポンス(200 OK)​

フィールド型説明
stepsarray並べ替えた後の全部の工程
stepsDigeststring並べ替えた後の工程の並びの値
definitionApprovalobject | nullテナントで定義の変更に承認が要るとき、この変更は承認待ちになり、ここに承認待ちの様子が入ります(status が "pending"。項目は定義の承認の項目)。承認されるまで、実行は前の定義で動きます。承認が要らず、すぐ反映したときは null

レスポンス例​

JSON
{
"steps": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"position": 1,
"name": "金額の確認",
"description": "請求書の金額と明細を照合します",
"enabled": true,
"defaultZone": "ai",
"branchConfig": null,
"reworkToStepId": null,
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null,
"digest": "jZ38OtGgLnS14QCvjZdg5PdyrGEHPK0EhxgDZzEnE2Y"
},
{
"stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"position": 2,
"name": "差異の報告",
"description": null,
"enabled": true,
"defaultZone": "ai",
"branchConfig": null,
"reworkToStepId": null,
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null,
"digest": "idyMTCSnJ2toCfD4Y8F_cqLwFwZ-cyJpByz-v1nxscE"
},
{
"stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"position": 3,
"name": "差異の確認",
"description": null,
"enabled": true,
"defaultZone": "gate",
"branchConfig": null,
"reworkToStepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null,
"digest": "27bA5P1PM8JFDwEEZhLP5DDn77Q8MFWq-YcGa6q8Sso"
}
],
"stepsDigest": "TQbgPozTGXVTzA52FXfg_NPAcQRj94bGXmyUVP-WTeo",
"definitionApproval": null
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId が UUID の形式ではない、baseDigest が無い・空・文字列ではない、または stepIds が全部の工程の並びになっていない
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
403forbiddenシステム連携のトークンで呼び出した
403owner_onlyオーナーではないメンバー
403sso_required認証サーバーのアカウントと結び付いていない利用者
404project_not_foundプロジェクトが存在しない、またはメンバーではない
409stale_base取得した後に工程の並びが変わっている。承認待ちがあるときは、既定の取得の digest では合いません。definition=pending で読み直し、その digest を baseDigest に送ってください
409flow_structure_conflict条件分岐の置き方と食い違う(理由は error.reason。工程を並べ替える API の誤りの表の下)
413body_too_largeボディが 16 KiB を超える
415unsupported_media_typeボディの Content-Type が application/json ではない
409definition_invalid承認待ちの変更に重ねると定義が成り立たない(理由の種類は error.reason)。definition=pending で読み直し、重ねた形を見て直してください
503approval_setting_unavailable定義の承認の設定を確かめられない。時間をおいて送り直してください
503definition_busy同じ定義の変更が処理中。時間をおいて送り直してください

409(flow_structure_conflict)が条件分岐の置き方によるときは、error.reason に理由が入ります。branch_nested(ほかの条件分岐のレーンに条件分岐が入る)・route_into_branch_lane(レーンの外の工程から条件分岐のレーンの中へ差し戻し先・次の工程が向く)です。工程を足す・変える・消す API の flow_structure_conflict も同じです。

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

工程を消します。オーナーだけが呼べます。その工程を指す差し戻し先・次の工程・トリガーの開始工程は外れ、その工程の配置と巡回も外れます。過去のワークフローの実行や確認依頼が使った工程は、記録のために残ります(historyKept が true)。承認待ちになったとき(definitionApproval.status が "pending")は、deleted: true が返っても、承認されるまで消えません。既定の取得には残ります。

パスパラメータ​

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

リクエスト例​

Delete step
1curl -X DELETE https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d \
2-H "Authorization: Bearer <access_token>"

レスポンス(200 OK)​

フィールド型説明
stepIdstring消した工程の ID
deletedbooleanいつも true
historyKeptboolean | null記録のために工程を残したかどうか。承認待ちになったときは null(まだ消えていないため)
stepsarray消した後の全部の工程
stepsDigeststring消した後の工程の並びの値
definitionApprovalobject | nullテナントで定義の変更に承認が要るとき、この変更は承認待ちになり、ここに承認待ちの様子が入ります(status が "pending"。項目は定義の承認の項目)。承認されるまで、実行は前の定義で動きます。承認が要らず、すぐ反映したときは null

レスポンス例​

JSON
{
"stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"deleted": true,
"historyKept": false,
"steps": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"position": 1,
"name": "金額の確認",
"description": "請求書の金額と明細を照合します",
"enabled": true,
"defaultZone": "ai",
"branchConfig": null,
"reworkToStepId": null,
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null,
"digest": "jZ38OtGgLnS14QCvjZdg5PdyrGEHPK0EhxgDZzEnE2Y"
},
{
"stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"position": 2,
"name": "差異の確認",
"description": null,
"enabled": true,
"defaultZone": "gate",
"branchConfig": null,
"reworkToStepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null,
"digest": "27bA5P1PM8JFDwEEZhLP5DDn77Q8MFWq-YcGa6q8Sso"
}
],
"stepsDigest": "OCkD5Kg3AClwepKwjLk5TZT1bwRFId09NV7SQKZOpL4",
"definitionApproval": null
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId・stepId が UUID の形式ではない
403forbiddenシステム連携のトークンで呼び出した
403owner_onlyオーナーではないメンバー
403sso_required認証サーバーのアカウントと結び付いていない利用者
404step_not_found工程が存在しない、またはメンバーではないプロジェクト
409min_steps工程が下限の数しかない(ワークフローは 2 つ、サイクルは 1 つ)
409flow_structure_conflict条件分岐の置き方と食い違う(理由は error.reason。工程を並べ替える API の誤りの表の下)
409definition_invalid承認待ちの変更に重ねると定義が成り立たない(理由の種類は error.reason)。definition=pending で読み直し、重ねた形を見て直してください
503approval_setting_unavailable定義の承認の設定を確かめられない。時間をおいて送り直してください
503definition_busy同じ定義の変更が処理中。時間をおいて送り直してください

配置​

配置は、登録 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配置の担当工程を変える
PUT/v1/projects/{projectId}/placements/{placementId}/steps/{stepId}/runtime-config配置の工程の設定を書く
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 を置いているのがこのプロジェクトだけかどうか
agentStoppedboolean | null置いた Agent を管理者が止めているか。止めている間、この配置の工程は始まらず、再開を待ちます
relinkobject | nullいつも null
digeststring配置を変える API(担当工程・巡回・工程の設定)で baseDigest に送る値。担当工程・実行の設定・巡回から作られ、Agent の中身を変えても変わりません

GET/v1/projects/{projectId}/placements

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

クエリパラメータ​

パラメータ型必須説明
definitionstring—"pending" を付けると、定義の変更の承認待ちを重ねた見え方で返します。付けないときは、承認された定義を返します

リクエスト例​

List placements
1curl https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements \
2-H "Authorization: Bearer <access_token>"

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

フィールド型説明
placementsarray配置の配列。1 件の項目は「配置の項目」を参照
hasMorebooleanいつも false
definitionViewstring | nulldefinition=pending を付けたときだけ。"pending"(承認待ちを重ねた見え方)か "active"(承認待ちが無い)。組織の運用の役割を持ち、プロジェクトに参加していない人には null

レスポンス例​

JSON
{
"placements": [
{
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"agentId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
"displayOrder": 0,
"name": "請求書チェック",
"description": "請求書の金額と明細を照合します",
"goal": null,
"guardrail": null,
"skills": [],
"skillCount": 0,
"playbookId": null,
"playbookName": null,
"inputFiles": [],
"stepIds": [
"5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"
],
"sweeps": [],
"runtimeConfigs": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"runtimeConfig": null
}
],
"libraryBindings": [],
"memoryOrgId": null,
"memoryJobId": null,
"agentOwnerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"isShared": false,
"runtimeKind": "marketplace",
"marketplaceAgentId": "invoice-checker",
"exclusiveToThisProject": true,
"agentStopped": false,
"relink": null,
"digest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU"
}
],
"hasMore": false
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId が UUID の形式ではない
403forbiddenシステム連携のトークンで呼び出した
403sso_required認証サーバーのアカウントと結び付いていない利用者
404project_not_foundプロジェクトが存在しない、またはメンバーではない
409definition_invaliddefinition=pending で、承認待ちの変更に重ねると定義が成り立たない(理由の種類は error.reason)
503definition_busydefinition=pending で、同じ定義の変更が処理中。時間をおいて送り直してください

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

配置を 1 件取得します。

クエリパラメータ​

パラメータ型必須説明
definitionstring—"pending" を付けると、定義の変更の承認待ちを重ねた見え方で返します。付けないときは、承認された定義を返します

リクエスト例​

Get placement
1curl https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d \
2-H "Authorization: Bearer <access_token>"

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

フィールド型説明
placementobject配置。項目は「配置の項目」を参照
definitionViewstring | nulldefinition=pending を付けたときだけ。"pending"(承認待ちを重ねた見え方)か "active"(承認待ちが無い)。組織の運用の役割を持ち、プロジェクトに参加していない人には null

レスポンス例​

JSON
{
"placement": {
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"agentId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
"displayOrder": 0,
"name": "請求書チェック",
"description": "請求書の金額と明細を照合します",
"goal": null,
"guardrail": null,
"skills": [],
"skillCount": 0,
"playbookId": null,
"playbookName": null,
"inputFiles": [],
"stepIds": [
"5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"
],
"sweeps": [],
"runtimeConfigs": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"runtimeConfig": null
}
],
"libraryBindings": [],
"memoryOrgId": null,
"memoryJobId": null,
"agentOwnerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"isShared": false,
"runtimeKind": "marketplace",
"marketplaceAgentId": "invoice-checker",
"exclusiveToThisProject": true,
"agentStopped": false,
"relink": null,
"digest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU"
}
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId・placementId が UUID の形式ではない
403forbiddenシステム連携のトークンで呼び出した
403sso_required認証サーバーのアカウントと結び付いていない利用者
404placement_not_found配置が存在しない、ほかのプロジェクトの配置、またはメンバーではないプロジェクト
409definition_invaliddefinition=pending で、承認待ちの変更に重ねると定義が成り立たない(理由の種類は error.reason)
503definition_busydefinition=pending で、同じ定義の変更が処理中。時間をおいて送り直してください

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)。

ワークフローの定義を持つ登録 Agent は、置いて始めるのに要る定義(入力ファイル・出力・parameters の形と既定値・接続の枠)も返します。入力ファイルは、入力ファイルを上げる APIで上げ、ワークフローの実行の開始の config で渡します。定義が無い候補("cycle" の候補と、定義を読めないワークフローの候補)は、この 5 つの項目が null です(項目は省きません)。

クエリパラメータ​

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

リクエスト例​

List agent candidates
1curl "https://<your-domain>/api/v1/projects/agent-candidates?project_type=workflow" \
2-H "Authorization: Bearer <access_token>"

レスポンスフィールド(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
candidates[].inputsarray | null登録 Agent が受け取る入力ファイル。名前を、開始の config の fileBindings と、工程の設定の inputBindings に使います
candidates[].inputs[].namestring | null入力ファイルの名前
candidates[].inputs[].formatstring | null形式("markdown"・"yaml"・"json"・"text"・"binary")
candidates[].inputs[].requiredboolean必須かどうか
candidates[].inputs[].editableboolean人が中身を入れる入力かどうか
candidates[].inputs[].fromParametersbooleanparameters から作られる入力かどうか
candidates[].inputs[].schemaobject | null"yaml"・"json" の入力の形(JSON Schema)。上げるときにこの形で確かめます
candidates[].outputsarray | null登録 Agent が出す出力ファイル(name・format・required)。名前を、後の工程の inputBindings の output に使います
candidates[].parametersSchemaobject | nullparameters の形(JSON Schema)
candidates[].defaultsobject | null定義の既定値
candidates[].connectionSlotsarray | null接続の枠。name(枠の名前)・required(必須かどうか)・allowedProviderIds(指定できる連携先の ID の配列)
hasMorebooleanいつも false(全件を返します)

レスポンス例​

JSON
{
"candidates": [
{
"marketplaceAgentId": "invoice-checker",
"displayName": "請求書チェック",
"description": "請求書の金額と明細を照合します",
"iconUrl": null,
"tags": [
"経理"
],
"certified": true,
"certificationProblem": null,
"inputs": [
{
"name": "invoice",
"format": "json",
"required": true,
"editable": false,
"fromParameters": false,
"schema": {
"type": "object"
}
}
],
"outputs": [
{
"name": "report",
"format": "markdown",
"required": true
}
],
"parametersSchema": {
"type": "object",
"properties": {
"currency": {
"type": "string"
}
}
},
"defaults": {
"currency": "JPY"
},
"connectionSlots": []
}
],
"hasMore": false
}

エラーレスポンス​

ステータス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 はありません。

リクエスト例​

Place agent
1curl -X POST https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "marketplaceAgentId": "invoice-checker",
6 "stepIds": [
7 "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"
8 ]
9}'

レスポンス(201 Created)​

フィールド型説明
placementobject置いた配置。項目は「配置の項目」を参照
definitionApprovalobject | nullテナントで定義の変更に承認が要るとき、この変更は承認待ちになり、ここに承認待ちの様子が入ります(status が "pending"。項目は定義の承認の項目)。承認されるまで、実行は前の定義で動きます。承認が要らず、すぐ反映したときは null

レスポンス例​

JSON
{
"placement": {
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"agentId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
"displayOrder": 0,
"name": "請求書チェック",
"description": "請求書の金額と明細を照合します",
"goal": null,
"guardrail": null,
"skills": [],
"skillCount": 0,
"playbookId": null,
"playbookName": null,
"inputFiles": [],
"stepIds": [
"5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"
],
"sweeps": [],
"runtimeConfigs": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"runtimeConfig": null
}
],
"libraryBindings": [],
"memoryOrgId": null,
"memoryJobId": null,
"agentOwnerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"isShared": false,
"runtimeKind": "marketplace",
"marketplaceAgentId": "invoice-checker",
"exclusiveToThisProject": true,
"agentStopped": false,
"relink": null,
"digest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU"
},
"definitionApproval": null
}

エラーレスポンス​

ステータス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 ではない
409definition_invalid承認待ちの変更に重ねると定義が成り立たない(理由の種類は error.reason)。definition=pending で読み直し、重ねた形を見て直してください
503approval_setting_unavailable定義の承認の設定を確かめられない。時間をおいて送り直してください
503definition_busy同じ定義の変更が処理中。時間をおいて送り直してください

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

配置を外します。オーナーだけが呼べます。過去のワークフローの実行が使った配置は、記録のために残ります(historyKept が true)。承認待ちになったとき(definitionApproval.status が "pending")は、deleted: true が返っても、承認されるまで外れません。既定の取得には残ります。外した配置の過去の実行は、実行履歴に元の配置の ID(placementId)のまま残ります。

リクエスト例​

Remove placement
1curl -X DELETE https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d \
2-H "Authorization: Bearer <access_token>"

レスポンス(200 OK)​

フィールド型説明
placementIdstring外した配置の ID
deletedbooleanいつも true
historyKeptboolean | null記録のために配置を残したかどうか。承認待ちになったときは null(まだ外れていないため)
definitionApprovalobject | nullテナントで定義の変更に承認が要るとき、この変更は承認待ちになり、ここに承認待ちの様子が入ります(status が "pending"。項目は定義の承認の項目)。承認されるまで、実行は前の定義で動きます。承認が要らず、すぐ反映したときは null

レスポンス例​

JSON
{
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"deleted": true,
"historyKept": false,
"definitionApproval": null
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId・placementId が UUID の形式ではない
403forbiddenシステム連携のトークンで呼び出した
403owner_onlyオーナーではないメンバー
403sso_required認証サーバーのアカウントと結び付いていない利用者
404placement_not_found配置が存在しない、ほかのプロジェクトの配置、またはメンバーではないプロジェクト
409definition_invalid承認待ちの変更に重ねると定義が成り立たない(理由の種類は error.reason)。definition=pending で読み直し、重ねた形を見て直してください
503approval_setting_unavailable定義の承認の設定を確かめられない。時間をおいて送り直してください
503definition_busy同じ定義の変更が処理中。時間をおいて送り直してください

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

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

リクエストボディ​

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

リクエスト例​

Update placement steps
1curl -X PUT https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/steps \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU",
6 "stepIds": [
7 "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
8 "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d"
9 ]
10}'

レスポンス(200 OK)​

フィールド型説明
placementobject変えた後の配置(新しい digest)
definitionApprovalobject | nullテナントで定義の変更に承認が要るとき、この変更は承認待ちになり、ここに承認待ちの様子が入ります(status が "pending"。項目は定義の承認の項目)。承認されるまで、実行は前の定義で動きます。承認が要らず、すぐ反映したときは null

レスポンス例​

JSON
{
"placement": {
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"agentId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
"displayOrder": 0,
"name": "請求書チェック",
"description": "請求書の金額と明細を照合します",
"goal": null,
"guardrail": null,
"skills": [],
"skillCount": 0,
"playbookId": null,
"playbookName": null,
"inputFiles": [],
"stepIds": [
"5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d"
],
"sweeps": [],
"runtimeConfigs": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"runtimeConfig": null
},
{
"stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"runtimeConfig": null
}
],
"libraryBindings": [],
"memoryOrgId": null,
"memoryJobId": null,
"agentOwnerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"isShared": false,
"runtimeKind": "marketplace",
"marketplaceAgentId": "invoice-checker",
"exclusiveToThisProject": true,
"agentStopped": false,
"relink": null,
"digest": "T4llTd4mnzoQvxn2wLcaiiTARKxh9AMsregqNUhNaCg"
},
"definitionApproval": null
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId・placementId が UUID の形式ではない、baseDigest が無い・空・文字列ではない、または stepIds の誤り(12 個を超える、このプロジェクトの工程ではない、同じ工程を重ねた など)
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
403forbiddenシステム連携のトークンで呼び出した
403owner_onlyオーナーではないメンバー
403sso_required認証サーバーのアカウントと結び付いていない利用者
404placement_not_found配置が存在しない、ほかのプロジェクトの配置、またはメンバーではないプロジェクト
409stale_base取得した後に配置が変わっている。承認待ちがあるときは、既定の取得の digest では合いません。definition=pending で読み直し、その digest を baseDigest に送ってください
413body_too_largeボディが 16 KiB を超える
415unsupported_media_typeボディの Content-Type が application/json ではない
409definition_invalid承認待ちの変更に重ねると定義が成り立たない(理由の種類は error.reason)。definition=pending で読み直し、重ねた形を見て直してください
503approval_setting_unavailable定義の承認の設定を確かめられない。時間をおいて送り直してください
503definition_busy同じ定義の変更が処理中。時間をおいて送り直してください

PUT/v1/projects/{projectId}/placements/{placementId}/steps/{stepId}/runtime-config

配置の 1 つの工程の設定を、送った内容で丸ごと置き換えます。プロジェクトのオーナーだけが呼べます。workflow では、登録 Agent の parameters、接続の枠への連携先の対応(connectionBindings)、前の工程の出力をどの入力ファイルに渡すか(inputBindings)を書きます。cycle では、環境変数(env)だけを書きます。設定の項目を 1 つも送らないと、その工程の設定を消します。ここで書いた設定は、workflow では次に始めるワークフローの実行から、cycle では次に始まる巡回(トリガーの発火で始まるものを含む)から使われます。

パスパラメータ​

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

リクエストボディ​

フィールド型必須説明
baseDigeststring必須配置の取得で返る digest
parametersobject—workflow だけ。登録 Agent の parameters(置ける登録 Agent の一覧の parametersSchema の形)
connectionBindingsobject—workflow だけ。接続の枠の名前(connectionSlots[].name)から連携先の ID への対応
inputBindingsobject—workflow だけ。入力ファイルの名前(inputs[].name)から { "placementId", "output", "stepId" }(前の工程の配置・その出力の名前(outputs[].name)・工程。stepId は省けます)への対応
envobject—cycle だけ。環境変数の名前から値(文字列)への対応。32 個まで

ボディは 16 KiB までです。

リクエスト例​

Update placement runtime config
1curl -X PUT https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/steps/5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819/runtime-config \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU",
6 "parameters": {
7 "currency": "JPY"
8 },
9 "connectionBindings": {},
10 "inputBindings": {
11 "invoice": {
12 "placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
13 "output": "report"
14 }
15 }
16}'

レスポンス(200 OK)​

フィールド型説明
placementobject書いた後の配置(新しい digest)。項目は「配置の項目」を参照
definitionApprovalobject | nullテナントで定義の変更に承認が要るとき、この変更は承認待ちになり、ここに承認待ちの様子が入ります(status が "pending"。項目は定義の承認の項目)。承認されるまで、実行は前の定義で動きます。承認が要らず、すぐ反映したときは null

レスポンス例​

JSON
{
"placement": {
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"agentId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
"displayOrder": 0,
"name": "請求書チェック",
"description": "請求書の金額と明細を照合します",
"goal": null,
"guardrail": null,
"skills": [],
"skillCount": 0,
"playbookId": null,
"playbookName": null,
"inputFiles": [],
"stepIds": [
"5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"
],
"sweeps": [],
"runtimeConfigs": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"runtimeConfig": {
"parameters": {
"currency": "JPY"
},
"connection_bindings": {},
"input_bindings": {
"invoice": {
"project_agent_id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"output": "report"
}
}
}
}
],
"libraryBindings": [],
"memoryOrgId": null,
"memoryJobId": null,
"agentOwnerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"isShared": false,
"runtimeKind": "marketplace",
"marketplaceAgentId": "invoice-checker",
"exclusiveToThisProject": true,
"agentStopped": false,
"relink": null,
"digest": "EjOdiFVd4xYReELiRIREoCHSrd35rG1a0RcKlyvS52s"
},
"definitionApproval": null
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId・placementId・stepId が UUID の形式ではない、baseDigest が無い、またはプロジェクトの型に合わない項目を送った(workflow に env、cycle に parameters・connectionBindings・inputBindings。param にその名前)
400invalid_runtime_config設定が登録 Agent の定義に合わない(message に理由の初めの 3 つ)
400runtime_not_allowedこの配置の工程には設定を書けない(登録 Agent に定義が無いなど)
400env_invalid・env_too_many・env_too_large・env_value_invalid・env_name_invalid・env_name_reserved・env_name_denied・env_secret_override・env_denied_config_invalidcycle の env を受け付けられない(形が違う・多すぎる〈名前は 32 個まで〉・大きすぎる〈名前と値の合計が 16KiB まで〉・値が文字列ではない・名前が使えない・予約された名前・管理者が許していない名前・登録 Agent の秘密の名前・管理者の決まりを読めない。message に名前)
400invalid_bodyリクエストボディが壊れた JSON、または JSON のオブジェクトではない
403forbiddenシステム連携のトークンで呼び出した
403owner_onlyプロジェクトのメンバーだが、オーナーではない
403sso_required認証サーバーのアカウントと結び付いていない利用者
404placement_not_foundプロジェクト・配置が存在しない、メンバーではない、またはその配置がその工程を担当していない
409stale_basebaseDigest が今の配置の digest と違う(取得し直して送り直してください)。承認待ちがあるときは、既定の取得の digest では合いません。definition=pending で読み直し、その digest を baseDigest に送ってください
413body_too_largeリクエストボディが 16 KiB を超過
415unsupported_media_typeリクエストボディがあるのに、Content-Type が application/json ではない
409definition_invalid承認待ちの変更に重ねると定義が成り立たない(理由の種類は error.reason)。definition=pending で読み直し、重ねた形を見て直してください
503approval_setting_unavailable定義の承認の設定を確かめられない。時間をおいて送り直してください
503definition_busy同じ定義の変更が処理中。時間をおいて送り直してください

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

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

リクエストボディ​

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

リクエスト例​

Update placement schedule
1curl -X PATCH https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/schedule \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU",
6 "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
7 "enabled": true,
8 "cron": "0 9 * * 1",
9 "timezone": "Asia/Tokyo"
10}'

レスポンス(200 OK)​

フィールド型説明
placementobject変えた後の配置(新しい digest)
definitionApprovalobject | nullテナントで定義の変更に承認が要るとき、この変更は承認待ちになり、ここに承認待ちの様子が入ります(status が "pending"。項目は定義の承認の項目)。承認されるまで、実行は前の定義で動きます。承認が要らず、すぐ反映したときは null

レスポンス例​

JSON
{
"placement": {
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"agentId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
"displayOrder": 0,
"name": "請求書チェック",
"description": "請求書の金額と明細を照合します",
"goal": null,
"guardrail": null,
"skills": [],
"skillCount": 0,
"playbookId": null,
"playbookName": null,
"inputFiles": [],
"stepIds": [
"5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"
],
"sweeps": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"cron": "0 9 * * 1",
"timezone": "Asia/Tokyo",
"enabled": true
}
],
"runtimeConfigs": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"runtimeConfig": null
}
],
"libraryBindings": [],
"memoryOrgId": null,
"memoryJobId": null,
"agentOwnerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"isShared": false,
"runtimeKind": "marketplace",
"marketplaceAgentId": "invoice-checker",
"exclusiveToThisProject": true,
"agentStopped": false,
"relink": null,
"digest": "TQwslacxj54G-mnF8xImeTexwswd53sGTRNesIiHwyU"
},
"definitionApproval": null
}

エラーレスポンス​

ステータス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認証サーバーのアカウントと結び付いていない利用者
403feature_not_permitted巡回が有効になる変更(無効から有効にする、または有効な巡回の cron・timezone を変える。送らなかった項目は今の値で見ます)だが、管理者が定期実行の作成を許可していない。enabled に false を送る変更は通ります
404placement_not_found配置が存在しない、ほかのプロジェクトの配置、またはメンバーではないプロジェクト
409stale_base取得した後に配置が変わっている。承認待ちがあるときは、既定の取得の digest では合いません。definition=pending で読み直し、その digest を baseDigest に送ってください
409principalプロジェクトの実行の主体(今のプロジェクトの持ち主)を確かめられない
409not_marketplace登録 Agent の配置ではない(周期を持てるのは登録 Agent の配置だけ)
413body_too_largeボディが 16 KiB を超える
415unsupported_media_typeボディの Content-Type が application/json ではない
409definition_invalid承認待ちの変更に重ねると定義が成り立たない(理由の種類は error.reason)。definition=pending で読み直し、重ねた形を見て直してください
503feature_permissions_unavailable機能の許可を確かめられない。時間をおいて送り直してください
503approval_setting_unavailable定義の承認の設定を確かめられない。時間をおいて送り直してください
503definition_busy同じ定義の変更が処理中。時間をおいて送り直してください

トリガー​

トリガーは、プロジェクトを動かすきっかけです。時刻のトリガー("cron")は workflow のプロジェクトだけにあり、決めた時刻にワークフローの実行を始めます(cycle は、配置ごとの巡回で時刻に動かします)。Webhook のトリガー("webhook")は cycle のプロジェクトだけにあり、発火すると、トリガーに結び付いた配置を臨時に 1 回動かします。トリガーの ID と今の設定は、プロジェクトの取得の triggers で読めます。

エンドポイント一覧​

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

POST/v1/projects/{projectId}/triggers

トリガーを作ります。オーナーだけが呼べます。システム連携のトークンでは呼べません。

パスパラメータ​

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

リクエストボディ​

フィールド型必須説明
typestring必須"cron"(時刻。workflow だけ)または "webhook"(cycle だけ)
namestring | null—名前(100 文字まで)。省くか null で名前なし
enabledboolean—有効かどうか。省くと true。null は送れません
cronstring"cron" は必須5 項目の cron 式(分 時 日 月 曜日。例: "0 9 * * 1")。100 文字まで
timezonestring | null—"cron" のタイムゾーン(IANA の名前。例: "Asia/Tokyo"。64 文字まで)。省くか null で UTC。空の文字列は送れません
startStepIdstring | null—"cron" で始める工程(このプロジェクトの工程の ID)。省くか null で最初の工程から
placementIdstring"webhook" は必須発火で動かす配置の ID
stepIdstring"webhook" は必須発火で動かす工程の ID(その配置が受け持つ工程)

種類ごとに送れる項目が決まっています。"cron" は name・enabled・cron・timezone・startStepId、"webhook" は name・enabled・placementId・stepId です。もう一方の種類の項目を送ると 400 Bad Request(invalid_parameter。param はその項目)です。

レスポンス(201 Created)​

フィールド型説明
triggerobject作ったトリガー。プロジェクトの取得の triggers[] と同じ項目です(digest を含みます。作ったばかりの "cron" の startFailure は null)
definitionApprovalobject | nullテナントで定義の変更に承認が要るとき、この変更は承認待ちになり、ここに承認待ちの様子が入ります(status が "pending"。項目は定義の承認の項目)。承認されるまで、実行は前の定義で動きます。承認が要らず、すぐ反映したときは null

リクエスト例​

Create triggers
1curl -X POST https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/triggers \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "type": "cron",
6 "name": "毎週月曜 9 時",
7 "cron": "0 9 * * 1",
8 "timezone": "Asia/Tokyo"
9}'

レスポンス例​

JSON
{
"trigger": {
"triggerId": "8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40",
"type": "cron",
"name": "毎週月曜 9 時",
"enabled": true,
"lastFiredAt": null,
"nextFireAt": "2026-11-16T00:00:00.000Z",
"createdAt": "2026-11-10T09:00:00.000Z",
"cron": "0 9 * * 1",
"timezone": "Asia/Tokyo",
"startStepId": null,
"startFailure": null,
"digest": "Nb8SAh4xIBu2F65clLazvr8vEGwTTPar7GdAw5jDKRA"
},
"definitionApproval": null
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId が UUID の形式ではない、type が無い・null・"cron" と "webhook" 以外、"cron" に cron が無い、"webhook" に placementId・stepId が無い、もう一方の種類の項目を送った、cron が読めない式・100 文字を超える、timezone が IANA の名前ではない・空の文字列・64 文字を超える、name が 100 文字を超える、startStepId・placementId・stepId が UUID の形式ではない、enabled が真偽値ではない、startStepId がこのプロジェクトの工程ではない、または stepId がその配置の工程ではない
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
400webhook_cycle_only"webhook" のトリガーを cycle ではないプロジェクトに作ろうとした(workflow は "cron" を使います)
400cron_workflow_only"cron" のトリガーを cycle のプロジェクトに作ろうとした(cycle は配置ごとの巡回で時刻に動かします)
403forbiddenシステム連携のトークンで呼び出した
403owner_onlyオーナーではないメンバー
403sso_required認証サーバーのアカウントと結び付いていない利用者
403feature_not_permitted管理者が定期実行の作成を許可していない(トリガーを作るときは、種類・enabled によらず確かめます)
404project_not_foundプロジェクトが存在しない、またはメンバーではない
413body_too_largeボディが 16 KiB を超える
415unsupported_media_typeボディの Content-Type が application/json ではない
409definition_invalid承認待ちの変更に重ねると定義が成り立たない(理由の種類は error.reason)。definition=pending で読み直し、重ねた形を見て直してください
503feature_permissions_unavailable機能の許可を確かめられない。時間をおいて送り直してください
503approval_setting_unavailable定義の承認の設定を確かめられない。時間をおいて送り直してください
503definition_busy同じ定義の変更が処理中。時間をおいて送り直してください

PATCH/v1/projects/{projectId}/triggers/{triggerId}

トリガーを変えます。送った項目だけを変えます。オーナーだけが呼べます。システム連携のトークンでは呼べません。

パスパラメータ​

パラメータ型必須説明
projectIdstring必須プロジェクト ID(UUID)
triggerIdstring必須トリガー ID(UUID。プロジェクトの取得の triggers[].triggerId)

リクエストボディ​

フィールド型必須説明
baseDigeststring必須そのトリガーの digest(プロジェクトの取得の triggers[].digest)
namestring—名前(100 文字まで)
enabledboolean—有効かどうか
cronstring—5 項目の cron 式("cron" だけ)。100 文字まで
timezonestring—タイムゾーン("cron" だけ。IANA の名前。64 文字まで)
startStepIdstring—始める工程("cron" だけ。このプロジェクトの工程の ID)
placementIdstring—発火で動かす配置の ID("webhook" だけ)
stepIdstring—発火で動かす工程の ID("webhook" だけ。その配置が受け持つ工程)
  • baseDigest のほかに、少なくとも 1 つの項目を送ってください。
  • type は変えられません(送ると 400 Bad Request)。種類を変えるときは、トリガーを消して作り直します。
  • 項目を消すことはできません。null・空の文字列・空白だけを送ると 400 Bad Request です。

レスポンス(200 OK)​

フィールド型説明
triggerobject変えた後のトリガー(新しい digest)。プロジェクトの取得の triggers[] と同じ項目です
definitionApprovalobject | nullテナントで定義の変更に承認が要るとき、この変更は承認待ちになり、ここに承認待ちの様子が入ります(status が "pending"。項目は定義の承認の項目)。承認されるまで、実行は前の定義で動きます。承認が要らず、すぐ反映したときは null

リクエスト例​

Update 8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40
1curl -X PATCH https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/triggers/8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40 \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "baseDigest": "Nb8SAh4xIBu2F65clLazvr8vEGwTTPar7GdAw5jDKRA",
6 "enabled": false
7}'

レスポンス例​

JSON
{
"trigger": {
"triggerId": "8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40",
"type": "cron",
"name": "毎週月曜 9 時",
"enabled": false,
"lastFiredAt": null,
"nextFireAt": null,
"createdAt": "2026-11-10T09:00:00.000Z",
"cron": "0 9 * * 1",
"timezone": "Asia/Tokyo",
"startStepId": null,
"startFailure": null,
"digest": "hpCcTMyiZEFKOV5AE5g-Hszqkdf2P2HKL7AJz_s0RsU"
},
"definitionApproval": null
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId・triggerId が UUID の形式ではない、baseDigest が無い・空・文字列ではない、type を送った、変える項目が無い、項目に null・空の文字列・空白だけを送った、そのトリガーの種類ではない項目を送った、項目の型や長さ・値の誤り(作るときと同じ)、startStepId がこのプロジェクトの工程ではない、または stepId がその配置の工程ではない
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
400cron_workflow_onlycycle のプロジェクトの "cron" のトリガーを変えようとした(消すことはできます)
403forbiddenシステム連携のトークンで呼び出した
403owner_onlyオーナーではないメンバー
403sso_required認証サーバーのアカウントと結び付いていない利用者
403feature_not_permitted無効のトリガーを有効にしようとした(enabled に true)が、管理者が定期実行の作成を許可していない。有効にしない変更は通ります
404trigger_not_foundトリガーが存在しない、ほかのプロジェクトのもの、またはメンバーではないプロジェクト
409stale_base取得した後にトリガーが変わっている。承認待ちがあるときは、既定の取得の digest では合いません。definition=pending で読み直し、その digest を baseDigest に送ってください
413body_too_largeボディが 16 KiB を超える
415unsupported_media_typeボディの Content-Type が application/json ではない
409definition_invalid承認待ちの変更に重ねると定義が成り立たない(理由の種類は error.reason)。definition=pending で読み直し、重ねた形を見て直してください
503feature_permissions_unavailable機能の許可を確かめられない。時間をおいて送り直してください
503approval_setting_unavailable定義の承認の設定を確かめられない。時間をおいて送り直してください
503definition_busy同じ定義の変更が処理中。時間をおいて送り直してください

DELETE/v1/projects/{projectId}/triggers/{triggerId}

トリガーを消します。オーナーだけが呼べます。システム連携のトークンでは呼べません。承認待ちになったとき(definitionApproval.status が "pending")は、deleted: true が返っても、承認されるまで消えません。既定の取得には残ります。

パスパラメータ​

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

レスポンス(200 OK)​

フィールド型説明
triggerIdstring消したトリガーの ID
deletedbooleanいつも true
definitionApprovalobject | nullテナントで定義の変更に承認が要るとき、この変更は承認待ちになり、ここに承認待ちの様子が入ります(status が "pending"。項目は定義の承認の項目)。承認されるまで、実行は前の定義で動きます。承認が要らず、すぐ反映したときは null

リクエスト例​

Delete 8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40
1curl -X DELETE https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/triggers/8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40 \
2-H "Authorization: Bearer <access_token>"

レスポンス例​

JSON
{
"triggerId": "8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40",
"deleted": true,
"definitionApproval": null
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId・triggerId が UUID の形式ではない
403forbiddenシステム連携のトークンで呼び出した
403owner_onlyオーナーではないメンバー
403sso_required認証サーバーのアカウントと結び付いていない利用者
404trigger_not_foundトリガーが存在しない、ほかのプロジェクトのもの、またはメンバーではないプロジェクト
409definition_invalid承認待ちの変更に重ねると定義が成り立たない(理由の種類は error.reason)。definition=pending で読み直し、重ねた形を見て直してください
503approval_setting_unavailable定義の承認の設定を確かめられない。時間をおいて送り直してください
503definition_busy同じ定義の変更が処理中。時間をおいて送り直してください

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 文字を超える部分は省略されます

リクエスト例​

Fire trigger
1curl -X POST https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/triggers/d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70/fire \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "eventId": "order-20261118-0001",
6 "payload": {
7 "orderId": "A-1024"
8 }
9}'

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

フィールド型説明
resultstring"accepted"(新しく受け付けた)または "duplicate"(同じ eventId で受付済み)
jobIdstring受付先のジョブ ID。エージェント配置と工程の組み合わせごとに決まり、同じ組み合わせへの発火では同じ値になります(発火ごとには変わりません)。実行状況の取得(GET /v1/projects/{projectId}/runs/{runId})には使えません
executionIdstring受け付けた巡回の実行の ID。実行の結果の取得・巡回の実行を止めるに使えます。同じ eventId の送り直しでも同じ値です(送り直しの応答には入らないことがあります。そのときは、発火で動いた実行の見分け方で探します)。動き出すまで(1 分ほどかかることがあります。同じエージェント配置の同じ工程に先の発火が待っていれば、その後)は、実行の結果の取得で 404 Not Found(execution_not_found)です

レスポンス例​

JSON
{
"result": "accepted",
"jobId": "9b2e4c61-0f3a-4a9b-9c1d-2f7e5a8b3c40",
"executionId": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f"
}
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 ではない
404trigger_not_foundプロジェクト・トリガーが存在しない、アクセス権が無い、Webhook ではないトリガーを指定した、または workflow 型のプロジェクトを指定した
409trigger_disabledトリガーが無効化されている
409project_not_activeプロジェクトが実行可能な状態にない
409principal_suspendedプロジェクトを実行する人の利用を、管理者が止めている。管理者に、プロジェクトの持ち主を変更するか、利用の停止を解くよう頼む
409admin_stoppedプロジェクト、または発火で動かす配置の Agent を、管理者が止めている。再開は管理者に頼む
409placement_unavailable発火対象のエージェント配置が存在しない、または実行できる状態にない
409event_conflict同じ eventId で payload が異なる
413body_too_largeリクエストボディが 16 KiB を超過
429queue_full同じエージェント配置の同じ工程で実行を待っている発火が上限(20 件)に達している

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

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

Webhook​

プロジェクトの Webhook は、プロジェクトで出来事が起きたときに、決めた https の URL へ知らせます。1 つの Webhook は 1 つの出来事(event)を送ります。1 つのプロジェクトに 20 個まで作れます。トリガーの Webhook(外から発火してプロジェクトを動かすもの)とは別のものです。

  • 5 つの API とも、オーナーだけが呼べます(一覧と配送の結果も、オーナーではないメンバーは 403 Forbidden(owner_only))。システム連携のトークンでは呼べません。
  • secret は書くだけの値で、どの応答にも返りません(応答の hasSecret で、あるかが分かります)。値を入れ替えても digest は変わりません。secret には、英数字だけの乱数を使ってください。

出来事​

event送るとき
gate_reached確認依頼が届いたとき
gate_due_soon確認依頼の期限が近づいたとき
gate_overdue確認依頼が期限を過ぎたとき
run_deadline_overdueワークフローの実行が締め切りを過ぎたとき
run_stalledワークフローの実行が止まったままのとき
run_closedワークフローの実行が終わったとき

送る中身​

POST で、次の JSON を送ります。

フィールド型説明
eventstring出来事(上の表の値)
project_idstringプロジェクト ID
run_idstring | nullワークフローの実行の ID
workitem_idstring | null確認依頼の ID
occurred_atstring出来事の日時(ISO 8601)
linkstring | null画面で開く URL
statusstringrun_closed のときだけ。ワークフローの実行の終わりの状態("closed_done"・"closed_failed"・"closed_rejected"・"cancelled")
  • ヘッダー: Content-Type: application/json、X-Agentic-Star-Event(出来事)。secret があるときは X-Agentic-Star-Signature: sha256=<署名> も付けます。署名は、受け取った本文そのもの(バイト列)の HMAC-SHA256 を secret で作り、16 進数にしたものです。受け取る側で同じ計算をして比べてください。
  • 10 秒以内に 2xx を返すと、届いたことになります。ほかの応答(リダイレクトを含みます)・時間切れ・つながらないときは、1 分・5 分・30 分の後に送り直します(最初と合わせて 4 回まで)。同じ出来事が 2 回以上届くことがあります。
  • 配送の結果は 30 日残り、配送の結果を取得で読めます。

エンドポイント一覧​

メソッドエンドポイント説明
GET/v1/projects/{projectId}/webhooksWebhook の一覧を取得
POST/v1/projects/{projectId}/webhooksWebhook を作る
PATCH/v1/projects/{projectId}/webhooks/{webhookId}Webhook を変える
DELETE/v1/projects/{projectId}/webhooks/{webhookId}Webhook を消す
GET/v1/projects/{projectId}/webhooks/{webhookId}/deliveries配送の結果を取得

GET/v1/projects/{projectId}/webhooks

プロジェクトの Webhook を全部取得します(作った順)。オーナーだけが呼べます。

パスパラメータ​

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

レスポンス(200 OK)​

フィールド型説明
webhooksarrayWebhook の配列
webhooks[].webhookIdstringWebhook の ID
webhooks[].eventstring | null送る出来事
webhooks[].urlstring | null送り先の URL
webhooks[].enabledboolean | null有効かどうか
webhooks[].hasSecretbooleansecret があるかどうか(secret の値は返しません)
webhooks[].createdAtstring | null作成日時(ISO 8601)
webhooks[].lastDeliveryobject | null直近の配送の結果(status・httpStatus・at)。送り直しを待っている配送は入りません。まだ無ければ null
webhooks[].digeststringWebhook を変えるときに baseDigest に送る値
eventsstring[]送れる出来事の値
hasMorebooleanいつも false(全件を返します)

リクエスト例​

Get webhooks
1curl https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks \
2-H "Authorization: Bearer <access_token>"

レスポンス例​

JSON
{
"webhooks": [
{
"webhookId": "c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a",
"event": "run_closed",
"url": "https://example.com/hooks/agentic-star",
"enabled": true,
"hasSecret": true,
"createdAt": "2026-11-10T09:00:00.000Z",
"lastDelivery": { "status": "delivered", "httpStatus": 200, "at": "2026-11-10T10:15:02.000Z" },
"digest": "ZzMbbf4GuA4lERz6RWQYwm5-MIwi5DlFRdIX6Plzxb8"
}
],
"events": ["gate_reached", "gate_due_soon", "gate_overdue", "run_deadline_overdue", "run_stalled", "run_closed"],
"hasMore": false
}

エラーレスポンス​

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

POST/v1/projects/{projectId}/webhooks

Webhook を作ります。オーナーだけが呼べます。

パスパラメータ​

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

リクエストボディ​

フィールド型必須説明
eventstring必須送る出来事(上の「出来事」の値)
urlstring必須送り先の URL(2048 文字まで)。https だけで、ユーザー名・パスワードは入れられません。ホスト名は、外から届く公開のアドレスに引ける名前にします
secretstring | null—署名に使う値(256 文字まで)。省くか、null・空の文字列で署名なし
enabledboolean—有効かどうか。省くと true

レスポンス(201 Created)​

フィールド型説明
webhookobject作った Webhook。一覧の webhooks[] と同じ項目です(lastDelivery は null)

リクエスト例​

Create webhooks
1curl -X POST https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "event": "run_closed",
6 "url": "https://example.com/hooks/agentic-star",
7 "secret": "<secret>"
8}'

レスポンス例​

JSON
{
"webhook": {
"webhookId": "c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a",
"event": "run_closed",
"url": "https://example.com/hooks/agentic-star",
"enabled": true,
"hasSecret": true,
"createdAt": "2026-11-10T09:00:00.000Z",
"lastDelivery": null,
"digest": "ZzMbbf4GuA4lERz6RWQYwm5-MIwi5DlFRdIX6Plzxb8"
}
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId が UUID の形式ではない、event・url が無い・null、event が上の値ではない、url が文字列ではない・空白だけ・2048 文字を超える、secret が文字列ではない・256 文字を超える、または enabled が真偽値ではない
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
400invalid_url_formaturl が URL として読めない
400https_requiredurl が https ではない、またはユーザー名・パスワードが入っている
400blocked_hosturl のホストが、Webhook を受けられない宛先(ローカル・プライベート・内部のアドレス)
400unresolvable_hosturl のホスト名を引けない
400too_many_webhooksプロジェクトに Webhook がすでに 20 個ある
403forbiddenシステム連携のトークンで呼び出した
403owner_onlyオーナーではないメンバー
403sso_required認証サーバーのアカウントと結び付いていない利用者
404project_not_foundプロジェクトが存在しない、またはメンバーではない
413body_too_largeボディが 16 KiB を超える
415unsupported_media_typeボディの Content-Type が application/json ではない

PATCH/v1/projects/{projectId}/webhooks/{webhookId}

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

パスパラメータ​

パラメータ型必須説明
projectIdstring必須プロジェクト ID(UUID)
webhookIdstring必須Webhook の ID(UUID。一覧の webhooks[].webhookId)

リクエストボディ​

フィールド型必須説明
baseDigeststring必須その Webhook の digest(一覧の webhooks[].digest)
eventstring—送る出来事
urlstring—送り先の URL(作るときと同じ決まり)
secretstring | null—署名に使う値(256 文字まで)。送った値に置き換えます。null・空の文字列で消します
enabledboolean—有効かどうか
  • baseDigest のほかに、少なくとも 1 つの項目を送ってください。
  • event・url・enabled は消せません(null・空の文字列・空白だけを送ると 400 Bad Request)。

レスポンス(200 OK)​

フィールド型説明
webhookobject変えた後の Webhook(新しい digest)。一覧の webhooks[] と同じ項目です

リクエスト例​

Update c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a
1curl -X PATCH https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks/c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "baseDigest": "ZzMbbf4GuA4lERz6RWQYwm5-MIwi5DlFRdIX6Plzxb8",
6 "enabled": false
7}'

レスポンス例​

JSON
{
"webhook": {
"webhookId": "c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a",
"event": "run_closed",
"url": "https://example.com/hooks/agentic-star",
"enabled": false,
"hasSecret": true,
"createdAt": "2026-11-10T09:00:00.000Z",
"lastDelivery": { "status": "delivered", "httpStatus": 200, "at": "2026-11-10T10:15:02.000Z" },
"digest": "p6lFz_URDGJlbWylUwuz5Y41RzkRw7p7AFwUZOr6hpk"
}
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId・webhookId が UUID の形式ではない、baseDigest が無い・空・文字列ではない、変える項目が無い、event・url・enabled に null・空の文字列・空白だけを送った、または項目の型や長さ・値の誤り(作るときと同じ)
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
400invalid_url_formaturl が URL として読めない
400https_requiredurl が https ではない、またはユーザー名・パスワードが入っている
400blocked_hosturl のホストが、Webhook を受けられない宛先(ローカル・プライベート・内部のアドレス)
400unresolvable_hosturl のホスト名を引けない
403forbiddenシステム連携のトークンで呼び出した
403owner_onlyオーナーではないメンバー
403sso_required認証サーバーのアカウントと結び付いていない利用者
404webhook_not_foundWebhook が存在しない、ほかのプロジェクトのもの、またはメンバーではないプロジェクト
409stale_base取得した後に Webhook が変わっている
413body_too_largeボディが 16 KiB を超える
415unsupported_media_typeボディの Content-Type が application/json ではない

DELETE/v1/projects/{projectId}/webhooks/{webhookId}

Webhook を消します。オーナーだけが呼べます。

パスパラメータ​

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

レスポンス(200 OK)​

フィールド型説明
webhookIdstring消した Webhook の ID
deletedbooleanいつも true

リクエスト例​

Delete c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a
1curl -X DELETE https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks/c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a \
2-H "Authorization: Bearer <access_token>"

レスポンス例​

JSON
{
"webhookId": "c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a",
"deleted": true
}

エラーレスポンス​

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

GET/v1/projects/{projectId}/webhooks/{webhookId}/deliveries

Webhook の配送の結果を、新しい順に取得します(直近 30 日)。送った本文は返しません。オーナーだけが呼べます。

パスパラメータ​

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

クエリパラメータ​

パラメータ型デフォルト説明
limitinteger50取得件数(1-100)。cursor はありません

レスポンス(200 OK)​

フィールド型説明
deliveriesarray配送の結果の配列(新しい順)
deliveries[].deliveryIdstring | null配送の ID
deliveries[].eventstring | null出来事
deliveries[].attemptnumber | null何回目の送信か
deliveries[].statusstring | null"delivered"(届いた)・"pending"(送る前、または送り直しを待っている)・"failed"(届かなかった)
deliveries[].httpStatusnumber | null送り先が返した HTTP ステータス
deliveries[].atstring | null結果の日時(ISO 8601)
deliveries[].nextAttemptAtstring | null次に送り直す予定の日時(ISO 8601)
deliveries[].lastErrorstring | null届かなかった理由(例: "http_500"・"timeout")
hasMorebooleanlimit より古い結果があるかどうか(limit が 100 のときは、100 件そろえば true)

リクエスト例​

Get deliveries
1curl "https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks/c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a/deliveries?limit=20" \
2-H "Authorization: Bearer <access_token>"

レスポンス例​

JSON
{
"deliveries": [
{
"deliveryId": "1042",
"event": "run_closed",
"attempt": 1,
"status": "delivered",
"httpStatus": 200,
"at": "2026-11-10T10:15:02.000Z",
"nextAttemptAt": null,
"lastError": null
},
{
"deliveryId": "1031",
"event": "run_closed",
"attempt": 4,
"status": "failed",
"httpStatus": 503,
"at": "2026-11-09T18:42:10.000Z",
"nextAttemptAt": null,
"lastError": "http_503"
}
],
"hasMore": false
}

エラーレスポンス​

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

ワークフローの実行(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ワークフローの実行の確認担当者を付け替える
POST/v1/projects/{projectId}/runs/{runId}/cancelワークフローの実行を中断
POST/v1/projects/{projectId}/artifacts入力ファイルを上げる(下書き)
GET/v1/projects/{projectId}/artifactsワークフローの実行の成果物の一覧を取得
GET/v1/projects/{projectId}/artifacts/{artifactId}/content成果物の中身を取得
GET/v1/projects/{projectId}/runs/{runId}/case-configワークフローの実行の今の案件設定を取得
PUT/v1/projects/{projectId}/runs/{runId}/case-config確認待ちのワークフローの実行の案件設定を置き換える

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 文字まで
configobject—入力ファイルと工程の設定。{ "placements": [{ "placementId", "stepId", "parameters", "connectionBindings", "fileBindings" }] } の形で、配置と工程の組ごとに書きます。fileBindings は入力ファイルの名前(置ける登録 Agent の一覧の inputs[].name)から、上げた下書きの artifactId への対応、parameters は登録 Agent の parameters(parametersSchema の形)、connectionBindings は接続の枠の名前から連携先の ID への対応です。placementId・stepId のほかは省けます。省略・null は設定なし

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

config もボディ全体の 16 KiB に含まれます。

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

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

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

リクエスト例​

Start run
1curl -X POST https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs \
2-H "Authorization: Bearer <access_token>" \
3-H "Idempotency-Key: nightly-batch-20260917" \
4-H "Content-Type: application/json" \
5-d '{
6 "payload": {
7 "ticketId": "INC-1024",
8 "summary": "ログインできない利用者がいる"
9 }
10}'

レスポンス例​

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

同じキーで、違う payload か config を付けて再送すると 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 ではない
404project_not_foundプロジェクトが存在しない、またはアクセス権が無い
400approvers_required有効な確認工程に確認担当者が設定されていない
409unsupported_project_typecycle 型のプロジェクトを指定した
409project_inactiveプロジェクトが有効な状態ではない(一時停止中、またはアーカイブ済み)
409principal_suspendedプロジェクトを実行する人の利用を、管理者が止めている。管理者に、プロジェクトの持ち主を変更するか、利用の停止を解くよう頼む
409start_step_in_branch_lane開始の工程が条件分岐のレーンの中にある。時間トリガーの開始する工程を、条件分岐のレーンの外の工程にしてください
409definition_pendingプロジェクトの最初の定義が承認待ちの間は始められない。承認する人(ほかのオーナーか組織の管理者)が製品の画面で承認してから始めてください
409relink_required取り込みで見つからなかった参照をつなぎ直すまで、プロジェクトを始められない・再開できない。プロジェクトの取得の relink と配置の relink に、残っている参照が出ます。起動を断る参照の外し方: kind が "agent" の行は Agent を置き直す(POST /v1/projects/{projectId}/placements)、kind が "connector" の行は製品の画面で連携先を保存し直す。blocking が false の行は実行を断らない、必要に応じて再度設定する項目で、DELETE /v1/projects/{projectId}/relink で消せますが、それだけでは始められません
409admin_stoppedプロジェクト、またはプロジェクトに置いた登録 Agentを、管理者が止めている。再開は管理者に頼む(この API では再開できない)
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_configconfig の形が違う、知らない配置・工程を指している、設定が登録 Agent の定義に合わない、またはプロジェクトの工程に登録 Agent が置かれていない
409artifact_not_ready入力に指定した成果物が、まだ使える状態ではない(または確認した内容と違う)
409origin_conflict同じ Idempotency-Key で、違う payload か config を送った(同じ起点が、違う中身で使われている)
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)

リクエスト例​

Get run
1curl https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13 \
2-H "Authorization: Bearer <access_token>"

レスポンスフィールド(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。プロジェクトに参加していない、組織の運用の役割の人には null
runtimeKindstring | null実行環境の種類。"marketplace"(登録した Agent で動く実行)または "autonomous"。古い実行では null の場合があります
cancelRequestedAtstring | null中断が求められた日時(ISO 8601)。求められていなければ null
deadlineAtstring | nullワークフローの実行の締め切り(ISO 8601)。締め切りが無ければ null
configRevisionnumber | null案件設定のバージョン。登録した Agent で動く実行で使い、それ以外の実行では null。案件設定を直すときは、この値ではなく、案件設定の取得で読む revision を使います(読んだ後に入った変更を上書きしないため)
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工程の出力の要約。プロジェクトに参加していない、組織の運用の役割の人には null(中断で閉じた工程の "cancelled" は残ります)
steps[].outcomestring | nullAgent の実行の結果。"completed" / "incomplete" / "failed" / "timeout" / "stopped" / "denied" / "skipped" のいずれか。結果の無い行では null
steps[].reasonCodestring | null結果の理由コード。条件分岐で決められず人に選択してもらうときは "branch_undecided"、条件分岐で選ばれなかったレーンの工程は "branch_not_selected"
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": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"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)

リクエスト例​

List runs
1curl "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs?limit=20" \
2-H "Authorization: Bearer <access_token>"

レスポンスフィールド(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})で読みます。実行履歴には、始まっていない工程と確認待ちの工程は出ないため、どの工程も始まっていない古いワークフローの実行は見つけられません。

レスポンス例​

JSON
{
"runs": [
{
"runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"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": []
}
],
"hasMore": false
}

エラーレスポンス​

ステータス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 だけは、今の連携先の情報から求めます)。

リクエスト例​

Get run config
1curl https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/config \
2-H "Authorization: Bearer <access_token>"

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

フィールド型説明
runIdstringワークフローの実行の ID
takenAtstring | null設定を写した日時(ISO 8601)
stepsarray | null当時の工程。項目は「工程の項目」と同じです(digest を除きます。写しに無い項目は null。条件分岐の工程は branchConfig を含みます)
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 です。

レスポンス例​

JSON
{
"runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"takenAt": "2026-09-17T01:30:00.000Z",
"steps": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"position": 1,
"name": "金額の確認",
"description": "請求書の金額と明細を照合します",
"enabled": true,
"defaultZone": "ai",
"branchConfig": null,
"reworkToStepId": null,
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null
},
{
"stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"position": 2,
"name": "差異の確認",
"description": null,
"enabled": true,
"defaultZone": "gate",
"branchConfig": null,
"reworkToStepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null
},
{
"stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"position": 3,
"name": "差異の報告",
"description": null,
"enabled": true,
"defaultZone": "ai",
"branchConfig": null,
"reworkToStepId": null,
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null
}
],
"lanes": [
{
"id": "main",
"name": null,
"parentLaneId": null,
"stepIds": [
"5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d"
]
}
],
"forks": [],
"joins": [],
"placements": [
{
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"agentId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
"name": "請求書チェック",
"goal": null,
"guardrail": null,
"skills": [],
"playbookId": null,
"playbookName": null,
"runtimeConfigs": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"runtimeConfig": null
}
],
"libraryBindings": [],
"sweeps": [],
"stepIds": [
"5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"
]
}
],
"connectors": [],
"sendBackLimit": 3
}

エラーレスポンス​

ステータス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 で締め切りを外します

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

リクエスト例​

Set run deadline
1curl -X PATCH https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13 \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "deadlineAt": "2026-11-20T09:00:00.000Z"
6}'

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

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

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

レスポンス例​

JSON
{
"runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"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": "2026-11-20T09:00:00.000Z",
"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 の形式ではない、または deadlineAt が無い・ISO 8601 の日時ではない・今より後ではない
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
403forbiddenシステム連携のトークンで呼び出した
403operator_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 が空になることがあります。結果は、ワークフローの実行の取得と確認依頼の取得で確かめてください。

リクエスト例​

Reassign run approvers
1curl -X PUT https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/approvers \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "approverUserIds": [
6 "f47ac10b-58cc-4372-a567-0e02b2c3d479"
7 ],
8 "commandId": "reassign-20261118-0001"
9}'

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

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

レスポンス例​

JSON
{
"runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"approverUserIds": [
"f47ac10b-58cc-4372-a567-0e02b2c3d479"
],
"workItemIds": [
"c9d8e7f6-a5b4-4321-8fed-cba098765432"
]
}

エラーレスポンス​

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

POST/v1/projects/{projectId}/runs/{runId}/cancel

実行中か確認待ちのワークフローの実行(status が "running"・"waiting_gate")を中断します。画面の「中断する」と同じです。オーナーと運用担当(組織の運用の役割の人を含む)と、そのワークフローの実行を始めた本人が呼べます。システム連携のトークンでも呼べます。

中断すると、次のようになります。

  • ワークフローの実行の status が "cancelled"(中断)になります。元に戻せません。
  • まだ起動していない工程は起動されません。動いている工程の Agent には停止を伝えます(その工程の行の status は、止まるまで変わらないことがあります)。
  • 確認工程の、まだ判断されていない確認依頼は取り下げられます。

パスパラメータ​

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

リクエストボディ​

フィールド型必須説明
commandIdstring必須送り直しを見分ける値(英数字と _ . : - の 8〜128 文字)
reasonstring—中断の理由(500 文字まで)
  • 動いていないワークフローの実行(終わった後・中断した後)に送ると、何も変えずに 200 OK が返り、existing が true です。中断した後に送り直したときも同じです。
  • ほかの中断や、ワークフローの実行が終わるのと同じころに送ると、202 Accepted と 200 OK の別と existing が、実際と合わないことがあります。結果は、ワークフローの実行の取得(GET /v1/projects/{projectId}/runs/{runId})の status で確かめてください。
  • 504 Gateway Timeout は「中断されなかった」ことを意味しません。同じ commandId で送り直すか、ワークフローの実行の取得で status を確かめてください。

リクエスト例​

Cancel run
1curl -X POST https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/cancel \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "commandId": "cancel-20261118-0001",
6 "reason": "入力データの誤りに気づいたため"
7}'

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

この要求で新しく中断したときは 202 Accepted、新しく中断しなかったときは 200 OK です。

フィールド型説明
runIdstringワークフローの実行の ID
statusstring送った後のワークフローの実行の状態(中断したときは "cancelled")
cancelRequestedAtstring | null中断を受けた日時(ISO 8601)。中断されていないワークフローの実行では null
existingbooleanこの要求で新しく中断しなかったとき true(202 Accepted のときはいつも false)

レスポンス例​

JSON
{
"runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"status": "cancelled",
"cancelRequestedAt": "2026-11-18T05:12:30.000Z",
"existing": false
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId・runId が UUID の形式ではない、commandId が無い・形の誤り、または reason が文字列ではない・500 文字を超える
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
403operator_only自分が始めていないワークフローの実行を、オーナーでも運用担当でもなく、組織の運用の役割も持たないメンバーが中断しようとした
403sso_required認証サーバーのアカウントと結び付いていない利用者
404run_not_foundワークフローの実行が存在しない、ほかのプロジェクトのもの、またはメンバーではないプロジェクト
413body_too_largeボディが 16 KiB を超える
415unsupported_media_typeボディの Content-Type が application/json ではない

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

登録 Agent で動くワークフローの実行の、今の案件設定(配置と工程の組ごとの入力ファイル・パラメーター・連携先)を取得します。プロジェクトのメンバーと、組織の運用の役割の人なら呼べます。実行の状態は問いません。案件設定を直す前に、この API で今の設定と revision を読みます。

パスパラメータ​

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

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

フィールド型説明
revisionnumber | null案件設定のバージョン。案件設定を直すときに expectedRevision として送ります。登録 Agent で動かない実行では null
placementsarray配置と工程の組ごとの設定。項目は、ワークフローの実行の開始の config.placements と同じです(placementId・stepId・parameters・connectionBindings・fileBindings)。設定を書いていない組も返り、そのときは placementId・stepId だけです

リクエスト例​

Get case-config
1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/case-config \
2-H "Authorization: Bearer <access_token>"

レスポンス例​

JSON
{
"revision": 2,
"placements": [
{
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"parameters": { "language": "ja" },
"fileBindings": { "contract": "9b2f0c1e-3a4d-4e5f-8a6b-7c8d9e0f1a2b" }
},
{
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"stepId": "c2f1a8e4-6b3d-4e7a-9c15-8d2e4f6a7b90"
}
]
}

エラーレスポンス​

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

PUT/v1/projects/{projectId}/runs/{runId}/case-config

登録 Agent で動くワークフローの実行が確認待ち(status が "waiting_gate")の間に、案件設定をまるごと置き換えます。オーナーだけが呼べます。

  • 送った config.placements で、設定を全部置き換えます。送らなかった配置と工程の組の設定は消えます。案件設定を取得し、直したい所だけを変えて、全部を送ってください。空の配列を送ると、設定を全部消します。
  • expectedRevision には、案件設定の取得で読んだ revision を送ります。ワークフローの実行の取得の configRevision を使うと、読んだ後に入った変更を古い設定で上書きすることがあります。
  • 直した設定は、確認依頼を決めた後に起こす工程から使われます。直すと、確認待ちの確認依頼の contextVersion と決定の根拠が変わるので、決める前に確認依頼を読み直してください(応答の gate に新しい値が入ります)。

パスパラメータ​

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

リクエストボディ​

フィールド型必須説明
expectedRevisionnumber必須案件設定の取得で読んだ revision(1 以上の整数)。今の版と違うと 409 Conflict(revision_conflict)
commandIdstring必須送り直しを見分ける値(英数字と _ . : - の 8〜128 文字)
configobject必須{ "placements": [...] } の形の新しい案件設定。placements は必須の配列です。配置と工程の組の項目は、ワークフローの実行の開始の config と同じです
  • 上限: config を JSON にした長さは 262,144 文字までです(超えると 400 Bad Request(invalid_config))。ボディ全体が 787,456 バイトを超えると 413 Payload Too Large(body_too_large)です。
  • 同じ commandId で同じ内容を送り直すと、1 回目の結果が返ります(existing が true)。同じ commandId で違う内容を送ると 409 Conflict(command_conflict)です。

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

フィールド型説明
revisionnumber置き換えた後の案件設定のバージョン
placementsarray置き換えた後の設定。項目は案件設定の取得と同じです
gateobject | null確認待ちの確認依頼(workItemId・contextVersion・basisDigest)。決めるときは、この contextVersion・basisDigest か、確認依頼を取得し直した値を使います。無ければ null
existingboolean同じ commandId の送り直しで、1 回目の結果を返したときは true

リクエスト例​

Replace case-config
1curl -X PUT https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/case-config \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "expectedRevision": 2,
6 "commandId": "fix-contract-20261110-01",
7 "config": {
8 "placements": [
9 {
10 "placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
11 "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
12 "parameters": {
13 "language": "ja"
14 },
15 "fileBindings": {
16 "contract": "8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6"
17 }
18 }
19 ]
20 }
21}'

レスポンス例​

JSON
{
"revision": 3,
"placements": [
{
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"parameters": { "language": "ja" },
"fileBindings": { "contract": "8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6" }
}
],
"gate": {
"workItemId": "c9d8e7f6-a5b4-4321-8fed-cba098765432",
"contextVersion": 4,
"basisDigest": "5e0f6c9a3b2d1e4f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f"
},
"existing": false
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId・runId が UUID の形式ではない、expectedRevision が 1 以上の整数ではない、または commandId が無い・形の誤り
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
400invalid_configconfig が無い・placements が配列ではない、知らない配置・工程を指している、設定が登録 Agent の定義に合わない、または config が 262,144 文字を超える
400not_marketplace_run登録 Agent で動くワークフローの実行ではない
400connection_not_allowedプロジェクトの連携先ではない連携先を指定した
400artifact_format_mismatch入力に指定した成果物の形式が、求める形式と違う
400artifact_digest_missing入力に指定した成果物に digest が無い
400artifact_not_ready入力に指定した成果物が無い、ほかのワークフローの実行のもの、またはまだ使える状態ではない
403forbiddenシステム連携のトークンで呼び出した
403owner_onlyオーナーではないメンバー
403sso_required認証サーバーのアカウントと結び付いていない利用者
404run_not_foundワークフローの実行が存在しない、ほかのプロジェクトのもの、cycle のプロジェクト、またはメンバーではないプロジェクト
409run_runningワークフローの実行が確認待ちではない(ワークフローの実行を取得し直して状態を確かめる)
409run_closedワークフローの実行が終わっている
409revision_conflict読んだ後に案件設定が変わっている。案件設定を取得し直し、その revision を expectedRevision にして送る
409command_conflict同じ commandId で違う内容を送った
409connection_version_unavailable接続のバージョンを確かめられない。プロジェクトの連携先を確かめて送り直す
413body_too_largeボディが 787,456 バイトを超える
415unsupported_media_typeボディの Content-Type が application/json ではない

POST/v1/projects/{projectId}/artifacts

ワークフローの実行に渡す入力ファイルを、下書きとして上げます。プロジェクトの参加者(オーナー・運用担当・メンバー)と、組織の運用の役割の人が呼べます。上げた下書きは、ワークフローの実行の開始(POST /v1/projects/{projectId}/runs)の config の fileBindings に artifactId を指定すると、その実行の成果物になり、成果物の一覧と中身の取得で読めるようになります。実行に結び付くまでは、外部 API から中身を読めません(成果物の中身の取得は 404 Not Found)。システム連携のトークンでワークフローの実行を始めるときに指定できるのは、プロジェクトの今のオーナーが上げ、まだ実行に結び付いていない、書き終わった下書きだけです。

リクエストヘッダー​

ヘッダー必須説明
Idempotency-Key任意送り直しの防止キー。8〜128 文字で、使用できる文字は半角英数字と _ . : - です。同じキーで同じ名前・形式・中身を送り直すと、同じ下書きが返ります(200 OK)

パスパラメータ​

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

リクエストボディ(multipart/form-data)​

パラメータ型必須説明
filesfile必須上げるファイル。1 つだけ
namestring必須入力ファイルの名前(1〜128 文字)。置ける登録 Agent の一覧の inputs[].name
formatstring必須形式。"markdown"・"yaml"・"json"・"text"・"binary" のどれか。置ける登録 Agent の一覧の inputs[].format

大きさは、"binary" は 20 MiB まで、ほかの形式は 1 MiB までです。超えると 413 Payload Too Large(file_too_large)が返ります。"yaml"・"json" は、読めるかどうかと、プロジェクトに置いた登録 Agent の定義(inputs[].schema)に合うかを確かめます。

リクエスト例​

Upload draft artifact
1curl -X POST https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/artifacts \
2-H "Authorization: Bearer <access_token>" \
3-F "files=@invoice.json" \
4-F "name=invoice" \
5-F "format=json"

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

成果物の一覧の 1 件と同じ形です。

フィールド型説明
artifactIdstring下書きの ID(UUID)。開始の config の fileBindings に指定します
runIdstring | null下書きでは null
namestring | null成果物の名前
mimeTypestring | null成果物の MIME タイプ
sizenumber | null大きさ(バイト)
statusstring | null"ready"
createdAtstring | null作られた日時(ISO 8601)

新しく上げたときは 201 Created、同じ Idempotency-Key で同じ下書きを送り直したときは 200 OK が返ります。

レスポンス例​

JSON
{
"artifactId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"runId": null,
"name": "invoice",
"mimeType": "application/json",
"size": 512,
"status": "ready",
"createdAt": "2026-11-18T05:20:00.000Z"
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId が UUID の形式ではない、ファイルが無い・2 つ以上ある、name が無い・129 文字以上、または format が決まった値ではない(param にその名前)
400idempotency_key_invalidIdempotency-Key の長さまたは文字種が不正(キーは任意だが、送るなら形が合っていること)
400invalid_yamlformat が "yaml" で、中身を YAML として読めない
400invalid_jsonformat が "json" で、中身を JSON として読めない
400schema_violation中身が、置いた登録 Agent の入力の定義(inputs[].schema)に合わない
403forbiddenシステム連携のトークンで呼び出した
403sso_required認証サーバーのアカウントと結び付いていない利用者
403feature_not_permitted管理者がファイルの添付を許可していない
404project_not_foundプロジェクトが存在しない、またはメンバーではない
409artifact_conflict同じ Idempotency-Key で、違う名前・形式・中身を送った、またはその下書きがもう実行に結び付いている
413file_too_largeファイルが上限("binary" は 20 MiB、ほかは 1 MiB)を超える
415unsupported_media_typeリクエストが multipart/form-data ではない
503feature_permissions_unavailable機能の許可を確かめられない(時間をおいて送り直す)

GET/v1/projects/{projectId}/artifacts

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

パスパラメータ​

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

クエリパラメータ​

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

リクエスト例​

List run artifacts
1curl "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/artifacts?run_id=7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13" \
2-H "Authorization: Bearer <access_token>"

レスポンスフィールド(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)
hasMorebooleanいつも false(全件を返します)

レスポンス例​

JSON
{
"artifacts": [
{
"artifactId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"name": "report.md",
"mimeType": "text/markdown",
"size": 2048,
"status": "ready",
"createdAt": "2026-11-18T05:30:00.000Z"
}
],
"hasMore": false
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId が UUID の形式ではない、または run_id が無い・UUID の形式ではない
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

リクエスト例​

Get run artifact content
1curl https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/artifacts/1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d/content \
2-H "Authorization: Bearer <access_token>"

レスポンス(200 OK)​

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

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

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId・artifactId が UUID の形式ではない
403sso_required認証サーバーのアカウントと結び付いていない利用者
404project_not_foundプロジェクトが存在しない、またはメンバーではない
404artifact_not_found成果物が存在しない、ほかのプロジェクトのもの、またはワークフローの実行の成果物ではない
409forbidden_roleプロジェクトに参加していない組織の運用の役割の人が呼んだ
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実行の時系列を取得
POST/v1/projects/{projectId}/executions/{executionId}/cancelサイクルの巡回の実行を止める

結果の値​

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 値)

リクエスト例​

List executions
1curl "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions?outcome=success&limit=20" \
2-H "Authorization: Bearer <access_token>"

レスポンスフィールド(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(実行の結果で読みます)。プロジェクトに参加していない、組織の運用の役割の人には 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 の場合のみ含まれます

レスポンス例​

JSON
{
"executions": [
{
"executionId": "rs:1842",
"kind": "run_step",
"runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"stepName": "金額の確認",
"stepPosition": 1,
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"agentName": "経理 Agent",
"attempt": 1,
"lane": "main",
"outcome": "completed",
"reasonCode": null,
"resultState": "terminal",
"terminal": true,
"startedAt": "2026-11-18T01:30:05.000Z",
"endedAt": "2026-11-18T01:34:40.000Z",
"summary": "請求書 12 件を照合し、差異のあった 1 件を確認依頼にしました。",
"errorMessage": null,
"originType": "manual",
"actorLabel": null,
"gateDecision": null,
"conversationId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
"fixTarget": null,
"platformFailure": null,
"rerunOf": null
}
],
"hasMore": false
}

エラーレスポンス​

ステータス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:<数値> です。

システム連携のトークンで呼ぶと、状態の項目(executionId・kind・runId・stepId・placementId・attempt・outcome・reasonCode・resultState・terminal・startedAt・endedAt)だけを返します(システム連携 API リファレンス)。

パスパラメータ​

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

リクエスト例​

Get execution
1curl https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/rs:1842 \
2-H "Authorization: Bearer <access_token>"

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

実行履歴の 1 件の項目に加えて、次の項目を返します。summary は、workflow は 2000 文字まで、cycle は会話の最後の本文をそのまま返します。プロジェクトに参加していない、組織の運用の役割の人には、summary・edited・envelope.completionReport.comment は null、artifacts・files・inputs と、library の inputs・writes は空の配列で返ります。

フィールド型説明
connectionConfirmOfstring | nullいつも null
editedobject | 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 回ずつは、ツールの呼び出しの一覧で読みます。

レスポンス例​

JSON
{
"executionId": "rs:1842",
"kind": "run_step",
"runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"stepName": "金額の確認",
"stepPosition": 1,
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"agentName": "経理 Agent",
"attempt": 1,
"lane": "main",
"outcome": "completed",
"reasonCode": null,
"resultState": "terminal",
"terminal": true,
"startedAt": "2026-11-18T01:30:05.000Z",
"endedAt": "2026-11-18T01:34:40.000Z",
"summary": "請求書 12 件を照合し、差異のあった 1 件を確認依頼にしました。",
"errorMessage": null,
"originType": "manual",
"actorLabel": null,
"gateDecision": null,
"conversationId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
"fixTarget": null,
"platformFailure": null,
"rerunOf": null,
"connectionConfirmOf": null,
"edited": null,
"envelope": {
"counts": {
"toolCalls": 14,
"readCalls": 9,
"mutatingSuccess": 3,
"mutatingFailed": 0,
"unknownCalls": 0,
"opaqueCalls": 0,
"workspaceWrites": 3,
"mcpCalls": 0,
"mcpFailed": 0
},
"completionReport": {
"completed": true,
"reasonCode": null,
"fixTarget": null,
"comment": "12 件中 11 件が一致。1 件は金額の差異のため確認依頼にしました。",
"truncated": false
},
"platformFailure": null,
"tools": [
"read_file",
"write_file"
]
},
"usedSettings": {
"manifest": null,
"mcp": null
},
"questions": [],
"gates": [],
"artifacts": [],
"files": [],
"configuration": {
"policyVersion": null,
"policyDigest": null,
"policyProfile": null,
"model": null,
"mcpConfigVersion": null
},
"request": {
"originType": "manual",
"originRef": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"triggerId": null,
"scheduledAt": null,
"runStartedAt": "2026-11-18T01:30:00.000Z",
"reworkReason": null
},
"jobId": null,
"gateFor": null,
"routedFrom": null,
"late": null,
"inputs": [
{
"filename": "invoice.json",
"handoff": false
}
],
"library": {
"inputs": [],
"writes": []
}
}

エラーレスポンス​

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

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

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

クエリパラメータ​

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

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

リクエスト例​

List execution operations
1curl https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/rs:1842/operations \
2-H "Authorization: Bearer <access_token>"

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

フィールド型説明
operationsarray呼び出しの配列
operations[].operationIdstring | null呼び出しの ID
operations[].kindstring | null行の種類。"tool"(ツールの呼び出し)/ "a2a"(A2A のエージェントの呼び出し)/ "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呼び出しの結果。"ok"(成功)/ "error"(ツールのエラー)/ "failed"(失敗)。結果がまだ記録されていないときは 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 つにまとめて読んでください。

レスポンス例​

JSON
{
"operations": [
{
"operationId": "call:toolu_01ABC",
"kind": "access",
"resource": "read_file",
"action": "read",
"path": "/workspace/invoice.json",
"mcpServer": null,
"connectionId": null,
"connectionKind": null,
"attempted": true,
"effect": null,
"denied": null,
"durationMs": 12,
"reason": "granted"
}
],
"hasMore": false
}

エラーレスポンス​

ステータス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 値)

リクエスト例​

Get execution timeline
1curl "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/rs:1842/timeline?limit=50" \
2-H "Authorization: Bearer <access_token>"

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

フィールド型説明
rootExecutionIdstring実行の ID
originstring | null実行の始まり。"job"(ジョブ)/ "chat"(チャット)
ownerobject実行の持ち主
owner.userIdstring | null持ち主の利用者 ID。分からないときは null
executionsobject実行の要約(items)。結果・設定・ツールの呼び出しの数など
timelineobject記録の行(items)
timeline.items[].atstring記録の日時
timeline.items[].keynumber記録の ID。"tool.access" の行は、ツールの呼び出しの一覧の operationId と対応します(呼び出しの ID がある行は call:<呼び出しの ID>、無い行は 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消された会話・リソース
deleted.conversationsstring[]消された会話の ID
deleted.resourcesstring[]消されたリソース(ファイルなど)。このページの timeline.items[].resource に出るものだけ
hasMoreboolean続きがあるかどうか
cursorstring次ページ取得用カーソル。hasMore が true の場合のみ含まれます
snapshotAtstring | null記録を読んだ日時

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

レスポンス例​

JSON
{
"rootExecutionId": "a4c6e8f0-1b3d-4a5c-9e7f-2d4b6a8c0e1f",
"origin": "job",
"owner": {
"userId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
},
"executions": {
"items": [
{
"executionId": "a4c6e8f0-1b3d-4a5c-9e7f-2d4b6a8c0e1f",
"origin": "job",
"rootExecutionId": "a4c6e8f0-1b3d-4a5c-9e7f-2d4b6a8c0e1f",
"job": {
"id": "e3a5c7d9-1b2f-4c6e-8a0b-3d5f7a9c1e2b",
"mode": "once",
"scheduleType": "once",
"deletedAt": null,
"projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
"projectStepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"projectAgentId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"projectRunId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13"
},
"ownerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"conversationId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
"messageId": "b2c4d6e8-0a1b-4c3d-9e5f-7a9b1c3d5e7f",
"stepIndex": 0,
"status": "completed",
"startedAt": "2026-11-18T01:30:05.000Z",
"completedAt": "2026-11-18T01:34:40.000Z",
"terminal": {
"state": "terminal",
"outcome": "completed",
"outcomeReasonCode": null,
"hadMutatingSuccess": true,
"terminalAt": "2026-11-18T01:34:40.000Z",
"degradedFrom": null,
"envelopeVersion": 1,
"envelopeAppliedAt": "2026-11-18T01:34:41.000Z"
},
"logical": {
"outcome": "completed",
"hadMutatingSuccess": true,
"terminalAt": "2026-11-18T01:34:40.000Z"
},
"configuration": {
"policyVersion": null,
"policyDigest": null,
"policyProfile": null,
"model": null,
"mcpConfigVersion": null
},
"runtime": {
"podAdoptedAt": null,
"suspendedAt": null,
"interruptedReason": null
},
"alertDelivery": {
"status": null,
"errorPresent": false,
"at": null
},
"envelope": {
"envelopeVersion": 1,
"outcome": "completed",
"hadMutatingSuccess": true,
"counts": {
"toolCalls": 14,
"mutatingSuccess": 3
},
"completionReport": {
"completed": true,
"reasonCode": null,
"fixTarget": null,
"hasComment": true,
"truncated": false
}
},
"occurrence": null,
"projectRun": {
"id": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"originType": "manual",
"status": "running",
"currentStepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"snapshotSchemaVersion": 3
},
"runStep": {
"id": "1842",
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"attempt": 1,
"status": "done",
"laneId": null,
"resumeCommandId": null,
"supersededBy": null
},
"startActor": {
"kind": "person",
"ref": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
},
"missing": []
}
]
},
"timeline": {
"items": [
{
"at": "2026-11-18T01:30:06.000Z",
"key": 1201,
"section": "evidence",
"eventType": "context.manifest",
"writer": "worker",
"actor": {
"kind": "agent",
"ref": null,
"onBehalfOf": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
},
"resource": null,
"action": null,
"decision": null,
"reason": null,
"policyVersion": null,
"ref": {
"executionId": "a4c6e8f0-1b3d-4a5c-9e7f-2d4b6a8c0e1f",
"conversationId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
"messageId": null,
"requestId": null,
"sourceEventId": null,
"projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
"rootExecutionId": "a4c6e8f0-1b3d-4a5c-9e7f-2d4b6a8c0e1f",
"payloadDigest": null
},
"meta": {},
"available": true
}
]
},
"deleted": {
"conversations": [],
"resources": []
},
"hasMore": false,
"snapshotAt": "2026-11-18T05:40:00.000Z"
}

エラーレスポンス​

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

POST/v1/projects/{projectId}/executions/{executionId}/cancel

cycle のプロジェクトで、巡回の実行を止めます。画面の「停止する」と同じです。オーナーと運用担当(組織の運用の役割の人を含む)が呼べます。システム連携のトークンでも呼べます。ボディは要りません(送っても使いません)。

  • 止められるのは、cycle のプロジェクトの巡回の実行だけです。workflow の工程の実行(rs:<数値>)を指定すると 400 Bad Request(invalid_parameter)です。ワークフローの実行は、ワークフローの実行の中断で止めてください。
  • 受け付けてから実行が止まるまで、1 分ほどかかることがあります。止まったかは、実行の結果の取得(GET /v1/projects/{projectId}/executions/{executionId})で確かめてください。システム連携(サービスアカウント)のトークンでも呼べます(状態の項目だけを返します)。止める要求を受けたときに、まだ動き出していなかった実行は、実行の結果の取得で 404 Not Found(execution_not_found)のままです。
  • 前に止める要求を受けていた実行と、終わっていた実行は、何も変えずに 200 OK が返り、existing が true です。

パスパラメータ​

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

リクエスト例​

Cancel execution
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/a1b2c3d4-e5f6-4789-8abc-def012345678/cancel \
2-H "Authorization: Bearer <access_token>"

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

新しく止める要求を受けたときは 202 Accepted、そうでないときは 200 OK です。

フィールド型説明
executionIdstring実行の ID
statestring受け付けたときの状態。止まったかどうかは表しません(確かめ方は、この節の初めの箇条にあります)。値の例: "dispatched"(動いている実行に止める要求を伝えた)、"cancelled"(まだ動き出していなかった実行を取り消した)、"terminal"(すでに終わっていた実行)。ほかにも、受け付けた時点の実行や送信の状態の値がそのまま入ります。値の一覧を決めて使わないでください
existingboolean前に止める要求を受けていた、または実行が終わっていたとき true(202 Accepted のときはいつも false)

レスポンス例​

JSON
{
"executionId": "a1b2c3d4-e5f6-4789-8abc-def012345678",
"state": "dispatched",
"existing": false
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId が UUID の形式ではない、executionId が rs:<数値> でも UUID でもない、または executionId が workflow の工程の実行
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
403operator_onlyオーナーでも運用担当でもなく、組織の運用の役割も持たないメンバー
403sso_required認証サーバーのアカウントと結び付いていない利用者
404execution_not_found実行が存在しない、ほかのプロジェクトの実行、cycle ではないプロジェクト、またはメンバーではないプロジェクト
413body_too_largeボディが 16 KiB を超える
415unsupported_media_typeボディがあるのに、Content-Type が application/json ではない

ファイル​

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

エンドポイント一覧​

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

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

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

パスパラメータ​

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

クエリパラメータ​

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

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

リクエスト例​

Get project file content
1curl "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/files/content?path=/users/f47ac10b-58cc-4372-a567-0e02b2c3d479/plans/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/deliverables/report.pdf" \
2-H "Authorization: Bearer <access_token>"

レスポンス(200 OK)​

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

レスポンスヘッダー説明
Content-Typeファイルの MIME タイプ
Content-Lengthファイルサイズ(バイト)。大きさが分かるときだけ付きます
Accept-Ranges"bytes"(大きさが分かるときだけ付きます)
X-Content-Type-Options"nosniff"
Content-DispositionHTML・SVG・XML のファイルでは "attachment"(ダウンロードとして返します)
Content-Security-PolicyHTML・SVG・XML のファイルでは、スクリプトの実行や外部の読み込みを止める設定(sandbox ほか)が付きます

エラーレスポンス​

ステータス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)と同じです。

記録 (証跡)​

プロジェクトの中の決まった操作や出来事(確認の決定、実行ルールやメンバーの変更、実行の中のツールの記録など)の一覧です。設定の変更で残るのは、実行ルール・確認担当者・確認方法・メンバー・プロジェクトの Webhookの変更です(画面から変えたものも残ります)。プロジェクトの定義(基本情報・実行ルール・工程・配置・トリガー・アプリとメールの通知・連携先)の変更は、定義の版を記録するときに、前の版との差分が項目ごとに project.definition_changed で残ります(説明・目的などの長い欄は長さだけ)。巡回と、外へ出す Webhook の通知の変更は残りません。

エンドポイント一覧​

メソッドエンドポイント説明
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 値)

リクエスト例​

List audit events
1curl "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/audit?kind=policy.changed&limit=20" \
2-H "Authorization: Bearer <access_token>"

レスポンスフィールド(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.* など)は含まれません。実行の時系列で読みます。

レスポンス例​

JSON
{
"events": [
{
"eventId": 1042,
"occurredAt": "2026-11-18T04:20:11.000Z",
"eventType": "policy.changed",
"actorKind": "human",
"actorRef": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"decision": null,
"reason": null,
"executionId": null,
"runId": null,
"stepName": null,
"metadata": {}
}
],
"hasMore": false
}

エラーレスポンス​

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

KPI​

画面の概要の「この業務の実行結果」と同じ値を取得します(工程ごとの steps は、概要の「ワークフローの形」の「数値」に出る値です。確認工程だけの値は gates にもあります)。数え方は結果リファレンスを参照してください(工程ごとの値は工程ごとの数値)。

エンドポイント一覧​

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

GET/v1/projects/{projectId}/kpi

プロジェクトの KPI を取得します。プロジェクトのメンバーと、組織の運用の役割の人が読めます(公開されているプロジェクトでも、どちらでもなければ 404)。

クエリパラメータ​

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

リクエスト例​

Get project KPI
1curl "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/kpi?days=30" \
2-H "Authorization: Bearer <access_token>"

レスポンスフィールド(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)。steps が配列で、確認工程の行の gate が null でないときは、total・approvalRate・sendBackRate がその gate と同じ値です
stepsarray | null工程ごとの実績。有効な工程を位置の順に並べます(stepId・position・name・defaultZone・agent・gate・automation)。agent・gate・automation は、その工程の種類の 1 つだけが入り、ほかは null です。条件分岐の工程はどれも null です。取得できないときは null
steps[].namestring工程の名前(名前を付けていない工程は、プロジェクトの言語(無ければサービスの既定の言語)で作った名前)
steps[].defaultZonestring | null工程の種類。"ai"(Agent が実行)・"gate"(確認工程)・"branch"(条件分岐)のどれか
steps[].agentobject | nullAgent の工程の実績。上の Agentの完遂率と同じ項目(executions・succeeded・denominator・noChange・successRate・successRateStatus・outcomes・excluded・durationP95Minutes)を、その工程の実行だけで数えます
steps[].gateobject | null確認の工程の実績(mode・total・approvalRate・sendBackRate・waitMedianMinutes・deadlineDecisions)。deadlineDecisions は human.deadlineDecisions と同じ数え方で、その工程の確認依頼だけを数えます。human.deadlineDecisions と同じく、total が 0 なら rate が null です
steps[].automationobject | nullいつも null(外部の自動化の工程はありません)
humanobject確認対応の状況(reviewsPerRun・gateWaitMedianMinutes・interventions・deadlineDecisions)
human.deadlineDecisionsobject | null期間に作られた期限のある確認のうち、人が期限までに決めた件数と率(total: 決まったか期限を過ぎた件数・onTime: 人が期限までに決めた件数・rate: onTime / total。total が 0 なら null)。期限による自動の決定は期限内に数えません

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

エラーレスポンス​

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

レスポンス例​

JSON
{
"days": 30,
"successRate": 0.9318,
"successRateStatus": "ok",
"succeeded": 41,
"denominator": 44,
"executions": 46,
"noChange": 2,
"outcomes": {
"completed": 43,
"incomplete": 2,
"failed": 1,
"timeout": 0,
"stopped": 0,
"denied": 0,
"skipped": 1
},
"excluded": {
"skipped": 1,
"running": 1,
"missing": 2,
"unmeasured": 0,
"connectionConfirm": 0
},
"durationP95Minutes": 14,
"runs": {
"total": 24,
"closedDone": 20,
"closedFailed": 2,
"closedRejected": 1,
"cancelled": 1,
"p95Minutes": 22
},
"gates": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"position": 2,
"name": "差異の確認",
"mode": "blocking",
"total": 17,
"approvalRate": 0.88,
"sendBackRate": 0.12
}
],
"steps": [
{
"stepId": "2b3c4d5e-6f70-4819-a2b3-c4d5e6f70812",
"position": 1,
"name": "請求書の読み取り",
"defaultZone": "ai",
"agent": {
"executions": 46,
"succeeded": 41,
"denominator": 44,
"noChange": 2,
"successRate": 0.9318,
"successRateStatus": "ok",
"durationP95Minutes": 14,
"outcomes": {
"completed": 43,
"incomplete": 2,
"failed": 1,
"timeout": 0,
"stopped": 0,
"denied": 0,
"skipped": 1
},
"excluded": {
"skipped": 1,
"running": 1,
"missing": 2,
"unmeasured": 0,
"connectionConfirm": 0
}
},
"gate": null,
"automation": null
},
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"position": 2,
"name": "差異の確認",
"defaultZone": "gate",
"agent": null,
"gate": {
"mode": "blocking",
"total": 17,
"approvalRate": 0.88,
"sendBackRate": 0.12,
"waitMedianMinutes": 35,
"deadlineDecisions": {
"total": 15,
"onTime": 14,
"rate": 0.9333
}
},
"automation": null
}
],
"human": {
"reviewsPerRun": 0.7,
"gateWaitMedianMinutes": 35,
"interventions": 17,
"deadlineDecisions": {
"total": 15,
"onTime": 14,
"rate": 0.9333
}
}
}

確認依頼​

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

  • 読めるのは、確認担当者(確認依頼ができたときの担当者で、今もプロジェクトのメンバーの人)と、その人が設定した期間中の代理人、プロジェクトのオーナーです。それ以外の利用者には 404 Not Found(workitem_not_found)が返ります。
  • 判断ができるのは、確認担当者と期間中の代理人だけです。オーナーでも、そのどちらでもなければできません(403 Forbidden、not_gate_owner)。期限の延長は、それに加えて、オーナー・運用担当と組織の運用の役割の人もできます。代理人は、確認担当者が画面の設定(不在と代理人)で、期間を決めて同じ組織の利用者 1 人を指定します。代理人はプロジェクトのメンバーでなくてもかまいません。

エンドポイント一覧​

メソッドエンドポイント説明
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 の値)

リクエスト例​

List work items
1curl "https://<your-domain>/api/v1/workitems?state=open&limit=20" \
2-H "Authorization: Bearer <access_token>"

レスポンスフィールド(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 のときだけ含まれます

レスポンス例​

JSON
{
"workitems": [
{
"workItemId": "c9d8e7f6-a5b4-4321-8fed-cba098765432",
"title": "差異のある請求書の確認",
"status": "assigned",
"projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
"projectName": "請求書の突合",
"decision": null,
"requesterUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"expiresAt": "2026-11-20T09:00:00.000Z",
"gateMode": "blocking",
"overdue": false,
"decidedAt": null,
"createdAt": "2026-11-18T01:34:40.000Z",
"updatedAt": "2026-11-18T01:34:40.000Z",
"canDecide": true
}
],
"hasMore": false
}

エラーレスポンス​

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

GET/v1/workitems/{workItemId}

確認依頼を、確認の材料・経緯・選択できる次の工程と一緒に取得します。

パスパラメータ​

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

リクエスト例​

Get work item
1curl https://<your-domain>/api/v1/workitems/c9d8e7f6-a5b4-4321-8fed-cba098765432 \
2-H "Authorization: Bearer <access_token>"

レスポンスフィールド(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[].onBehalfOfRefstring | null代理人が判断したときの、代理した確認担当者の利用者 ID。確認担当者が自分で判断したときなどは null
activities[].reasonCodestring | null理由(条件分岐で決められず人に選択してもらうときは "branch_undecided")
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 の工程の結果によって確認を求めたとき。条件分岐で決められず人に選択してもらう確認では "branch_undecided")
escalateToUserIdstring | null期限超過時の連絡先の利用者 ID(確認依頼ができたときにメンバーだった人)
destinationsarray条件分岐の確認だけ、進む先の候補(destinationId・label・stepId と、進む先 branchRoute〈{"kind": "lane", "laneId"} か {"kind": "merge"}〉)が入ります。それ以外の確認依頼ではいつも空の配列(マーケットプレイス版では、確認工程に進め先を設定できません)
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条件分岐の確認だけ、進む先の候補(destinationId・label・stepId・stepName・stepPosition と、進む先 branchRoute〈{"kind": "lane", "laneId"} か {"kind": "merge"}〉)が入ります。それ以外の確認依頼ではいつも空の配列(マーケットプレイス版では、確認工程に進め先を設定できません)
laneobject | null確認を求めた工程のレーン(laneId・name・position)。レーンが無ければ null

レスポンス例​

JSON
{
"workitem": {
"workItemId": "c9d8e7f6-a5b4-4321-8fed-cba098765432",
"title": "差異のある請求書の確認",
"status": "assigned",
"projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
"decision": null,
"requesterUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"expiresAt": "2026-11-20T09:00:00.000Z",
"gateMode": "blocking",
"overdue": false,
"decidedAt": null,
"createdAt": "2026-11-18T01:34:40.000Z",
"updatedAt": "2026-11-18T01:34:40.000Z",
"canDecide": true,
"description": "請求書 12 件のうち 1 件に金額の差異があります。",
"runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"runStepId": "rs:1843",
"stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"approverUserIds": [
"f47ac10b-58cc-4372-a567-0e02b2c3d479"
],
"overdueAction": "none",
"evidence": {
"summary": "請求書 12 件を照合し、差異のあった 1 件を確認依頼にしました。",
"conversationId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
"files": [],
"gateKind": "review",
"stepName": "金額の確認",
"outcome": "completed",
"executionId": "a4c6e8f0-1b3d-4a5c-9e7f-2d4b6a8c0e1f",
"reasonCode": null,
"escalateToUserId": null,
"destinations": [],
"connector": null,
"service": null,
"mode": null,
"tool": null,
"waitMinutes": null
},
"decidedByKind": null,
"decidedByRef": null,
"decisionReason": null,
"sendBackToStepId": null,
"decisionResult": null
},
"activities": [
{
"activityId": 5301,
"eventType": "gate.requested",
"decision": "requested",
"actorKind": "system",
"actorRef": "system:completion-apply",
"onBehalfOfRef": null,
"reasonCode": "review",
"conversationId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
"metadata": {
"workitem_id": "c9d8e7f6-a5b4-4321-8fed-cba098765432",
"run_id": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"step_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"gate_mode": "blocking",
"gate_kind": "review"
},
"occurredAt": "2026-11-18T01:34:40.000Z"
}
],
"gate": {
"contextVersion": 1,
"basisDigest": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b",
"projectName": "請求書の突合",
"projectType": "workflow",
"stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"stepName": "差異の確認",
"stepPosition": 2,
"nextStep": {
"stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"name": "差異の報告",
"position": 3
},
"sendBackDefaultStepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"sendBackCandidates": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"name": "金額の確認",
"position": 1,
"sendBacks": 0
}
],
"sendBackLimit": 3,
"destinations": [],
"lane": 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 の工程に戻します
destinationIdstring—進め先("proceed" のとき。gate の destinations の destinationId。64 文字まで)。進め先のある確認依頼を進めるときは必須
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 で送り直してください。

リクエスト例​

Decide work item
1curl -X POST https://<your-domain>/api/v1/workitems/c9d8e7f6-a5b4-4321-8fed-cba098765432/decision \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "decision": "proceed",
6 "reason": "差異は税込・税抜の違いだったため",
7 "contextVersion": 1,
8 "basisDigest": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b",
9 "commandId": "decide-20261118-0001"
10}'

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

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

レスポンス例​

JSON
{
"decision": "proceed",
"channel": "api"
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterworkItemId・sendBackToStepId が UUID の形式ではない、decision が無い・上の値ではない、commandId・destinationId が空白だけ、contextVersion が 1 以上の整数ではない、basisDigest が 64 文字の小文字の 16 進ではない、または項目の型や長さの誤り
400invalid_parametersendBackFiles を送った(この API では受け付けません)
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
400reason_required"send_back"・"reject" で reason が無い
400invalid_send_back_stepsendBackToStepId が、差し戻し先に指定できる工程ではない
400destination_required進め先のある確認依頼を、destinationId なしで進めようとした
400invalid_destinationdestinationId が進め先に無い、または "proceed" 以外で destinationId を送った
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 の日時。今より後)

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

リクエスト例​

Extend work item
1curl -X PATCH https://<your-domain>/api/v1/workitems/c9d8e7f6-a5b4-4321-8fed-cba098765432 \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "expiresAt": "2026-11-22T09:00:00.000Z"
6}'

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

フィールド型説明
workitemobject | null延ばした後の確認依頼。項目は、確認依頼の取得の workitem と同じです。確認依頼を読めない人(確認担当者・期間中の代理人・オーナーのどれでもない、運用担当や組織の運用の役割の人)が延ばしたときは null
expiresAtstring延ばした後の期限(ISO 8601)
previousExpiresAtstring | null延ばす前の期限(ISO 8601)

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

レスポンス例​

JSON
{
"workitem": {
"workItemId": "c9d8e7f6-a5b4-4321-8fed-cba098765432",
"title": "差異のある請求書の確認",
"status": "assigned",
"projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
"decision": null,
"requesterUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"expiresAt": "2026-11-22T09:00:00.000Z",
"gateMode": "blocking",
"overdue": false,
"decidedAt": null,
"createdAt": "2026-11-18T01:34:40.000Z",
"updatedAt": "2026-11-18T01:34:40.000Z",
"canDecide": true,
"description": "請求書 12 件のうち 1 件に金額の差異があります。",
"runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"runStepId": "rs:1843",
"stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"approverUserIds": [
"f47ac10b-58cc-4372-a567-0e02b2c3d479"
],
"overdueAction": "none",
"evidence": {
"summary": "請求書 12 件を照合し、差異のあった 1 件を確認依頼にしました。",
"conversationId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
"files": [],
"gateKind": "review",
"stepName": "金額の確認",
"outcome": "completed",
"executionId": "a4c6e8f0-1b3d-4a5c-9e7f-2d4b6a8c0e1f",
"reasonCode": null,
"escalateToUserId": null,
"destinations": [],
"connector": null,
"service": null,
"mode": null,
"tool": null,
"waitMinutes": null
},
"decidedByKind": null,
"decidedByRef": null,
"decisionReason": null,
"sendBackToStepId": null,
"decisionResult": null
},
"expiresAt": "2026-11-22T09:00:00.000Z",
"previousExpiresAt": "2026-11-20T09:00:00.000Z"
}

エラーレスポンス​

ステータス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期限を延ばした後の読み直しが、確認依頼を読めないこと(404)のほかの理由で失敗した(確認依頼を読める人は、送り直す前に、確認依頼の取得で確かめてください)

キュー​

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

  • プロジェクトのキュー(GET /v1/projects/{projectId}/queue)は、そのプロジェクトの全部の行を返します。プロジェクトのメンバーと、組織の運用の役割の人なら読めます。
  • 自分のキュー(GET /v1/queue)は、参加しているプロジェクトのうち、自分が担当の行を返します。ほかの利用者の期間中の代理人になっているときは、その人の確認依頼の行も返します。
  • 行への操作は、下の表の「使う ID」(行に入っている ID。行の ID の queueItemId ではありません)を、その API に渡して行います。
すること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(行の ID の : の後ろ)の順で、変えられません。カーソルベースのページネーションに対応しています。

パスパラメータ​

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

クエリパラメータ​

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

リクエスト例​

List project queue
1curl "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/queue?kind=gate_pending&limit=20" \
2-H "Authorization: Bearer <access_token>"

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

フィールド型説明
queueItemsarrayキューの行の配列
queueItems[].queueItemIdstring行の ID。<対象の種類>:<対象の ID> の形です。対象の種類は workitem(確認依頼の行。gate_overdue・external_wait_blocked・gate_pending)・run_step(失敗した工程・差し戻し待ち)・placement(失敗した巡回)・run(締め切りの超過・停滞したワークフローの実行)の 4 つで、行の種類(kind)とは別の値です。確認依頼が gate_pending から gate_overdue に変わっても、ID は変わりません。行を見分けるときは、組み立てたり分けたりせず、返った値をそのまま使ってください。行への操作には workItemId・runId・executionId を使います
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差し戻せる回数の上限に達したかどうか
hasMoreboolean次のページが存在するかどうか
cursorstring次ページ取得用カーソル。hasMore が true の場合のみ含まれます

レスポンス例​

JSON
{
"queueItems": [
{
"queueItemId": "workitem:c9d8e7f6-a5b4-4321-8fed-cba098765432",
"kind": "gate_pending",
"priority": 3,
"projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
"projectName": "請求書の突合",
"workItemId": "c9d8e7f6-a5b4-4321-8fed-cba098765432",
"runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"executionId": null,
"stepName": "差異の確認",
"agentName": "経理 Agent",
"title": "差異のある請求書の確認",
"dueAt": "2026-11-20T09:00:00.000Z",
"elapsedFrom": "2026-11-18T01:30:00.000Z",
"assigneeUserIds": [
"f47ac10b-58cc-4372-a567-0e02b2c3d479"
],
"escalateToUserId": null,
"cause": null,
"gateKind": "review",
"observationErrorCode": null,
"sendBackLimitReached": false
}
],
"hasMore": false
}

エラーレスポンス​

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

GET/v1/queue

参加しているプロジェクトのうち、自分が担当の行と、期間中の代理人として判断できる確認依頼の行を、優先度の順に取得します。代理の行には、自分がメンバーでないプロジェクトの行も入ります。その確認依頼は、workItemId で読む・判断する・期限を延ばすことができます。プロジェクトをまたいで返します。クエリパラメータ・レスポンスフィールド・並びは、プロジェクトのキューと同じです。

リクエスト例​

List my queue
1curl "https://<your-domain>/api/v1/queue?kind=gate_pending&limit=20" \
2-H "Authorization: Bearer <access_token>"

レスポンス例​

JSON
{
"queueItems": [
{
"queueItemId": "workitem:c9d8e7f6-a5b4-4321-8fed-cba098765432",
"kind": "gate_pending",
"priority": 3,
"projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
"projectName": "請求書の突合",
"workItemId": "c9d8e7f6-a5b4-4321-8fed-cba098765432",
"runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"executionId": null,
"stepName": "差異の確認",
"agentName": "経理 Agent",
"title": "差異のある請求書の確認",
"dueAt": "2026-11-20T09:00:00.000Z",
"elapsedFrom": "2026-11-18T01:30:00.000Z",
"assigneeUserIds": [
"f47ac10b-58cc-4372-a567-0e02b2c3d479"
],
"escalateToUserId": null,
"cause": null,
"gateKind": "review",
"observationErrorCode": null,
"sendBackLimitReached": false
}
],
"hasMore": false
}

エラーレスポンス​

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

連携先​

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

  • 連携先の ID(connectionId)は、プロジェクトの取得の connectors[].connectionId と、ツールの呼び出しの一覧の operations[].connectionId で分かります。
  • テナントの利用者なら、どの連携先も読めます(プロジェクトのメンバーでなくても読めます)。ただし MCP の連携先は、管理コンソールで使える組織・職種を限っているとき、使えない人には 404 Not Found(connector_not_found)です。projectId を付けると、プロジェクトの画面と同じく、そのプロジェクトのオーナーの組織・職種で判断します(付けないときは、呼び出した人の組織・職種で判断します。呼び出した人がシステム管理者のときは、使える組織・職種の限りでは 404 にならず、この API で読めます)。管理コンソールで無効にされた・削除された連携先も 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 桁までの正の整数)

クエリパラメータ​

パラメータ型必須説明
projectIdstring—連携先を使うプロジェクトの ID(UUID)。付けると、使えるかをそのプロジェクトのオーナーの組織・職種で判断します。プロジェクトのメンバーか、組織の運用の役割の人だけが付けられます

リクエスト例​

Get MCP connector
1curl "https://<your-domain>/api/v1/connectors/mcp/12?projectId=3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31" \
2-H "Authorization: Bearer <access_token>"

レスポンスフィールド(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

レスポンス例​

JSON
{
"kind": "mcp",
"connectionId": "12",
"name": "社内ドキュメント検索",
"requiresLogin": false,
"tools": [
{
"name": "search_documents",
"displayName": "ドキュメント検索",
"description": "社内のドキュメントをキーワードで検索します",
"inputSchema": {
"type": "object",
"properties": {
"query": {
"type": "string"
}
},
"required": [
"query"
]
},
"outputSchema": null,
"declaredAnnotations": {
"readOnlyHint": true
},
"presentInLastFetch": true
}
],
"toolsFetchedAt": "2026-11-17T09:30:00.000Z"
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterconnectionId が 16 桁までの正の整数ではない、または projectId が UUID ではない
403forbiddenシステム連携のトークンで呼び出した
403sso_requiredprojectId を付けた呼び出しで、認証サーバーのアカウントと結び付いていない利用者
404connector_not_found連携先が存在しない、無効、または使える組織・職種に入っていない
404project_not_foundprojectId のプロジェクトが無い、またはメンバー・組織の運用の役割の人ではない

GET/v1/connectors/a2a/{connectionId}

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

パスパラメータ​

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

リクエスト例​

Get A2A connector
1curl https://<your-domain>/api/v1/connectors/a2a/7 \
2-H "Authorization: Bearer <access_token>"

レスポンスフィールド(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 の中身は、相手のエージェントが公開している形のままです。

レスポンス例​

JSON
{
"kind": "a2a",
"connectionId": "7",
"name": "翻訳 Agent",
"requiresLogin": false,
"agentCard": {
"description": "文書を指定した言語に翻訳します",
"version": "1.0.0",
"provider": {
"organization": "Example Corp.",
"url": "https://example.com"
},
"skills": [
{
"id": "translate",
"name": "翻訳",
"description": "文書を翻訳します",
"tags": [
"translation"
]
}
],
"capabilities": {
"streaming": true
},
"defaultInputModes": [
"text/plain"
],
"defaultOutputModes": [
"text/plain"
],
"supportedInterfaces": [
{
"url": "https://agent.example.com/a2a",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"documentationUrl": null,
"iconUrl": null,
"securitySchemes": null,
"securityRequirements": []
}
}

エラーレスポンス​

ステータス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リソースが現在処理中など、操作が競合
409 Conflict組織の運用の役割(管理コンソールの「管理の役割」で付ける「運用」の役割)の人が、プロジェクトに参加せずに、その役割では使えない操作を呼んだ(error.code は forbidden_role)。待っても直りません。オーナーだけの操作は、プロジェクトのオーナーに頼んでください。ほかの操作は、オーナーにプロジェクトに加えてもらうと、参加の役割のとおりに呼べます
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.reasonstring断りの理由の種類。プロジェクト API の 409(definition_invalid)のときだけ含まれます
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"
}
}

利用を止められた利用者​

管理者に利用を止められた利用者のトークンで呼ぶと、401 Unauthorized が返ります。error.code は account_suspended です。

次の API は、利用を止められたかどうかを見ません: GET /v1/organizations・GET /v1/job-types・GET /v1/user・PATCH /v1/user・GET /v1/marketplace-agents、MCP の list_agents と、進行中のタスクが無いときの cancel_chat、登録 Agent の Agent Card(GET /api/v1/a2a/agents/{agentId}/.well-known/agent-card.json)。