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

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

| 操作                                 | オーナー | 運用担当 | メンバー                            | 組織の運用の役割 ※1 | 呼べない人への断り                                                                         |
| ---------------------------------- | ---- | ---- | ------------------------------- | ----------- | --------------------------------------------------------------------------------- |
| プロジェクトとその中のもの（工程・配置・実行など）を読む       | ○    | ○    | ○                               | 一部 ※2       | —                                                                                 |
| ワークフローの実行の開始・トリガーの発火・入力ファイルの下書きの上げ | ○    | ○    | ○                               | ○           | —                                                                                 |
| ほかの運転の操作 ※3                        | ○    | ○    | ×（ワークフローの実行の中断は、その実行を始めた本人なら ○） | ○           | `403 Forbidden`（`operator_only`）                                                  |
| Webhook の API（一覧と配送の結果を含む）         | ○    | ×    | ×                               | ×           | `403 Forbidden`（`owner_only`）。参加していない組織の運用の役割の人は `409 Conflict`（`forbidden_role`） |
| ほかの書き込む API（プロジェクトを作る API を除く）     | ○    | ×    | ×                               | ×           | `403 Forbidden`（`owner_only`）。参加していない組織の運用の役割の人は `409 Conflict`（`forbidden_role`） |

- ※1 プロジェクトの所属組織で、組織の運用の役割（管理コンソールの「管理の役割」で付ける「運用」の役割）を持つ人です。プロジェクトに参加していなくても、表で ○ の操作を呼べます。参加している人がこの役割も持つときは、参加の役割に加えて運転の操作を呼べます。
- ※2 参加していない組織の運用の役割の人には、
  <!-- -->
  成果物の一覧と中身の取得
  <!-- -->
  、定義の承認待ちの取得は `409 Conflict`（`forbidden_role`）、プロジェクトのファイルの中身は `400 Bad Request`（`file_not_found`）です。ワークフローの実行と実行の、Agent の文とファイルの項目は null か空で返ります。
- ※3
  <!-- -->
  ワークフローの実行の締め切り・確認担当者の付け替え・ワークフローの実行の中断・サイクルの巡回の実行の停止・プロジェクトの一時停止と再開
  <!-- -->
  です。
- 確認依頼・キュー・連携先の API の呼べる人は、それぞれの節に書いています。

| 場面                                                           | 返るもの                                                                                                                                                                                                                                                                |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| メンバーでも、プロジェクトの所属組織で組織の運用の役割を持つ人でもないプロジェクトと、存在しないプロジェクト       | どちらも `404 Not Found` で、応答から区別できません。ただし、公開されているプロジェクトは、メンバーでなくてもプロジェクトの取得（`GET /v1/projects/{projectId}`）で構造だけを読めます                                                                                                                                                  |
| `404 Not Found` の code                                       | エンドポイントごとに 1 つで、パスの最後の資源の名前です（例: 配置の API は `placement_not_found`、実行の API は `execution_not_found`）。パスに資源の ID が無いエンドポイントは `project_not_found` です。配置の下の工程の設定を書き込む API（`runtime-config`）は、パスの最後が工程の ID でも `placement_not_found` です。プロジェクトが見えないときも、そのエンドポイントの code で返ります |
| ボディで指定した ID（登録 Agent・工程・利用者など）が存在しない・見えない                    | エンドポイントごとに違います（例: 配置の `marketplaceAgentId` は `400 Bad Request`（`agent_not_found`）、配置の `stepIds` は `400 Bad Request`（`invalid_parameter`））。各エンドポイントの説明とエラーレスポンスを参照してください                                                                                             |
| 一覧を絞り込むクエリ（`placement_id`・`step_id`・`run_id`）に存在しない ID を指定した | 空の一覧が返ります                                                                                                                                                                                                                                                           |
| 本体の利用者の記録が認証サーバーのアカウントと結び付いていない利用者のトークン                      | プロジェクト・確認依頼・キューの API で `403 Forbidden`（`sso_required`）が返ります（プロジェクト一覧の取得・ワークフローの実行の開始・トリガーの発火・ワークフローの実行の取得を除きます）。メイン画面に一度ログインすると結び付きます                                                                                                                               |

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

### リクエストの扱い

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

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

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

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

<!-- -->

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

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

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

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

| API                                                      | 送り直しを見分けるもの                | 同じもので送り直すと                                     |
| -------------------------------------------------------- | -------------------------- | ---------------------------------------------- |
| ワークフローの実行の開始                                             | `Idempotency-Key` ヘッダー（必須） | 1 回目の結果が返ります                                   |
| トリガーの発火                                                  | ボディの `eventId`             | 1 回目の結果が返ります                                   |
| 確認依頼の判断・確認担当者の付け替え・ワークフローの実行の中断・確認待ちのワークフローの実行の案件設定の置き換え | ボディの `commandId`           | 1 回目の結果が返ります（返り方は各エンドポイントの説明を参照してください）         |
| 入力ファイルを上げる                                               | `Idempotency-Key` ヘッダー（任意） | 1 回目の結果が返ります                                   |
| 登録 Agent を置く                                             | 同じ 登録 Agent と同じ担当工程        | 置いてある配置が返ります                                   |
| プロジェクトを作る・工程を作る                                          | —                          | もう 1 つ作られます。送り直す前に、プロジェクトの一覧や取得で作られたかを確かめてください |

### 人を表す項目

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

### ページネーション

| パラメータ    | 型         | 説明                                                 |
| -------- | --------- | -------------------------------------------------- |
| `limit`  | `integer` | 1ページあたりの取得件数（1-100）。デフォルトは 50 件です                  |
| `cursor` | `string`  | 次のページを取得するためのカーソル値。前回のレスポンスに含まれる cursor をそのまま指定します |

- `hasMore` が `true` のときだけ `cursor` が返ります。一覧の数（total）は返しません。
- `limit` の範囲や既定値が違う一覧、`limit` の無い一覧、全件を返す一覧と、続きを読めない一覧（`hasMore` の意味が違う一覧）は、各エンドポイントの説明に書いています。

## プロジェクト

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

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

| メソッド   | エンドポイント                                        | 説明                         |
| ------ | ---------------------------------------------- | -------------------------- |
| GET    | `/v1/projects`                                 | 自分が参加しているプロジェクトの一覧を取得      |
| GET    | `/v1/projects/shared`                          | 公開されているプロジェクトの一覧を取得        |
| GET    | `/v1/projects/organizations`                   | プロジェクトに付けられる組織を取得          |
| GET    | `/v1/projects/{projectId}`                     | プロジェクトを取得                  |
| POST   | `/v1/projects`                                 | プロジェクトを作る                  |
| PATCH  | `/v1/projects/{projectId}`                     | プロジェクトを変える                 |
| DELETE | `/v1/projects/{projectId}`                     | プロジェクトを消す                  |
| GET    | `/v1/projects/{projectId}/control`             | 統制の設定を取得                   |
| GET    | `/v1/projects/{projectId}/definition`          | プロジェクトの定義を書き出す             |
| POST   | `/v1/projects/import`                          | 書き出した定義からプロジェクトを作る（取り込み）   |
| DELETE | `/v1/projects/{projectId}/relink`              | 取り込んだ定義の、必要に応じて再度設定する項目を消す |
| GET    | `/v1/projects/{projectId}/definition-approval` | 定義の承認待ちを取得                 |
| DELETE | `/v1/projects/{projectId}/definition-approval` | 定義の承認待ちを取り消す               |

### GET`/v1/projects`

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

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

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

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

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

<!-- -->

#### リクエスト例

