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

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

システム連携のトークンで呼べるプロジェクトの API は、プロジェクト一覧の取得・ワークフローの実行の開始・トリガーの発火・ワークフローの実行の取得の 4 つだけです（[システム連携 API リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/api-reference.md#projects)）。このページのほかの API をシステム連携のトークンで呼ぶと `403 Forbidden`（`forbidden`）が返ります。

## ベース URL

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

Marketplace

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

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

## 認証

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

```text
Authorization: Bearer <access_token>
```

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

このページの API は、アプリケーション（外部ツールでのログイン）で得た利用者のトークンで呼びます。外部ツールでのログインは、管理者がその入口を開けた環境でだけ使えます（[API 利用準備ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/setup-guide.md)）。外部ツールでのログイン以外で得た利用者のトークン（メイン画面にログインしたときのトークンなど）で呼ぶと、どのエンドポイントも `404 Not Found` が返ります。トークンの取得方法については、[認証ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/auth-guide.md) および [認証 API リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/auth-mp-ref.md) を参照してください。

## 共通の決まり

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

### 呼べる人と 404・403

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

### リクエストの扱い

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

### 書き換えと送り直し

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

### 人を表す項目

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

### ページネーション

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

## プロジェクト

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

### エンドポイント一覧

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

### GET`/v1/projects`

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

#### クエリパラメータ

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

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

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

<!-- -->

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

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

#### レスポンス例

<!-- -->

<!-- -->

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

#### エラーレスポンス

| ステータス | 説明                                                                   |
| ----- | -------------------------------------------------------------------- |
| `400` | limit（1〜100 の範囲外）、cursor、または my\_role が不正（code は invalid\_parameter） |

### GET`/v1/projects/shared`

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

#### クエリパラメータ

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

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

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

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

#### エラーレスポンス

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

### GET`/v1/projects/organizations`

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

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

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

#### エラーレスポンス

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

### GET`/v1/projects/{projectId}`

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

#### パスパラメータ

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

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

| フィールド                              | 型                 | 説明                                                                                                                   |
| ---------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------- |
| `project`                          | `object`          | プロジェクト（下の表）                                                                                                          |
| `steps`                            | `array`           | 工程の配列（並び順）。1 件の項目は「工程の項目」を参照                                                                                         |
| `stepsDigest`                      | `string`          | 工程の並びの値。工程を並べ替えるときに baseDigest に送ります                                                                                 |
| `members`                          | `array`           | メンバーの配列                                                                                                              |
| `members[].userId`                 | `string`          | 利用者 ID                                                                                                               |
| `members[].role`                   | `string \| null`  | "owner" または "member"                                                                                                 |
| `members[].joinedAt`               | `string \| null`  | メンバーになった日時（ISO 8601）                                                                                                 |
| `members[].name`                   | `string \| null`  | 利用者の名前                                                                                                               |
| `members[].email`                  | `string \| null`  | 利用者のメールアドレス                                                                                                          |
| `placements`                       | `array`           | 配置の配列。1 件の項目は「配置の項目」を参照                                                                                              |
| `triggers`                         | `array`           | トリガーの配列（時刻と Webhook のトリガーだけ）                                                                                         |
| `triggers[].triggerId`             | `string \| null`  | トリガー ID（UUID）。トリガーの発火に使います                                                                                           |
| `triggers[].type`                  | `string`          | "cron"（時刻）または "webhook"                                                                                              |
| `triggers[].name`                  | `string \| null`  | 名前                                                                                                                   |
| `triggers[].enabled`               | `boolean \| null` | 有効かどうか                                                                                                               |
| `triggers[].lastFiredAt`           | `string \| null`  | 最後に発火した日時（ISO 8601）                                                                                                  |
| `triggers[].nextFireAt`            | `string \| null`  | 次に発火する予定の日時（ISO 8601）                                                                                                |
| `triggers[].createdAt`             | `string \| null`  | 作成日時（ISO 8601）                                                                                                       |
| `triggers[].cron`                  | `string \| null`  | cron 式（"cron" のトリガーだけ）                                                                                               |
| `triggers[].timezone`              | `string \| null`  | タイムゾーン（"cron" のトリガーだけ）                                                                                               |
| `triggers[].startStepId`           | `string \| null`  | 始める工程の ID（"cron" のトリガーだけ）                                                                                            |
| `triggers[].placementId`           | `string \| null`  | 起動する配置の ID（"webhook" のトリガーだけ）                                                                                        |
| `triggers[].stepId`                | `string \| null`  | 起動する工程の ID（"webhook" のトリガーだけ）                                                                                        |
| `triggers[].startFailure`          | `object \| null`  | 開始の失敗（"cron" のトリガーだけ）。開始できなかったときだけ入り、ほかは null。下の「開始の失敗の読み方」を参照                                                       |
| `triggers[].startFailure.reason`   | `string \| null`  | 開始できなかった理由のコード                                                                                                       |
| `triggers[].startFailure.since`    | `string \| null`  | その理由で開始できなくなった日時（ISO 8601）                                                                                           |
| `stepStartFailures`                | `array`           | 先頭の工程に付けた時刻で開始する形の、開始の失敗の配列。開始できなかった工程だけが入ります。下の「開始の失敗の読み方」を参照                                                       |
| `stepStartFailures[].stepId`       | `string \| null`  | 工程の ID                                                                                                               |
| `stepStartFailures[].reason`       | `string \| null`  | 開始できなかった理由のコード                                                                                                       |
| `stepStartFailures[].since`        | `string \| null`  | その理由で開始できなくなった日時（ISO 8601）                                                                                           |
| `notifications`                    | `object`          | 通知の設定                                                                                                                |
| `notifications.gateReached`        | `boolean \| null` | 確認依頼が届いたときに通知するかどうか                                                                                                  |
| `notifications.gateOverdue`        | `boolean \| null` | 確認依頼が期限を過ぎたときに通知するかどうか                                                                                               |
| `notifications.runDeadlineOverdue` | `boolean \| null` | ワークフローの実行が締め切りを過ぎたときに通知するかどうか                                                                                        |
| `notifications.runStalled`         | `boolean \| null` | ワークフローの実行が停滞したとき（limits.stallHours のあいだ進まないとき）に通知するかどうか                                                              |
| `connectors`                       | `array`           | このプロジェクトに登録した連携先の配列                                                                                                  |
| `connectors[].kind`                | `string \| null`  | "mcp" または "a2a"                                                                                                      |
| `connectors[].connectionId`        | `string \| null`  | 連携先の ID。連携先の API（GET /v1/connectors/{kind}/{connectionId}）で中身を読めます。管理画面で無効にされた・削除された連携先と、連携先の情報を確かめられなかったときは null    |
| `connectors[].name`                | `string \| null`  | 連携先の名前                                                                                                               |
| `connectors[].ledgerEnabled`       | `boolean \| null` | 台帳として使う連携先かどうか                                                                                                       |
| `connectors[].confirmMode`         | `string \| null`  | この連携先を使う前に、人の確認を求めるかの設定。"none" / "first\_per\_execution" / "always" のどれか。画面で設定します                                    |
| `connectors[].confirmWaitMinutes`  | `number \| null`  | その確認を待つ時間の上限（分）                                                                                                      |
| `connectors[].login`               | `string \| null`  | ログインの状態。"connected"（ログイン済み）/ "reauth\_required"（ログインし直しが必要）/ "not\_connected"（未ログイン）。状態を確かめられないときは null。ログインは画面で行います |
| `connectors[].createdAt`           | `string \| null`  | 登録日時（ISO 8601）                                                                                                       |

`project` の項目:

| フィールド                        | 型                 | 説明                                                                 |
| ---------------------------- | ----------------- | ------------------------------------------------------------------ |
| `projectId`                  | `string`          | プロジェクト ID（UUID）                                                    |
| `name`                       | `string \| null`  | プロジェクト名                                                            |
| `description`                | `string \| null`  | 説明                                                                 |
| `tags`                       | `array`           | タグの配列                                                              |
| `type`                       | `string \| null`  | "workflow" または "cycle"                                             |
| `status`                     | `string \| null`  | "active"（稼働中）/ "paused"（停止中）/ "archived"（アーカイブ）のいずれか               |
| `policy`                     | `object \| null`  | 実行ルール。画面で設定した値のまま返ります。この API では変えられません                             |
| `limits`                     | `object \| null`  | 実行の上限                                                              |
| `limits.maxRetriesPerStep`   | `number`          | 1 つの工程で失敗したときにやり直す回数の上限                                            |
| `limits.maxSendBacksPerStep` | `number`          | 同じ工程へ差し戻せる回数の上限                                                    |
| `limits.runDeadlineHours`    | `number \| null`  | ワークフローの実行の締め切りの既定（開始からの時間）。null または無ければ締め切りを付けません                  |
| `limits.stallHours`          | `number`          | 進まないまま、この時間が過ぎると停滞とみなす時間（無ければ 24 時間）                               |
| `limits.maxMinutesPerRun`    | `number \| null`  | 1 回の実行の長さの上限（分）。5・15・30・60・90・120 のどれか。無いとき・null のときは、この上限を付けていません |
| `language`                   | `string \| null`  | プロジェクトの言語                                                          |
| `flowStructure`              | `object \| null`  | いつも null                                                           |
| `reportTargets`              | `object \| null`  | 今は使っていない項目です（値が入っていても使われません）                                       |
| `escalateToUserId`           | `string \| null`  | プロジェクトの既定の連絡先の利用者 ID（期限を過ぎた確認依頼の連絡先。このエンドポイントでは変えられません）            |
| `organizationCode`           | `string \| null`  | 組織のコード                                                             |
| `organizationName`           | `string \| null`  | 組織の名前                                                              |
| `isShared`                   | `boolean \| null` | 公開しているかどうか                                                         |
| `copyCount`                  | `number \| null`  | コピーされた回数                                                           |
| `ownerUserId`                | `string \| null`  | 持ち主の利用者 ID                                                         |
| `myRole`                     | `string \| null`  | 呼んだ利用者の役割。"owner" または "member"。プレビューでは null                        |
| `createdAt`                  | `string \| null`  | 作成日時（ISO 8601）                                                     |
| `updatedAt`                  | `string \| null`  | 最終更新日時（ISO 8601）                                                   |
| `digest`                     | `string`          | プロジェクトを変えるときに baseDigest に送る値                                      |

<!-- -->

開始の失敗の読み方（`triggers[].startFailure`・`stepStartFailures`）:

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

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

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

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

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

<!-- -->

#### エラーレスポンス

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

### POST`/v1/projects`

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

#### リクエストボディ

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

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

#### レスポンス（201 Created）

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

#### エラーレスポンス

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

### PATCH`/v1/projects/{projectId}`

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

#### パスパラメータ

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

#### リクエストボディ

| フィールド                        | 型                 | 必須 | 説明                                                                                                                                                                                               |
| ---------------------------- | ----------------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `baseDigest`                 | `string`          | 必須 | プロジェクトの取得の project.digest                                                                                                                                                                        |
| `name`                       | `string`          | —  | プロジェクト名（255 文字まで。空・空白だけにはできません）                                                                                                                                                                  |
| `description`                | `string`          | —  | 説明（5000 文字まで。空の文字列・空白だけ・null にはできません）                                                                                                                                                            |
| `tags`                       | `array`           | —  | タグ（作るときと同じ）。送ると全部が置き換わります                                                                                                                                                                        |
| `status`                     | `string`          | —  | "active" / "paused" / "archived"                                                                                                                                                                 |
| `isShared`                   | `boolean`         | —  | 公開するかどうか                                                                                                                                                                                         |
| `limits`                     | `object`          | —  | 実行の上限。送った項目だけを今の値に重ねます                                                                                                                                                                           |
| `limits.maxRetriesPerStep`   | `integer`         | —  | 0〜10                                                                                                                                                                                             |
| `limits.maxSendBacksPerStep` | `integer`         | —  | 1〜10                                                                                                                                                                                             |
| `limits.runDeadlineHours`    | `integer \| null` | —  | 1〜2160。null は締め切りを付けない                                                                                                                                                                           |
| `limits.stallHours`          | `integer`         | —  | 1〜720                                                                                                                                                                                            |
| `limits.maxMinutesPerRun`    | `integer \| null` | —  | 1 回の実行の長さの上限（分）。5・15・30・60・90・120 のどれか。null は上限を付けない                                                                                                                                             |
| `organizationCode`           | `string \| null`  | —  | 組織のコード（255 文字まで）。組織をまだ付けていないプロジェクトに 1 回だけ付けられます。今の値と同じ値は何も変えません（取得の値をそのまま送り返せます）。組織が付いているプロジェクトに違う値を送ると 409（organization\_locked）です。null は、組織がまだ付いていなければ何も変えず、付いていれば 409（organization\_locked）です |

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

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

<!-- -->

#### レスポンス（200 OK）

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

#### エラーレスポンス

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

### DELETE`/v1/projects/{projectId}`

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

#### パスパラメータ

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

#### レスポンス（200 OK）

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

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

#### エラーレスポンス

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

### GET`/v1/projects/{projectId}/control`

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

#### パスパラメータ

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

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

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

#### エラーレスポンス

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

## 工程

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

### エンドポイント一覧

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

### 工程の項目

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

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

確認工程の設定（`gateConfig`）:

| フィールド              | 型                | 説明                                                                                                                                                                                                                |
| ------------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `approverUserIds`  | `array`          | 確認担当者の利用者 ID の配列（プロジェクトのメンバーから 20 人まで）                                                                                                                                                                            |
| `deadlineHours`    | `number \| null` | 確認期限（時間。1〜720）                                                                                                                                                                                                    |
| `mode`             | `string \| null` | 確認方法。送れるのは "blocking"（担当者の判断を待つ）だけです（"notify\_only" は 400 structure\_not\_for\_marketplace）。前の版で保存した "notify\_only" が返ることがありますが、ワークフローの実行では値によらず担当者の判断を待ちます                                                       |
| `overdueAction`    | `string \| null` | 期限を過ぎたとき。送れるのは "none"（期限を過ぎても自動では決まらず、通知して待ち続けます）か null（"none" として動きます）です（"proceed"・"send\_back"・"reject" は 400 structure\_not\_for\_marketplace）。前の版で保存した値が返ることがありますが、ワークフローの実行では値によらず、期限を過ぎても自動では決まらず通知して待ち続けます |
| `escalateToUserId` | `string \| null` | 期限超過時の連絡先の利用者 ID（プロジェクトのメンバー）                                                                                                                                                                                     |
| `destinations`     | `array`          | いつも含まれません（マーケットプレイス版では、進め先を設定できません）                                                                                                                                                                               |

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

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

| 工程の項目                                                 | workflow | cycle                          |
| ----------------------------------------------------- | -------- | ------------------------------ |
| 確認工程（defaultZone の "gate"）と、その設定（gateConfig・gateKind） | 付けられる    | 400（cycle\_gate\_not\_allowed） |
| onDenied・onDegraded の "gate"                          | 付けられる    | 400（cycle\_gate\_not\_allowed） |
| schedule（工程の時刻）                                       | 付けられる    | 400（invalid\_parameter）        |
| reworkToStepId（差し戻し先）                                 | 付けられる    | 400（invalid\_parameter）        |

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

### POST`/v1/projects/{projectId}/steps`

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

#### パスパラメータ

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

#### リクエストボディ

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

<!-- -->

#### レスポンス（201 Created）

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

#### エラーレスポンス

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

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

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

#### パスパラメータ

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

#### リクエストボディ

| フィールド            | 型                | 必須 | 説明                                                                                                                                                                                               |
| ---------------- | ---------------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `baseDigest`     | `string`         | 必須 | その工程の digest                                                                                                                                                                                     |
| `name`           | `string \| null` | —  | 工程の名前（100 文字まで）。空の文字列・null で既定の名前に戻します。空白だけにはできません                                                                                                                                               |
| `description`    | `string`         | —  | 説明（2000 文字まで。空の文字列・空白だけ・null にはできません）                                                                                                                                                            |
| `defaultZone`    | `string`         | —  | "ai" または "gate"                                                                                                                                                                                  |
| `enabled`        | `boolean`        | —  | 有効かどうか                                                                                                                                                                                           |
| `gateConfig`     | `object \| null` | —  | 確認工程の設定。送った項目だけを今の値に重ねます。null で設定を外します。前の版で "notify\_only" や期限後の自動処理を保存した工程では、ほかの項目だけを送っても 400（structure\_not\_for\_marketplace）になります。そのときは mode に "blocking"、overdueAction に "none" を一緒に送ってください |
| `gateKind`       | `string \| null` | —  | "review" または "manual"                                                                                                                                                                            |
| `reworkToStepId` | `string \| null` | —  | 差し戻し先（この工程より前の工程）。null で外します                                                                                                                                                                     |
| `onDenied`       | `string \| null` | —  | "gate" / "closed\_failed"                                                                                                                                                                        |
| `onDegraded`     | `string \| null` | —  | "gate" / "proceed"                                                                                                                                                                               |
| `schedule`       | `object \| null` | —  | 工程の時刻（workflow だけ）。expression（5 項目の cron 式）と timezone（省くと UTC）。null で外します                                                                                                                        |

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

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

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

#### レスポンス（200 OK）

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

#### エラーレスポンス

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

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

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

#### パスパラメータ

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

#### リクエストボディ

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

#### レスポンス（200 OK）

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

#### エラーレスポンス

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

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

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

#### パスパラメータ

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

#### レスポンス（200 OK）

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

#### エラーレスポンス

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

## 配置

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

### エンドポイント一覧

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

### 配置の項目

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

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

### GET`/v1/projects/{projectId}/placements`

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

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

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

#### エラーレスポンス

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

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

配置を 1 件取得します。

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

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

#### エラーレスポンス

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

### GET`/v1/projects/agent-candidates`

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

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

#### クエリパラメータ

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

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

| フィールド                               | 型                 | 説明                                      |
| ----------------------------------- | ----------------- | --------------------------------------- |
| `candidates`                        | `array`           | 置ける登録 Agent の配列                         |
| `candidates[].marketplaceAgentId`   | `string \| null`  | 登録 Agent の ID。配置を置く API に指定します          |
| `candidates[].displayName`          | `string \| null`  | 表示名                                     |
| `candidates[].description`          | `string \| null`  | 説明                                      |
| `candidates[].iconUrl`              | `string \| null`  | アイコンの URL                               |
| `candidates[].tags`                 | `array`           | タグの配列                                   |
| `candidates[].certified`            | `boolean \| null` | ワークフローで使うための認定があるかどうか（"workflow" のときだけ） |
| `candidates[].certificationProblem` | `string \| null`  | 認定が無い理由のコード。認定があるときと、"cycle" のときは null  |

#### エラーレスポンス

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

### POST`/v1/projects/{projectId}/placements`

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

#### リクエストボディ

| フィールド                | 型        | 必須 | 説明                                                                     |
| -------------------- | -------- | -- | ---------------------------------------------------------------------- |
| `marketplaceAgentId` | `string` | 必須 | 置く登録 Agent の ID（置ける Agent の候補の marketplaceAgentId。1〜100 文字。前後の空白は除きます） |
| `stepIds`            | `array`  | —  | 担当工程の ID の配列（このプロジェクトの工程を 12 個まで）。省くと担当工程なしで置きます                       |

- 同じ Agent がすでに置いてあるときは `409 Conflict`（`placement_already_exists`）です。担当工程まで同じときは、送り直しとして、置いてある配置を返します。担当工程を変えるときは、配置の担当工程を変える API を使います。
- `agentId` は送れません（送ると `400 Bad Request`（`invalid_parameter`））。
  <!-- -->
- 新しく置いた配置は、配置の並び（`displayOrder`）の最後に入ります。ただし、前に外した配置（過去のワークフローの実行が使っていたため残っている配置）と同じ Agent を置くと、その配置が元の ID と並びの位置で戻ります。同じ工程の配置を 1 つずつ実行するときは、この並びの順に動きます。配置を並べ替える API はありません。

#### レスポンス（201 Created）

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

#### エラーレスポンス

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

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

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

#### レスポンス（200 OK）

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

#### エラーレスポンス

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

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

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

#### リクエストボディ

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

#### レスポンス（200 OK）

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

#### エラーレスポンス

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

<!-- -->

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

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

#### リクエストボディ

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

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

#### レスポンス（200 OK）

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

#### エラーレスポンス

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

## トリガー

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

### エンドポイント一覧

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

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

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

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

#### パスパラメータ

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

#### リクエストボディ

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

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

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

#### レスポンス例

```json
{
  "result": "accepted",
  "jobId": "9b2e4c61-0f3a-4a9b-9c1d-2f7e5a8b3c40"
}
```

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

#### 再送

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

#### エラーレスポンス

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

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

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

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

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

### エンドポイント一覧

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

### POST`/v1/projects/{projectId}/runs`

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

#### リクエストヘッダー

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

#### パスパラメータ

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

#### リクエストボディ

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

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

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

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

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

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

#### リクエスト例

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

#### レスポンス例

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

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

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

#### エラーレスポンス

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

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

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

#### パスパラメータ

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

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

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

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

##### 実行を始めたもの

| 始めたもの            | startedByRef                     | actorLabel                  |
| ---------------- | -------------------------------- | --------------------------- |
| 利用者（画面・API から開始） | 利用者 ID                           | null                        |
| サービスアカウント        | "client:" に続くサービスアカウントのクライアント ID | サービスアカウントの名前（分からない場合は null） |
| 定期実行             | null                             | null                        |

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

#### レスポンス例

<!-- -->

<!-- -->

```json
{
  "runId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "running",
  "originType": "api",
  "originRef": "nightly-batch-20260917",
  "currentStepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
  "startedByRef": "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                | 説明                                    |
| ----- | ------------------- | ------------------------------------- |
| `400` | `invalid_parameter` | projectId または runId が UUID の形式ではない    |
| `404` | `run_not_found`     | 実行が存在しない、別のプロジェクトの実行を指定した、またはアクセス権が無い |

### GET`/v1/projects/{projectId}/runs`

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

#### クエリパラメータ

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

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

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

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

#### エラーレスポンス

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

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

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

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

| フィールド           | 型                | 説明                                                                                                                                                                                                                                                                                                        |
| --------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `runId`         | `string`         | ワークフローの実行の ID                                                                                                                                                                                                                                                                                             |
| `takenAt`       | `string \| null` | 設定を写した日時（ISO 8601）                                                                                                                                                                                                                                                                                        |
| `steps`         | `array \| null`  | 当時の工程。項目は「工程の項目」と同じです（digest を除きます。写しに無い項目は null）                                                                                                                                                                                                                                                         |
| `lanes`         | `array \| null`  | "main" の 1 本に全部の工程が入ります（name は null）                                                                                                                                                                                                                                                                      |
| `forks`         | `array \| null`  | いつも空の配列                                                                                                                                                                                                                                                                                                   |
| `joins`         | `array \| null`  | いつも空の配列                                                                                                                                                                                                                                                                                                   |
| `placements`    | `array \| 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 はいつも空の配列 |
| `connectors`    | `array \| null`  | 当時の連携先（kind・connectionId・name・ledgerEnabled）。name は始めたときの名前。connectionId は今の連携先の情報から求めます（管理画面で無効にされた・削除された、または確かめられなかったときは null）                                                                                                                                                                          |
| `sendBackLimit` | `number \| null` | 差し戻せる回数の上限                                                                                                                                                                                                                                                                                                |

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

#### エラーレスポンス

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

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

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

#### パスパラメータ

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

#### リクエストボディ

| フィールド        | 型                | 必須 | 説明                                      |
| ------------ | ---------------- | -- | --------------------------------------- |
| `deadlineAt` | `string \| null` | 必須 | 締め切り（ISO 8601 の日時。今より後）。null で締め切りを外します |

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

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

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

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

#### エラーレスポンス

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

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

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

#### パスパラメータ

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

#### リクエストボディ

| フィールド             | 型        | 必須 | 説明                                                                   |
| ----------------- | -------- | -- | -------------------------------------------------------------------- |
| `approverUserIds` | `array`  | 必須 | 新しい確認担当者の利用者 ID の配列（1〜50 人。今のプロジェクトのメンバーだけ。1 つは 128 文字まで。同じ人は 1 度だけ） |
| `commandId`       | `string` | 必須 | 送り直しを見分ける値（英数字と \_ . : - の 8〜128 文字）                                 |

- 同じ `commandId` で同じ確認担当者を送り直すと、1 回目と同じ結果が返ります。同じ `commandId` で違う確認担当者を送ると `409 Conflict`（`command_conflict`）です。
- 確認担当者か対象の確認依頼がとても多い付け替え（例: 確認担当者 50 人）では、同じ `commandId` で送り直したときに確認担当者を比べられず、1 回目の結果として 200 が返り、`workItemIds` が空になることがあります。結果は、ワークフローの実行の取得と確認依頼の取得で確かめてください。

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

| フィールド             | 型        | 説明                        |
| ----------------- | -------- | ------------------------- |
| `runId`           | `string` | ワークフローの実行の ID             |
| `approverUserIds` | `array`  | 置き換えた後の確認担当者の利用者 ID（送った値） |
| `workItemIds`     | `array`  | 確認担当者を置き換えた確認依頼の ID       |

#### エラーレスポンス

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

### GET`/v1/projects/{projectId}/artifacts`

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

#### パスパラメータ

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

#### クエリパラメータ

| パラメータ    | 型        | デフォルト | 説明                     |
| -------- | -------- | ----- | ---------------------- |
| `run_id` | `string` | `—`   | 必須。ワークフローの実行の ID（UUID） |

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

| フィールド                    | 型                | 説明                                     |
| ------------------------ | ---------------- | -------------------------------------- |
| `artifacts`              | `array`          | 成果物の配列                                 |
| `artifacts[].artifactId` | `string \| null` | 成果物の ID（UUID）                          |
| `artifacts[].runId`      | `string \| null` | ワークフローの実行の ID                          |
| `artifacts[].name`       | `string \| null` | 成果物の名前                                 |
| `artifacts[].mimeType`   | `string \| null` | 成果物の MIME タイプ                          |
| `artifacts[].size`       | `number \| null` | 大きさ（バイト）                               |
| `artifacts[].status`     | `string \| null` | "ready"（読める）または "uploading"（書き終わっていない） |
| `artifacts[].createdAt`  | `string \| null` | 作られた日時（ISO 8601）                       |

#### エラーレスポンス

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

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

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

#### パスパラメータ

| パラメータ        | 型        | 必須 | 説明                               |
| ------------ | -------- | -- | -------------------------------- |
| `projectId`  | `string` | 必須 | プロジェクト ID（UUID）                  |
| `artifactId` | `string` | 必須 | 成果物の ID（UUID）。成果物の一覧の artifactId |

#### レスポンス（200 OK）

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

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

#### エラーレスポンス

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

## 実行

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

### エンドポイント一覧

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

### 結果の値

`outcome`（結果）の値です。画面の表示は[結果リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/project/reference/results-ref.md)を参照してください。

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

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

<!-- -->

### GET`/v1/projects/{projectId}/executions`

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

#### クエリパラメータ

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

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

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

#### エラーレスポンス

| ステータス | code                | 説明                                                                                                                                                                                                          |
| ----- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | `invalid_parameter` | projectId・placement\_id・step\_id・run\_id が UUID の形式ではない、snake\_case と前の名前に違う値を指定した、from・to が ISO 8601 の日時ではない、outcome・fix\_target が上の値ではない、reason\_code が理由の形ではない・2 回以上指定した、q が 200 文字を超える、limit・cursor が不正 |
| `403` | `forbidden`         | システム連携のトークンで呼び出した                                                                                                                                                                                           |
| `403` | `sso_required`      | 認証サーバーのアカウントと結び付いていない利用者                                                                                                                                                                                    |
| `404` | `project_not_found` | プロジェクトが存在しない、またはメンバーではない                                                                                                                                                                                    |

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

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

#### パスパラメータ

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

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

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

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

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

#### エラーレスポンス

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

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

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

#### クエリパラメータ

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

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

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

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

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

#### エラーレスポンス

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

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

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

#### クエリパラメータ

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

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

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

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

#### エラーレスポンス

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

<!-- -->

## ファイル

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

### エンドポイント一覧

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

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

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

#### パスパラメータ

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

#### クエリパラメータ

| パラメータ        | 型        | デフォルト | 説明                                                                       |
| ------------ | -------- | ----- | ------------------------------------------------------------------------ |
| `path`       | `string` | `—`   | 必須。ファイルのパス（実行の結果の files\[].filepath、または確認依頼の evidence.files\[].filepath） |
| `version_id` | `string` | `—`   | バージョンの ID。省くと今のバージョン                                                     |

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

#### レスポンス（200 OK）

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

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

#### エラーレスポンス

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

保存先の失敗（500・502・503）は、[成果物取得](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/user-api-reference.md#artifacts)（`GET /v1/files/proxy`）と同じです。

## 記録 (証跡)

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

### エンドポイント一覧

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

### GET`/v1/projects/{projectId}/audit`

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

#### クエリパラメータ

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

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

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

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

#### エラーレスポンス

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

## KPI

画面の概要の「KPI」と同じ値を取得します。数え方は[結果リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/project/reference/results-ref.md)を参照してください。

### エンドポイント一覧

| メソッド | エンドポイント                        | 説明      |
| ---- | ------------------------------ | ------- |
| GET  | `/v1/projects/{projectId}/kpi` | KPI を取得 |

### GET`/v1/projects/{projectId}/kpi`

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

#### クエリパラメータ

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

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

| フィールド                | 型                | 説明                                                                                               |
| -------------------- | ---------------- | ------------------------------------------------------------------------------------------------ |
| `days`               | `number`         | 期間（日）                                                                                            |
| `successRate`        | `number \| null` | Agentの完遂率（0〜1。正常完了 ÷ 終了）。終了が 0 件なら null                                                          |
| `successRateStatus`  | `string`         | "ok"（確定）/ "incomplete"（記録不足があり暫定値）/ "none"（記録不足が無く、終了が 0 件）                                      |
| `succeeded`          | `number`         | 正常完了の数                                                                                           |
| `denominator`        | `number`         | 終了の数（正常完了と「失敗・要対応」の合計。変化なしで終わった実行は入れません）                                                         |
| `executions`         | `number`         | 終わった実行の数（denominator と noChange の合計）                                                             |
| `noChange`           | `number`         | 変化なしで終わった実行の数（結果は completed で、理由が "no\_change"）。終了・正常完了には入れません                                   |
| `outcomes`           | `object`         | 結果ごとの数（completed・incomplete・failed・timeout・stopped・denied・skipped）。completed には、変化なしで終わった実行も入ります |
| `excluded`           | `object`         | 集計外の数（skipped・running・missing・unmeasured・connectionConfirm）。connectionConfirm はいつも 0             |
| `durationP95Minutes` | `number \| null` | 処理時間の目安（p95。分）                                                                                   |
| `runs`               | `object`         | ワークフローの実行の数（total・closedDone・closedFailed・closedRejected・cancelled）と p95Minutes                  |
| `gates`              | `array`          | 確認工程ごとの実績（stepId・position・name・mode・total・approvalRate・sendBackRate）                             |
| `human`              | `object`         | 確認対応の状況（reviewsPerRun・gateWaitMedianMinutes・interventions）                                       |

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

#### エラーレスポンス

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

<!-- -->

## 確認依頼

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

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

### エンドポイント一覧

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

### GET`/v1/workitems`

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

#### クエリパラメータ

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

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

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

#### エラーレスポンス

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

### GET`/v1/workitems/{workItemId}`

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

#### パスパラメータ

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

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

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

確認の材料（`workitem.evidence`）:

| フィールド              | 型                | 説明                                                                                                                        |
| ------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `summary`          | `string \| null` | 確認の材料の文。ふつうは確認する工程の Agent の出力で、Agent の工程の結果によって確認を求めたときは、結果とその理由の要約                                                       |
| `conversationId`   | `string \| null` | 確認する工程の実行の会話の ID                                                                                                          |
| `files`            | `array`          | 確認する工程のファイル（会話 API の deliverables と同じ形。中身はファイルの中身の取得（GET /v1/projects/{projectId}/files/content）に filepath を path で渡して取る） |
| `gateKind`         | `string \| null` | 確認の種類。"review"（確認）/ "manual"（手作業）                                                                                         |
| `stepName`         | `string \| null` | 確認を求めた工程の名前                                                                                                               |
| `outcome`          | `string \| null` | 確認する工程の実行の結果（実行の「結果の値」）                                                                                                   |
| `executionId`      | `string \| null` | 確認する工程の実行の ID（実行の結果を取得する API で読めます）                                                                                       |
| `reasonCode`       | `string \| null` | 結果の理由（Agent の工程の結果によって確認を求めたとき）                                                                                           |
| `escalateToUserId` | `string \| null` | 期限超過時の連絡先の利用者 ID（確認依頼ができたときにメンバーだった人）                                                                                     |
| `destinations`     | `array`          | いつも空の配列（マーケットプレイス版では、進め先を設定できません）                                                                                         |
| `connector`        | `object \| null` | いつも null                                                                                                                  |
| `service`          | `string \| null` | いつも null                                                                                                                  |
| `mode`             | `string \| null` | いつも null                                                                                                                  |
| `tool`             | `string \| null` | いつも null                                                                                                                  |
| `waitMinutes`      | `number \| null` | いつも null                                                                                                                  |

判断に使う情報（`gate`）:

| フィールド                   | 型                | 説明                                                                               |
| ----------------------- | ---------------- | -------------------------------------------------------------------------------- |
| `contextVersion`        | `number`         | 確認依頼のバージョン（1 以上）。バージョン付きの確認（ワークフローの確認）のときだけ含まれます。判断の contextVersion にそのまま送ります    |
| `basisDigest`           | `string \| null` | 確認の材料の digest（64 文字の 16 進）。contextVersion と同じときだけ含まれます。判断の basisDigest にそのまま送ります |
| `projectName`           | `string \| null` | プロジェクト名                                                                          |
| `projectType`           | `string \| null` | プロジェクトの型                                                                         |
| `stepId`                | `string \| null` | 確認を求めた工程の ID                                                                     |
| `stepName`              | `string \| null` | 確認を求めた工程の名前                                                                      |
| `stepPosition`          | `number \| null` | 確認を求めた工程の位置                                                                      |
| `nextStep`              | `object \| null` | 進めたときの次の工程（stepId・name・position）。次の工程が無ければ null                                  |
| `sendBackDefaultStepId` | `string \| null` | 差し戻し先を指定しないときの戻り先の工程の ID                                                         |
| `sendBackCandidates`    | `array`          | 差し戻し先に指定できる工程（stepId・name・position・sendBacks）。sendBacks はその工程へ差し戻した回数            |
| `sendBackLimit`         | `number \| null` | 1 つの工程へ差し戻せる回数の上限                                                                |
| `destinations`          | `array`          | いつも空の配列（マーケットプレイス版では、進め先を設定できません）                                                |
| `lane`                  | `object \| null` | 確認を求めた工程のレーン（laneId・name・position）。レーンが無ければ null                                 |

#### エラーレスポンス

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

### POST`/v1/workitems/{workItemId}/decision`

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

#### リクエストボディ

| フィールド              | 型         | 必須 | 説明                                                                                              |
| ------------------ | --------- | -- | ----------------------------------------------------------------------------------------------- |
| `decision`         | `string`  | 必須 | "proceed"（進める）/ "send\_back"（差し戻す）/ "reject"（却下する）                                              |
| `reason`           | `string`  | —  | 理由（10000 文字まで）。"send\_back"・"reject" のときは必須                                                     |
| `sendBackToStepId` | `string`  | —  | 差し戻し先の工程の ID（"send\_back" のとき。gate の sendBackCandidates の工程）。省くと sendBackDefaultStepId の工程に戻します |
| `commandId`        | `string`  | —  | 送り直しを見分ける値（128 文字まで）                                                                            |
| `contextVersion`   | `integer` | —  | 判断する前に読んだ確認依頼の gate.contextVersion（1 以上の整数）。gate に含まれるときは必須                                     |
| `basisDigest`      | `string`  | —  | 判断する前に読んだ確認依頼の gate.basisDigest（64 文字の小文字の 16 進）。gate に含まれるときは必須                                |

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

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

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

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

#### エラーレスポンス

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

### PATCH`/v1/workitems/{workItemId}`

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

#### パスパラメータ

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

#### リクエストボディ

| フィールド       | 型        | 必須 | 説明                       |
| ----------- | -------- | -- | ------------------------ |
| `expiresAt` | `string` | 必須 | 新しい期限（ISO 8601 の日時。今より後） |

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

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

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

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

#### エラーレスポンス

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

## キュー

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

- プロジェクトのキュー（`GET /v1/projects/{projectId}/queue`）は、そのプロジェクトの全部の行を返します。プロジェクトのメンバーなら読めます。
- 自分のキュー（`GET /v1/queue`）は、参加しているプロジェクトのうち、自分が担当の行を返します。
- 行への操作は、次の API に行の ID を渡して行います。

| すること                  | API                                                   | 使う ID        |
| --------------------- | ----------------------------------------------------- | ------------ |
| 確認依頼を進める・差し戻す・却下する    | `POST /v1/workitems/{workItemId}/decision`            | `workItemId` |
| 確認依頼の期限を延ばす           | `PATCH /v1/workitems/{workItemId}`                    | `workItemId` |
| ワークフローの実行の締め切りを変える    | `PATCH /v1/projects/{projectId}/runs/{runId}`         | `runId`      |
| ワークフローの実行の確認担当者を付け替える | `PUT /v1/projects/{projectId}/runs/{runId}/approvers` | `runId`      |

### エンドポイント一覧

| メソッド | エンドポイント                          | 説明            |
| ---- | -------------------------------- | ------------- |
| 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 の順で、変えられません。カーソルベースのページネーションに対応しています。

#### パスパラメータ

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

#### クエリパラメータ

| パラメータ    | 型         | デフォルト | 説明                             |
| -------- | --------- | ----- | ------------------------------ |
| `kind`   | `string`  | `—`   | 行の種類で絞り込み（上の「行の種類」の値）          |
| `limit`  | `integer` | `50`  | 1 ページの取得件数（1-100）              |
| `cursor` | `string`  | `—`   | 次ページ取得用カーソル（前回レスポンスの cursor 値） |

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

| フィールド                               | 型                 | 説明                                                                                                                                              |
| ----------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `queueItems`                        | `array`           | キューの行の配列                                                                                                                                        |
| `queueItems[].queueItemId`          | `string`          | 行の ID（<種類>:\<ID> の形）                                                                                                                            |
| `queueItems[].kind`                 | `string`          | 行の種類（上の「行の種類」）                                                                                                                                  |
| `queueItems[].priority`             | `number \| null`  | 優先度（1〜4。1 が高い）                                                                                                                                  |
| `queueItems[].projectId`            | `string \| null`  | プロジェクトの ID                                                                                                                                      |
| `queueItems[].projectName`          | `string \| null`  | プロジェクトの名前                                                                                                                                       |
| `queueItems[].workItemId`           | `string \| null`  | 確認依頼の ID。確認依頼の行（gate\_overdue・external\_wait\_blocked・gate\_pending）だけで、それ以外は null。確認依頼の API でそのまま使えます                                          |
| `queueItems[].runId`                | `string \| null`  | ワークフローの実行の ID。無ければ null                                                                                                                         |
| `queueItems[].stepId`               | `string \| null`  | 工程の ID。無ければ null                                                                                                                                |
| `queueItems[].placementId`          | `string \| null`  | 配置の ID。無ければ null                                                                                                                                |
| `queueItems[].executionId`          | `string \| null`  | 実行の ID。実行の結果の取得でそのまま使えます。失敗した工程（execution\_failed）は rs:<数値>、失敗した巡回（sweep\_failed）は巡回の実行の UUID、確認依頼の行は確認の材料（evidence.executionId）と同じ値。それ以外は null |
| `queueItems[].stepName`             | `string \| null`  | 工程の名前                                                                                                                                           |
| `queueItems[].agentName`            | `string \| null`  | Agent の名前                                                                                                                                       |
| `queueItems[].title`                | `string \| null`  | 確認依頼の題。確認依頼の行だけで、それ以外は null                                                                                                                     |
| `queueItems[].dueAt`                | `string \| null`  | 期限（ISO 8601）。確認依頼の期限か、ワークフローの実行の締め切り。それ以外は null                                                                                                 |
| `queueItems[].elapsedFrom`          | `string \| null`  | 経過を数える起点（ISO 8601）。確認依頼の行は、確認依頼ができた日時                                                                                                           |
| `queueItems[].assigneeUserIds`      | `array`           | 担当者の利用者 ID。確認依頼の行はその確認担当者、差し戻し待ちは差し戻した確認の確認担当者（どちらも今もメンバーの人）。失敗した工程・失敗した巡回・締め切りの超過・停滞は、プロジェクトのオーナー                                              |
| `queueItems[].escalateToUserId`     | `string \| null`  | 期限超過時の連絡先の利用者 ID。確認依頼の行だけで、それ以外は null                                                                                                           |
| `queueItems[].cause`                | `object \| null`  | 失敗から来た行の、結果（outcome）と理由（reasonCode）。それ以外は null                                                                                                  |
| `queueItems[].gateKind`             | `string \| null`  | 確認の種類（確認の材料の gateKind と同じ値）                                                                                                                     |
| `queueItems[].observationErrorCode` | `string \| null`  | 外部の待ちの観測が失敗した理由                                                                                                                                 |
| `queueItems[].sendBackLimitReached` | `boolean \| null` | 差し戻せる回数の上限に達したかどうか                                                                                                                              |
| `hasMore`                           | `boolean`         | 次のページが存在するかどうか                                                                                                                                  |
| `cursor`                            | `string`          | 次ページ取得用カーソル。hasMore が true の場合のみ含まれます                                                                                                           |

#### エラーレスポンス

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

### GET`/v1/queue`

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

#### エラーレスポンス

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

## 連携先

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

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

### エンドポイント一覧

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

### GET`/v1/connectors/mcp/{connectionId}`

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

#### パスパラメータ

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

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

| フィールド                         | 型                 | 説明                                                                       |
| ----------------------------- | ----------------- | ------------------------------------------------------------------------ |
| `kind`                        | `string`          | "mcp"                                                                    |
| `connectionId`                | `string`          | 連携先の ID                                                                  |
| `name`                        | `string \| null`  | 連携先の名前                                                                   |
| `requiresLogin`               | `boolean`         | プロジェクトの画面でログインしてから使う連携先かどうか                                              |
| `tools`                       | `array`           | ツールの配列                                                                   |
| `tools[].name`                | `string \| null`  | ツールの名前                                                                   |
| `tools[].displayName`         | `string \| null`  | 表示名                                                                      |
| `tools[].description`         | `string \| null`  | 説明                                                                       |
| `tools[].inputSchema`         | `object \| null`  | ツールの入力のスキーマ（MCP サーバーが申告した形のまま）。管理画面でツールの一覧を取り直すまでは null                  |
| `tools[].outputSchema`        | `object \| null`  | ツールの出力のスキーマ（MCP サーバーが申告した形のまま）。申告が無ければ null                              |
| `tools[].declaredAnnotations` | `object \| null`  | ツールの注釈（readOnlyHint など。MCP サーバーの自己申告のまま）。本製品はこの申告を確かめておらず、実行の制御にも使っていません |
| `tools[].presentInLastFetch`  | `boolean \| null` | 最後に取得したときにもあったかどうか（false は、MCP サーバーから無くなったツール）                           |
| `toolsFetchedAt`              | `string \| null`  | ツールの一覧を最後に取得した日時（ISO 8601）。ツールが 0 件の取得でも、取得した日時が入ります。一度も取得していなければ null   |

#### エラーレスポンス

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

### GET`/v1/connectors/a2a/{connectionId}`

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

#### パスパラメータ

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

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

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

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

#### エラーレスポンス

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

## 実行の会話

実行の中で Agent とやりとりした会話（Agent への依頼の文、途中の説明、最終応答など）は、会話 API の `GET /v1/conversations/{conversationId}/messages`で読みます。詳しくは[ユーザー API リファレンス（会話・組織）の会話管理](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/user-api-reference.md#conversations)を参照してください。

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

## エラーレスポンス

### HTTP ステータスコード

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

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

### エラーレスポンス形式

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

| フィールド                    | 型        | 説明                                                                                                                                                                                                                                       |
| ------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `error.type`             | `string` | エラーの分類。"invalid\_request\_error"、"authentication\_error"、"insufficient\_scope\_error"、"forbidden\_error"、"not\_found\_error"、"conflict\_error"、"payload\_too\_large\_error"、"rate\_limit\_error"、"server\_error"、"upstream\_error" のいずれか |
| `error.message`          | `string` | 人間が読めるエラーメッセージ                                                                                                                                                                                                                           |
| `error.code`             | `string` | 機械的に処理可能なエラーコード（例: "missing\_parameter"、"invalid\_parameter"、"invalid\_token"）                                                                                                                                                           |
| `error.param`            | `string` | エラーの原因となったパラメータ名。バリデーションエラー時のみ含まれます                                                                                                                                                                                                      |
| `error.suggested_action` | `string` | 推奨される対処方法。一部のエラーでのみ含まれます                                                                                                                                                                                                                 |

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