**List projects**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/projects",
  headers={"Authorization": f"Bearer {token}"},
  params={"limit": "20"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects" + "?limit=20",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/projects?limit=20", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

| フィールド                  | 型         | 説明                                                                         |
| ---------------------- | --------- | -------------------------------------------------------------------------- |
| `projects`             | `array`   | プロジェクトオブジェクトの配列                                                            |
| `projects[].projectId` | `string`  | プロジェクト ID（UUID）                                                            |
| `projects[].name`      | `string`  | プロジェクト名                                                                    |
| `projects[].type`      | `string`  | "workflow" または "cycle"                                                     |
| `projects[].status`    | `string`  | プロジェクトの状態。"active" / "paused" / "archived" / "admin\_stopped"（管理者が停止）のいずれか |
| `projects[].tags`      | `array`   | タグの配列。設定されていない場合は空の配列                                                      |
| `projects[].myRole`    | `string`  | 呼び手自身のそのプロジェクトでの役割。"owner"（オーナー）・"operator"（運用担当）・"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" は更新日時の新しい順 |

#### リクエスト例

**List shared projects**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/projects/shared",
  headers={"Authorization": f"Bearer {token}"},
  params={"type": "workflow", "limit": "20"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/shared" + "?type=workflow&limit=20",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/projects/shared?type=workflow&limit=20", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### レスポンスフィールド（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" / "admin\_stopped"（管理者が停止）のいずれか |
| `projects[].tags`               | `array`          | タグの配列                                                            |
| `projects[].shareScope`         | `string \| null` | 公開の範囲。"all"（全員）または "organizations"（shareOrganizations の組織の利用者だけ） |
| `projects[].shareOrganizations` | `array \| null`  | 公開先の組織のコードの配列。shareScope が "organizations" のときに使います              |
| `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` は含まれません。

#### レスポンス例

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

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

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

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

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

#### リクエスト例

**Get project organizations**

**curl**

```curl
curl https://<your-domain>/api/v1/projects/organizations \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/projects/organizations",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/organizations",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/projects/organizations", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

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

#### レスポンス例

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

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

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

<!-- -->

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

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

#### パスパラメータ

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

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

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

#### リクエスト例

**Get project**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

| フィールド                              | 型                 | 説明                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ---------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project`                          | `object`          | プロジェクト（下の表）                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `steps`                            | `array`           | 工程の配列（並び順）。1 件の項目は「工程の項目」を参照                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `stepsDigest`                      | `string`          | 工程の並びの値。工程を並べ替えるときに baseDigest に送ります                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `members`                          | `array`           | メンバーの配列                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `members[].userId`                 | `string`          | 利用者 ID                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `members[].role`                   | `string \| null`  | "owner"・"operator"・"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）                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `triggers[].digest`                | `string`          | トリガーを変えるときに baseDigest に送る値                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `stepStartFailures`                | `array`           | 先頭の工程に付けた時刻で開始する形の、開始の失敗の配列。開始できなかった工程だけが入ります。下の「開始の失敗の読み方」を参照                                                                                                                                                                                                                                                                                                                                                                                              |
| `stepStartFailures[].stepId`       | `string \| null`  | 工程の ID                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `stepStartFailures[].reason`       | `string \| null`  | 開始できなかった理由のコード                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `stepStartFailures[].since`        | `string \| null`  | その理由で開始できなくなった日時（ISO 8601）                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `notifications`                    | `object`          | 通知の設定                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `notifications.gateReached`        | `boolean \| null` | 確認依頼が届いたときに通知するかどうか                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `notifications.gateDueSoon`        | `boolean \| null` | 確認依頼の期限が近づいたときに催促を通知するかどうか（前の版の本体では 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）                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `definitionView`                   | `string \| null`  | definition=pending を付けたときだけ。"pending"（承認待ちを重ねた見え方）か "active"（承認待ちが無い）。組織の運用の役割を持ち、プロジェクトに参加していない人には null                                                                                                                                                                                                                                                                                                                                                    |
| `relink`                           | `object \| null`  | 書き出した定義から取り込んだプロジェクトで、この環境で見つからず、つなぎ直しが要る参照。無ければ null                                                                                                                                                                                                                                                                                                                                                                                                       |
| `relink.items`                     | `array`           | つなぎ直しが要る参照の配列                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `relink.items[].kind`              | `string`          | 参照の種類。"connector"（見つからない連携先）と "agent"（見つからない登録 Agent）は、つなぎ直すまで実行の開始・再開を断ります。"connection"・"playbook\_version"・"automation\_destination"・"approvers"・"branch\_target"・"external\_wait"・"trigger"・"library"・"input\_files"・"placement\_env"・"lanes"・"connection\_binding"・"input\_binding" は必要に応じて再度設定する項目で、実行は断りません。"branch\_target" は、条件分岐のレーンの工程が見つからず、レーンと条件を外したことを表します。"unavailable" は、この環境の版で使えない物と、cycle の定義の時刻のトリガー（what が "cron\_trigger"）を外したことを表します |
| `relink.items[].blocking`          | `boolean`         | true のとき、実行の開始・再開を断ります。kind が "unavailable" の行には入りません                                                                                                                                                                                                                                                                                                                                                                                                       |
| `relink.items[].*`                 | `—`               | 行の種類に応じて、手がかりの項目（agent・name・step・what・from・to・type・count・names・agents）が入ります。名前・版・数だけで、ID・URL は入りません。names は環境変数の名前だけで、値は入りません                                                                                                                                                                                                                                                                                                                               |

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

`project` の項目:

| フィールド                        | 型                 | 説明                                                                                  |
| ---------------------------- | ----------------- | ----------------------------------------------------------------------------------- |
| `projectId`                  | `string`          | プロジェクト ID（UUID）                                                                     |
| `name`                       | `string \| null`  | プロジェクト名                                                                             |
| `description`                | `string \| null`  | 説明                                                                                  |
| `tags`                       | `array`           | タグの配列                                                                               |
| `type`                       | `string \| null`  | "workflow" または "cycle"                                                              |
| `status`                     | `string \| null`  | "active"（稼働中）/ "paused"（停止中）/ "archived"（アーカイブ）/ "admin\_stopped"（管理者が停止）のいずれか      |
| `adminStop`                  | `object \| null`  | 管理者が止めているときの、停止元・理由・時刻。止めていなければ null。プロジェクトの取得だけで返ります                               |
| `adminStop.source`           | `string \| null`  | 停止元。"aster"（AGENTIC STAR の管理者）、または連携先の "agent365"・"aws"                             |
| `adminStop.reasonCode`       | `string \| null`  | 理由の種類。"admin"（管理者が止めた）・"remote\_stopped"（連携先で止められた）・"remote\_unreachable"（連携先に届かない） |
| `adminStop.reason`           | `string \| null`  | 理由の文。無ければ null                                                                      |
| `adminStop.stoppedAt`        | `string \| null`  | 止めた時刻（ISO 8601）                                                                     |
| `policy`                     | `object \| null`  | 実行ルール。画面で設定した値のまま返ります。この API では変えられません                                              |
| `limits`                     | `object \| null`  | 実行の上限                                                                               |
| `limits.maxRetriesPerStep`   | `number`          | 1 つの工程で失敗したときにやり直す回数の上限                                                             |
| `limits.maxSendBacksPerStep` | `number`          | 同じ工程へ差し戻せる回数の上限                                                                     |
| `limits.runDeadlineHours`    | `number \| null`  | ワークフローの実行の締め切りの既定（開始からの時間）。null または無ければ締め切りを付けません                                   |
| `limits.stallHours`          | `number`          | 進まないまま、この時間が過ぎると停滞とみなす時間（無ければ 24 時間）                                                |
| `language`                   | `string \| null`  | プロジェクトの言語                                                                           |
| `flowStructure`              | `object \| null`  | いつも null                                                                            |
| `reportTargets`              | `object \| null`  | 今は使っていない項目です（値が入っていても使われません）                                                        |
| `escalateToUserId`           | `string \| null`  | プロジェクトの既定の連絡先の利用者 ID（期限を過ぎた確認依頼の連絡先。このエンドポイントでは変えられません）                             |
| `organizationCode`           | `string \| null`  | 組織のコード                                                                              |
| `organizationName`           | `string \| null`  | 組織の名前                                                                               |
| `isShared`                   | `boolean \| null` | 公開しているかどうか                                                                          |
| `shareScope`                 | `string \| null`  | 公開の範囲。"all"（全員）または "organizations"（shareOrganizations の組織の利用者だけ）                    |
| `shareOrganizations`         | `array \| null`   | 公開先の組織のコードの配列。shareScope が "organizations" のときに使います                                 |
| `copyCount`                  | `number \| null`  | コピーされた回数                                                                            |
| `ownerUserId`                | `string \| null`  | 持ち主の利用者 ID                                                                          |
| `myRole`                     | `string \| null`  | 呼んだ利用者の役割。"owner"・"operator"・"member" のどれか。プレビューと、参加していない組織の運用の役割の人では null          |
| `orgOperator`                | `boolean`         | 呼んだ利用者が、プロジェクトの所属組織で組織の運用の役割を持つか。プロジェクトの取得だけで返ります（一覧には無い）                           |
| `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`・`adminStop` を除きます。`myRole` は null）・`steps`（各工程の `digest` を除きます）・`placements`（`placementId`・`agentId`・`name`・`description`・`goal`・`stepIds`・`skillCount` だけ）を返します。`stepsDigest`・`members`・`triggers`・`stepStartFailures`・`notifications`・`connectors`・`relink` は返しません。

<!-- -->

#### レスポンス例

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

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

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

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

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

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

#### パスパラメータ

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

#### リクエスト例

**Export project definition**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/definition",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/definition",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/definition", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

| フィールド        | 型        | 説明                      |
| ------------ | -------- | ----------------------- |
| `definition` | `object` | プロジェクトの定義（製品の書き出しの形のまま） |

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

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

### POST`/v1/projects/import`

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

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

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

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

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

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

#### レスポンス例

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

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

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

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

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

#### パスパラメータ

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

#### リクエスト例

**Dismiss project relink**

**curl**

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

**Python**

```python
import requests

response = requests.delete(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/relink",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/relink",
{
  method: "DELETE",
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("DELETE", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/relink", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

```json
{
  "projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
  "dismissed": true
}
```

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

| ステータス | code                | 説明                       |
| ----- | ------------------- | ------------------------ |
| `400` | `invalid_parameter` | projectId が UUID の形式ではない |
| `403` | `forbidden`         | システム連携のトークンで呼び出した        |
| `403` | `owner_only`        | オーナーではないメンバー             |
| `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"                                                                                                                             |
| `organizationCode`     | `string \| null` | —  | 組織のコード（255 文字まで）。付けられるのは GET /v1/projects/organizations で返る組織だけ。null・空の文字列・空白だけは、付けないのと同じです                                                                    |
| `steps`                | `array`          | —  | 工程の並び（12 個まで）。空でない配列を渡すときは、workflow は 2 つ以上、cycle は 1 つ以上です。省くか空の配列のときは、既定の工程で作ります（workflow は Agent が実行する工程・確認工程・Agent が実行する工程の 3 つ、cycle は Agent が実行する工程 2 つ） |
| `steps[].name`         | `string \| null` | —  | 工程の名前（100 文字まで。空の文字列・null は既定の名前です。空白だけにはできません）                                                                                                                |
| `steps[].description`  | `string \| null` | —  | 工程の説明（空の文字列・null は説明なし）                                                                                                                                        |
| `steps[].enabled`      | `boolean`        | —  | 有効かどうか（true または false）。省くと有効です                                                                                                                                 |
| `steps[].zone`         | `string`         | —  | "ai"（Agent が実行）または "gate"（確認工程）。省くと "ai"。cycle では "ai" だけ。null は送れません                                                                                          |
| `steps[].outputConfig` | `—`              | —  | 送れません（null 以外は 400 output\_config\_invalid。null は送らないのと同じです）                                                                                                   |

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

#### リクエスト例

**Create project**

**curl**

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

**Python**

```python
import requests

response = requests.post(
  "https://<your-domain>/api/v1/projects",
  headers={"Authorization": f"Bearer {token}"},
  json={'name': '請求書の突合', 'description': '請求書の金額と明細を照合し、差異を確認依頼にします', 'tags': ['経理'], 'type': 'workflow', 'organizationCode': 'eng'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"name": "請求書の突合", "description": "請求書の金額と明細を照合し、差異を確認依頼にします", "tags": ["経理"], "type": "workflow", "organizationCode": "eng"}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"name": "請求書の突合", "description": "請求書の金額と明細を照合し、差異を確認依頼にします", "tags": ["経理"], "type": "workflow", "organizationCode": "eng"}`)
req, _ := http.NewRequest("POST", "https://<your-domain>/api/v1/projects", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

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

#### レスポンス例

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

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

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

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

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

#### パスパラメータ

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

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

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

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

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

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

<!-- -->

#### リクエスト例

**Update project**

**curl**

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

**Python**

```python
import requests

response = requests.patch(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
  headers={"Authorization": f"Bearer {token}"},
  json={'baseDigest': 'qHnScSdRAclmcFJVVCjKUrMsl5SELfkKS5UPAVidUJk', 'status': 'paused'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
{
  method: "PATCH",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"baseDigest": "qHnScSdRAclmcFJVVCjKUrMsl5SELfkKS5UPAVidUJk", "status": "paused"}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"baseDigest": "qHnScSdRAclmcFJVVCjKUrMsl5SELfkKS5UPAVidUJk", "status": "paused"}`)
req, _ := http.NewRequest("PATCH", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

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

#### レスポンス例

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

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

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

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

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

#### パスパラメータ

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

#### リクエスト例

**Delete project**

**curl**

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

**Python**

```python
import requests

response = requests.delete(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
{
  method: "DELETE",
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("DELETE", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

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

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

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

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

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

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

#### パスパラメータ

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

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

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

#### リクエスト例

**Get project control**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/control",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/control",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/control", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

#### レスポンス例

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

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

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

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

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

#### パスパラメータ

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

#### リクエスト例

**Get definition approval**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/definition-approval",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/definition-approval",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/definition-approval", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

| フィールド                            | 型                | 説明                                                                             |
| -------------------------------- | ---------------- | ------------------------------------------------------------------------------ |
| `required`                       | `boolean`        | テナントで定義の変更に承認が要るかどうか                                                           |
| `activeVersion`                  | `number \| null` | 承認された（実行に使う）定義の版の番号                                                            |
| `pending`                        | `object \| null` | 承認待ちの変更。無ければ null。項目は下の定義の承認の項目の pending と同じで、createdAt と changes が加わります       |
| `pending.createdAt`              | `string \| null` | 承認待ちができた日時（ISO 8601）                                                           |
| `pending.changes`                | `array`          | 承認された定義から変わる所の配列                                                               |
| `pending.changes[].section`      | `string`         | 変わる所の種類。"project"・"steps"・"placements"・"triggers"・"notifications"・"connectors" |
| `pending.changes[].key`          | `string \| null` | その種類の中のどれか（工程・配置・トリガーの ID、連携先の ID、通知の種類と経路）。"project" のときは null                |
| `pending.changes[].change`       | `string`         | "added"（足す）・"removed"（外す）・"updated"（変える）                                       |
| `pending.changes[].fields`       | `array`          | 変わった欄の手がかりの名前。この要約だけの名前で、取得の答えの項目の名前とは一致しません。中身は definition=pending の読みで確かめます  |
| `lastRejection`                  | `object \| null` | 最後に差し戻された変更（その後に承認された変更があれば null）                                              |
| `lastRejection.version`          | `number`         | 差し戻された版の番号                                                                     |
| `lastRejection.reviewedByUserId` | `string \| null` | 差し戻した利用者 ID                                                                    |
| `lastRejection.reviewedAt`       | `string \| null` | 差し戻した日時（ISO 8601）                                                              |
| `lastRejection.reason`           | `string \| null` | 差し戻しの理由                                                                        |
| `approverRule`                   | `string`         | 承認できる人の決まり（下の定義の承認の項目と同じ）                                                      |
| `approvers`                      | `object`         | 承認できる人                                                                         |
| `approvers.ownerUserIds`         | `array`          | 承認できるオーナーの利用者 ID の配列（申請した人を除きます）                                               |
| `approvers.orgAdminCount`        | `number`         | 承認できる組織の管理者の数                                                                  |
| `approvers.available`            | `boolean`        | 承認できる人がいるかどうか                                                                  |
| `canApprove`                     | `boolean`        | 呼んだ人が承認できるかどうか（承認は製品の画面で行います）                                                  |
| `canWithdraw`                    | `boolean`        | 呼んだ人が承認待ちを取り消せるかどうか（オーナー）                                                      |

#### 定義の承認の項目

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

| フィールド                        | 型                 | 説明                                                                               |
| ---------------------------- | ----------------- | -------------------------------------------------------------------------------- |
| `required`                   | `boolean \| null` | テナントで定義の変更に承認が要るかどうか。承認待ちを取り消した答えで、設定を確かめられなかったときは null                          |
| `status`                     | `string`          | "pending"（承認待ちがある）または "none"（無い）                                                 |
| `activeVersion`              | `number \| null`  | 承認された（実行に使う）定義の版の番号。まだ無ければ null                                                  |
| `pending`                    | `object \| null`  | 承認待ちの変更。無ければ null                                                                |
| `pending.version`            | `number`          | 承認待ちの版の番号                                                                        |
| `pending.digest`             | `string`          | 承認待ちの変更の値。承認待ちを取り消すときに pendingDigest に送ります（プロジェクトの取得の digest とは別の値です）            |
| `pending.baseVersion`        | `number \| null`  | 承認待ちの変更の元になった版の番号                                                                |
| `pending.initial`            | `boolean`         | 作ったプロジェクトの最初の定義の承認待ちかどうか。true の間は、実行を始められません                                     |
| `pending.requestedByUserIds` | `array`           | 変更を申請した利用者 ID の配列（承認待ちに変更を重ねた人を含みます）                                             |
| `pending.updatedAt`          | `string \| null`  | 承認待ちが最後に変わった日時（ISO 8601）                                                         |
| `pending.workItemId`         | `string \| null`  | 承認する人に届いている承認の依頼の ID（受信トレイの行の ID。確認依頼の API では読めません）                              |
| `approverRule`               | `string`          | 承認できる人の決まり。"owner\_or\_org\_admin\_not\_requester"（申請した人ではない、プロジェクトのオーナーか組織の管理者） |
| `approversAvailable`         | `boolean`         | 承認できる人がいるかどうか                                                                    |

#### レスポンス例

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

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

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

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

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

#### パスパラメータ

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

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

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

#### リクエスト例

**Withdraw definition approval**

**curl**

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

**Python**

```python
import requests

response = requests.delete(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/definition-approval",
  headers={"Authorization": f"Bearer {token}"},
  params={"pendingDigest": "c3d7b0e6e1840e4008c84b6e53e66bfc500453c3ff3a2a543d70374dc38b82d1"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/definition-approval" + "?pendingDigest=c3d7b0e6e1840e4008c84b6e53e66bfc500453c3ff3a2a543d70374dc38b82d1",
{
  method: "DELETE",
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("DELETE", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/definition-approval?pendingDigest=c3d7b0e6e1840e4008c84b6e53e66bfc500453c3ff3a2a543d70374dc38b82d1", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

| フィールド                | 型        | 説明                                                    |
| -------------------- | -------- | ----------------------------------------------------- |
| `definitionApproval` | `object` | 取り消した後の様子（項目は[定義の承認の項目](#definition-approval-object)） |

#### レスポンス例

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

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

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

## 工程

工程は、プロジェクトの流れの単位です。Agent が実行する工程（`defaultZone` が `"ai"`）と、人が判断する確認工程（`"gate"`）があります。<!-- -->前の工程の結果で進むレーンを選ぶ条件分岐の工程（`"branch"`。Agent を置きません）もあります。工程は 12 個までです。工程を消して下限（ワークフローは 2 個、サイクルは 1 個）より少なくすることはできません。

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

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

### 工程の項目

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

| フィールド                    | 型                 | 説明                                                                                                                        |
| ------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `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"（確認工程）・"branch"（条件分岐）のどれか                                                                           |
| `branchConfig`           | `object \| null`  | 条件分岐の設定（defaultZone が "branch" の工程だけ。ほかの工程と、まだ設定していない条件分岐の工程は null）。公開されているプロジェクトのプレビューでも返します                             |
| `branchConfig.lanes[]`   | `object[]`        | レーン。id・name（名前の無いレーンは null。変えるときは省けます）・stepIds（そのレーンの工程の ID。上から順に実行）                                                      |
| `branchConfig.rules[]`   | `object[]`        | 条件。id・kind（判定対象と規則の種類）と規則ごとの値・to（当てはまったときの進む先）                                                                            |
| `branchConfig.otherwise` | `object`          | どの条件にも当てはまらないときの進む先                                                                                                       |
| `reworkToStepId`         | `string \| null`  | 差し戻すときの戻り先の工程の ID（確認工程で使います）                                                                                              |
| `gateConfig`             | `object \| null`  | 確認工程の設定（下の表）                                                                                                              |
| `gateKind`               | `string \| null`  | 確認の種類。"review"（確認。Agent の結果を人が判断する）または "manual"（手作業。人が作業してから進める）                                                          |
| `schedule`               | `object \| null`  | 工程の時刻（workflow だけ）。expression（cron 式）と timezone                                                                           |
| `scheduleNextFireAt`     | `string \| null`  | 工程の時刻で次に動く予定の日時（ISO 8601）                                                                                                 |
| `onDenied`               | `string \| null`  | 「ルールにより実行できない場合」の扱い。"gate"（確認を求める）/ "closed\_failed"（失敗として閉じる）。前の版で保存した "goto" が返ることがありますが、ワークフローの実行では "gate" と同じく確認を求めます |
| `onDegraded`             | `string \| null`  | 「Agent の報告による失敗のとき」の扱い。"gate"（確認を求める）。前の版で保存した "proceed"・"goto" が返ることがありますが、ワークフローの実行では "gate" と同じく確認を求めます                |
| `outcomeRoutes`          | `object \| null`  | いつも null（マーケットプレイス版では、結果ごとの次の工程を設定できません）                                                                                  |
| `laneId`                 | `string \| null`  | いつも null                                                                                                                  |
| `placementExecution`     | `string \| null`  | いつも null（置いた順に 1 つずつ実行）                                                                                                   |
| `digest`                 | `string`          | 工程を変えるときに baseDigest に送る値                                                                                                 |

<!-- -->

<!-- -->

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

規則の種類（`rules[].kind`）:

| kind                 | 値                                                                                                      | 当たるとき                                                  |
| -------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ |
| `text_contains`      | value（200 文字まで。空白だけにはできません）・negate                                                                     | 前の工程の結果の文に value を含む（negate が true なら、含まない）            |
| `json_field`         | path（ドット区切りの項目の名前。200 文字まで）・op（"eq"・"ne"・"gte"・"lte"・"exists"）・value（op が "exists" のほか。200 文字までの文字列か数） | 前の工程の結果の JSON の項目が value と同じ・違う・以上・以下（"exists" は項目がある） |
| `files_exist`        | negate                                                                                                 | 成果物がある（negate が true なら、ない）                            |
| `files_count`        | op（"gte"・"lte"）・value（0 以上の整数）                                                                         | 成果物の数が value 以上・以下                                     |
| `file_type`          | fileType（"pdf"・"excel"・"word"・"powerpoint"・"image"）                                                    | その種類の成果物がある                                            |
| `file_name_contains` | value（200 文字まで。空白だけにはできません）                                                                            | 名前に value を含む成果物がある                                    |
| `duration_minutes`   | op（"gte"・"lte"）・value（分。0 以上の整数）                                                                       | 前の工程の処理時間が value 分以上・以下                                |
| `send_backs`         | op（"gte"）・value（0 以上の整数）                                                                               | この工程に戻された回数が value 回以上                                 |
| `mutating`           | negate                                                                                                 | 前の工程で書き込み操作があった（negate が true なら、なかった）                 |
| `no_change_reported` | —                                                                                                      | Agent が「変更は要らなかった」と報告した                                |

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

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

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

| フィールド              | 型                | 説明                                                                                                                                                                                                                |
| ------------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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）   |
| 条件分岐の工程（defaultZone の "branch"）と branchConfig         | 付けられる    | 400（cycle\_branch\_not\_allowed） |
| onDenied・onDegraded の "gate"                          | 付けられる    | 400（cycle\_gate\_not\_allowed）   |
| schedule（工程の時刻）                                       | 付けられる    | 400（invalid\_parameter）          |
| reworkToStepId（差し戻し先）                                 | 付けられる    | 400（invalid\_parameter）          |

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

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

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

#### パスパラメータ

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

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

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

<!-- -->

#### リクエスト例

**Create step**

**curl**

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

**Python**

```python
import requests

response = requests.post(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps",
  headers={"Authorization": f"Bearer {token}"},
  json={'name': '差異の報告', 'description': None, 'defaultZone': 'ai', 'afterStepId': 'a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"name": "差異の報告", "description": null, "defaultZone": "ai", "afterStepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"name": "差異の報告", "description": null, "defaultZone": "ai", "afterStepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"}`)
req, _ := http.NewRequest("POST", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

| フィールド                | 型                | 説明                                                                                                                                                        |
| -------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `step`               | `object`         | 足した工程                                                                                                                                                     |
| `steps`              | `array`          | 足した後の全部の工程（並び順）                                                                                                                                           |
| `stepsDigest`        | `string`         | 足した後の工程の並びの値                                                                                                                                              |
| `definitionApproval` | `object \| null` | テナントで定義の変更に承認が要るとき、この変更は承認待ちになり、ここに承認待ちの様子が入ります（status が "pending"。項目は[定義の承認の項目](#definition-approval-object)）。承認されるまで、実行は前の定義で動きます。承認が要らず、すぐ反映したときは null |

#### レスポンス例

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

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

| ステータス | code                            | 説明                                                                                                                                                                                                              |
| ----- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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"・期限後の自動処理）を送った。error.param に、断られた項目の名前（gateConfig.mode など）が入ります                                                                                                              |
| `400` | `step_reference_on_create`      | gateConfig に destinations を送った（null・空の配列を含みます。マーケットプレイス版では進め先を設定できません）、または branchConfig を送った（error.param は branchConfig。工程を足した後、レーンの工程を後ろに置いてから、工程を変える API で付けてください）                                            |
| `400` | `cycle_gate_not_allowed`        | cycle に確認工程を足そうとした                                                                                                                                                                                              |
| `400` | `cycle_branch_not_allowed`      | cycle に条件分岐の工程（"branch"）を足そうとした                                                                                                                                                                                 |
| `400` | `branch_step_settings`          | 条件分岐の工程では使えない項目を送った。その項目を送らないでください（error.param にその項目の名前）                                                                                                                                                        |
| `400` | `output_config_invalid`         | outputConfig を送った（マーケットプレイス版では使えません。null は送らないのと同じです）。error.param は outputConfig                                                                                                                                |
| `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 個ある                                                                                                                                                                                                   |
| `409` | `flow_structure_conflict`       | 条件分岐の置き方と食い違う（理由は error.reason。工程を並べ替える API の誤りの表の下）                                                                                                                                                            |
| `413` | `body_too_large`                | ボディが 32 KiB を超える                                                                                                                                                                                                |
| `415` | `unsupported_media_type`        | ボディの Content-Type が application/json ではない                                                                                                                                                                       |
| `409` | `definition_invalid`            | 承認待ちの変更に重ねると定義が成り立たない（理由の種類は error.reason）。definition=pending で読み直し、重ねた形を見て直してください                                                                                                                              |
| `503` | `approval_setting_unavailable`  | 定義の承認の設定を確かめられない。時間をおいて送り直してください                                                                                                                                                                                |
| `503` | `definition_busy`               | 同じ定義の変更が処理中。時間をおいて送り直してください                                                                                                                                                                                     |

### 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"・"branch" のどれか                                                                                                                                                                        |
| `branchConfig`   | `object \| null` | —  | 条件分岐の設定（defaultZone が "branch" の工程だけ。形は工程の項目の branchConfig と下の決まり）。送ると丸ごと置き換え、null で外します                                                                                                         |
| `outputConfig`   | `—`              | —  | 送れません（null 以外は 400 output\_config\_invalid。null は送らないのと同じで、null だけでは変える項目が無い 400 invalid\_parameter です）                                                                                          |
| `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"（"goto" は 400 structure\_not\_for\_marketplace）。前の版で保存した値の工程でも、onDenied を送らなければ断られません。取得した値をそのまま送り返すと 400 です                                                            |
| `onDegraded`     | `string \| null` | —  | "gate"（"proceed"・"goto" は 400 structure\_not\_for\_marketplace）。前の版で保存した値の工程でも、onDegraded を送らなければ断られません。取得した値をそのまま送り返すと 400 です                                                                   |
| `schedule`       | `object \| null` | —  | 工程の時刻（workflow だけ）。expression（5 項目の cron 式）と timezone（省くと UTC）。null で外します                                                                                                                        |

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

<!-- -->

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

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

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

#### リクエスト例

**Update step**

**curl**

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

**Python**

```python
import requests

response = requests.patch(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps/5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
  headers={"Authorization": f"Bearer {token}"},
  json={'baseDigest': 'jZ38OtGgLnS14QCvjZdg5PdyrGEHPK0EhxgDZzEnE2Y', 'name': '金額の確認（税込）'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps/5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
{
  method: "PATCH",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"baseDigest": "jZ38OtGgLnS14QCvjZdg5PdyrGEHPK0EhxgDZzEnE2Y", "name": "金額の確認（税込）"}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"baseDigest": "jZ38OtGgLnS14QCvjZdg5PdyrGEHPK0EhxgDZzEnE2Y", "name": "金額の確認（税込）"}`)
req, _ := http.NewRequest("PATCH", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps/5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

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

#### レスポンス例

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

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

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

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

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

#### パスパラメータ

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

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

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

#### リクエスト例

**Reorder steps**

**curl**

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

**Python**

```python
import requests

response = requests.put(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps/order",
  headers={"Authorization": f"Bearer {token}"},
  json={'baseDigest': '6r94LWhMkQ54T1GkU_ntdq-ZfgpGyeGFyu4Gt32V9H0', 'stepIds': ['5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819', '7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d', 'a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d']},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps/order",
{
  method: "PUT",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"baseDigest": "6r94LWhMkQ54T1GkU_ntdq-ZfgpGyeGFyu4Gt32V9H0", "stepIds": ["5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819", "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d", "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"]}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"baseDigest": "6r94LWhMkQ54T1GkU_ntdq-ZfgpGyeGFyu4Gt32V9H0", "stepIds": ["5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819", "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d", "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"]}`)
req, _ := http.NewRequest("PUT", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps/order", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

| フィールド                | 型                | 説明                                                                                                                                                        |
| -------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `steps`              | `array`          | 並べ替えた後の全部の工程                                                                                                                                              |
| `stepsDigest`        | `string`         | 並べ替えた後の工程の並びの値                                                                                                                                            |
| `definitionApproval` | `object \| null` | テナントで定義の変更に承認が要るとき、この変更は承認待ちになり、ここに承認待ちの様子が入ります（status が "pending"。項目は[定義の承認の項目](#definition-approval-object)）。承認されるまで、実行は前の定義で動きます。承認が要らず、すぐ反映したときは null |

#### レスポンス例

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

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

| ステータス | code                           | 説明                                                                                                           |
| ----- | ------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| `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`                   | 取得した後に工程の並びが変わっている。承認待ちがあるときは、既定の取得の digest では合いません。definition=pending で読み直し、その digest を baseDigest に送ってください |
| `409` | `flow_structure_conflict`      | 条件分岐の置き方と食い違う（理由は error.reason。工程を並べ替える API の誤りの表の下）                                                         |
| `413` | `body_too_large`               | ボディが 16 KiB を超える                                                                                             |
| `415` | `unsupported_media_type`       | ボディの Content-Type が application/json ではない                                                                    |
| `409` | `definition_invalid`           | 承認待ちの変更に重ねると定義が成り立たない（理由の種類は error.reason）。definition=pending で読み直し、重ねた形を見て直してください                           |
| `503` | `approval_setting_unavailable` | 定義の承認の設定を確かめられない。時間をおいて送り直してください                                                                             |
| `503` | `definition_busy`              | 同じ定義の変更が処理中。時間をおいて送り直してください                                                                                  |

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

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

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

#### パスパラメータ

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

#### リクエスト例

**Delete step**

**curl**

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

**Python**

```python
import requests

response = requests.delete(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
{
  method: "DELETE",
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("DELETE", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

| フィールド                | 型                 | 説明                                                                                                                                                        |
| -------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stepId`             | `string`          | 消した工程の ID                                                                                                                                                 |
| `deleted`            | `boolean`         | いつも true                                                                                                                                                  |
| `historyKept`        | `boolean \| null` | 記録のために工程を残したかどうか。承認待ちになったときは null（まだ消えていないため）                                                                                                             |
| `steps`              | `array`           | 消した後の全部の工程                                                                                                                                                |
| `stepsDigest`        | `string`          | 消した後の工程の並びの値                                                                                                                                              |
| `definitionApproval` | `object \| null`  | テナントで定義の変更に承認が要るとき、この変更は承認待ちになり、ここに承認待ちの様子が入ります（status が "pending"。項目は[定義の承認の項目](#definition-approval-object)）。承認されるまで、実行は前の定義で動きます。承認が要らず、すぐ反映したときは null |

#### レスポンス例

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

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

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

## 配置

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

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

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

### 配置の項目

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

| フィールド                    | 型                 | 説明                                                                                 |
| ------------------------ | ----------------- | ---------------------------------------------------------------------------------- |
| `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 を置いているのがこのプロジェクトだけかどうか                                                    |
| `agentStopped`           | `boolean \| null` | 置いた Agent を管理者が止めているか。止めている間、この配置の工程は始まらず、再開を待ちます                                  |
| `relink`                 | `object \| null`  | いつも null                                                                           |
| `digest`                 | `string`          | 配置を変える API（担当工程・巡回・工程の設定）で baseDigest に送る値。担当工程・実行の設定・巡回から作られ、Agent の中身を変えても変わりません |

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

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

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

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

#### リクエスト例

**List placements**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

| フィールド            | 型                | 説明                                                                                                       |
| ---------------- | ---------------- | -------------------------------------------------------------------------------------------------------- |
| `placements`     | `array`          | 配置の配列。1 件の項目は「配置の項目」を参照                                                                                  |
| `hasMore`        | `boolean`        | いつも false                                                                                                |
| `definitionView` | `string \| null` | definition=pending を付けたときだけ。"pending"（承認待ちを重ねた見え方）か "active"（承認待ちが無い）。組織の運用の役割を持ち、プロジェクトに参加していない人には null |

#### レスポンス例

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

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

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

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

配置を 1 件取得します。

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

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

#### リクエスト例

**Get placement**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

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

#### レスポンス例

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

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

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

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

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

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

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

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

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

#### リクエスト例

**List agent candidates**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/projects/agent-candidates",
  headers={"Authorization": f"Bearer {token}"},
  params={"project_type": "workflow"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/agent-candidates" + "?project_type=workflow",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/projects/agent-candidates?project_type=workflow", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### レスポンスフィールド（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                                          |
| `candidates[].inputs`                  | `array \| null`   | 登録 Agent が受け取る入力ファイル。名前を、開始の config の fileBindings と、工程の設定の inputBindings に使います |
| `candidates[].inputs[].name`           | `string \| null`  | 入力ファイルの名前                                                                       |
| `candidates[].inputs[].format`         | `string \| null`  | 形式（"markdown"・"yaml"・"json"・"text"・"binary"）                                    |
| `candidates[].inputs[].required`       | `boolean`         | 必須かどうか                                                                          |
| `candidates[].inputs[].editable`       | `boolean`         | 人が中身を入れる入力かどうか                                                                  |
| `candidates[].inputs[].fromParameters` | `boolean`         | parameters から作られる入力かどうか                                                         |
| `candidates[].inputs[].schema`         | `object \| null`  | "yaml"・"json" の入力の形（JSON Schema）。上げるときにこの形で確かめます                                |
| `candidates[].outputs`                 | `array \| null`   | 登録 Agent が出す出力ファイル（name・format・required）。名前を、後の工程の inputBindings の output に使います |
| `candidates[].parametersSchema`        | `object \| null`  | parameters の形（JSON Schema）                                                      |
| `candidates[].defaults`                | `object \| null`  | 定義の既定値                                                                          |
| `candidates[].connectionSlots`         | `array \| null`   | 接続の枠。name（枠の名前）・required（必須かどうか）・allowedProviderIds（指定できる連携先の ID の配列）           |
| `hasMore`                              | `boolean`         | いつも false（全件を返します）                                                              |

#### レスポンス例

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

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

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

#### リクエスト例

**Place agent**

**curl**

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

**Python**

```python
import requests

response = requests.post(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements",
  headers={"Authorization": f"Bearer {token}"},
  json={'marketplaceAgentId': 'invoice-checker', 'stepIds': ['5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819']},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"marketplaceAgentId": "invoice-checker", "stepIds": ["5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"]}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"marketplaceAgentId": "invoice-checker", "stepIds": ["5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"]}`)
req, _ := http.NewRequest("POST", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

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

#### レスポンス例

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

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

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

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

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

#### リクエスト例

**Remove placement**

**curl**

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

**Python**

```python
import requests

response = requests.delete(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
{
  method: "DELETE",
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("DELETE", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

| フィールド                | 型                 | 説明                                                                                                                                                        |
| -------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `placementId`        | `string`          | 外した配置の ID                                                                                                                                                 |
| `deleted`            | `boolean`         | いつも true                                                                                                                                                  |
| `historyKept`        | `boolean \| null` | 記録のために配置を残したかどうか。承認待ちになったときは null（まだ外れていないため）                                                                                                             |
| `definitionApproval` | `object \| null`  | テナントで定義の変更に承認が要るとき、この変更は承認待ちになり、ここに承認待ちの様子が入ります（status が "pending"。項目は[定義の承認の項目](#definition-approval-object)）。承認されるまで、実行は前の定義で動きます。承認が要らず、すぐ反映したときは null |

#### レスポンス例

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

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

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

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

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

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

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

#### リクエスト例

**Update placement steps**

**curl**

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

**Python**

```python
import requests

response = requests.put(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/steps",
  headers={"Authorization": f"Bearer {token}"},
  json={'baseDigest': 'dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU', 'stepIds': ['5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819', '7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d']},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/steps",
{
  method: "PUT",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU", "stepIds": ["5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819", "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d"]}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU", "stepIds": ["5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819", "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d"]}`)
req, _ := http.NewRequest("PUT", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/steps", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

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

#### レスポンス例

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

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

| ステータス | code                           | 説明                                                                                                                  |
| ----- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| `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`                   | 取得した後に配置が変わっている。承認待ちがあるときは、既定の取得の digest では合いません。definition=pending で読み直し、その digest を baseDigest に送ってください           |
| `413` | `body_too_large`               | ボディが 16 KiB を超える                                                                                                    |
| `415` | `unsupported_media_type`       | ボディの Content-Type が application/json ではない                                                                           |
| `409` | `definition_invalid`           | 承認待ちの変更に重ねると定義が成り立たない（理由の種類は error.reason）。definition=pending で読み直し、重ねた形を見て直してください                                  |
| `503` | `approval_setting_unavailable` | 定義の承認の設定を確かめられない。時間をおいて送り直してください                                                                                    |
| `503` | `definition_busy`              | 同じ定義の変更が処理中。時間をおいて送り直してください                                                                                         |

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

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

#### パスパラメータ

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

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

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

ボディは 16 KiB までです。

#### リクエスト例

**Update placement runtime config**

**curl**

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

**Python**

```python
import requests

response = requests.put(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/steps/5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819/runtime-config",
  headers={"Authorization": f"Bearer {token}"},
  json={'baseDigest': 'dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU', 'parameters': {'currency': 'JPY'}, 'connectionBindings': {}, 'inputBindings': {'invoice': {'placementId': '0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d', 'output': 'report'}}},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/steps/5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819/runtime-config",
{
  method: "PUT",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU", "parameters": {"currency": "JPY"}, "connectionBindings": {}, "inputBindings": {"invoice": {"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "output": "report"}}}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU", "parameters": {"currency": "JPY"}, "connectionBindings": {}, "inputBindings": {"invoice": {"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "output": "report"}}}`)
req, _ := http.NewRequest("PUT", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/steps/5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819/runtime-config", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

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

#### レスポンス例

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

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

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

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

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

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

| フィールド        | 型         | 必須 | 説明                                                                                                                                                          |
| ------------ | --------- | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `baseDigest` | `string`  | 必須 | その配置の digest                                                                                                                                                |
| `stepId`     | `string`  | —  | 巡回の工程の ID（配置の担当工程）。担当工程が 1 つの配置では省けます                                                                                                                       |
| `enabled`    | `boolean` | —  | true で巡回、false で停止。true でも、工程が無効・プロジェクトが一時停止・管理者がプロジェクトかその Agent を止めている・プロジェクトを実行する人の利用を管理者が止めているあいだは巡回しない（工程を有効に戻したとき、プロジェクトや Agent が再開されたときは、保存した周期で巡回する） |
| `cron`       | `string`  | —  | 周期（5 項目の cron 式。100 文字まで）                                                                                                                                   |
| `timezone`   | `string`  | —  | タイムゾーン（IANA のタイムゾーン名。64 文字まで。例: "Asia/Tokyo"）                                                                                                               |

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

#### リクエスト例

**Update placement schedule**

**curl**

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

**Python**

```python
import requests

response = requests.patch(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/schedule",
  headers={"Authorization": f"Bearer {token}"},
  json={'baseDigest': 'dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU', 'stepId': '5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819', 'enabled': True, 'cron': '0 9 * * 1', 'timezone': 'Asia/Tokyo'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/schedule",
{
  method: "PATCH",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU", "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819", "enabled": true, "cron": "0 9 * * 1", "timezone": "Asia/Tokyo"}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU", "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819", "enabled": true, "cron": "0 9 * * 1", "timezone": "Asia/Tokyo"}`)
req, _ := http.NewRequest("PATCH", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/schedule", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

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

#### レスポンス例

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

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

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

## トリガー

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

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

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

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

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

#### パスパラメータ

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

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

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

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

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

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

#### リクエスト例

**Create triggers**

**curl**

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

**Python**

```python
import requests

response = requests.post(
  "https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/triggers",
  headers={"Authorization": f"Bearer {token}"},
  json={'type': 'cron', 'name': '毎週月曜 9 時', 'cron': '0 9 * * 1', 'timezone': 'Asia/Tokyo'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/triggers",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"type": "cron", "name": "毎週月曜 9 時", "cron": "0 9 * * 1", "timezone": "Asia/Tokyo"}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"type": "cron", "name": "毎週月曜 9 時", "cron": "0 9 * * 1", "timezone": "Asia/Tokyo"}`)
req, _ := http.NewRequest("POST", "https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/triggers", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### レスポンス例

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

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

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

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

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

#### パスパラメータ

| パラメータ       | 型        | 必須 | 説明                                             |
| ----------- | -------- | -- | ---------------------------------------------- |
| `projectId` | `string` | 必須 | プロジェクト ID（UUID）                                |
| `triggerId` | `string` | 必須 | トリガー ID（UUID。プロジェクトの取得の triggers\[].triggerId） |

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

| フィールド         | 型         | 必須 | 説明                                            |
| ------------- | --------- | -- | --------------------------------------------- |
| `baseDigest`  | `string`  | 必須 | そのトリガーの digest（プロジェクトの取得の triggers\[].digest） |
| `name`        | `string`  | —  | 名前（100 文字まで）                                  |
| `enabled`     | `boolean` | —  | 有効かどうか                                        |
| `cron`        | `string`  | —  | 5 項目の cron 式（"cron" だけ）。100 文字まで              |
| `timezone`    | `string`  | —  | タイムゾーン（"cron" だけ。IANA の名前。64 文字まで）            |
| `startStepId` | `string`  | —  | 始める工程（"cron" だけ。このプロジェクトの工程の ID）              |
| `placementId` | `string`  | —  | 発火で動かす配置の ID（"webhook" だけ）                    |
| `stepId`      | `string`  | —  | 発火で動かす工程の ID（"webhook" だけ。その配置が受け持つ工程）        |

- baseDigest のほかに、少なくとも 1 つの項目を送ってください。
- `type` は変えられません（送ると `400 Bad Request`）。種類を変えるときは、トリガーを消して作り直します。
- 項目を消すことはできません。null・空の文字列・空白だけを送ると `400 Bad Request` です。

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

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

#### リクエスト例

**Update 8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40**

**curl**

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

**Python**

```python
import requests

response = requests.patch(
  "https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/triggers/8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40",
  headers={"Authorization": f"Bearer {token}"},
  json={'baseDigest': 'Nb8SAh4xIBu2F65clLazvr8vEGwTTPar7GdAw5jDKRA', 'enabled': False},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/triggers/8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40",
{
  method: "PATCH",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"baseDigest": "Nb8SAh4xIBu2F65clLazvr8vEGwTTPar7GdAw5jDKRA", "enabled": false}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"baseDigest": "Nb8SAh4xIBu2F65clLazvr8vEGwTTPar7GdAw5jDKRA", "enabled": false}`)
req, _ := http.NewRequest("PATCH", "https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/triggers/8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### レスポンス例

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

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

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

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

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

#### パスパラメータ

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

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

| フィールド                | 型                | 説明                                                                                                                                                        |
| -------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `triggerId`          | `string`         | 消したトリガーの ID                                                                                                                                               |
| `deleted`            | `boolean`        | いつも true                                                                                                                                                  |
| `definitionApproval` | `object \| null` | テナントで定義の変更に承認が要るとき、この変更は承認待ちになり、ここに承認待ちの様子が入ります（status が "pending"。項目は[定義の承認の項目](#definition-approval-object)）。承認されるまで、実行は前の定義で動きます。承認が要らず、すぐ反映したときは null |

#### リクエスト例

**Delete 8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40**

**curl**

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

**Python**

```python
import requests

response = requests.delete(
  "https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/triggers/8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/triggers/8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40",
{
  method: "DELETE",
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("DELETE", "https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/triggers/8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### レスポンス例

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

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

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

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

#### リクエスト例

**Fire trigger**

**curl**

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

**Python**

```python
import requests

response = requests.post(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/triggers/d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70/fire",
  headers={"Authorization": f"Bearer {token}"},
  json={'eventId': 'order-20261118-0001', 'payload': {'orderId': 'A-1024'}},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/triggers/d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70/fire",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"eventId": "order-20261118-0001", "payload": {"orderId": "A-1024"}}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"eventId": "order-20261118-0001", "payload": {"orderId": "A-1024"}}`)
req, _ := http.NewRequest("POST", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/triggers/d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70/fire", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

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

#### レスポンス例

<!-- -->

<!-- -->

```json
{
  "result": "accepted",
  "jobId": "9b2e4c61-0f3a-4a9b-9c1d-2f7e5a8b3c40",
  "executionId": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f"
}
```

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

#### 再送

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

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

| ステータス | code                     | 説明                                                                          |
| ----- | ------------------------ | --------------------------------------------------------------------------- |
| `400` | `invalid_event_id`       | eventId が無い、または形式が不正                                                        |
| `400` | `invalid_parameter`      | projectId または triggerId が UUID の形式ではない                                      |
| `400` | `invalid_body`           | リクエストボディが壊れた JSON、または JSON のオブジェクトではない                                      |
| `415` | `unsupported_media_type` | リクエストボディがあるのに、Content-Type が application/json ではない                          |
| `404` | `trigger_not_found`      | プロジェクト・トリガーが存在しない、アクセス権が無い、Webhook ではないトリガーを指定した、または workflow 型のプロジェクトを指定した |
| `409` | `trigger_disabled`       | トリガーが無効化されている                                                               |
| `409` | `project_not_active`     | プロジェクトが実行可能な状態にない                                                           |
| `409` | `principal_suspended`    | プロジェクトを実行する人の利用を、管理者が止めている。管理者に、プロジェクトの持ち主を変更するか、利用の停止を解くよう頼む               |
| `409` | `admin_stopped`          | プロジェクト、または発火で動かす配置の Agent を、管理者が止めている。再開は管理者に頼む                             |
| `409` | `placement_unavailable`  | 発火対象のエージェント配置が存在しない、または実行できる状態にない                                           |
| `409` | `event_conflict`         | 同じ eventId で payload が異なる                                                   |
| `413` | `body_too_large`         | リクエストボディが 16 KiB を超過                                                        |
| `429` | `queue_full`             | 同じエージェント配置の同じ工程で実行を待っている発火が上限（20 件）に達している                                   |

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

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

## Webhook

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

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

### 出来事

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

### 送る中身

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

| フィールド         | 型                | 説明                                                                                                 |
| ------------- | ---------------- | -------------------------------------------------------------------------------------------------- |
| `event`       | `string`         | 出来事（上の表の値）                                                                                         |
| `project_id`  | `string`         | プロジェクト ID                                                                                          |
| `run_id`      | `string \| null` | ワークフローの実行の ID                                                                                      |
| `workitem_id` | `string \| null` | 確認依頼の ID                                                                                           |
| `occurred_at` | `string`         | 出来事の日時（ISO 8601）                                                                                   |
| `link`        | `string \| null` | 画面で開く URL                                                                                          |
| `status`      | `string`         | run\_closed のときだけ。ワークフローの実行の終わりの状態（"closed\_done"・"closed\_failed"・"closed\_rejected"・"cancelled"） |

- ヘッダー: `Content-Type: application/json`、`X-Agentic-Star-Event`（出来事）。`secret` があるときは `X-Agentic-Star-Signature: sha256=<署名>` も付けます。署名は、受け取った本文そのもの（バイト列）の HMAC-SHA256 を `secret` で作り、16 進数にしたものです。受け取る側で同じ計算をして比べてください。
- 10 秒以内に `2xx` を返すと、届いたことになります。ほかの応答（リダイレクトを含みます）・時間切れ・つながらないときは、1 分・5 分・30 分の後に送り直します（最初と合わせて 4 回まで）。同じ出来事が 2 回以上届くことがあります。
- 配送の結果は 30 日残り、[配送の結果を取得](#list-webhook-deliveries)で読めます。

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

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

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

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

#### パスパラメータ

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

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

| フィールド                     | 型                 | 説明                                                            |
| ------------------------- | ----------------- | ------------------------------------------------------------- |
| `webhooks`                | `array`           | Webhook の配列                                                   |
| `webhooks[].webhookId`    | `string`          | Webhook の ID                                                  |
| `webhooks[].event`        | `string \| null`  | 送る出来事                                                         |
| `webhooks[].url`          | `string \| null`  | 送り先の URL                                                      |
| `webhooks[].enabled`      | `boolean \| null` | 有効かどうか                                                        |
| `webhooks[].hasSecret`    | `boolean`         | secret があるかどうか（secret の値は返しません）                               |
| `webhooks[].createdAt`    | `string \| null`  | 作成日時（ISO 8601）                                                |
| `webhooks[].lastDelivery` | `object \| null`  | 直近の配送の結果（status・httpStatus・at）。送り直しを待っている配送は入りません。まだ無ければ null |
| `webhooks[].digest`       | `string`          | Webhook を変えるときに baseDigest に送る値                               |
| `events`                  | `string[]`        | 送れる出来事の値                                                      |
| `hasMore`                 | `boolean`         | いつも false（全件を返します）                                            |

#### リクエスト例

**Get webhooks**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### レスポンス例

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

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

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

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

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

#### パスパラメータ

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

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

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

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

| フィールド     | 型        | 説明                                                       |
| --------- | -------- | -------------------------------------------------------- |
| `webhook` | `object` | 作った Webhook。一覧の webhooks\[] と同じ項目です（lastDelivery は null） |

#### リクエスト例

**Create webhooks**

**curl**

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

**Python**

```python
import requests

response = requests.post(
  "https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks",
  headers={"Authorization": f"Bearer {token}"},
  json={'event': 'run_closed', 'url': 'https://example.com/hooks/agentic-star', 'secret': '<secret>'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"event": "run_closed", "url": "https://example.com/hooks/agentic-star", "secret": "<secret>"}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"event": "run_closed", "url": "https://example.com/hooks/agentic-star", "secret": "<secret>"}`)
req, _ := http.NewRequest("POST", "https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### レスポンス例

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

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

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

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

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

#### パスパラメータ

| パラメータ       | 型        | 必須 | 説明                                           |
| ----------- | -------- | -- | -------------------------------------------- |
| `projectId` | `string` | 必須 | プロジェクト ID（UUID）                              |
| `webhookId` | `string` | 必須 | Webhook の ID（UUID。一覧の webhooks\[].webhookId） |

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

| フィールド        | 型                | 必須 | 説明                                           |
| ------------ | ---------------- | -- | -------------------------------------------- |
| `baseDigest` | `string`         | 必須 | その Webhook の digest（一覧の webhooks\[].digest）  |
| `event`      | `string`         | —  | 送る出来事                                        |
| `url`        | `string`         | —  | 送り先の URL（作るときと同じ決まり）                         |
| `secret`     | `string \| null` | —  | 署名に使う値（256 文字まで）。送った値に置き換えます。null・空の文字列で消します |
| `enabled`    | `boolean`        | —  | 有効かどうか                                       |

- baseDigest のほかに、少なくとも 1 つの項目を送ってください。
- `event`・`url`・`enabled` は消せません（null・空の文字列・空白だけを送ると `400 Bad Request`）。

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

| フィールド     | 型        | 説明                                                |
| --------- | -------- | ------------------------------------------------- |
| `webhook` | `object` | 変えた後の Webhook（新しい digest）。一覧の webhooks\[] と同じ項目です |

#### リクエスト例

**Update c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a**

**curl**

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

**Python**

```python
import requests

response = requests.patch(
  "https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks/c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a",
  headers={"Authorization": f"Bearer {token}"},
  json={'baseDigest': 'ZzMbbf4GuA4lERz6RWQYwm5-MIwi5DlFRdIX6Plzxb8', 'enabled': False},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks/c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a",
{
  method: "PATCH",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"baseDigest": "ZzMbbf4GuA4lERz6RWQYwm5-MIwi5DlFRdIX6Plzxb8", "enabled": false}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"baseDigest": "ZzMbbf4GuA4lERz6RWQYwm5-MIwi5DlFRdIX6Plzxb8", "enabled": false}`)
req, _ := http.NewRequest("PATCH", "https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks/c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### レスポンス例

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

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

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

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

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

#### パスパラメータ

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

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

| フィールド       | 型         | 説明               |
| ----------- | --------- | ---------------- |
| `webhookId` | `string`  | 消した Webhook の ID |
| `deleted`   | `boolean` | いつも true         |

#### リクエスト例

**Delete c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a**

**curl**

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

**Python**

```python
import requests

response = requests.delete(
  "https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks/c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks/c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a",
{
  method: "DELETE",
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("DELETE", "https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks/c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### レスポンス例

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

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

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

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

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

#### パスパラメータ

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

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

| パラメータ   | 型         | デフォルト | 説明                        |
| ------- | --------- | ----- | ------------------------- |
| `limit` | `integer` | `50`  | 取得件数（1-100）。cursor はありません |

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

| フィールド                        | 型                | 説明                                                             |
| ---------------------------- | ---------------- | -------------------------------------------------------------- |
| `deliveries`                 | `array`          | 配送の結果の配列（新しい順）                                                 |
| `deliveries[].deliveryId`    | `string \| null` | 配送の ID                                                         |
| `deliveries[].event`         | `string \| null` | 出来事                                                            |
| `deliveries[].attempt`       | `number \| null` | 何回目の送信か                                                        |
| `deliveries[].status`        | `string \| null` | "delivered"（届いた）・"pending"（送る前、または送り直しを待っている）・"failed"（届かなかった） |
| `deliveries[].httpStatus`    | `number \| null` | 送り先が返した HTTP ステータス                                             |
| `deliveries[].at`            | `string \| null` | 結果の日時（ISO 8601）                                                |
| `deliveries[].nextAttemptAt` | `string \| null` | 次に送り直す予定の日時（ISO 8601）                                          |
| `deliveries[].lastError`     | `string \| null` | 届かなかった理由（例: "http\_500"・"timeout"）                             |
| `hasMore`                    | `boolean`        | limit より古い結果があるかどうか（limit が 100 のときは、100 件そろえば true）           |

#### リクエスト例

**Get deliveries**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks/c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a/deliveries",
  headers={"Authorization": f"Bearer {token}"},
  params={"limit": "20"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks/c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a/deliveries" + "?limit=20",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks/c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a/deliveries?limit=20", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### レスポンス例

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

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

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

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

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

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

| メソッド  | エンドポイント                                                   | 説明                        |
| ----- | --------------------------------------------------------- | ------------------------- |
| POST  | `/v1/projects/{projectId}/runs`                           | ワークフローの実行を開始              |
| GET   | `/v1/projects/{projectId}/runs/{runId}`                   | ワークフローの実行を取得              |
| GET   | `/v1/projects/{projectId}/runs`                           | ワークフローの実行の一覧を取得           |
| GET   | `/v1/projects/{projectId}/runs/{runId}/config`            | ワークフローの実行を始めたときの設定を取得     |
| PATCH | `/v1/projects/{projectId}/runs/{runId}`                   | ワークフローの実行の締め切りを決める・外す     |
| PUT   | `/v1/projects/{projectId}/runs/{runId}/approvers`         | ワークフローの実行の確認担当者を付け替える     |
| POST  | `/v1/projects/{projectId}/runs/{runId}/cancel`            | ワークフローの実行を中断              |
| POST  | `/v1/projects/{projectId}/artifacts`                      | 入力ファイルを上げる（下書き）           |
| GET   | `/v1/projects/{projectId}/artifacts`                      | ワークフローの実行の成果物の一覧を取得       |
| GET   | `/v1/projects/{projectId}/artifacts/{artifactId}/content` | 成果物の中身を取得                 |
| GET   | `/v1/projects/{projectId}/runs/{runId}/case-config`       | ワークフローの実行の今の案件設定を取得       |
| PUT   | `/v1/projects/{projectId}/runs/{runId}/case-config`       | 確認待ちのワークフローの実行の案件設定を置き換える |

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

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

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

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

#### パスパラメータ

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

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

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

| パラメータ     | 型        | 必須 | 説明                                                                                                                                                                                                                                                                                                                                                                   |
| --------- | -------- | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payload` | `any`    | —  | 実行の依頼。JSON の値（オブジェクト・配列・文字列など）を、中身を変えずに受け取ります。最初の工程のエージェントが context.start\_input で受け取ります（マーケットプレイスのワークフローガイドの「外から始めた run の依頼」を参照）。依頼の中にファイルの ID を入れても、ファイルは添付されません。省略・null は依頼なし。JSON の文字列にして 8,000 文字まで                                                                                                                                                             |
| `config`  | `object` | —  | 入力ファイルと工程の設定。{ "placements": \[{ "placementId", "stepId", "parameters", "connectionBindings", "fileBindings" }] } の形で、配置と工程の組ごとに書きます。fileBindings は入力ファイルの名前（置ける登録 Agent の一覧の inputs\[].name）から、上げた下書きの artifactId への対応、parameters は登録 Agent の parameters（parametersSchema の形）、connectionBindings は接続の枠の名前から連携先の ID への対応です。placementId・stepId のほかは省けます。省略・null は設定なし |

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

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

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

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

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

#### リクエスト例

**Start run**

**curl**

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

**Python**

```python
import requests

response = requests.post(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs",
  headers={"Authorization": f"Bearer {token}", "Idempotency-Key": "nightly-batch-20260917"},
  json={'payload': {'ticketId': 'INC-1024', 'summary': 'ログインできない利用者がいる'}},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Idempotency-Key": "nightly-batch-20260917",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"payload": {"ticketId": "INC-1024", "summary": "ログインできない利用者がいる"}}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"payload": {"ticketId": "INC-1024", "summary": "ログインできない利用者がいる"}}`)
req, _ := http.NewRequest("POST", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Idempotency-Key", "nightly-batch-20260917")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### レスポンス例

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

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

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

#### リクエスト例

**Get run**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### レスポンスフィールド（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。プロジェクトに参加していない、組織の運用の役割の人には 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。案件設定を直すときは、この値ではなく、案件設定の取得で読む revision を使います（読んだ後に入った変更を上書きしないため）                                                                          |
| `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` | 工程の出力の要約。プロジェクトに参加していない、組織の運用の役割の人には null（中断で閉じた工程の "cancelled" は残ります）                                                                                                                   |
| `steps[].outcome`                 | `string \| null` | Agent の実行の結果。"completed" / "incomplete" / "failed" / "timeout" / "stopped" / "denied" / "skipped" のいずれか。結果の無い行では null                                                                    |
| `steps[].reasonCode`              | `string \| null` | 結果の理由コード。条件分岐で決められず人に選択してもらうときは "branch\_undecided"、条件分岐で選ばれなかったレーンの工程は "branch\_not\_selected"                                                                                          |
| `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": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
  "status": "running",
  "originType": "api",
  "originRef": "nightly-batch-20260917",
  "currentStepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
  "startedByRef": "client:order-batch",
  "actorLabel": null,
  "startedAt": "2026-09-17T01:30:00.000Z",
  "endedAt": null,
  "summary": null,
  "runtimeKind": "marketplace",
  "cancelRequestedAt": null,
  "deadlineAt": null,
  "configRevision": 1,
  "steps": [
    {
      "runStepId": "rs:1042",
      "stepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
      "placementId": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8",
      "executionId": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
      "conversationId": null,
      "status": "running",
      "attempt": 1,
      "lane": "main",
      "scheduledAt": null,
      "startedAt": "2026-09-17T01:30:01.000Z",
      "endedAt": null,
      "outputSummary": null,
      "outcome": null,
      "reasonCode": null,
      "held": false,
      "visit": 1,
      "reworkReason": null,
      "gateFor": null,
      "routedFrom": null,
      "late": null,
      "gate": null,
      "resumeCommandId": null,
      "resumeReason": null,
      "supersededBy": null,
      "gateKind": null,
      "connectionConfirmOf": null
    }
  ],
  "plannedPlacements": [
    { "stepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f", "placementId": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8" },
    { "stepId": "c2f1a8e4-6b3d-4e7a-9c15-8d2e4f6a7b90", "placementId": null }
  ],
  "lanes": []
}
```

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

| ステータス | code                | 説明                                    |
| ----- | ------------------- | ------------------------------------- |
| `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） |

#### リクエスト例

**List runs**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs",
  headers={"Authorization": f"Bearer {token}"},
  params={"limit": "20"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs" + "?limit=20",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs?limit=20", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

#### レスポンス例

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

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

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

#### リクエスト例

**Get run config**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/config",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/config",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/config", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

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

#### レスポンス例

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

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

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

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

#### リクエスト例

**Set run deadline**

**curl**

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

**Python**

```python
import requests

response = requests.patch(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
  headers={"Authorization": f"Bearer {token}"},
  json={'deadlineAt': '2026-11-20T09:00:00.000Z'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
{
  method: "PATCH",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"deadlineAt": "2026-11-20T09:00:00.000Z"}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"deadlineAt": "2026-11-20T09:00:00.000Z"}`)
req, _ := http.NewRequest("PATCH", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

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

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

#### レスポンス例

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

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

| ステータス | code                        | 説明                                                                          |
| ----- | --------------------------- | --------------------------------------------------------------------------- |
| `400` | `invalid_parameter`         | projectId・runId が UUID の形式ではない、または deadlineAt が無い・ISO 8601 の日時ではない・今より後ではない |
| `400` | `invalid_body`              | ボディが壊れた JSON、または JSON のオブジェクトではない                                           |
| `403` | `forbidden`                 | システム連携のトークンで呼び出した                                                           |
| `403` | `operator_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` が空になることがあります。結果は、ワークフローの実行の取得と確認依頼の取得で確かめてください。

#### リクエスト例

**Reassign run approvers**

**curl**

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

**Python**

```python
import requests

response = requests.put(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/approvers",
  headers={"Authorization": f"Bearer {token}"},
  json={'approverUserIds': ['f47ac10b-58cc-4372-a567-0e02b2c3d479'], 'commandId': 'reassign-20261118-0001'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/approvers",
{
  method: "PUT",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"approverUserIds": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], "commandId": "reassign-20261118-0001"}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"approverUserIds": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], "commandId": "reassign-20261118-0001"}`)
req, _ := http.NewRequest("PUT", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/approvers", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

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

#### レスポンス例

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

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

| ステータス | 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` | `operator_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 ではない                                                                                         |

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

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

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

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

#### パスパラメータ

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

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

| フィールド       | 型        | 必須 | 説明                                   |
| ----------- | -------- | -- | ------------------------------------ |
| `commandId` | `string` | 必須 | 送り直しを見分ける値（英数字と \_ . : - の 8〜128 文字） |
| `reason`    | `string` | —  | 中断の理由（500 文字まで）                      |

- 動いていないワークフローの実行（終わった後・中断した後）に送ると、何も変えずに `200 OK` が返り、`existing` が `true` です。中断した後に送り直したときも同じです。
- ほかの中断や、ワークフローの実行が終わるのと同じころに送ると、`202 Accepted` と `200 OK` の別と `existing` が、実際と合わないことがあります。結果は、ワークフローの実行の取得（`GET /v1/projects/{projectId}/runs/{runId}`）の `status` で確かめてください。
- `504 Gateway Timeout` は「中断されなかった」ことを意味しません。同じ `commandId` で送り直すか、ワークフローの実行の取得で `status` を確かめてください。

#### リクエスト例

**Cancel run**

**curl**

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

**Python**

```python
import requests

response = requests.post(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/cancel",
  headers={"Authorization": f"Bearer {token}"},
  json={'commandId': 'cancel-20261118-0001', 'reason': '入力データの誤りに気づいたため'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/cancel",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"commandId": "cancel-20261118-0001", "reason": "入力データの誤りに気づいたため"}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"commandId": "cancel-20261118-0001", "reason": "入力データの誤りに気づいたため"}`)
req, _ := http.NewRequest("POST", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/cancel", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

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

| フィールド               | 型                | 説明                                                 |
| ------------------- | ---------------- | -------------------------------------------------- |
| `runId`             | `string`         | ワークフローの実行の ID                                      |
| `status`            | `string`         | 送った後のワークフローの実行の状態（中断したときは "cancelled"）             |
| `cancelRequestedAt` | `string \| null` | 中断を受けた日時（ISO 8601）。中断されていないワークフローの実行では null        |
| `existing`          | `boolean`        | この要求で新しく中断しなかったとき true（202 Accepted のときはいつも false） |

#### レスポンス例

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

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

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

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

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

#### パスパラメータ

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

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

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

#### リクエスト例

**Get case-config**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/case-config",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/case-config",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/case-config", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### レスポンス例

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

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

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

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

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

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

#### パスパラメータ

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

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

| フィールド              | 型        | 必須 | 説明                                                                                             |
| ------------------ | -------- | -- | ---------------------------------------------------------------------------------------------- |
| `expectedRevision` | `number` | 必須 | 案件設定の取得で読んだ revision（1 以上の整数）。今の版と違うと 409 Conflict（revision\_conflict）                         |
| `commandId`        | `string` | 必須 | 送り直しを見分ける値（英数字と \_ . : - の 8〜128 文字）                                                           |
| `config`           | `object` | 必須 | { "placements": \[...] } の形の新しい案件設定。placements は必須の配列です。配置と工程の組の項目は、ワークフローの実行の開始の config と同じです |

- 上限: `config` を JSON にした長さは 262,144 文字までです（超えると `400 Bad Request`（`invalid_config`））。ボディ全体が 787,456 バイトを超えると `413 Payload Too Large`（`body_too_large`）です。
- 同じ `commandId` で同じ内容を送り直すと、1 回目の結果が返ります（`existing` が `true`）。同じ `commandId` で違う内容を送ると `409 Conflict`（`command_conflict`）です。

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

| フィールド        | 型                | 説明                                                                                                                  |
| ------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------- |
| `revision`   | `number`         | 置き換えた後の案件設定のバージョン                                                                                                   |
| `placements` | `array`          | 置き換えた後の設定。項目は案件設定の取得と同じです                                                                                           |
| `gate`       | `object \| null` | 確認待ちの確認依頼（workItemId・contextVersion・basisDigest）。決めるときは、この contextVersion・basisDigest か、確認依頼を取得し直した値を使います。無ければ null |
| `existing`   | `boolean`        | 同じ commandId の送り直しで、1 回目の結果を返したときは true                                                                             |

#### リクエスト例

**Replace case-config**

**curl**

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

**Python**

```python
import requests

response = requests.put(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/case-config",
  headers={"Authorization": f"Bearer {token}"},
  json={'expectedRevision': 2, 'commandId': 'fix-contract-20261110-01', 'config': {'placements': [{'placementId': '0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d', 'stepId': '5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819', 'parameters': {'language': 'ja'}, 'fileBindings': {'contract': '8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6'}}]}},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/case-config",
{
  method: "PUT",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"expectedRevision": 2, "commandId": "fix-contract-20261110-01", "config": {"placements": [{"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819", "parameters": {"language": "ja"}, "fileBindings": {"contract": "8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6"}}]}}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"expectedRevision": 2, "commandId": "fix-contract-20261110-01", "config": {"placements": [{"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819", "parameters": {"language": "ja"}, "fileBindings": {"contract": "8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6"}}]}}`)
req, _ := http.NewRequest("PUT", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/case-config", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### レスポンス例

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

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

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

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

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

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

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

#### パスパラメータ

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

#### リクエストボディ（multipart/form-data）

| パラメータ    | 型        | 必須 | 説明                                                                                 |
| -------- | -------- | -- | ---------------------------------------------------------------------------------- |
| `files`  | `file`   | 必須 | 上げるファイル。1 つだけ                                                                      |
| `name`   | `string` | 必須 | 入力ファイルの名前（1〜128 文字）。置ける登録 Agent の一覧の inputs\[].name                                |
| `format` | `string` | 必須 | 形式。"markdown"・"yaml"・"json"・"text"・"binary" のどれか。置ける登録 Agent の一覧の inputs\[].format |

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

#### リクエスト例

**Upload draft artifact**

**curl**

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

**Python**

```python
import requests

with open("invoice.json", "rb") as f:
  response = requests.post(
      "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/artifacts",
      headers={"Authorization": f"Bearer {token}"},
      files={"files": f},
      data={"name": "invoice", "format": "json"},
  )

print(response.json())
```

**TypeScript**

```typescript
const formData = new FormData();
formData.append("files", file); // File object
formData.append("name", "invoice");
formData.append("format", "json");

const response = await fetch("https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/artifacts", {
method: "POST",
headers: { "Authorization": "Bearer " + accessToken },
body: formData,
});

const data = await response.json();
console.log(data);
```

**Go**

```go
file, _ := os.Open("invoice.json")
defer file.Close()

body := &bytes.Buffer{}
writer := multipart.NewWriter(body)
part, _ := writer.CreateFormFile("files", "invoice.json")
io.Copy(part, file)
writer.WriteField("name", "invoice")
writer.WriteField("format", "json")
writer.Close()

req, _ := http.NewRequest("POST", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/artifacts", body)
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", writer.FormDataContentType())
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

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

| フィールド        | 型                | 説明                                             |
| ------------ | ---------------- | ---------------------------------------------- |
| `artifactId` | `string`         | 下書きの ID（UUID）。開始の config の fileBindings に指定します |
| `runId`      | `string \| null` | 下書きでは null                                     |
| `name`       | `string \| null` | 成果物の名前                                         |
| `mimeType`   | `string \| null` | 成果物の MIME タイプ                                  |
| `size`       | `number \| null` | 大きさ（バイト）                                       |
| `status`     | `string \| null` | "ready"                                        |
| `createdAt`  | `string \| null` | 作られた日時（ISO 8601）                               |

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

#### レスポンス例

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

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

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

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

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

#### パスパラメータ

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

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

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

#### リクエスト例

**List run artifacts**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/artifacts",
  headers={"Authorization": f"Bearer {token}"},
  params={"run_id": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13"},
)

with open("artifact.bin", "wb") as f:
  f.write(response.content)
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/artifacts" + "?run_id=7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const bytes = new Uint8Array(await response.arrayBuffer());
console.log(bytes.length);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/artifacts?run_id=7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

body, _ := io.ReadAll(resp.Body)
os.WriteFile("artifact.bin", body, 0644)
```

#### レスポンスフィールド（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）                       |
| `hasMore`                | `boolean`        | いつも false（全件を返します）                     |

#### レスポンス例

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

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

| ステータス | code                | 説明                                                    |
| ----- | ------------------- | ----------------------------------------------------- |
| `400` | `invalid_parameter` | projectId が UUID の形式ではない、または run\_id が無い・UUID の形式ではない |
| `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 |

#### リクエスト例

**Get run artifact content**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/artifacts/1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d/content",
  headers={"Authorization": f"Bearer {token}"},
)

with open("artifact.bin", "wb") as f:
  f.write(response.content)
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/artifacts/1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d/content",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const bytes = new Uint8Array(await response.arrayBuffer());
console.log(bytes.length);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/artifacts/1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d/content", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

body, _ := io.ReadAll(resp.Body)
os.WriteFile("artifact.bin", body, 0644)
```

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

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

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

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

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

### 結果の値

`outcome`（結果）の値です。画面の表示は[結果リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/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 値）                                                                                                                                                                    |

#### リクエスト例

**List executions**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions",
  headers={"Authorization": f"Bearer {token}"},
  params={"outcome": "success", "limit": "20"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions" + "?outcome=success&limit=20",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions?outcome=success&limit=20", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

#### レスポンス例

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

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

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

システム連携のトークンで呼ぶと、状態の項目（`executionId`・`kind`・`runId`・`stepId`・`placementId`・`attempt`・`outcome`・`reasonCode`・`resultState`・`terminal`・`startedAt`・`endedAt`）だけを返します（[システム連携 API リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/api-reference.md#projects)）。

#### パスパラメータ

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

#### リクエスト例

**Get execution**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/rs:1842",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/rs:1842",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/rs:1842", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

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

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

#### レスポンス例

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

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

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

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

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

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

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

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

#### リクエスト例

**List execution operations**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/rs:1842/operations",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/rs:1842/operations",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/rs:1842/operations", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

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

#### レスポンス例

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

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

| ステータス | code                  | 説明                                          |
| ----- | --------------------- | ------------------------------------------- |
| `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 値） |

#### リクエスト例

**Get execution timeline**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/rs:1842/timeline",
  headers={"Authorization": f"Bearer {token}"},
  params={"limit": "50"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/rs:1842/timeline" + "?limit=50",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/rs:1842/timeline?limit=50", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

| フィールド                        | 型                | 説明                                                                                                          |
| ---------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------- |
| `rootExecutionId`            | `string`         | 実行の ID                                                                                                      |
| `origin`                     | `string \| null` | 実行の始まり。"job"（ジョブ）/ "chat"（チャット）                                                                             |
| `owner`                      | `object`         | 実行の持ち主                                                                                                      |
| `owner.userId`               | `string \| null` | 持ち主の利用者 ID。分からないときは null                                                                                    |
| `executions`                 | `object`         | 実行の要約（items）。結果・設定・ツールの呼び出しの数など                                                                             |
| `timeline`                   | `object`         | 記録の行（items）                                                                                                 |
| `timeline.items[].at`        | `string`         | 記録の日時                                                                                                       |
| `timeline.items[].key`       | `number`         | 記録の ID。"tool.access" の行は、ツールの呼び出しの一覧の operationId と対応します（呼び出しの ID がある行は `call:<呼び出しの ID>`、無い行は `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`         | 消された会話・リソース                                                                                                 |
| `deleted.conversations`      | `string[]`       | 消された会話の ID                                                                                                  |
| `deleted.resources`          | `string[]`       | 消されたリソース（ファイルなど）。このページの `timeline.items[].resource` に出るものだけ                                                 |
| `hasMore`                    | `boolean`        | 続きがあるかどうか                                                                                                   |
| `cursor`                     | `string`         | 次ページ取得用カーソル。hasMore が true の場合のみ含まれます                                                                       |
| `snapshotAt`                 | `string \| null` | 記録を読んだ日時                                                                                                    |

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

#### レスポンス例

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

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

| ステータス | code                  | 説明                                                               |
| ----- | --------------------- | ---------------------------------------------------------------- |
| `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`   | 記録を読む機能が使えない                                                     |

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

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

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

#### パスパラメータ

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

#### リクエスト例

**Cancel execution**

**curl**

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

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/a1b2c3d4-e5f6-4789-8abc-def012345678/cancel",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/a1b2c3d4-e5f6-4789-8abc-def012345678/cancel",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/a1b2c3d4-e5f6-4789-8abc-def012345678/cancel", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

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

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

#### レスポンス例

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

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

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

## ファイル

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

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

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

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

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

#### パスパラメータ

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

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

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

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

#### リクエスト例

**Get project file content**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/files/content",
  headers={"Authorization": f"Bearer {token}"},
  params={"path": "/users/f47ac10b-58cc-4372-a567-0e02b2c3d479/plans/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/deliverables/report.pdf"},
)

with open("report.pdf", "wb") as f:
  f.write(response.content)
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/files/content" + "?path=/users/f47ac10b-58cc-4372-a567-0e02b2c3d479/plans/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/deliverables/report.pdf",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const bytes = new Uint8Array(await response.arrayBuffer());
console.log(bytes.length);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/files/content?path=/users/f47ac10b-58cc-4372-a567-0e02b2c3d479/plans/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/deliverables/report.pdf", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

body, _ := io.ReadAll(resp.Body)
os.WriteFile("report.pdf", body, 0644)
```

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

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

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

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

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

## 記録 (証跡)

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

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

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

#### リクエスト例

**List audit events**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/audit",
  headers={"Authorization": f"Bearer {token}"},
  params={"kind": "policy.changed", "limit": "20"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/audit" + "?kind=policy.changed&limit=20",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/audit?kind=policy.changed&limit=20", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

#### レスポンス例

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

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

| ステータス | code                | 説明                                                                                                           |
| ----- | ------------------- | ------------------------------------------------------------------------------------------------------------ |
| `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

画面の概要の「この業務の実行結果」と同じ値を取得します（工程ごとの `steps` は、概要の「ワークフローの形」の「数値」に出る値です。確認工程だけの値は `gates` にもあります）。数え方は[結果リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/reference/results-ref.md)を参照してください（工程ごとの値は[工程ごとの数値](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/reference/results-ref.md#工程ごとの数値)）。

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

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

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

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

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

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

#### リクエスト例

**Get project KPI**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/kpi",
  headers={"Authorization": f"Bearer {token}"},
  params={"days": "30"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/kpi" + "?days=30",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/kpi?days=30", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

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

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

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

#### レスポンス例

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

<!-- -->

## 確認依頼

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

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

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

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

### GET`/v1/workitems`

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

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

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

#### リクエスト例

**List work items**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/workitems",
  headers={"Authorization": f"Bearer {token}"},
  params={"state": "open", "limit": "20"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/workitems" + "?state=open&limit=20",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/workitems?state=open&limit=20", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

#### レスポンス例

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

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

| ステータス | code                | 説明                                                                                                      |
| ----- | ------------------- | ------------------------------------------------------------------------------------------------------- |
| `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） |

#### リクエスト例

**Get work item**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/workitems/c9d8e7f6-a5b4-4321-8fed-cba098765432",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/workitems/c9d8e7f6-a5b4-4321-8fed-cba098765432",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/workitems/c9d8e7f6-a5b4-4321-8fed-cba098765432", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

#### レスポンス例

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

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

| ステータス | code                 | 説明                        |
| ----- | -------------------- | ------------------------- |
| `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 の工程に戻します |
| `destinationId`    | `string`  | —  | 進め先（"proceed" のとき。gate の destinations の destinationId。64 文字まで）。進め先のある確認依頼を進めるときは必須              |
| `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` で送り直してください。

#### リクエスト例

**Decide work item**

**curl**

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

**Python**

```python
import requests

response = requests.post(
  "https://<your-domain>/api/v1/workitems/c9d8e7f6-a5b4-4321-8fed-cba098765432/decision",
  headers={"Authorization": f"Bearer {token}"},
  json={'decision': 'proceed', 'reason': '差異は税込・税抜の違いだったため', 'contextVersion': 1, 'basisDigest': '3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b', 'commandId': 'decide-20261118-0001'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/workitems/c9d8e7f6-a5b4-4321-8fed-cba098765432/decision",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"decision": "proceed", "reason": "差異は税込・税抜の違いだったため", "contextVersion": 1, "basisDigest": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b", "commandId": "decide-20261118-0001"}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"decision": "proceed", "reason": "差異は税込・税抜の違いだったため", "contextVersion": 1, "basisDigest": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b", "commandId": "decide-20261118-0001"}`)
req, _ := http.NewRequest("POST", "https://<your-domain>/api/v1/workitems/c9d8e7f6-a5b4-4321-8fed-cba098765432/decision", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

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

#### レスポンス例

```json
{
  "decision": "proceed",
  "channel": "api"
}
```

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

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

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

#### リクエスト例

**Extend work item**

**curl**

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

**Python**

```python
import requests

response = requests.patch(
  "https://<your-domain>/api/v1/workitems/c9d8e7f6-a5b4-4321-8fed-cba098765432",
  headers={"Authorization": f"Bearer {token}"},
  json={'expiresAt': '2026-11-22T09:00:00.000Z'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/workitems/c9d8e7f6-a5b4-4321-8fed-cba098765432",
{
  method: "PATCH",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"expiresAt": "2026-11-22T09:00:00.000Z"}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"expiresAt": "2026-11-22T09:00:00.000Z"}`)
req, _ := http.NewRequest("PATCH", "https://<your-domain>/api/v1/workitems/c9d8e7f6-a5b4-4321-8fed-cba098765432", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

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

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

#### レスポンス例

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

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

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

## キュー

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

- プロジェクトのキュー（`GET /v1/projects/{projectId}/queue`）は、そのプロジェクトの全部の行を返します。プロジェクトのメンバーと、組織の運用の役割の人なら読めます。
- 自分のキュー（`GET /v1/queue`）は、参加しているプロジェクトのうち、自分が担当の行を返します。ほかの利用者の期間中の代理人になっているときは、その人の確認依頼の行も返します。
- 行への操作は、下の表の「使う ID」（行に入っている ID。行の ID の `queueItemId` ではありません）を、その API に渡して行います。

| すること                  | 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（行の ID の `:` の後ろ）の順で、変えられません。カーソルベースのページネーションに対応しています。

#### パスパラメータ

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

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

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

#### リクエスト例

**List project queue**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/queue",
  headers={"Authorization": f"Bearer {token}"},
  params={"kind": "gate_pending", "limit": "20"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/queue" + "?kind=gate_pending&limit=20",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/queue?kind=gate_pending&limit=20", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

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

#### レスポンス例

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

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

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

### GET`/v1/queue`

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

#### リクエスト例

**List my queue**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/queue",
  headers={"Authorization": f"Bearer {token}"},
  params={"kind": "gate_pending", "limit": "20"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/queue" + "?kind=gate_pending&limit=20",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/queue?kind=gate_pending&limit=20", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### レスポンス例

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

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

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

## 連携先

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

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

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

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

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

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

#### パスパラメータ

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

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

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

#### リクエスト例

**Get MCP connector**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/connectors/mcp/12",
  headers={"Authorization": f"Bearer {token}"},
  params={"projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/connectors/mcp/12" + "?projectId=3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/connectors/mcp/12?projectId=3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

#### レスポンス例

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

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

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

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

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

#### パスパラメータ

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

#### リクエスト例

**Get A2A connector**

**curl**

```curl
curl https://<your-domain>/api/v1/connectors/a2a/7 \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/connectors/a2a/7",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/connectors/a2a/7",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/connectors/a2a/7", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

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

#### レスポンス例

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

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

| ステータス | code                  | 説明                             |
| ----- | --------------------- | ------------------------------ |
| `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/marketplace/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`               | リソースが現在処理中など、操作が競合                                                                                                                                                                        |
| `409 Conflict`               | 組織の運用の役割（管理コンソールの「管理の役割」で付ける「運用」の役割）の人が、プロジェクトに参加せずに、その役割では使えない操作を呼んだ（`error.code` は `forbidden_role`）。待っても直りません。オーナーだけの操作は、プロジェクトのオーナーに頼んでください。ほかの操作は、オーナーにプロジェクトに加えてもらうと、参加の役割のとおりに呼べます |
| `413 Payload Too Large`      | リクエストボディがサイズ上限を超過                                                                                                                                                                         |
| `415 Unsupported Media Type` | リクエストボディの形式（Content-Type）に対応していない                                                                                                                                                         |
| `429 Too Many Requests`      | レート制限または同時実行の上限を超過。`error.type` は `rate_limit_error` で、`error.code` はエンドポイントにより異なります（例: 月間上限は `monthly_quota_exceeded`、プロジェクトの同時実行は `too_many_active_runs`）。時間をおいて再試行してください               |
| `500 Internal Server Error`  | サーバー内部エラー                                                                                                                                                                                 |
| `502 Bad Gateway`            | 上流サービス（認証基盤・チャット基盤等）との通信エラー                                                                                                                                                               |
| `503 Service Unavailable`    | サービス一時利用不可                                                                                                                                                                                |
| `504 Gateway Timeout`        | 上流サービスの応答タイムアウト                                                                                                                                                                           |

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

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

| フィールド                    | 型        | 説明                                                                                                                                                                                                                                       |
| ------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `error.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.reason`           | `string` | 断りの理由の種類。プロジェクト API の 409（definition\_invalid）のときだけ含まれます                                                                                                                                                                                 |
| `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"
  }
}
```

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

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

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