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

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

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

## ベース URL

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

SaaS

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

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

## 認証

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

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

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

| スコープ             | できること                                                                                                 |
| ---------------- | ----------------------------------------------------------------------------------------------------- |
| `project:read`   | プロジェクトと、その中のもの（工程・配置・実行・記録 (証跡)・KPI・ライブラリなど）、確認依頼、連携先、キューを読む                                          |
| `project:write`  | プロジェクトを作る・変える、工程と配置を変える、トリガーと Webhook を作る・変える・消す、ワークフローの実行の締め切りと確認担当者を変える、プロジェクトのライブラリのファイルを足す・変える・消す |
| `project:delete` | プロジェクトを消す                                                                                             |
| `project:run`    | ワークフローの実行を始める、トリガーを発火する、失敗した巡回をもう一度動かす、閉じたワークフローの実行を再開する、ワークフローの実行を中断する                               |
| `project:decide` | 確認依頼を判断する、確認依頼の期限を延ばす                                                                                 |

`project:*` のスコープは、名前がぴったり合うときだけ使えます。トークンの取得方法・スコープの詳細については、[認証ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/auth-guide.md) および [認証 API リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/auth-saas-ref.md) を参照してください。

## 共通の決まり

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

### 呼べる人と 404・403

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

| 操作                                                                | オーナー | 運用担当 | メンバー                            | 組織の運用の役割 ※1 | 呼べない人への断り                                                                         |
| ----------------------------------------------------------------- | ---- | ---- | ------------------------------- | ----------- | --------------------------------------------------------------------------------- |
| プロジェクトとその中のもの（工程・配置・実行など）を読む                                      | ○    | ○    | ○                               | 一部 ※2       | —                                                                                 |
| ワークフローの実行の開始・トリガーの発火                                              | ○    | ○    | ○                               | ○           | —                                                                                 |
| ほかの運転の操作 ※3                                                       | ○    | ○    | ×（ワークフローの実行の中断は、その実行を始めた本人なら ○） | ○           | `403 Forbidden`（`operator_only`）                                                  |
| プロジェクトのライブラリのファイルの登録・取り込み・新しいバージョン・前のバージョンに戻す・元の成果物の新しいバージョンの取り込み | ○    | ○    | ○                               | ×           | 参加していない組織の運用の役割の人は `409 Conflict`（`forbidden_role`）                               |
| 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` です。プロジェクトが見えないときも、そのエンドポイントの code で返ります |
| ボディで指定した ID（Agent・工程・利用者など）が存在しない・見えない                       | エンドポイントごとに違います（例: 配置の `agentId` は `400 Bad Request`（`agent_not_found`）、配置の `stepIds` は `400 Bad Request`（`invalid_parameter`））。各エンドポイントの説明とエラーレスポンスを参照してください                        |
| 一覧を絞り込むクエリ（`placement_id`・`step_id`・`run_id`）に存在しない ID を指定した | 空の一覧が返ります                                                                                                                                                                           |
| SSO でログインしていない利用者のトークン                                       | プロジェクト・確認依頼・キューの 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              |
| プロジェクトのライブラリにファイルを送る               | ファイル 1 つが 512 MB まで |
| ほかの API                            | 16 KiB              |

レスポンスには `x-request-id` ヘッダーが付きます。サービス側で採番する値で、リクエストで送った値は使われません。お問い合わせの際はこの値をお知らせください。

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

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

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

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

| API                                             | 送り直しを見分けるもの                | 同じもので送り直すと                                     |
| ----------------------------------------------- | -------------------------- | ---------------------------------------------- |
| ワークフローの実行の開始                                    | `Idempotency-Key` ヘッダー（必須） | 1 回目の結果が返ります                                   |
| トリガーの発火                                         | ボディの `eventId`             | 1 回目の結果が返ります                                   |
| 確認依頼の判断・確認担当者の付け替え・閉じたワークフローの実行の再開・ワークフローの実行の中断 | ボディの `commandId`           | 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 つの型があります。型は作るときに決め、後から変えられません。

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

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

### 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://api.fd.agenticstar.tm.softbank.jp/api/v1/projects?limit=20" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects",
  headers={"Authorization": f"Bearer {token}"},
  params={"limit": "20"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects" + "?limit=20",
{
  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?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） |
| `403` | project:read スコープが不足（code は insufficient\_scope）                     |

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

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

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

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

#### リクエスト例

**List shared projects**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/shared?type=workflow&limit=20" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/shared",
  headers={"Authorization": f"Bearer {token}"},
  params={"type": "workflow", "limit": "20"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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` | `insufficient_scope` | project:read スコープが不足               |
| `403` | `forbidden`          | システム連携のトークンで呼び出した                  |
| `403` | `sso_required`       | SSO でログインしていない利用者                  |

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

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

#### リクエスト例

**Get project organizations**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/organizations \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/organizations",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/organizations",
{
  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/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` | `insufficient_scope`       | project:read スコープが不足              |
| `403` | `forbidden`                | システム連携のトークンで呼び出した                 |
| `403` | `sso_required`             | SSO でログインしていない利用者                 |
| `503` | `organization_unavailable` | 所属している組織を確かめられない（時間をおいて送り直してください） |

### GET`/v1/projects/automation-destinations`

外部の自動化の工程（`defaultZone` が `"automation"`）に設定できる宛先の一覧を取得します。宛先は管理者が管理コンソールで登録したもので、工程の `automationConfig.destinationId` に、ここで返る `destinationId` を指定します。宛先の URL と鍵は返しません。名前の順に、500 件までを返します。

#### リクエスト例

**List automation destinations**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/automation-destinations \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/automation-destinations",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/automation-destinations",
{
  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/automation-destinations", 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）

| フィールド                          | 型                | 説明                                                                                |
| ------------------------------ | ---------------- | --------------------------------------------------------------------------------- |
| `destinations`                 | `array`          | 宛先の配列（名前の順。500 件まで）                                                               |
| `destinations[].destinationId` | `string`         | 宛先の ID（UUID）                                                                      |
| `destinations[].name`          | `string \| null` | 宛先の名前                                                                             |
| `destinations[].active`        | `boolean`        | 有効かどうか。無効の宛先を指定した工程は、保存・実行の開始ができません                                               |
| `dlpEnabled`                   | `boolean`        | 管理コンソールの「DLP 連携」が有効（OFF 以外）かどうか。設定を読めないときも true。true の間は、外部の自動化の工程を保存・有効化・実行できません |
| `hasMore`                      | `boolean`        | いつも false（500 件を超える分は返しません）                                                       |

#### レスポンス例

```json
{
  "destinations": [
    {
      "destinationId": "b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e",
      "name": "経費精算システム",
      "active": true
    }
  ],
  "dlpEnabled": false,
  "hasMore": false
}
```

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

| ステータス | code                                  | 説明                                               |
| ----- | ------------------------------------- | ------------------------------------------------ |
| `403` | `insufficient_scope`                  | project:read スコープが不足                             |
| `403` | `forbidden`                           | システム連携のトークンで呼び出した                                |
| `403` | `sso_required`                        | SSO でログインしていない利用者                                |
| `409` | `automation_destinations_unavailable` | この環境では外部の自動化の宛先を使えない。管理者に、外部の自動化の宛先を用意してもらってください |

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

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

#### パスパラメータ

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

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

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

#### リクエスト例

**Get project**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31 \
-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",
  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",
{
  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", 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}）で中身を読めます。ログインが要らない連携先にも ID が入ります。管理コンソールで無効にされた・削除された連携先と、連携先の情報を確かめられなかったときは null                                                                                                                                                                                                                                                                                                                |
| `connectors[].name`                | `string \| null`  | 連携先の名前                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `connectors[].ledgerEnabled`       | `boolean \| null` | 共通の記録先にする連携先かどうか                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `connectors[].confirmMode`         | `string \| null`  | この連携先を使う前に、人の確認を求めるか。"none"（求めない）/ "first\_per\_execution"（実行ごとに最初の 1 回）/ "always"（使うたび）。A2A の連携先はいつも "none" です。確認は確認依頼（gateKind が "connection"）として届き、承認すると Agent を起動し直します。承認が効くのは、workflow の "first\_per\_execution" では同じワークフローの実行の後の工程まで、"always" では起動し直した回（そこからさらに確認を求めて起動し直した回を含みます）だけです。cycle にはワークフローの実行の区切りが無いので、"first\_per\_execution" も "always" と同じです。画面で設定します                                                                                   |
| `connectors[].confirmWaitMinutes`  | `number \| null`  | その確認を待つ時間の上限（分）                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `connectors[].login`               | `string \| null`  | ログインの状態。"connected"（ログイン済み）/ "reauth\_required"（ログインし直しが必要）/ "not\_connected"（未ログイン）/ "not\_required"（ログインが要らない連携先）。状態を確かめられないときは 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・公開・削除<!-- -->はオーナーだけです<!-- -->。組織の運用の役割の人も、参加していなくても、運用担当の操作を呼べます。組織の運用の役割も持たないメンバーが運用担当の操作を呼ぶと `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 時間）                                                |
| `limits.maxMinutesPerRun`    | `number \| null`  | 1 回の実行の長さの上限（分）。5・15・30・60・90・120 のどれか。無いとき・null のときは、この上限を付けていません                  |
| `language`                   | `string \| null`  | プロジェクトの言語                                                                           |
| `flowStructure`              | `object \| null`  | レーンの定義（workflow で、工程を並行して進めるとき）。下の「レーンの定義」を参照                                       |
| `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 に送る値                                                       |

レーンの定義（`flowStructure`）:

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

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

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

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

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

| 値                       | 意味                            |
| ----------------------- | ----------------------------- |
| `approvers_required`    | 人の確認の工程に、今もメンバーの確認担当者がいない     |
| `start_step_after_fork` | 始める工程が、分かれた後（レーンの中）にある        |
| `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` は返しません。

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

#### レスポンス例

```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,
      "maxMinutesPerRun": null
    },
    "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": "lGx3-Zc_YrHdaUo_vpWqlGviCDvwmnk9df9KcrJKYqM",
    "adminStop": null,
    "orgOperator": false,
    "relink": null
  },
  "steps": [
    {
      "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
      "position": 1,
      "name": "金額の確認",
      "description": "請求書の金額と明細を照合します",
      "enabled": true,
      "defaultZone": "ai",
      "automationConfig": null,
      "branchConfig": null,
      "reworkToStepId": null,
      "gateConfig": null,
      "gateKind": null,
      "schedule": null,
      "scheduleNextFireAt": null,
      "onDenied": null,
      "onDegraded": null,
      "outcomeRoutes": null,
      "laneId": null,
      "placementExecution": null,
      "outputConfig": null,
      "digest": "jZ38OtGgLnS14QCvjZdg5PdyrGEHPK0EhxgDZzEnE2Y"
    },
    {
      "stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "position": 2,
      "name": "差異の確認",
      "description": null,
      "enabled": true,
      "defaultZone": "gate",
      "automationConfig": null,
      "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,
      "outputConfig": null,
      "digest": "27bA5P1PM8JFDwEEZhLP5DDn77Q8MFWq-YcGa6q8Sso"
    },
    {
      "stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
      "position": 3,
      "name": "差異の報告",
      "description": null,
      "enabled": true,
      "defaultZone": "ai",
      "automationConfig": null,
      "branchConfig": null,
      "reworkToStepId": null,
      "gateConfig": null,
      "gateKind": null,
      "schedule": null,
      "scheduleNextFireAt": null,
      "onDenied": null,
      "onDegraded": null,
      "outcomeRoutes": null,
      "laneId": null,
      "placementExecution": null,
      "outputConfig": 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": "経理 Agent",
      "description": "請求書の金額と明細を照合します",
      "goal": "請求書の金額と明細を照合し、差異を報告する",
      "guardrail": "金額を書き換えない",
      "skills": [
        {
          "skillId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
          "name": "請求書の読み取り"
        }
      ],
      "skillCount": 1,
      "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,
      "instructionAddendum": null,
      "agentOwnerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "isShared": false,
      "runtimeKind": "autonomous",
      "marketplaceAgentId": null,
      "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` | `insufficient_scope` | project:read スコープが不足                   |
| `403` | `forbidden`          | システム連携のトークンで呼び出した                      |
| `403` | `sso_required`       | SSO でログインしていない利用者                      |
| `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://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/definition \
-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/definition",
  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/definition",
{
  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/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` | `insufficient_scope` | project:read スコープが不足                 |
| `403` | `forbidden`          | システム連携のトークンで呼び出した                    |
| `403` | `owner_only`         | オーナーではないメンバー                         |
| `403` | `sso_required`       | SSO でログインしていない利用者                    |
| `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,
      "maxMinutesPerRun": null
    },
    "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": "kzBrbi0YeE0_5B4uneAqHvcVkr-B9gZeHxAqpFPLXI0"
  },
  "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` | `insufficient_scope`              | project:write スコープが不足                                                                                     |
| `403` | `forbidden`                       | システム連携のトークンで呼び出した                                                                                         |
| `403` | `sso_required`                    | SSO でログインしていない利用者                                                                                         |
| `403` | `feature_not_permitted`           | 定義にトリガーか、時刻を入れた工程（どの工程でも）があるが、管理者が定期実行の作成を許可していない（取り込みでは巡回はいつも無効なので、巡回では断りません）。作る前に断るので、作りかけのプロジェクトは残りません |
| `403` | `license_status_unavailable`      | ライセンスを確かめられない                                                                                             |
| `409` | `project_limit_reached`           | プロジェクトの数が上限に達している（数は error.message）                                                                       |
| `413` | `body_too_large`                  | ボディが 3 MiB を超える                                                                                           |
| `415` | `unsupported_media_type`          | ボディの Content-Type が application/json ではない                                                                 |
| `503` | `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://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/relink \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.delete(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/relink",
  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/relink",
{
  method: "DELETE",
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

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

**Go**

```go
req, _ := http.NewRequest("DELETE", "https://api.fd.agenticstar.tm.softbank.jp/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` | `insufficient_scope` | project:write スコープが不足    |
| `403` | `forbidden`          | システム連携のトークンで呼び出した        |
| `403` | `owner_only`         | オーナーではないメンバー             |
| `403` | `sso_required`       | SSO でログインしていない利用者        |
| `404` | `project_not_found`  | プロジェクトが存在しない、またはメンバーではない |

### POST`/v1/projects`

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

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

| フィールド                        | 型                | 必須 | 説明                                                                                                                                                             |
| ---------------------------- | ---------------- | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                       | `string`         | 必須 | プロジェクト名（255 文字まで。空白だけにはできません）                                                                                                                                  |
| `description`                | `string`         | —  | 説明（5000 文字まで）                                                                                                                                                  |
| `tags`                       | `array`          | —  | タグ（1 つ 30 文字までの文字列を 10 個まで。前後の空白と先頭の # を除き、小文字にして保存します。そうして空になるタグと、同じになるタグは送れません）                                                                              |
| `type`                       | `string`         | —  | "cycle" または "workflow"。省くと "cycle"                                                                                                                             |
| `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"（確認工程）・"automation"（外部の自動化）のどれか。省くと "ai"。cycle では "ai" だけ。null は送れません                                                                    |
| `steps[].automationConfig`   | `object \| null` | —  | 外部の自動化の設定（zone が "automation" の工程だけ）。形は工程の項目の automationConfig と同じです。省くと設定の無い工程を作ります（実行の開始の前に設定が要ります）                                                          |
| `steps[].placementExecution` | `string \| null` | —  | "parallel" を指定すると、その工程に置いた Agent を同時に実行します（workflow の "ai" の工程だけ）。省くか null・"serial" のときは 1 つずつ実行します                                                            |
| `steps[].outputConfig`       | `object \| null` | —  | 次の工程に渡す値と資料の役割（workflow の "ai" の工程だけ）。形と決まりは工程の項目の outputConfig と同じです。省けます                                                                                     |

`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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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,
      "maxMinutesPerRun": null
    },
    "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": "lGx3-Zc_YrHdaUo_vpWqlGviCDvwmnk9df9KcrJKYqM"
  },
  "steps": [
    {
      "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
      "position": 1,
      "name": null,
      "description": null,
      "enabled": true,
      "defaultZone": "ai",
      "automationConfig": null,
      "branchConfig": null,
      "reworkToStepId": null,
      "gateConfig": null,
      "gateKind": null,
      "schedule": null,
      "scheduleNextFireAt": null,
      "onDenied": null,
      "onDegraded": null,
      "outcomeRoutes": null,
      "laneId": null,
      "placementExecution": null,
      "outputConfig": null,
      "digest": "klTw4jQoxuF17jBz4GL9aYU5DcFDjcv24zXfBEWTMtw"
    },
    {
      "stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "position": 2,
      "name": null,
      "description": null,
      "enabled": true,
      "defaultZone": "gate",
      "automationConfig": null,
      "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,
      "outputConfig": null,
      "digest": "rBZ_uP64l5OjdSlPVOdAoWThVePY0Rqei1BltLAcvQg"
    },
    {
      "stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
      "position": 3,
      "name": null,
      "description": null,
      "enabled": true,
      "defaultZone": "ai",
      "automationConfig": null,
      "branchConfig": null,
      "reworkToStepId": null,
      "gateConfig": null,
      "gateKind": null,
      "schedule": null,
      "scheduleNextFireAt": null,
      "onDenied": null,
      "onDegraded": null,
      "outcomeRoutes": null,
      "laneId": null,
      "placementExecution": null,
      "outputConfig": 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` | `invalid_parameter`                   | steps\[].automationConfig の形・値の誤り（error.param に steps\[N].automationConfig の項目の名前）                                                                             |
| `400` | `automation_body_invalid`             | steps\[].automationConfig.body の中身が決まりに合わない（16 KiB・深さ 16・差し込める名前）。error.param は steps で、どの工程かは返りません                                                            |
| `400` | `automation_config_not_allowed`       | zone が "automation" でない工程に automationConfig を指定した                                                                                                              |
| `400` | `cycle_automation_not_allowed`        | cycle に外部の自動化の工程（"automation"）を指定した                                                                                                                            |
| `400` | `automation_destination_missing`      | 外部の自動化の工程の宛先が見つからない。steps\[].automationConfig.destinationId を宛先の一覧（GET /v1/projects/automation-destinations）の有効な宛先にしてください。一覧に宛先が無いときは、管理者に頼んでください（どの工程かは返りません） |
| `400` | `automation_destination_inactive`     | 外部の自動化の工程の宛先が無効。管理者に宛先を有効にしてもらうか、宛先の一覧（GET /v1/projects/automation-destinations）の別の有効な宛先を選んでください（どの工程かは返りません）                                                  |
| `409` | `automation_dlp_enabled`              | DLP 連携が有効な間は、外部の自動化の工程を保存・実行できない。管理者に DLP 連携を切ってもらってください                                                                                                       |
| `409` | `automation_destinations_unavailable` | この環境では外部の自動化の宛先を使えない。管理者に、外部の自動化の宛先を用意してもらってください                                                                                                               |
| `400` | `parallel_workflow_only`              | cycle の工程に placementExecution の "parallel" を指定した                                                                                                               |
| `400` | `parallel_ai_only`                    | "ai" ではない工程に placementExecution の "parallel" を指定した                                                                                                             |
| `400` | `output_config_invalid`               | steps\[].outputConfig の形・数・長さの誤り、名前の重なり、または "ai" でない工程・cycle の工程に送った（決まりは工程の項目の outputConfig）。error.param は steps で、どの工程かは返りません                                |
| `400` | `organization_not_member`             | 付けられない組織を指定した                                                                                                                                                  |
| `403` | `insufficient_scope`                  | project:write スコープが不足                                                                                                                                          |
| `403` | `forbidden`                           | システム連携のトークンで呼び出した                                                                                                                                              |
| `403` | `sso_required`                        | SSO でログインしていない利用者                                                                                                                                              |
| `403` | `license_status_unavailable`          | ライセンスを確かめられない                                                                                                                                                  |
| `409` | `project_limit_reached`               | プロジェクトの数が上限に達している（数は error.message）                                                                                                                            |
| `413` | `body_too_large`                      | ボディが 3 MiB を超える                                                                                                                                                |
| `415` | `unsupported_media_type`              | ボディの Content-Type が application/json ではない                                                                                                                      |
| `503` | `organization_unavailable`            | 所属している組織を確かめられない                                                                                                                                               |
| `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                                                                                                                                                                                            |
| `limits.maxMinutesPerRun`    | `integer \| null` | —  | 1 回の実行の長さの上限（分）。5・15・30・60・90・120 のどれか。null は上限を付けない                                                                                                                                             |
| `flowStructure`              | `object \| null`  | —  | レーンの定義（取得と同じ形）。送ると全部が置き換わります。null でレーンを無くします                                                                                                                                                     |
| `organizationCode`           | `string \| null`  | —  | 組織のコード（255 文字まで）。組織をまだ付けていないプロジェクトに 1 回だけ付けられます。今の値と同じ値は何も変えません（取得の値をそのまま送り返せます）。組織が付いているプロジェクトに違う値を送ると 409（organization\_locked）です。null は、組織がまだ付いていなければ何も変えず、付いていれば 409（organization\_locked）です |

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

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

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

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

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

#### リクエスト例

**Update project**

**curl**

```curl
curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31 \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "baseDigest": "lGx3-Zc_YrHdaUo_vpWqlGviCDvwmnk9df9KcrJKYqM",
  "status": "paused"
}'
```

**Python**

```python
import requests

response = requests.patch(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
  headers={"Authorization": f"Bearer {token}"},
  json={'baseDigest': 'lGx3-Zc_YrHdaUo_vpWqlGviCDvwmnk9df9KcrJKYqM', 'status': 'paused'},
)

print(response.json())
```

**TypeScript**

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

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

**Go**

```go
payload := []byte(`{"baseDigest": "lGx3-Zc_YrHdaUo_vpWqlGviCDvwmnk9df9KcrJKYqM", "status": "paused"}`)
req, _ := http.NewRequest("PATCH", "https://api.fd.agenticstar.tm.softbank.jp/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,
      "maxMinutesPerRun": null
    },
    "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": "kzBrbi0YeE0_5B4uneAqHvcVkr-B9gZeHxAqpFPLXI0"
  },
  "definitionApproval": null
}
```

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

| ステータス | code                           | 説明                                                                                                                                                                                                                   |
| ----- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | `invalid_parameter`            | projectId が UUID の形式ではない、baseDigest が無い・空・文字列ではない、変える項目が無い、name を空・空白だけにした、description を空の文字列・空白だけ・null にした、name・status・tags・isShared・limits に null を送った、項目の型や値の誤り（タグの空・重なりを含みます）、または type・policy・connectSecret を送った |
| `400` | `invalid_body`                 | ボディが壊れた JSON、または JSON のオブジェクトではない                                                                                                                                                                                    |
| `400` | `invalid_share_scope`          | shareScope が "all"・"organizations" ではない                                                                                                                                                                              |
| `400` | `invalid_share_organizations`  | shareOrganizations が配列ではない、21 件以上、または文字列でない・空・空白だけ・256 文字以上の値がある                                                                                                                                                     |
| `400` | `share_organizations_required` | shareScope に "organizations" と空の shareOrganizations を送った、または公開している（送った値か今の値の isShared が true）のに、範囲が "organizations" で組織が 1 件も無い（送った値と今の値を合わせて見ます）                                                                    |
| `400` | `invalid_flow_structure`       | レーンの定義が、上の決まりに合わない                                                                                                                                                                                                   |
| `400` | `organization_not_member`      | 付けられない組織を指定した                                                                                                                                                                                                        |
| `403` | `insufficient_scope`           | project:write スコープが不足                                                                                                                                                                                                |
| `403` | `forbidden`                    | システム連携のトークンで呼び出した                                                                                                                                                                                                    |
| `403` | `owner_only`                   | status を "archived" にする変更か、status のほかの変えられる項目（上のリクエストボディの表の項目）を含む変更を、オーナーではないメンバーが送った                                                                                                                                |
| `403` | `operator_only`                | 一時停止・再開だけの変更を、オーナーでも運用担当でもなく、組織の運用の役割も持たないメンバーが送った                                                                                                                                                                   |
| `403` | `sso_required`                 | SSO でログインしていない利用者                                                                                                                                                                                                    |
| `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 を送った）                                                                                                                                                                                       |
| `403` | `license_status_unavailable`   | "archived" から戻そうとしたが、ライセンスを確かめられない                                                                                                                                                                                   |
| `409` | `project_limit_reached`        | "archived" から戻そうとしたが、プロジェクトの数が上限に達している                                                                                                                                                                               |
| `413` | `body_too_large`               | ボディが 16 KiB を超える                                                                                                                                                                                                     |
| `415` | `unsupported_media_type`       | ボディの Content-Type が application/json ではない                                                                                                                                                                            |
| `503` | `organization_unavailable`     | 所属している組織を確かめられない                                                                                                                                                                                                     |
| `503` | `approval_setting_unavailable` | 定義の承認の設定を確かめられない。時間をおいて送り直してください                                                                                                                                                                                     |
| `503` | `definition_busy`              | 同じ定義の変更が処理中。時間をおいて送り直してください                                                                                                                                                                                          |

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

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

#### パスパラメータ

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

#### リクエスト例

**Delete project**

**curl**

```curl
curl -X DELETE https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31 \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.delete(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
  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",
{
  method: "DELETE",
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

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

**Go**

```go
req, _ := http.NewRequest("DELETE", "https://api.fd.agenticstar.tm.softbank.jp/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` | `insufficient_scope` | project:delete スコープが不足             |
| `403` | `forbidden`          | システム連携のトークンで呼び出した                  |
| `403` | `owner_only`         | オーナーではないメンバー                       |
| `403` | `sso_required`       | SSO でログインしていない利用者                  |
| `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://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/control \
-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/control",
  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/control",
{
  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/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"（通知して待機する）/ "proceed"（自動で進める）/ "send\_back"（自動で差し戻す）/ "reject"（自動で却下する）                    |
| `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` | `insufficient_scope` | project:read スコープが不足                                            |
| `403` | `forbidden`          | システム連携のトークンで呼び出した                                               |
| `403` | `sso_required`       | SSO でログインしていない利用者                                               |
| `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://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/definition-approval \
-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/definition-approval",
  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/definition-approval",
{
  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/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` | `insufficient_scope`           | project:read スコープが不足             |
| `403` | `forbidden`                    | システム連携のトークンで呼び出した                |
| `403` | `sso_required`                 | SSO でログインしていない利用者                |
| `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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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` | `insufficient_scope` | project:write スコープが不足                                         |
| `403` | `forbidden`          | システム連携のトークンで呼び出した                                             |
| `403` | `owner_only`         | オーナーではないメンバー                                                  |
| `403` | `sso_required`       | SSO でログインしていない利用者                                             |
| `404` | `project_not_found`  | プロジェクトが存在しない、またはメンバーではない                                      |
| `409` | `no_pending`         | 承認待ちが無い。承認待ちの要約を読み直してから決めてください                                |
| `409` | `approval_stale`     | pendingDigest が今の承認待ちと違う（承認待ちに変更が重なった）。承認待ちの要約を読み直してから決めてください |
| `503` | `definition_busy`    | 同じ定義の変更が処理中。時間をおいて送り直してください                                   |

## 工程

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

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

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

### 工程の項目

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

| フィールド                             | 型                 | 説明                                                                                                           |
| --------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------ |
| `stepId`                          | `string`          | 工程の ID（UUID）                                                                                                 |
| `position`                        | `number \| null`  | 工程の位置（1 から）                                                                                                  |
| `name`                            | `string \| null`  | 工程の名前。null のときは画面で既定の名前（「工程1」など）が出ます                                                                         |
| `description`                     | `string \| null`  | 説明                                                                                                           |
| `enabled`                         | `boolean \| null` | 有効かどうか                                                                                                       |
| `defaultZone`                     | `string \| null`  | "ai"（Agent が実行）・"gate"（確認工程）・"automation"（外部の自動化）・"branch"（条件分岐）のどれか                                         |
| `automationConfig`                | `object \| null`  | 外部の自動化の設定（defaultZone が "automation" の工程だけ。設定が無ければ null）。公開されているプロジェクトのプレビューでは、宛先の名前（destinationName）だけを返します |
| `automationConfig.destinationId`  | `string`          | 宛先の ID（UUID）。宛先の一覧（GET /v1/projects/automation-destinations）の destinationId                                  |
| `automationConfig.body`           | `object`          | 宛先へ送る本文の形（JSON のオブジェクト）。文字列の中に {{名前}} で値を差し込めます（下の決まり）                                                       |
| `automationConfig.timeoutSeconds` | `number`          | 宛先の応答を待つ時間（秒。1〜300）                                                                                          |
| `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"（outcomeRoutes の工程へ進める）                |
| `onDegraded`                      | `string \| null`  | 「Agent の報告による失敗のとき」の扱い。"gate"（確認を求める）/ "proceed"（そのまま進める）/ "goto"（outcomeRoutes の工程へ進める）                     |
| `outcomeRoutes`                   | `object \| null`  | onDenied・onDegraded が "goto" のときの次の工程                                                                        |
| `outcomeRoutes.onDenied.stepId`   | `string`          | 「ルールにより実行できない場合」に進める工程の ID                                                                                   |
| `outcomeRoutes.onDegraded.stepId` | `string`          | 「Agent の報告による失敗のとき」に進める工程の ID                                                                                |
| `laneId`                          | `string \| null`  | この工程が属するレーンの ID                                                                                              |
| `placementExecution`              | `string \| null`  | "parallel"（この工程に置いた Agent を同時に実行する）。null は置いた順に 1 つずつ実行                                                      |
| `outputConfig`                    | `object \| null`  | 次の工程に渡す値と資料の役割（workflow の "ai" の工程だけ。設定が無ければ null）。公開されているプロジェクトのプレビューでも返します                                 |
| `outputConfig.values[]`           | `object[]`        | 次の工程に渡す値。name（名前）と description（説明。省けます）                                                                      |
| `outputConfig.files[]`            | `object[]`        | 成果物のファイルに付ける資料の役割。role（役割の名前）と description（説明。省けます）                                                          |
| `digest`                          | `string`          | 工程を変えるときに baseDigest に送る値                                                                                    |

`automationConfig` の決まり: 鍵は `destinationId`（要る）・`body`（省くと `{}`）・`timeoutSeconds`（省くと 60）の 3 つだけです。`body` と `timeoutSeconds` に null は送れません（省くのとは違います）。`automationConfig` 自体は省けます。設定の無い外部の自動化の工程は保存できますが、ワークフローの実行の開始の前に設定が要ります。工程を変えるときに null を送ると、設定が外れます。形・値の誤りは `400`（`invalid_parameter`。`error.param` に `automationConfig.destinationId` などの項目の名前）です。`body` は 16 KiB・深さ 16 までで、要求全体の上限（32 KiB）とは別の決まりです。`body` の文字列に差し込める名前は、`previous.output`（前の工程の出力。20,000 文字まで）・`previous.summary`（その要約）・`run.id`・`step.id`・`step.name`・`project.id`・`project.name`・`input.subject`・`input.body`（開始の入力の件名と本文）・`idempotency_key`（送り直しでも変わらない値）の 10 個だけです。中身の決まりに合わないと `400`（`automation_body_invalid`）です。

`outputConfig` の決まり: 値（`values`）は 5 つ・役割（`files`）は 3 つまでです。`name`・`role` は 40 文字まで、`description` は 200 文字までで、`description` は省けます。前後の空白・改行は除いて保存し、途中に改行などの制御文字があると断ります。値も役割も空なら null（設定なし）になります。値の名前と役割の名前は、1 つの工程の中で重ねられません。この工程の Agent に、名前を付けた値（文。1 つ 1,000 文字まで。超えた分は切れます）と、成果物のどのファイルがどの役割の資料かを返してもらい、次の工程に渡します。返されなかった値・見つからない資料は、推し量って埋めずに、そうだったことを次の工程に渡します。値は、成否・条件分岐の判定には使いません。工程を変える API で null を送ると外れ、"ai" でない領域に変えても外れます。cycle の工程には付けられません。決まりに合わないときは 400 `output_config_invalid`（`error.param` は `outputConfig`）です。

`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 が「変更は要らなかった」と報告した                                |
| `ai`                 | question（yes か no で答えられる問い。200 文字まで。空白だけにはできません）                                                       | 判定だけをするモデルが前の工程の出力の先頭を読んで yes と答えた（この環境で使えないときは断られます）  |

工程を変える 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"（期限後に自動で進める）                              |
| `overdueAction`         | `string \| null` | 期限を過ぎたら。"none"（通知して待機する）/ "proceed"（自動で進める）/ "send\_back"（自動で差し戻す）/ "reject"（自動で却下する） |
| `escalateToUserId`      | `string \| null` | 期限超過時の連絡先の利用者 ID（プロジェクトのメンバー）                                                         |
| `destinations`          | `array`          | 担当者が進め先として選べる工程（2〜5 個。この工程より後ろの工程）。設定していないときは含まれません                                   |
| `destinations[].id`     | `string`         | 次の工程の候補の ID（英数字と \_ - の 64 文字まで）                                                      |
| `destinations[].label`  | `string`         | 画面に出す名前（100 文字まで）                                                                     |
| `destinations[].stepId` | `string`         | 進め先の工程の ID                                                                            |

確認工程の設定が無いとき（`gateConfig` が null、または項目が無いとき）は、`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 の "automation"）                 | 付けられる           | 400（cycle\_automation\_not\_allowed） |
| 条件分岐の工程（defaultZone の "branch"）と branchConfig         | 付けられる           | 400（cycle\_branch\_not\_allowed）     |
| onDenied・onDegraded の "gate"                          | 付けられる           | 400（cycle\_gate\_not\_allowed）       |
| onDenied・onDegraded の "goto" と outcomeRoutes          | 付けられる           | 400（cycle\_route\_not\_allowed）      |
| placementExecution の "parallel"                       | "ai" の工程だけ付けられる | 400（parallel\_workflow\_only）        |
| 次の工程に渡す値と資料の役割（outputConfig）                          | "ai" の工程だけ付けられる | 400（output\_config\_invalid）         |
| 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"・"automation"・"branch" のどれか。省くと "ai"。null・空の文字列は送れません                             |
| `automationConfig`   | `object \| null` | —  | 外部の自動化の設定（defaultZone が "automation" の工程だけ。形は工程の項目の automationConfig と下の決まり）。省くと設定の無い工程を足します |
| `branchConfig`       | `—`              | —  | 送れません（400 step\_reference\_on\_create）。工程を足した後、レーンの工程を後ろに置いてから、工程を変える API で付けます              |
| `outputConfig`       | `object \| null` | —  | 次の工程に渡す値と資料の役割（defaultZone が "ai" の工程だけ。形は工程の項目の outputConfig と上の決まり）。省けます                   |
| `afterStepId`        | `string`         | —  | この工程の後ろに足す（このプロジェクトの工程の ID）                                                                  |
| `beforeStepId`       | `string`         | —  | この工程の前に足す（このプロジェクトの工程の ID）。afterStepId と両方を指定すると、この工程の前に足します。どちらも省くと末尾に足します                  |
| `gateConfig`         | `object \| null` | —  | 確認工程の設定（工程の項目の gateConfig と同じ形。destinations は工程を変えるときに設定します）。null は設定なし                      |
| `placementExecution` | `string \| null` | —  | "parallel" で同時に実行。null か "serial" は 1 つずつ実行                                                  |

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

#### リクエスト例

**Create step**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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",
    "automationConfig": null,
    "branchConfig": null,
    "reworkToStepId": null,
    "gateConfig": null,
    "gateKind": null,
    "schedule": null,
    "scheduleNextFireAt": null,
    "onDenied": null,
    "onDegraded": null,
    "outcomeRoutes": null,
    "laneId": null,
    "placementExecution": null,
    "outputConfig": null,
    "digest": "idyMTCSnJ2toCfD4Y8F_cqLwFwZ-cyJpByz-v1nxscE"
  },
  "steps": [
    {
      "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
      "position": 1,
      "name": "金額の確認",
      "description": "請求書の金額と明細を照合します",
      "enabled": true,
      "defaultZone": "ai",
      "automationConfig": null,
      "branchConfig": null,
      "reworkToStepId": null,
      "gateConfig": null,
      "gateKind": null,
      "schedule": null,
      "scheduleNextFireAt": null,
      "onDenied": null,
      "onDegraded": null,
      "outcomeRoutes": null,
      "laneId": null,
      "placementExecution": null,
      "outputConfig": null,
      "digest": "jZ38OtGgLnS14QCvjZdg5PdyrGEHPK0EhxgDZzEnE2Y"
    },
    {
      "stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "position": 2,
      "name": "差異の確認",
      "description": null,
      "enabled": true,
      "defaultZone": "gate",
      "automationConfig": null,
      "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,
      "outputConfig": null,
      "digest": "27bA5P1PM8JFDwEEZhLP5DDn77Q8MFWq-YcGa6q8Sso"
    },
    {
      "stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
      "position": 3,
      "name": "差異の報告",
      "description": null,
      "enabled": true,
      "defaultZone": "ai",
      "automationConfig": null,
      "branchConfig": null,
      "reworkToStepId": null,
      "gateConfig": null,
      "gateKind": null,
      "schedule": null,
      "scheduleNextFireAt": null,
      "onDenied": null,
      "onDegraded": null,
      "outcomeRoutes": null,
      "laneId": null,
      "placementExecution": null,
      "outputConfig": 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` | `step_reference_on_create`            | gateConfig に destinations を送った（null・空の配列を含みます。進め先は、工程を足した後に工程を変える API で設定します）、または 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 の形・数・長さの誤り、name・role・description の途中の制御文字、名前の重なり、または "ai" でない工程・cycle の工程に送った（上の決まり）。error.param は outputConfig                                                                                    |
| `400` | `automation_body_invalid`             | automationConfig.body の中身が決まりに合わない（16 KiB・深さ 16・差し込める名前）。error.param は automationConfig.body                                                                                                                    |
| `400` | `automation_config_not_allowed`       | defaultZone が "automation" でない工程に automationConfig を指定した                                                                                                                                                        |
| `400` | `automation_step_settings`            | 外部の自動化の工程では使えない項目（確認・時刻・次の工程の候補・同時に実行・差し戻し先）を送った。その項目を送らないでください（error.param にその項目の名前）                                                                                                                           |
| `400` | `cycle_automation_not_allowed`        | cycle に外部の自動化の工程（"automation"）を指定した                                                                                                                                                                             |
| `400` | `automation_destination_missing`      | 外部の自動化の工程の宛先が見つからない。automationConfig.destinationId を宛先の一覧（GET /v1/projects/automation-destinations）の有効な宛先にするか、その工程を止めてください。一覧に宛先が無いときは、管理者に頼んでください                                                              |
| `400` | `automation_destination_inactive`     | 外部の自動化の工程の宛先が無効。管理者に宛先を有効にしてもらうか、automationConfig.destinationId を宛先の一覧（GET /v1/projects/automation-destinations）の別の有効な宛先にするか、その工程を止めてください                                                                       |
| `409` | `automation_dlp_enabled`              | DLP 連携が有効な間は、外部の自動化の工程を保存・実行できない。管理者に DLP 連携を切ってもらってください                                                                                                                                                        |
| `409` | `automation_destinations_unavailable` | この環境では外部の自動化の宛先を使えない。管理者に、外部の自動化の宛先を用意してもらってください                                                                                                                                                                |
| `400` | `parallel_workflow_only`              | cycle の工程に "parallel" を指定した                                                                                                                                                                                     |
| `400` | `parallel_ai_only`                    | 確認工程に "parallel" を指定した                                                                                                                                                                                          |
| `400` | `parallel_not_for_marketplace`        | マーケットプレイス版の登録 Agent を置いたプロジェクトで "parallel" を指定した                                                                                                                                                                |
| `400` | `approver_not_member`                 | 確認担当者にメンバーではない利用者を指定した                                                                                                                                                                                          |
| `400` | `approvers_required`                  | 稼働中の workflow に、確認担当者のいない確認工程を足そうとした                                                                                                                                                                            |
| `400` | `escalate_to_not_member`              | 期限超過時の連絡先にメンバーではない利用者を指定した                                                                                                                                                                                      |
| `403` | `insufficient_scope`                  | project:write スコープが不足                                                                                                                                                                                           |
| `403` | `forbidden`                           | システム連携のトークンで呼び出した                                                                                                                                                                                               |
| `403` | `owner_only`                          | オーナーではないメンバー                                                                                                                                                                                                    |
| `403` | `sso_required`                        | SSO でログインしていない利用者                                                                                                                                                                                               |
| `404` | `project_not_found`                   | プロジェクトが存在しない、またはメンバーではない                                                                                                                                                                                        |
| `409` | `too_many_steps`                      | 工程がすでに 12 個ある                                                                                                                                                                                                   |
| `409` | `flow_structure_conflict`             | レーンの定義や条件分岐の置き方と食い違う（条件分岐の理由は 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"・"automation"・"branch" のどれか                                                                                                         |
| `automationConfig`   | `object \| null` | —  | 外部の自動化の設定（defaultZone が "automation" の工程だけ。形は工程の項目の automationConfig と下の決まり）。null で設定を外します                                                     |
| `branchConfig`       | `object \| null` | —  | 条件分岐の設定（defaultZone が "branch" の工程だけ。形は工程の項目の branchConfig と下の決まり）。送ると丸ごと置き換え、null で外します                                                       |
| `outputConfig`       | `object \| null` | —  | 次の工程に渡す値と資料の役割（defaultZone が "ai" の工程だけ。形は工程の項目の outputConfig と上の決まり）。送ると丸ごと置き換え、null で外します                                                    |
| `enabled`            | `boolean`        | —  | 有効かどうか。サイクルでは、無効にするとその工程の配置は新しい起動を受け付けず（受け付けた分は取り消さない）、有効に戻すと巡回を有効にしていた配置は保存した周期で巡回に戻る                                                         |
| `gateConfig`         | `object \| null` | —  | 確認工程の設定。送った項目だけを今の値に重ねます。null で設定を外します                                                                                                         |
| `gateKind`           | `string \| null` | —  | "review" または "manual"                                                                                                                          |
| `reworkToStepId`     | `string \| null` | —  | 差し戻し先（この工程より前の工程）。null で外します                                                                                                                   |
| `onDenied`           | `string \| null` | —  | "gate" / "closed\_failed" / "goto"                                                                                                             |
| `onDegraded`         | `string \| null` | —  | "gate" / "proceed" / "goto"                                                                                                                    |
| `outcomeRoutes`      | `object \| null` | —  | "goto" のときの次の工程（この工程より後ろの工程）。送ると全部が置き換わります（onDenied だけを変えるときも onDegraded を一緒に送ってください）。null で外します。onDenied・onDegraded のどちらも含まないときは、送らなかったのと同じです |
| `placementExecution` | `string \| null` | —  | "parallel" で同時に実行。null か "serial" は 1 つずつ実行                                                                                                    |
| `schedule`           | `object \| null` | —  | 工程の時刻（workflow だけ）。expression（5 項目の cron 式）と timezone（省くと UTC）。null で外します                                                                      |

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

領域（`defaultZone`）を変えると、前の領域の設定は消えます（外部の自動化の工程にすると確認・時刻などの設定が外れ、ほかの領域にすると `automationConfig` が外れます。"ai" でない領域にすると `outputConfig` も外れます）。Agent を置いた工程は、外部の自動化の工程にできません。

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

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

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

#### リクエスト例

**Update step**

**curl**

```curl
curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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",
    "automationConfig": null,
    "branchConfig": null,
    "reworkToStepId": null,
    "gateConfig": null,
    "gateKind": null,
    "schedule": null,
    "scheduleNextFireAt": null,
    "onDenied": null,
    "onDegraded": null,
    "outcomeRoutes": null,
    "laneId": null,
    "placementExecution": null,
    "outputConfig": 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` | `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 の形・数・長さの誤り、name・role・description の途中の制御文字、名前の重なり、または "ai" でない工程・cycle の工程に送った（上の決まり）。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`                       | ほかの条件分岐のレーンの工程を、この条件分岐やそのレーンにしようとした。先にほかの条件分岐のレーンから外すか、レーンの外の工程を使ってください                                                                                                                                                                                                                  |
| `400` | `branch_in_lane`                      | 条件分岐の工程かそのレーンの工程が、並列のレーンの中にある。並列のレーンの外へ移してから送り直してください                                                                                                                                                                                                                                    |
| `409` | `branch_step_has_agents`              | Agent を置いた工程を、条件分岐の工程にしようとした。先に配置を外してください                                                                                                                                                                                                                                                |
| `409` | `branch_ai_unavailable`               | kind が "ai" の規則を送ったが、この環境では AI に判定させる条件分岐を使えない。管理者に判定の設定を頼むか、ほかの種類の規則を使ってください                                                                                                                                                                                                            |
| `400` | `automation_body_invalid`             | automationConfig.body の中身が決まりに合わない（16 KiB・深さ 16・差し込める名前）。error.param は automationConfig.body                                                                                                                                                                                             |
| `400` | `automation_config_not_allowed`       | defaultZone が "automation" でない工程に automationConfig を指定した                                                                                                                                                                                                                                 |
| `400` | `automation_step_settings`            | 外部の自動化の工程では使えない項目（確認・時刻・次の工程の候補・同時に実行・差し戻し先）を送った。その項目を送らないでください（error.param にその項目の名前）                                                                                                                                                                                                    |
| `400` | `cycle_automation_not_allowed`        | cycle に外部の自動化の工程（"automation"）を指定した                                                                                                                                                                                                                                                      |
| `409` | `automation_step_has_agents`          | Agent を置いた工程を、外部の自動化の工程にしようとした。先に配置を外してください                                                                                                                                                                                                                                              |
| `400` | `automation_destination_missing`      | 外部の自動化の工程の宛先が見つからない。automationConfig.destinationId を宛先の一覧（GET /v1/projects/automation-destinations）の有効な宛先にするか、その工程を止めてください。一覧に宛先が無いときは、管理者に頼んでください                                                                                                                                       |
| `400` | `automation_destination_inactive`     | 外部の自動化の工程の宛先が無効。管理者に宛先を有効にしてもらうか、automationConfig.destinationId を宛先の一覧（GET /v1/projects/automation-destinations）の別の有効な宛先にするか、その工程を止めてください                                                                                                                                                |
| `409` | `automation_dlp_enabled`              | DLP 連携が有効な間は、外部の自動化の工程を保存・実行できない。管理者に DLP 連携を切ってもらってください                                                                                                                                                                                                                                 |
| `409` | `automation_destinations_unavailable` | この環境では外部の自動化の宛先を使えない。管理者に、外部の自動化の宛先を用意してもらってください                                                                                                                                                                                                                                         |
| `400` | `parallel_workflow_only`              | cycle の工程に "parallel" を指定した                                                                                                                                                                                                                                                              |
| `400` | `parallel_ai_only`                    | 確認工程に "parallel" を指定した                                                                                                                                                                                                                                                                   |
| `400` | `parallel_not_for_marketplace`        | マーケットプレイス版の登録 Agent を置いたプロジェクトで "parallel" を指定した                                                                                                                                                                                                                                         |
| `400` | `approver_not_member`                 | 確認担当者にメンバーではない利用者を指定した                                                                                                                                                                                                                                                                   |
| `400` | `approvers_required`                  | 稼働中の workflow で、有効な確認工程の確認担当者がいなくなる                                                                                                                                                                                                                                                      |
| `400` | `escalate_to_not_member`              | 期限超過時の連絡先にメンバーではない利用者を指定した                                                                                                                                                                                                                                                               |
| `400` | `invalid_send_back_step`              | 差し戻し先が、この工程より前の工程ではない                                                                                                                                                                                                                                                                    |
| `400` | `invalid_destinations`                | destinations の形の誤り（2〜5 個ではない、ID・名前・工程の重複 など）                                                                                                                                                                                                                                             |
| `400` | `destinations_gate_only`              | 確認工程ではない工程に destinations を設定しようとした                                                                                                                                                                                                                                                       |
| `400` | `destinations_notify_only`            | 確認方法が "notify\_only" の工程に destinations を設定しようとした                                                                                                                                                                                                                                         |
| `400` | `invalid_destination_step`            | destinations の工程が、この工程より後ろの工程ではない                                                                                                                                                                                                                                                        |
| `400` | `invalid_outcome_routes`              | outcomeRoutes の形の誤り                                                                                                                                                                                                                                                                      |
| `400` | `invalid_outcome_route`               | "goto" の次の工程が無い、またはこの工程より後ろの工程ではない                                                                                                                                                                                                                                                       |
| `403` | `insufficient_scope`                  | project:write スコープが不足                                                                                                                                                                                                                                                                    |
| `403` | `forbidden`                           | システム連携のトークンで呼び出した                                                                                                                                                                                                                                                                        |
| `403` | `owner_only`                          | オーナーではないメンバー                                                                                                                                                                                                                                                                             |
| `403` | `sso_required`                        | SSO でログインしていない利用者                                                                                                                                                                                                                                                                        |
| `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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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",
      "automationConfig": null,
      "branchConfig": null,
      "reworkToStepId": null,
      "gateConfig": null,
      "gateKind": null,
      "schedule": null,
      "scheduleNextFireAt": null,
      "onDenied": null,
      "onDegraded": null,
      "outcomeRoutes": null,
      "laneId": null,
      "placementExecution": null,
      "outputConfig": null,
      "digest": "jZ38OtGgLnS14QCvjZdg5PdyrGEHPK0EhxgDZzEnE2Y"
    },
    {
      "stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
      "position": 2,
      "name": "差異の報告",
      "description": null,
      "enabled": true,
      "defaultZone": "ai",
      "automationConfig": null,
      "branchConfig": null,
      "reworkToStepId": null,
      "gateConfig": null,
      "gateKind": null,
      "schedule": null,
      "scheduleNextFireAt": null,
      "onDenied": null,
      "onDegraded": null,
      "outcomeRoutes": null,
      "laneId": null,
      "placementExecution": null,
      "outputConfig": null,
      "digest": "idyMTCSnJ2toCfD4Y8F_cqLwFwZ-cyJpByz-v1nxscE"
    },
    {
      "stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "position": 3,
      "name": "差異の確認",
      "description": null,
      "enabled": true,
      "defaultZone": "gate",
      "automationConfig": null,
      "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,
      "outputConfig": null,
      "digest": "27bA5P1PM8JFDwEEZhLP5DDn77Q8MFWq-YcGa6q8Sso"
    }
  ],
  "stepsDigest": "TQbgPozTGXVTzA52FXfg_NPAcQRj94bGXmyUVP-WTeo",
  "definitionApproval": null
}
```

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

| ステータス | code                           | 説明                                                                                                           |
| ----- | ------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| `400` | `invalid_parameter`            | projectId が UUID の形式ではない、baseDigest が無い・空・文字列ではない、または stepIds が全部の工程の並びになっていない                               |
| `400` | `invalid_body`                 | ボディが壊れた JSON、または JSON のオブジェクトではない                                                                            |
| `403` | `insufficient_scope`           | project:write スコープが不足                                                                                        |
| `403` | `forbidden`                    | システム連携のトークンで呼び出した                                                                                            |
| `403` | `owner_only`                   | オーナーではないメンバー                                                                                                 |
| `403` | `sso_required`                 | SSO でログインしていない利用者                                                                                            |
| `404` | `project_not_found`            | プロジェクトが存在しない、またはメンバーではない                                                                                     |
| `409` | `stale_base`                   | 取得した後に工程の並びが変わっている。承認待ちがあるときは、既定の取得の 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`（ほかの条件分岐のレーンに条件分岐が入る）<!-- -->・`branch_in_lane`（条件分岐かそのレーンの工程が並列のレーンに入る）・`fork_source_branch`（並列のレーンが条件分岐かそのレーンの工程から分かれる）・`join_next_branch_lane`（並列のレーンの合流が条件分岐のレーンの工程へ続く）<!-- -->・`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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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",
      "automationConfig": null,
      "branchConfig": null,
      "reworkToStepId": null,
      "gateConfig": null,
      "gateKind": null,
      "schedule": null,
      "scheduleNextFireAt": null,
      "onDenied": null,
      "onDegraded": null,
      "outcomeRoutes": null,
      "laneId": null,
      "placementExecution": null,
      "outputConfig": null,
      "digest": "jZ38OtGgLnS14QCvjZdg5PdyrGEHPK0EhxgDZzEnE2Y"
    },
    {
      "stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "position": 2,
      "name": "差異の確認",
      "description": null,
      "enabled": true,
      "defaultZone": "gate",
      "automationConfig": null,
      "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,
      "outputConfig": null,
      "digest": "27bA5P1PM8JFDwEEZhLP5DDn77Q8MFWq-YcGa6q8Sso"
    }
  ],
  "stepsDigest": "OCkD5Kg3AClwepKwjLk5TZT1bwRFId09NV7SQKZOpL4",
  "definitionApproval": null
}
```

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

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

## 配置

配置は、<!-- -->ライブラリの Agent <!-- -->をプロジェクトの工程に置いたものです。1 つのプロジェクトに同じ Agent を置けるのは 1 つの配置だけで、1 つの配置は複数の工程（担当工程）を持てます。cycle では、Agent を動かす周期（巡回）を配置と工程の組ごとに決めます。<!-- -->外部の自動化の工程と条件分岐の工程には、Agent を置けません。

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

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

### 配置の項目

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

| フィールド                    | 型                 | 説明                                                                                                                                                             |
| ------------------------ | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `placementId`            | `string`          | 配置の ID（UUID）                                                                                                                                                   |
| `agentId`                | `string \| null`  | 置いた Agent の ID（ライブラリの Agent の ID）                                                                                                                              |
| `displayOrder`           | `number \| null`  | 表示の順                                                                                                                                                           |
| `name`                   | `string \| null`  | Agent の名前                                                                                                                                                      |
| `description`            | `string \| null`  | Agent の説明                                                                                                                                                      |
| `goal`                   | `string \| null`  | Agent のゴール（指示）                                                                                                                                                 |
| `guardrail`              | `string \| null`  | Agent のガードレール                                                                                                                                                  |
| `skills`                 | `array`           | Agent が使うスキル（skillId・name）                                                                                                                                     |
| `skillCount`             | `number \| null`  | スキルの数                                                                                                                                                          |
| `playbookId`             | `string \| null`  | Agent が使うプレイブックの ID                                                                                                                                            |
| `playbookName`           | `string \| null`  | プレイブックの名前                                                                                                                                                      |
| `inputFiles`             | `array`           | Agent の入力ファイル（filename だけ）                                                                                                                                     |
| `stepIds`                | `array`           | 担当工程の ID の配列                                                                                                                                                   |
| `sweeps`                 | `array`           | 巡回の設定（cycle）。担当工程ごとに stepId・cron・timezone・enabled                                                                                                              |
| `runtimeConfigs`         | `array`           | 工程ごとの実行の設定（stepId・runtimeConfig）。runtimeConfig の中身は保存した形のまま返ります。プロジェクトのライブラリの対応づけは libraryBindings で返し、runtimeConfig には入れません（対応づけしか無い工程の runtimeConfig は null） |
| `libraryBindings`        | `array`           | プロジェクトのライブラリのファイルを、工程ごとに作業場所のどの名前で渡すか（stepId・fileId・workspaceName）。対応づけが無ければ空の配列                                                                               |
| `memoryOrgId`            | `string \| null`  | 配置の記憶の組織                                                                                                                                                       |
| `memoryJobId`            | `string \| null`  | 配置の記憶の職種                                                                                                                                                       |
| `instructionAddendum`    | `string \| null`  | このプロジェクトでの追加の指示。実行のとき、Agent の指示（goal）の後ろに続けて渡します（Agent 本体は変えません）。無ければ 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`  | 書き出した定義から取り込んだプロジェクトで、置いた Agent が指す、見つからなかったプレイブック・スキル。Agent を保存し直すと外れます。無ければ null                                                                             |
| `relink.playbook`        | `object \| null`  | 見つからなかったプレイブック（name・versionNo）                                                                                                                                 |
| `relink.skills`          | `array`           | 見つからなかったスキル（name・versionNo）の配列                                                                                                                                 |
| `digest`                 | `string`          | 配置を変える API（担当工程・記憶・追加の指示・巡回・ライブラリの対応づけ）で baseDigest に送る値。担当工程・記憶・追加の指示（あるときだけ）・実行の設定（プロジェクトのライブラリの対応づけを含みます）・巡回から作られ、Agent の中身を変えても変わりません                      |

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

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

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

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

#### リクエスト例

**List placements**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements \
-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/placements",
  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/placements",
{
  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/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": "経理 Agent",
      "description": "請求書の金額と明細を照合します",
      "goal": "請求書の金額と明細を照合し、差異を報告する",
      "guardrail": "金額を書き換えない",
      "skills": [
        {
          "skillId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
          "name": "請求書の読み取り"
        }
      ],
      "skillCount": 1,
      "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,
      "instructionAddendum": null,
      "agentOwnerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "isShared": false,
      "runtimeKind": "autonomous",
      "marketplaceAgentId": null,
      "exclusiveToThisProject": true,
      "agentStopped": false,
      "relink": null,
      "digest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU"
    }
  ],
  "hasMore": false
}
```

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

| ステータス | code                 | 説明                                                              |
| ----- | -------------------- | --------------------------------------------------------------- |
| `400` | `invalid_parameter`  | projectId が UUID の形式ではない                                        |
| `403` | `insufficient_scope` | project:read スコープが不足                                            |
| `403` | `forbidden`          | システム連携のトークンで呼び出した                                               |
| `403` | `sso_required`       | SSO でログインしていない利用者                                               |
| `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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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": "経理 Agent",
    "description": "請求書の金額と明細を照合します",
    "goal": "請求書の金額と明細を照合し、差異を報告する",
    "guardrail": "金額を書き換えない",
    "skills": [
      {
        "skillId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
        "name": "請求書の読み取り"
      }
    ],
    "skillCount": 1,
    "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,
    "instructionAddendum": null,
    "agentOwnerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "isShared": false,
    "runtimeKind": "autonomous",
    "marketplaceAgentId": null,
    "exclusiveToThisProject": true,
    "agentStopped": false,
    "relink": null,
    "digest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU"
  }
}
```

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

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

<!-- -->

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

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

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

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

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

#### リクエスト例

**Place agent**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "agentId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
  "stepIds": [
    "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"
  ]
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements",
  headers={"Authorization": f"Bearer {token}"},
  json={'agentId': 'b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e', 'stepIds': ['5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819']},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"agentId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e", "stepIds": ["5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"]}),
}
);

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

**Go**

```go
payload := []byte(`{"agentId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e", "stepIds": ["5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"]}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/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": "経理 Agent",
    "description": "請求書の金額と明細を照合します",
    "goal": "請求書の金額と明細を照合し、差異を報告する",
    "guardrail": "金額を書き換えない",
    "skills": [
      {
        "skillId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
        "name": "請求書の読み取り"
      }
    ],
    "skillCount": 1,
    "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,
    "instructionAddendum": null,
    "agentOwnerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "isShared": false,
    "runtimeKind": "autonomous",
    "marketplaceAgentId": null,
    "exclusiveToThisProject": true,
    "agentStopped": false,
    "relink": null,
    "digest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU"
  },
  "definitionApproval": null
}
```

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

| ステータス | code                           | 説明                                                                                     |
| ----- | ------------------------------ | -------------------------------------------------------------------------------------- |
| `400` | `invalid_parameter`            | projectId・agentId が UUID の形式ではない、または stepIds の誤り（12 個を超える、このプロジェクトの工程ではない、同じ工程を重ねた など） |
| `400` | `invalid_body`                 | ボディが壊れた JSON、または JSON のオブジェクトではない                                                      |
| `400` | `agent_not_found`              | agentId の Agent が存在しない、または見えない                                                         |
| `400` | `agent_not_owned`              | 自分の Agent ではない                                                                         |
| `400` | `automation_step_no_agent`     | 外部の自動化の工程には Agent を置けない。その工程を担当工程から外してください                                             |
| `400` | `branch_step_no_agent`         | 条件分岐の工程には Agent を置けない。その工程を担当工程から外してください                                               |
| `403` | `insufficient_scope`           | project:write スコープが不足                                                                  |
| `403` | `forbidden`                    | システム連携のトークンで呼び出した                                                                      |
| `403` | `owner_only`                   | オーナーではないメンバー                                                                           |
| `403` | `sso_required`                 | SSO でログインしていない利用者                                                                      |
| `404` | `project_not_found`            | プロジェクトが存在しない、またはメンバーではない                                                               |
| `409` | `placement_already_exists`     | 同じ Agent がすでに置いてある（担当工程が違う）                                                            |
| `409` | `unsupported_runtime`          | この API では置けない Agent（マーケットプレイス版の登録 Agent など）                                            |
| `413` | `body_too_large`               | ボディが 16 KiB を超える                                                                       |
| `415` | `unsupported_media_type`       | ボディの Content-Type が application/json ではない                                              |
| `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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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` | `insufficient_scope`           | project:write スコープが不足                                                              |
| `403` | `forbidden`                    | システム連携のトークンで呼び出した                                                                  |
| `403` | `owner_only`                   | オーナーではないメンバー                                                                       |
| `403` | `sso_required`                 | SSO でログインしていない利用者                                                                  |
| `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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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": "経理 Agent",
    "description": "請求書の金額と明細を照合します",
    "goal": "請求書の金額と明細を照合し、差異を報告する",
    "guardrail": "金額を書き換えない",
    "skills": [
      {
        "skillId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
        "name": "請求書の読み取り"
      }
    ],
    "skillCount": 1,
    "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,
    "instructionAddendum": null,
    "agentOwnerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "isShared": false,
    "runtimeKind": "autonomous",
    "marketplaceAgentId": null,
    "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 のオブジェクトではない                                                                                   |
| `400` | `automation_step_no_agent`     | 外部の自動化の工程には Agent を置けない。その工程を担当工程から外してください                                                                          |
| `400` | `branch_step_no_agent`         | 条件分岐の工程には Agent を置けない。その工程を担当工程から外してください                                                                            |
| `403` | `insufficient_scope`           | project:write スコープが不足                                                                                               |
| `403` | `forbidden`                    | システム連携のトークンで呼び出した                                                                                                   |
| `403` | `owner_only`                   | オーナーではないメンバー                                                                                                        |
| `403` | `sso_required`                 | SSO でログインしていない利用者                                                                                                   |
| `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`              | 同じ定義の変更が処理中。時間をおいて送り直してください                                                                                         |

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

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

#### リクエスト例

**Get memory candidates**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/memory-candidates \
-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/memory-candidates",
  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/memory-candidates",
{
  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/memory-candidates", 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`          | 組織の候補（orgId・label）    |
| `jobs`          | `array`          | 職種の候補（jobId・label）    |
| `unresolved`    | `number \| null` | 組織と職種を確かめられなかったメンバーの数 |
| `hasMore`       | `boolean`        | いつも false（全件を返します）    |

#### レスポンス例

```json
{
  "organizations": [
    {
      "orgId": "eng",
      "label": "エンジニアリング部門"
    }
  ],
  "jobs": [
    {
      "jobId": "dev",
      "label": "開発者"
    }
  ],
  "unresolved": 0,
  "hasMore": false
}
```

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

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

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

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

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

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

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

#### リクエスト例

**Update placement memory**

**curl**

```curl
curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/memory \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU",
  "orgId": "eng",
  "jobId": "dev"
}'
```

**Python**

```python
import requests

response = requests.patch(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/memory",
  headers={"Authorization": f"Bearer {token}"},
  json={'baseDigest': 'dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU', 'orgId': 'eng', 'jobId': 'dev'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/memory",
{
  method: "PATCH",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU", "orgId": "eng", "jobId": "dev"}),
}
);

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

**Go**

```go
payload := []byte(`{"baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU", "orgId": "eng", "jobId": "dev"}`)
req, _ := http.NewRequest("PATCH", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/memory", 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": "経理 Agent",
    "description": "請求書の金額と明細を照合します",
    "goal": "請求書の金額と明細を照合し、差異を報告する",
    "guardrail": "金額を書き換えない",
    "skills": [
      {
        "skillId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
        "name": "請求書の読み取り"
      }
    ],
    "skillCount": 1,
    "playbookId": null,
    "playbookName": null,
    "inputFiles": [],
    "stepIds": [
      "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"
    ],
    "sweeps": [],
    "runtimeConfigs": [
      {
        "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
        "runtimeConfig": null
      }
    ],
    "libraryBindings": [],
    "memoryOrgId": "eng",
    "memoryJobId": "dev",
    "instructionAddendum": null,
    "agentOwnerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "isShared": false,
    "runtimeKind": "autonomous",
    "marketplaceAgentId": null,
    "exclusiveToThisProject": true,
    "agentStopped": false,
    "relink": null,
    "digest": "Zhik2lSjR0HXwcqoh7OgPRUebWu1jON1_cveQsUv9r0"
  },
  "definitionApproval": null
}
```

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

| ステータス | code                            | 説明                                                                                                        |
| ----- | ------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `400` | `invalid_parameter`             | projectId・placementId が UUID の形式ではない、baseDigest が無い・空・文字列ではない、変える項目が無い、または orgId・jobId が文字列でも null でもない   |
| `400` | `invalid_body`                  | ボディが壊れた JSON、または JSON のオブジェクトではない                                                                         |
| `400` | `memory_not_candidate`          | 記憶の候補に無い値を指定した                                                                                            |
| `403` | `insufficient_scope`            | project:write スコープが不足                                                                                     |
| `403` | `forbidden`                     | システム連携のトークンで呼び出した                                                                                         |
| `403` | `owner_only`                    | オーナーではないメンバー                                                                                              |
| `403` | `sso_required`                  | SSO でログインしていない利用者                                                                                         |
| `404` | `placement_not_found`           | 配置が存在しない、ほかのプロジェクトの配置、またはメンバーではないプロジェクト                                                                   |
| `409` | `stale_base`                    | 取得した後に配置が変わっている。承認待ちがあるときは、既定の取得の 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`               | 同じ定義の変更が処理中。時間をおいて送り直してください                                                                               |
| `503` | `memory_candidates_unavailable` | メンバーの組織・職種を確かめられない（時間をおいて送り直してください）                                                                       |

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

配置の、このプロジェクトでの追加の指示（`instructionAddendum`）を書き換えます。実行のとき、Agent の指示（goal）の後ろに続けて渡します（Agent 本体は変えません）。プロジェクトのオーナーだけが呼べます。書き換えた後に始めた実行と、まだ起動していない巡回から効きます（始めている実行は、始めたときの指示のまま）。

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

| フィールド                 | 型                | 必須 | 説明                                        |
| --------------------- | ---------------- | -- | ----------------------------------------- |
| `baseDigest`          | `string`         | 必須 | その配置の digest                              |
| `instructionAddendum` | `string \| null` | 必須 | 追加の指示。5,000 文字まで。null・空の文字列・空白だけの文字列で外します |

#### リクエスト例

**Update placement instruction**

**curl**

```curl
curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/instruction \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU",
  "instructionAddendum": "金額は税込で照合してください"
}'
```

**Python**

```python
import requests

response = requests.patch(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/instruction",
  headers={"Authorization": f"Bearer {token}"},
  json={'baseDigest': 'dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU', 'instructionAddendum': '金額は税込で照合してください'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/instruction",
{
  method: "PATCH",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU", "instructionAddendum": "金額は税込で照合してください"}),
}
);

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

**Go**

```go
payload := []byte(`{"baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU", "instructionAddendum": "金額は税込で照合してください"}`)
req, _ := http.NewRequest("PATCH", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/instruction", 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": "経理 Agent",
    "description": "請求書の金額と明細を照合します",
    "goal": "請求書の金額と明細を照合し、差異を報告する",
    "guardrail": "金額を書き換えない",
    "skills": [
      {
        "skillId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
        "name": "請求書の読み取り"
      }
    ],
    "skillCount": 1,
    "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,
    "instructionAddendum": "金額は税込で照合してください",
    "agentOwnerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "isShared": false,
    "runtimeKind": "autonomous",
    "marketplaceAgentId": null,
    "exclusiveToThisProject": true,
    "agentStopped": false,
    "relink": null,
    "digest": "NX0HCliRM3UTX63-vwkd-VzC40s6Jhia8QD2l9Vh1Ic"
  },
  "definitionApproval": null
}
```

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

| ステータス | code                           | 説明                                                                                                                     |
| ----- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `400` | `invalid_parameter`            | projectId・placementId が UUID の形式ではない、baseDigest が無い・空・文字列ではない、instructionAddendum が無い・文字列でも null でもない、または 5,000 文字を超える |
| `400` | `invalid_body`                 | ボディが壊れた JSON、または JSON のオブジェクトではない                                                                                      |
| `403` | `insufficient_scope`           | project:write スコープが不足                                                                                                  |
| `403` | `forbidden`                    | システム連携のトークンで呼び出した                                                                                                      |
| `403` | `owner_only`                   | オーナーではないメンバー                                                                                                           |
| `403` | `sso_required`                 | SSO でログインしていない利用者                                                                                                      |
| `404` | `placement_not_found`          | 配置が存在しない、ほかのプロジェクトの配置、またはメンバーではないプロジェクト                                                                                |
| `409` | `stale_base`                   | 取得した後に配置が変わっている。承認待ちがあるときは、既定の取得の 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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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": "経理 Agent",
    "description": "請求書の金額と明細を照合します",
    "goal": "請求書の金額と明細を照合し、差異を報告する",
    "guardrail": "金額を書き換えない",
    "skills": [
      {
        "skillId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
        "name": "請求書の読み取り"
      }
    ],
    "skillCount": 1,
    "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,
    "instructionAddendum": null,
    "agentOwnerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "isShared": false,
    "runtimeKind": "autonomous",
    "marketplaceAgentId": null,
    "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` | `insufficient_scope`              | project:write スコープが不足                                                                                                                                                                                                                      |
| `403` | `forbidden`                       | システム連携のトークンで呼び出した                                                                                                                                                                                                                          |
| `403` | `owner_only`                      | オーナーではないメンバー                                                                                                                                                                                                                               |
| `403` | `sso_required`                    | SSO でログインしていない利用者                                                                                                                                                                                                                          |
| `403` | `feature_not_permitted`           | 巡回が有効になる変更（無効から有効にする、または有効な巡回の cron・timezone を変える。送らなかった項目は今の値で見ます）だが、管理者が定期実行の作成を許可していない。enabled に false を送る変更は通ります                                                                                                                       |
| `404` | `placement_not_found`             | 配置が存在しない、ほかのプロジェクトの配置、またはメンバーではないプロジェクト                                                                                                                                                                                                    |
| `409` | `stale_base`                      | 取得した後に配置が変わっている。承認待ちがあるときは、既定の取得の digest では合いません。definition=pending で読み直し、その digest を baseDigest に送ってください                                                                                                                                  |
| `409` | `principal`                       | プロジェクトの実行の主体（今のプロジェクトの持ち主）を確かめられない                                                                                                                                                                                                         |
| `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` で読めます。<!-- -->「メールで起動」はこの API では扱いません（作る・変える・消すは画面で行います）。

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

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

### 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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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` | `insufficient_scope`              | project:write スコープが不足                                                                                                                                                                                                                                                                                                                 |
| `403` | `forbidden`                       | システム連携のトークンで呼び出した                                                                                                                                                                                                                                                                                                                     |
| `403` | `owner_only`                      | オーナーではないメンバー                                                                                                                                                                                                                                                                                                                          |
| `403` | `sso_required`                    | SSO でログインしていない利用者                                                                                                                                                                                                                                                                                                                     |
| `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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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` | `insufficient_scope`              | project:write スコープが不足                                                                                                                                                                                 |
| `403` | `forbidden`                       | システム連携のトークンで呼び出した                                                                                                                                                                                     |
| `403` | `owner_only`                      | オーナーではないメンバー                                                                                                                                                                                          |
| `403` | `sso_required`                    | SSO でログインしていない利用者                                                                                                                                                                                     |
| `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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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` | `insufficient_scope`           | project:write スコープが不足                                                              |
| `403` | `forbidden`                    | システム連携のトークンで呼び出した                                                                  |
| `403` | `owner_only`                   | オーナーではないメンバー                                                                       |
| `403` | `sso_required`                 | SSO でログインしていない利用者                                                                  |
| `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` が返ります。

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

#### パスパラメータ

| パラメータ       | 型        | 必須 | 説明                 |
| ----------- | -------- | -- | ------------------ |
| `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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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}）には使えません |

#### レスポンス例

<!-- -->

<!-- -->

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

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

#### 再送

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

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

| ステータス | code                     | 説明                                                                            |
| ----- | ------------------------ | ----------------------------------------------------------------------------- |
| `400` | `invalid_event_id`       | eventId が無い、または形式が不正                                                          |
| `400` | `invalid_parameter`      | projectId または triggerId が UUID の形式ではない                                        |
| `400` | `invalid_body`           | リクエストボディが壊れた JSON、または JSON のオブジェクトではない                                        |
| `415` | `unsupported_media_type` | リクエストボディがあるのに、Content-Type が application/json ではない                            |
| `403` | `insufficient_scope`     | project:run スコープが不足                                                           |
| `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 を超過                                                          |

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

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

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

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

## 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)で読めます。

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

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

### 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://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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` | `insufficient_scope` | project:read スコープが不足     |
| `403` | `forbidden`          | システム連携のトークンで呼び出した        |
| `403` | `owner_only`         | オーナーではないメンバー             |
| `403` | `sso_required`       | SSO でログインしていない利用者        |
| `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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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` | `insufficient_scope`     | project:write スコープが不足                                                                                                                    |
| `403` | `forbidden`              | システム連携のトークンで呼び出した                                                                                                                        |
| `403` | `owner_only`             | オーナーではないメンバー                                                                                                                             |
| `403` | `sso_required`           | SSO でログインしていない利用者                                                                                                                        |
| `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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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` | `insufficient_scope`     | project:write スコープが不足                                                                                                                 |
| `403` | `forbidden`              | システム連携のトークンで呼び出した                                                                                                                     |
| `403` | `owner_only`             | オーナーではないメンバー                                                                                                                          |
| `403` | `sso_required`           | SSO でログインしていない利用者                                                                                                                     |
| `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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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` | `insufficient_scope` | project:write スコープが不足                         |
| `403` | `forbidden`          | システム連携のトークンで呼び出した                             |
| `403` | `owner_only`         | オーナーではないメンバー                                  |
| `403` | `sso_required`       | SSO でログインしていない利用者                             |
| `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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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` | `insufficient_scope` | project:read スコープが不足                                      |
| `403` | `forbidden`          | システム連携のトークンで呼び出した                                         |
| `403` | `owner_only`         | オーナーではないメンバー                                              |
| `403` | `sso_required`       | SSO でログインしていない利用者                                         |
| `404` | `webhook_not_found`  | Webhook が存在しない、ほかのプロジェクトのもの、またはメンバーではないプロジェクト             |

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

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

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

| メソッド  | エンドポイント                                           | 説明                     | スコープ (SaaS)     |
| ----- | ------------------------------------------------- | ---------------------- | --------------- |
| POST  | `/v1/projects/{projectId}/runs`                   | ワークフローの実行を開始           | `project:run`   |
| GET   | `/v1/projects/{projectId}/runs/{runId}`           | ワークフローの実行を取得           | `project:read`  |
| GET   | `/v1/projects/{projectId}/runs`                   | ワークフローの実行の一覧を取得        | `project:read`  |
| GET   | `/v1/projects/{projectId}/runs/{runId}/config`    | ワークフローの実行を始めたときの設定を取得  | `project:read`  |
| PATCH | `/v1/projects/{projectId}/runs/{runId}`           | ワークフローの実行の締め切りを決める・外す  | `project:write` |
| PUT   | `/v1/projects/{projectId}/runs/{runId}/approvers` | ワークフローの実行の確認担当者を付け替える  | `project:write` |
| POST  | `/v1/projects/{projectId}/runs/{runId}/cancel`    | ワークフローの実行を中断           | `project:run`   |
| GET   | `/v1/projects/{projectId}/runs/{runId}/resume`    | 閉じたワークフローの実行の再開の選択肢を取得 | `project:read`  |
| POST  | `/v1/projects/{projectId}/runs/{runId}/resume`    | 閉じたワークフローの実行を再開        | `project:run`   |

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

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

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

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

#### パスパラメータ

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

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

ボディは省けます。送信する場合は JSON のオブジェクトにしてください。<!-- -->下のフィールドのほかは無視されます。ただし config を送ると 400 Bad Request（invalid\_parameter）が返ります。

| パラメータ     | 型     | 必須 | 説明                                                                                                                                                                                                                 |
| --------- | ----- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `payload` | `any` | —  | 実行の依頼。JSON の値（オブジェクト・配列・文字列など）を、中身を変えずに受け取ります。最初の工程（分かれた後はレーンごとの最初の工程）のエージェントへの依頼に、JSON の文字列にして添えて渡されます。エージェントには、外から届いたデータで指示ではないものとして渡されます。依頼の中にファイルの ID を入れても、ファイルは添付されません。省略・null は依頼なし。JSON の文字列にして 8,000 文字まで |

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

<!-- -->

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

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

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

#### リクエスト例

**Start run**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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` を付けて再送すると `409 Conflict`（`origin_conflict`）が返ります。

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

| ステータス | code                              | 説明                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ----- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400` | `idempotency_key_required`        | Idempotency-Key ヘッダーが無い                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `400` | `idempotency_key_invalid`         | Idempotency-Key の長さまたは文字種が不正                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `400` | `invalid_parameter`               | projectId が UUID の形式ではない、または config を送った（この API では受け付けない。param は config）                                                                                                                                                                                                                                                                                                                                                                         |
| `400` | `payload_too_large`               | payload を JSON の文字列にした長さが 8,000 文字を超える                                                                                                                                                                                                                                                                                                                                                                                                           |
| `400` | `invalid_body`                    | リクエストボディが壊れた JSON、または JSON のオブジェクトではない                                                                                                                                                                                                                                                                                                                                                                                                           |
| `413` | `body_too_large`                  | リクエストボディが 16 KiB を超過                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `415` | `unsupported_media_type`          | リクエストボディがあるのに、Content-Type が application/json ではない                                                                                                                                                                                                                                                                                                                                                                                               |
| `403` | `insufficient_scope`              | project:run スコープが不足                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `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" の行は製品の画面で連携先を保存し直す、配置の relink（置いた Agent が指す、見つからなかったプレイブック・スキル）は Agent を spec つきで保存し直す（PATCH /v1/agents/{agentId}。spec を送らない更新では外れません）。blocking が false の行は実行を断らない、必要に応じて再度設定する項目で、DELETE /v1/projects/{projectId}/relink で消せますが、それだけでは始められません |
| `409` | `branch_ai_unavailable`           | AI に判定させる条件分岐の工程を、この環境では実行できない。管理者に判定の設定を頼むか、製品の画面でその工程を止めてから、新しく始めてください                                                                                                                                                                                                                                                                                                                                                                         |
| `409` | `automation_dlp_enabled`          | DLP 連携が有効な間は、外部の自動化の工程を保存・実行できない。管理者に DLP 連携を切ってもらってください。それまでは、外部の自動化の工程を止めるか外せば始められます                                                                                                                                                                                                                                                                                                                                                           |
| `409` | `automation_destination_missing`  | 外部の自動化の工程の宛先が見つからない。工程を変える API で automationConfig.destinationId を宛先の一覧（GET /v1/projects/automation-destinations）の有効な宛先にするか、その工程を止めてください。一覧に宛先が無いときは、管理者に頼んでください                                                                                                                                                                                                                                                                                  |
| `409` | `automation_destination_inactive` | 外部の自動化の工程の宛先が無効。管理者に宛先を有効にしてもらうか、工程を変える API で automationConfig.destinationId を宛先の一覧（GET /v1/projects/automation-destinations）の別の有効な宛先にするか、その工程を止めてください                                                                                                                                                                                                                                                                                           |
| `409` | `admin_stopped`                   | プロジェクトを、管理者が止めている。再開は管理者に頼む（この API では再開できない）                                                                                                                                                                                                                                                                                                                                                                                                     |
| `409` | `unsupported_runtime`             | プロジェクト内のエージェントの実行環境が混在しているなど、実行できない構成                                                                                                                                                                                                                                                                                                                                                                                                            |
| `409` | `origin_conflict`                 | 同じ Idempotency-Key で、違う payload を送った                                                                                                                                                                                                                                                                                                                                                                                                             |
| `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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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" 以外は、実行が終わったことを表します。ただし "closed\_rejected" と "closed\_failed" は、オーナーか運用担当（組織の運用の役割の人を含む）が再開すると、同じ実行が "running" に戻ります（endedAt も null に戻ります） |
| `originType`                      | `string \| null` | 実行の始まり方。"manual"（画面から開始）/ "api"（API で開始）/ "mail"（メールで開始）/ "cron"（定期実行）のいずれか                                                                                                                                                                                                                                     |
| `originRef`                       | `string \| null` | 始まり方ごとの参照値。API で開始した実行では、開始したときの Idempotency-Key の値                                                                                                                                                                                                                                                             |
| `currentStepId`                   | `string \| null` | 進んでいる工程の ID（UUID）。レーンに分かれて進んでいる間は、分岐する前の工程の ID。完了した実行では null。ほかの理由で終わった実行では、終わったときの工程の ID が残る場合があります                                                                                                                                                                                                            |
| `startedByRef`                    | `string \| null` | 実行を始めたもの。値は下の「実行を始めたもの」の表のとおり                                                                                                                                                                                                                                                                                   |
| `actorLabel`                      | `string \| null` | 利用者ではない起動者の表示名（システム連携の名前、またはメールの送信元のアドレス）。それ以外は null                                                                                                                                                                                                                                                            |
| `startedAt`                       | `string \| null` | 開始日時（ISO 8601）。開始前は null                                                                                                                                                                                                                                                                                        |
| `endedAt`                         | `string \| null` | 終了日時（ISO 8601）。終了前は null。閉じた実行を再開すると null に戻ります                                                                                                                                                                                                                                                                 |
| `summary`                         | `string \| null` | 完了した実行で、出力が記録された最後の完了した工程の出力（先頭 2,000 文字）。そうした工程が無い場合と、完了していない実行では null。プロジェクトに参加していない、組織の運用の役割の人には null                                                                                                                                                                                                        |
| `runtimeKind`                     | `string \| null` | 実行環境の種類（"autonomous"）。古い実行では null の場合があります                                                                                                                                                                                                                                                                      |
| `cancelRequestedAt`               | `string \| null` | 中断が求められた日時（ISO 8601）。求められていなければ null                                                                                                                                                                                                                                                                            |
| `deadlineAt`                      | `string \| null` | ワークフローの実行の締め切り（ISO 8601）。締め切りが無ければ null                                                                                                                                                                                                                                                                         |
| `configRevision`                  | `number \| null` | 案件設定のバージョン（Marketplace 版の実行だけ）。SaaS 版の実行では null                                                                                                                                                                                                                                                                 |
| `steps`                           | `array`          | 工程ごとの実行の記録。記録した順                                                                                                                                                                                                                                                                                                |
| `steps[].runStepId`               | `string`         | 工程の実行の ID（"rs:" で始まる）                                                                                                                                                                                                                                                                                           |
| `steps[].stepId`                  | `string \| null` | 工程の ID（UUID）                                                                                                                                                                                                                                                                                                    |
| `steps[].placementId`             | `string \| null` | その工程を担当した配置の ID（UUID）。Agent を動かさない行（確認の工程など）では null                                                                                                                                                                                                                                                             |
| `steps[].executionId`             | `string \| null` | Agent の実行の ID。Agent を動かし始めると付きます。外部の自動化の工程では null                                                                                                                                                                                                                                                               |
| `steps[].conversationId`          | `string \| null` | Agent の実行の会話の ID。Agent を動かし始めると付きます                                                                                                                                                                                                                                                                             |
| `steps[].status`                  | `string`         | "pending"（実行待ち）/ "running"（実行中）/ "waiting\_gate"（確認待ち）/ "done"（完了）/ "failed"（失敗）/ "skipped"（実行を省略）のいずれか                                                                                                                                                                                                         |
| `steps[].attempt`                 | `number \| null` | 同じ回の中での再試行の回数（1 から）。閉じた実行の再開と、接続の確認の承認で起動し直したときも増えます                                                                                                                                                                                                                                                            |
| `steps[].lane`                    | `string \| null` | 工程が属するレーンの ID。レーンに分かれていない工程は "main"                                                                                                                                                                                                                                                                             |
| `steps[].scheduledAt`             | `string \| null` | 工程に時刻が設定されているとき、その時刻まで待つ行の予定日時（ISO 8601）。動き始めると null                                                                                                                                                                                                                                                            |
| `steps[].startedAt`               | `string \| null` | 開始日時（ISO 8601）                                                                                                                                                                                                                                                                                                  |
| `steps[].endedAt`                 | `string \| null` | 終了日時（ISO 8601）                                                                                                                                                                                                                                                                                                  |
| `steps[].outputSummary`           | `string \| null` | 工程の出力の要約。プロジェクトに参加していない、組織の運用の役割の人には 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` | 確認の要約。確認の工程の行と、接続の確認の待ちの行（gateKind が "connection"）に付きます。それ以外の行では null                                                                                                                                                                                                                                           |
| `steps[].gate.decision`           | `string \| null` | "proceed"（進める）/ "send\_back"（差し戻す）/ "reject"（却下）のいずれか。決まっていなければ null                                                                                                                                                                                                                                            |
| `steps[].gate.waitSource`         | `string \| null` | 何を待つ確認か。"human"（人の判断）/ "external"（外部の条件）                                                                                                                                                                                                                                                                        |
| `steps[].resumeCommandId`         | `string \| null` | 閉じた実行の再開でこの行を起動したときの commandId。その再開で起動した行（選んだ工程と、起動し直したほかのレーン）に付きます。それ以外は null                                                                                                                                                                                                                                  |
| `steps[].resumeReason`            | `string \| null` | 閉じた実行の再開の理由の文。resumeCommandId と同じ行に付きます。それ以外は null                                                                                                                                                                                                                                                              |
| `steps[].supersededBy`            | `string \| null` | 閉じた実行の再開で、前の回に残っていた行を閉じたとき "resume"。それ以外は null                                                                                                                                                                                                                                                                  |
| `steps[].gateKind`                | `string \| null` | 接続の確認の待ちの行（Agent が人の確認の要る連携先を使おうとして止めたときに立つ行）なら "connection"。それ以外は null                                                                                                                                                                                                                                         |
| `steps[].connectionConfirmOf`     | `string \| null` | 接続の確認の承認で起動し直した行なら、その確認依頼の ID（workItemId）。それ以外は null                                                                                                                                                                                                                                                            |
| `steps[].handoff`                 | `object \| null` | この工程の実行で次の工程に渡した値と資料。工程に次の工程に渡す値と資料の役割（outputConfig）が無ければ null。中身を見られない人には出ません                                                                                                                                                                                                                                  |
| `steps[].handoff.values`          | `object`         | 値の名前 → 返された文（1 つ 1,000 文字まで）                                                                                                                                                                                                                                                                                    |
| `steps[].handoff.files`           | `object`         | 役割の名前 → { filename }（その役割の資料のファイル名）                                                                                                                                                                                                                                                                             |
| `steps[].handoff.missing[]`       | `object[]`       | 届かなかった物。name（値か役割の名前）と reason（"not\_returned"〈Agent が返さなかった〉/ "file\_not\_found"〈成果物に無い〉）                                                                                                                                                                                                                       |
| `steps[].handoff.truncated`       | `string[]`       | 1,000 文字で切った値の名前。無ければ \[]                                                                                                                                                                                                                                                                                       |
| `plannedPlacements`               | `array`          | 開始したときの設定で、動く予定の工程と配置の並び                                                                                                                                                                                                                                                                                        |
| `plannedPlacements[].stepId`      | `string \| null` | 工程の ID（UUID）                                                                                                                                                                                                                                                                                                    |
| `plannedPlacements[].placementId` | `string \| null` | 配置の ID（UUID）。確認の工程と Agent の無い工程では null                                                                                                                                                                                                                                                                          |
| `lanes`                           | `array`          | 分岐した後の、レーンごとの状況。分岐する前と、レーンを使わない実行では空の配列                                                                                                                                                                                                                                                                         |
| `lanes[].laneId`                  | `string`         | レーンの ID                                                                                                                                                                                                                                                                                                         |
| `lanes[].name`                    | `string \| null` | レーンの名前                                                                                                                                                                                                                                                                                                          |
| `lanes[].position`                | `number \| null` | レーンの並び（1 から）                                                                                                                                                                                                                                                                                                    |
| `lanes[].state`                   | `string`         | "running"（実行中）/ "waiting\_gate"（確認待ち）/ "arrived"（合流待ち）/ "closed"（終了）のいずれか                                                                                                                                                                                                                                       |
| `lanes[].currentStepId`           | `string \| null` | そのレーンで進んでいる工程の ID（UUID）。合流待ちのレーンでは null。終わったレーンでは、最後の工程の ID が残る場合があります                                                                                                                                                                                                                                          |
| `lanes[].arrived`                 | `boolean`        | 合流する地点に着いたか                                                                                                                                                                                                                                                                                                     |

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

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

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

2026-09-25 より前にシステム連携が始めた実行では、`startedByRef` は null です。

#### レスポンス例

<!-- -->

<!-- -->

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

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

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

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

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

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

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

#### リクエスト例

**List runs**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs?limit=20" \
-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",
  headers={"Authorization": f"Bearer {token}"},
  params={"limit": "20"},
)

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" + "?limit=20",
{
  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?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": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
      "actorLabel": null,
      "startedAt": "2026-09-17T01:30:00.000Z",
      "endedAt": null,
      "summary": null,
      "runtimeKind": "autonomous",
      "cancelRequestedAt": null,
      "deadlineAt": null,
      "configRevision": null,
      "steps": [
        {
          "runStepId": "rs:1042",
          "stepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
          "placementId": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8",
          "executionId": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
          "conversationId": "9c8b7a6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
          "status": "running",
          "attempt": 1,
          "lane": "main",
          "scheduledAt": null,
          "startedAt": "2026-09-17T01:30:01.000Z",
          "endedAt": null,
          "outputSummary": null,
          "outcome": null,
          "reasonCode": null,
          "held": false,
          "visit": 1,
          "reworkReason": null,
          "gateFor": null,
          "routedFrom": null,
          "late": null,
          "gate": null,
          "resumeCommandId": null,
          "resumeReason": null,
          "supersededBy": null,
          "gateKind": null,
          "connectionConfirmOf": null,
          "handoff": 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` | `insufficient_scope` | project:read スコープが不足                                                                                  |
| `403` | `forbidden`          | システム連携のトークンで呼び出した                                                                                     |
| `403` | `sso_required`       | SSO でログインしていない利用者                                                                                     |
| `404` | `project_not_found`  | プロジェクトが存在しない、またはメンバーではない                                                                              |

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

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

#### リクエスト例

**Get run 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/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/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/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/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。外部の自動化の工程は automationConfig を、Agent が実行する工程（"ai"）は outputConfig を含みます。条件分岐の工程は branchConfig を含みます）                                                                                                     |
| `lanes`         | `array \| null`  | 当時のレーン（id・name・parentLaneId・stepIds）。レーンを持たない形の写しでは、"main" の 1 本に全部の工程が入り、name は null                                                                                                                                                                   |
| `forks`         | `array \| null`  | 当時の分かれる所（id・afterStepId・laneIds・joinId）                                                                                                                                                                                                                 |
| `joins`         | `array \| null`  | 当時の合流する所（id・mode・laneIds・nextStepId）                                                                                                                                                                                                                    |
| `placements`    | `array \| null`  | 当時の配置（placementId・agentId・name・goal・guardrail・skills・playbookId・playbookName・runtimeConfigs・libraryBindings・sweeps・stepIds・instructionAddendum）。runtimeConfigs・libraryBindings は配置の項目と同じ形。goal・guardrail・skills・playbookId・instructionAddendum は始めたときの値 |
| `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",
      "automationConfig": null,
      "branchConfig": null,
      "reworkToStepId": null,
      "gateConfig": null,
      "gateKind": null,
      "schedule": null,
      "scheduleNextFireAt": null,
      "onDenied": null,
      "onDegraded": null,
      "outcomeRoutes": null,
      "laneId": null,
      "placementExecution": null,
      "outputConfig": null
    },
    {
      "stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "position": 2,
      "name": "差異の確認",
      "description": null,
      "enabled": true,
      "defaultZone": "gate",
      "automationConfig": null,
      "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,
      "outputConfig": null
    },
    {
      "stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
      "position": 3,
      "name": "差異の報告",
      "description": null,
      "enabled": true,
      "defaultZone": "ai",
      "automationConfig": null,
      "branchConfig": null,
      "reworkToStepId": null,
      "gateConfig": null,
      "gateKind": null,
      "schedule": null,
      "scheduleNextFireAt": null,
      "onDenied": null,
      "onDegraded": null,
      "outcomeRoutes": null,
      "laneId": null,
      "placementExecution": null,
      "outputConfig": 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": "経理 Agent",
      "goal": "請求書の金額と明細を照合し、差異を報告する",
      "guardrail": "金額を書き換えない",
      "skills": [
        {
          "skillId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
          "name": "請求書の読み取り"
        }
      ],
      "playbookId": null,
      "playbookName": null,
      "runtimeConfigs": [
        {
          "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
          "runtimeConfig": null
        }
      ],
      "libraryBindings": [],
      "sweeps": [],
      "stepIds": [
        "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"
      ],
      "instructionAddendum": null
    }
  ],
  "connectors": [],
  "sendBackLimit": 3
}
```

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

| ステータス | code                 | 説明                                                           |
| ----- | -------------------- | ------------------------------------------------------------ |
| `400` | `invalid_parameter`  | projectId・runId が UUID の形式ではない                               |
| `403` | `insufficient_scope` | project:read スコープが不足                                         |
| `403` | `forbidden`          | システム連携のトークンで呼び出した                                            |
| `403` | `sso_required`       | SSO でログインしていない利用者                                            |
| `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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "actorLabel": null,
  "startedAt": "2026-09-17T01:30:00.000Z",
  "endedAt": null,
  "summary": null,
  "runtimeKind": "autonomous",
  "cancelRequestedAt": null,
  "deadlineAt": "2026-11-20T09:00:00.000Z",
  "configRevision": null,
  "steps": [
    {
      "runStepId": "rs:1042",
      "stepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
      "placementId": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8",
      "executionId": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
      "conversationId": "9c8b7a6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
      "status": "running",
      "attempt": 1,
      "lane": "main",
      "scheduledAt": null,
      "startedAt": "2026-09-17T01:30:01.000Z",
      "endedAt": null,
      "outputSummary": null,
      "outcome": null,
      "reasonCode": null,
      "held": false,
      "visit": 1,
      "reworkReason": null,
      "gateFor": null,
      "routedFrom": null,
      "late": null,
      "gate": null,
      "resumeCommandId": null,
      "resumeReason": null,
      "supersededBy": null,
      "gateKind": null,
      "connectionConfirmOf": null,
      "handoff": 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` | `insufficient_scope`        | project:write スコープが不足                                                       |
| `403` | `forbidden`                 | システム連携のトークンで呼び出した                                                           |
| `403` | `operator_only`             | オーナーでも運用担当でもなく、組織の運用の役割も持たないメンバー                                            |
| `403` | `sso_required`              | SSO でログインしていない利用者                                                           |
| `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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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` | `insufficient_scope`     | project:write スコープが不足                                                                                                             |
| `403` | `forbidden`              | システム連携のトークンで呼び出した                                                                                                                 |
| `403` | `operator_only`          | オーナーでも運用担当でもなく、組織の運用の役割も持たないメンバー                                                                                                  |
| `403` | `sso_required`           | SSO でログインしていない利用者                                                                                                                 |
| `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 には停止を伝えます。
  <!-- -->
- 確認工程の、まだ判断されていない確認依頼は取り下げられます。

#### パスパラメータ

| パラメータ       | 型        | 必須 | 説明                  |
| ----------- | -------- | -- | ------------------- |
| `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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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` | `insufficient_scope`     | project:run スコープが不足                                                              |
| `403` | `operator_only`          | 自分が始めていないワークフローの実行を、オーナーでも運用担当でもなく、組織の運用の役割も持たないメンバーが中断しようとした                    |
| `403` | `sso_required`           | SSO でログインしていない利用者                                                                |
| `404` | `run_not_found`          | ワークフローの実行が存在しない、ほかのプロジェクトのもの、またはメンバーではないプロジェクト                                   |
| `413` | `body_too_large`         | ボディが 16 KiB を超える                                                                 |
| `415` | `unsupported_media_type` | ボディの Content-Type が application/json ではない                                        |

<!-- -->

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

却下または失敗で閉じたワークフローの実行（`status` が `"closed_rejected"`・`"closed_failed"`）を再開できるかと、再開できる工程を取得します。オーナーと運用担当（組織の運用の役割の人を含む）が呼べます（読む API ですが、オーナーでも運用担当でもなく、組織の運用の役割も持たないメンバーは `403 Forbidden`（`operator_only`）です）。閉じていないワークフローの実行や、完了・中断で終わったワークフローの実行でも `200 OK` で、`resumable` が `false` になります。

- 再開できる工程は、閉じる原因になった工程（却下では最後に却下された確認工程、失敗では最後に失敗した Agent が実行する工程か外部の自動化の工程）と同じレーンにある、その工程まで（その工程を含みます）の、Agent が実行する工程と外部の自動化の工程です。無効にしていない工程で、Agent が実行する工程は、ワークフローの実行を始めたときに Agent が置かれていた工程だけです。`"main"` では、分かれる前と合流した後をまたげません。
- 既定の工程（`defaultStepId`）は、原因の工程が Agent が実行する工程か外部の自動化の工程ならその工程、確認工程ならその前の直近の候補の工程です。

#### パスパラメータ

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

#### リクエスト例

**Get run resume options**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/resume \
-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/resume",
  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/resume",
{
  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/resume", 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                                                                                                                                   |
| `status`                    | `string`         | ワークフローの実行の今の状態                                                                                                                                  |
| `endedAt`                   | `string \| null` | 終わった日時（ISO 8601）                                                                                                                                |
| `resumable`                 | `boolean`        | 再開できるか                                                                                                                                          |
| `reason`                    | `string \| null` | 再開できないわけ。"status\_not\_resumable"（却下・失敗で閉じたワークフローの実行ではない）/ "run\_not\_resumable"（始めたときの設定が残っていない）/ "no\_resume\_step"（再開できる工程が無い）。再開できるときは null |
| `cause`                     | `object \| null` | 閉じた原因。原因の工程が分からないときは null                                                                                                                       |
| `cause.kind`                | `string`         | "rejected"（確認工程で却下された）/ "failed"（Agent が実行する工程か外部の自動化の工程が失敗した）                                                                                  |
| `cause.stepId`              | `string`         | 原因の工程の ID                                                                                                                                       |
| `cause.stepName`            | `string`         | 原因の工程の名前                                                                                                                                        |
| `cause.comment`             | `string \| null` | 却下の理由の文（却下で、理由が書かれているとき）                                                                                                                        |
| `cause.outcome`             | `string \| null` | 失敗した工程の結果（失敗のとき）                                                                                                                                |
| `cause.reasonCode`          | `string \| null` | 失敗した工程の理由のコード（失敗のとき）                                                                                                                            |
| `defaultStepId`             | `string \| null` | 既定の再開の工程の ID。再開できないときは null                                                                                                                     |
| `candidates`                | `array`          | 再開できる工程（工程の並び順）。再開できないときは空の配列                                                                                                                   |
| `candidates[].stepId`       | `string`         | 工程の ID。再開の fromStepId に入れます                                                                                                                     |
| `candidates[].name`         | `string`         | 工程の名前                                                                                                                                           |
| `candidates[].position`     | `number \| null` | 工程の並び順                                                                                                                                          |
| `candidates[].laneId`       | `string \| null` | 工程のあるレーンの ID（"main" の工程は null）                                                                                                                  |
| `candidates[].laneName`     | `string \| null` | レーンの名前（"main" と、名前の無いレーンは null）                                                                                                                 |
| `candidates[].lanePosition` | `number \| null` | "main" 以外のレーンの中での並び（1 から。"main" は null）                                                                                                         |

#### レスポンス例

```json
{
  "runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
  "status": "closed_failed",
  "endedAt": "2026-11-18T02:10:00.000Z",
  "resumable": true,
  "reason": null,
  "cause": {
    "kind": "failed",
    "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
    "stepName": "金額の確認",
    "comment": null,
    "outcome": "failed",
    "reasonCode": null
  },
  "defaultStepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
  "candidates": [
    {
      "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
      "name": "金額の確認",
      "position": 1,
      "laneId": null,
      "laneName": null,
      "lanePosition": null
    }
  ]
}
```

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

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

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

却下または失敗で閉じたワークフローの実行を、選んだ工程から、同じワークフローの実行のまま動かし直します。オーナーと運用担当（組織の運用の役割の人を含む）が呼べます。再開できる工程は、再開の選択肢の取得（`GET /v1/projects/{projectId}/runs/{runId}/resume`）の `candidates` で確かめてください。

再開すると、次のようになります。

- 同じワークフローの実行の `status` が `"running"` に戻り、`endedAt` が null に戻ります。
- 選んだ工程から、次の回（`attempt`）の工程の行が足されます。レーンの工程から再開するときは、合流する所に着いていたほかのレーンは着いたままで、閉じたときに止まったほかのレーンは止まった工程から起動し直します。
- 前の回に残っていた工程の行（`status` が `"pending"`・`"running"`・`"waiting_gate"`）は `"failed"` になり、`supersededBy` が `"resume"` になります。前の回の結果は残ります。
- 再開の理由の文は、この再開で起動した工程の行の `resumeReason` に残り、ワークフローの実行の取得で読めます。記録 (証跡) には「ワークフロー実行の再開」（`run.resumed`）が残りますが、理由の文は残りません。

#### パスパラメータ

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

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

| フィールド            | 型        | 必須 | 説明                                                                 |
| ---------------- | -------- | -- | ------------------------------------------------------------------ |
| `fromStepId`     | `string` | 必須 | 再開する工程の ID（UUID）。再開の選択肢の取得の candidates\[].stepId のどれか              |
| `reason`         | `string` | 必須 | 再開の理由（1000 文字まで。前後の空白も数えます。空白だけにはできません）                            |
| `expectedStatus` | `string` | 必須 | 今の状態。"closed\_rejected" か "closed\_failed"（再開の選択肢の取得の status と同じ値） |
| `commandId`      | `string` | 必須 | 送り直しを見分ける値（英数字と \_ . : - の 8〜128 文字）                               |

- 同じ `commandId` で同じ内容を送り直すと、再開はもう一度は行わず、1 回目と同じ `stepId`・`attempt`・`runStepIds` が返ります。`status` は、送り直したときのワークフローの実行の今の状態です。同じ `commandId` で違う内容を送ると `409 Conflict`（`command_conflict`）です。
- 送った `expectedStatus` と今の状態が違うと `409 Conflict`（`status_changed`）です（ほかの人が先に再開したときなど）。ワークフローの実行と再開の選択肢を取得し直し、まだ再開できるなら、その状態と選択肢で送り直してください。

#### リクエスト例

**Resume run**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/resume \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "fromStepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
  "reason": "入力データを直したため",
  "expectedStatus": "closed_failed",
  "commandId": "resume-20261118-0001"
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/resume",
  headers={"Authorization": f"Bearer {token}"},
  json={'fromStepId': '5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819', 'reason': '入力データを直したため', 'expectedStatus': 'closed_failed', 'commandId': 'resume-20261118-0001'},
)

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/resume",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"fromStepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819", "reason": "入力データを直したため", "expectedStatus": "closed_failed", "commandId": "resume-20261118-0001"}),
}
);

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

**Go**

```go
payload := []byte(`{"fromStepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819", "reason": "入力データを直したため", "expectedStatus": "closed_failed", "commandId": "resume-20261118-0001"}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/resume", 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                                                                        |
| `status`     | `string`         | 再開した後のワークフローの実行の状態                                                                   |
| `stepId`     | `string`         | 再開した工程の ID                                                                           |
| `attempt`    | `number \| null` | 再開した工程の行の回                                                                           |
| `runStepIds` | `array`          | この再開で起動した工程の行の ID（rs:<数値>。選んだ工程と、起動し直したほかのレーン）。ワークフローの実行の取得の steps\[].runStepId と同じ形 |

#### レスポンス例

```json
{
  "runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
  "status": "running",
  "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
  "attempt": 2,
  "runStepIds": [
    "rs:1051"
  ]
}
```

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

| ステータス | code                              | 説明                                                                                                                                                               |
| ----- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | `invalid_parameter`               | projectId・runId・fromStepId が UUID の形式ではない、reason が無い・文字列ではない・1000 文字を超える・空白だけ、expectedStatus が "closed\_rejected" / "closed\_failed" ではない、または commandId が無い・形の誤り |
| `400` | `invalid_body`                    | ボディが壊れた JSON、または JSON のオブジェクトではない                                                                                                                                |
| `400` | `invalid_resume_step`             | fromStepId が再開できる工程ではない                                                                                                                                          |
| `403` | `insufficient_scope`              | project:run スコープが不足                                                                                                                                              |
| `403` | `forbidden`                       | システム連携のトークンで呼び出した                                                                                                                                                |
| `403` | `operator_only`                   | オーナーでも運用担当でもなく、組織の運用の役割も持たないメンバー                                                                                                                                 |
| `403` | `sso_required`                    | SSO でログインしていない利用者                                                                                                                                                |
| `404` | `run_not_found`                   | ワークフローの実行が存在しない、ほかのプロジェクトのもの、cycle のプロジェクト、またはメンバーではないプロジェクト                                                                                                     |
| `409` | `status_changed`                  | expectedStatus と今の状態が違う                                                                                                                                          |
| `409` | `run_not_resumable`               | 始めたときの設定が残っていないワークフローの実行                                                                                                                                         |
| `409` | `project_inactive`                | プロジェクトが有効な状態ではない（一時停止中、またはアーカイブ済み）                                                                                                                               |
| `409` | `principal_suspended`             | プロジェクトを実行する人の利用を、管理者が止めている。管理者に、プロジェクトの持ち主を変更するか、利用の停止を解くよう頼む                                                                                                    |
| `409` | `automation_dlp_enabled`          | DLP 連携が有効な間は、外部の自動化の工程を保存・実行できない。管理者に DLP 連携を切ってもらってください。それまでは、外部の自動化の工程を止めるか外せば始められます                                                                           |
| `409` | `automation_destination_missing`  | 外部の自動化の工程の宛先が見つからない。工程を変える API で automationConfig.destinationId を宛先の一覧（GET /v1/projects/automation-destinations）の有効な宛先にするか、その工程を止めてください。一覧に宛先が無いときは、管理者に頼んでください  |
| `409` | `automation_destination_inactive` | 外部の自動化の工程の宛先が無効。管理者に宛先を有効にしてもらうか、工程を変える API で automationConfig.destinationId を宛先の一覧（GET /v1/projects/automation-destinations）の別の有効な宛先にするか、その工程を止めてください           |
| `409` | `admin_stopped`                   | プロジェクトを、管理者が止めている。再開は管理者に頼む                                                                                                                                      |
| `409` | `unsupported_runtime`             | このサービスで動かせない種類の Agent が置かれている                                                                                                                                    |
| `409` | `command_conflict`                | 同じ commandId で違う内容を送った                                                                                                                                           |
| `413` | `body_too_large`                  | ボディが 16 KiB を超える                                                                                                                                                 |
| `415` | `unsupported_media_type`          | ボディの Content-Type が application/json ではない                                                                                                                        |
| `429` | `too_many_active_runs`            | 同じプロジェクトで、実行中と確認待ちの実行が合わせて上限（3 件）に達している                                                                                                                          |

## 実行

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

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

| メソッド | エンドポイント                                                        | 説明                | スコープ (SaaS)    |
| ---- | -------------------------------------------------------------- | ----------------- | -------------- |
| GET  | `/v1/projects/{projectId}/executions`                          | 実行履歴を取得           | `project:read` |
| GET  | `/v1/projects/{projectId}/executions/{executionId}`            | 実行の結果を取得          | `project:read` |
| GET  | `/v1/projects/{projectId}/executions/{executionId}/operations` | ツールの呼び出しの一覧を取得    | `project:read` |
| GET  | `/v1/projects/{projectId}/executions/{executionId}/timeline`   | 実行の時系列を取得         | `project:read` |
| POST | `/v1/projects/{projectId}/executions/{executionId}/rerun`      | 失敗した巡回の実行をもう一度動かす | `project:run`  |

### 結果の値

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

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

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

Agent が人の確認の要る連携先を使おうとして止めた実行（接続の確認）は、`outcome` が `incomplete`、`reasonCode` が `connection_confirm_requested` です（画面の表示は「接続の確認のため停止」）。この実行は失敗に数えません（実行履歴の `outcome=problems`・[キュー](#queue)の巡回の失敗・[KPI](#kpi) の完遂率などに入りません）。確認は[確認依頼](#workitems)として届きます。

### 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）が一致する実行に絞り込み（例: connection\_confirm\_requested）。大文字と小文字を区別します。英字で始まり、英数字と \_ . : - の 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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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`  | 試行の回数（基盤の失敗でやり直すと増えます。workflow の工程は、接続の確認の承認で起動し直したときも増えます。cycle は、周期の巡回の `outcome` が `"failed"` または `"timeout"` で終わると新しい実行で 1 回だけ取り直し、その実行は 2 です（`"incomplete"`・`"stopped"`・`"denied"` などでは取り直しません）。ほかに起動し直したときは新しい実行になり、1 です） |
| `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" / "mail" / "cron"）、cycle は "cron"（巡回）、"mail"（メールで起動）または "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`  | 失敗した巡回の再実行で動いた実行なら、元の実行の ID（接続の確認の承認で起動し直した巡回の実行も、止めた実行の ID）。それ以外は null                                                                                                                                                         |
| `executions[].automationHttpStatus` | `number \| null`  | 外部の自動化の工程の送信で、宛先が返した HTTP の状態。時間切れ・届かなかったときと、外部の自動化でない行は 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,
      "automationHttpStatus": 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` | `insufficient_scope` | project:read スコープが不足                                                                                                                                                                                        |
| `403` | `forbidden`          | システム連携のトークンで呼び出した                                                                                                                                                                                           |
| `403` | `sso_required`       | SSO でログインしていない利用者                                                                                                                                                                                           |
| `404` | `project_not_found`  | プロジェクトが存在しない、またはメンバーではない                                                                                                                                                                                    |

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

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

<!-- -->

#### パスパラメータ

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

#### リクエスト例

**Get execution**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/rs:1842 \
-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/executions/rs:1842",
  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/rs:1842",
{
  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/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`  | 接続の確認の承認で起動し直した実行なら、その確認依頼の ID（workItemId）。それ以外は null                                                                                                                                                                    |
| `edited`                              | `object \| null`  | 確認の工程で、確認した人が出力の文を直して進めたとき、直した文と、直した人・時刻・確認依頼。次の工程には直した文が渡ります。summary は元の出力のまま。直していなければ null                                                                                                                             |
| `edited.text`                         | `string`          | 直した文                                                                                                                                                                                                                     |
| `edited.editedByUserId`               | `string \| null`  | 直した人の利用者 ID。記録が無いときは null                                                                                                                                                                                                |
| `edited.editedAt`                     | `string \| null`  | 直した日時（ISO 8601）。記録が無いときは null                                                                                                                                                                                            |
| `edited.workItemId`                   | `string \| null`  | その確認依頼の ID（workItemId）。記録が無いときは null                                                                                                                                                                                     |
| `billingSteps`                        | `integer \| null` | 業務のステップの数（KPI の業務のステップと同じ式）。終わった実行だけで、終わっていない実行は null。課金の対象でない結果は 0、件数が記録されていなければ 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）                                                                                                                                      |
| `automation`                          | `object \| null`  | 外部の自動化の工程の送信の記録。外部の自動化でない実行は null。値の無い項目は null                                                                                                                                                                           |
| `automation.destinationId`            | `string \| null`  | 宛先の ID                                                                                                                                                                                                                   |
| `automation.destinationName`          | `string \| null`  | 宛先の名前                                                                                                                                                                                                                    |
| `automation.httpStatus`               | `number \| null`  | 宛先が返した HTTP の状態。時間切れ・届かなかったときは null                                                                                                                                                                                      |
| `automation.durationMs`               | `number \| null`  | 送信にかかった時間（ミリ秒）                                                                                                                                                                                                           |
| `automation.bodyDigest`               | `string \| null`  | 送った本文の SHA-256（本文そのものは記録しません）                                                                                                                                                                                            |
| `automation.timeoutSeconds`           | `number \| null`  | 応答を待つ時間（秒）                                                                                                                                                                                                               |
| `automation.visit`                    | `number \| null`  | その工程の何回目の訪れか。送り直しでは同じ値、差し戻し・閉じた実行の再開では新しい値になります                                                                                                                                                                          |
| `handoff`                             | `object \| null`  | この実行で次の工程に渡した値と資料。工程に次の工程に渡す値と資料の役割（outputConfig）が無ければ null。中身を見られない人には出ません                                                                                                                                              |
| `handoff.values`                      | `object`          | 値の名前 → 返された文（1 つ 1,000 文字まで）                                                                                                                                                                                             |
| `handoff.files`                       | `object`          | 役割の名前 → { filename }（その役割の資料のファイル名）                                                                                                                                                                                      |
| `handoff.missing[]`                   | `object[]`        | 届かなかった物。name（値か役割の名前）と reason（"not\_returned"〈Agent が返さなかった〉/ "file\_not\_found"〈成果物に無い〉）                                                                                                                                |
| `handoff.truncated`                   | `string[]`        | 1,000 文字で切った値の名前。無ければ \[]                                                                                                                                                                                                |
| `library`                             | `object`          | その実行のプロジェクトのライブラリの記録。inputs（入力に使ったバージョン）と writes（書き戻した結果）の配列                                                                                                                                                             |
| `library.inputs[]`                    | `object`          | fileId・filename・deleted（プロジェクトのライブラリから消されたか）・at・versionId・contentDigest（中身の sha256）・workspaceName（作業場所での名前）。versionId が null のときは contentDigest でバージョンを見分けます                                                             |
| `library.writes[]`                    | `object`          | inputs の項目に加えて、inputVersion（書き戻しの元にしたバージョン）・result（"saved" / "unchanged" / "skipped" / "failed"）・reason（skipped・failed の理由。例: "not\_registered"・"invalid\_blob"）                                                         |

- `questions` と `gates` の `…Kind` が `"human"` なら、`…Ref` は利用者 ID です。人ではないときは `…Ref` が null です。
- `questions` は、実行の記録の新しい方から 200 行の中にある質問だけです。それより古い質問は、実行の時系列（`section` が `"confirmation"` の行）で読みます。
- `files` は 20 件までです。
- `library` は、その実行の記録の古い方から 200 行の中の分だけです。プロジェクトのライブラリに無いファイルの記録は入りません。
  <!-- -->
- ツールの呼び出しの 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,
  "billingSteps": 16,
  "automation": null,
  "handoff": 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` | `insufficient_scope`  | project:read スコープが不足                                            |
| `403` | `forbidden`           | システム連携のトークンで呼び出した                                               |
| `403` | `sso_required`        | SSO でログインしていない利用者                                               |
| `404` | `execution_not_found` | 実行が存在しない、ほかのプロジェクトの実行、またはメンバーではないプロジェクト                         |

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

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

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

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

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

#### リクエスト例

**List execution operations**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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` | `insufficient_scope`  | project:read スコープが不足                        |
| `403` | `forbidden`           | システム連携のトークンで呼び出した                           |
| `403` | `sso_required`        | SSO でログインしていない利用者                           |
| `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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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` | `insufficient_scope`  | project:read スコープが不足                                             |
| `403` | `forbidden`           | システム連携のトークンで呼び出した                                                |
| `403` | `sso_required`        | SSO でログインしていない利用者                                                |
| `404` | `execution_not_found` | 実行が存在しない、ほかのプロジェクトの実行、またはメンバーではないプロジェクト                          |
| `413` | `trace_too_large`     | 記録が大きすぎて読めない                                                     |
| `502` | `trace_unreachable`   | 記録を読めなかった（時間をおいて送り直してください）                                       |
| `503` | `trace_unavailable`   | 記録を読む機能が使えない                                                     |

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

cycle のプロジェクトで、失敗した巡回の実行を、同じ配置・同じ工程でもう一度動かします。画面の再実行と同じです。オーナーと運用担当（組織の運用の役割の人を含む）が呼べます。ボディは要りません（送っても使いません）。

- 周期の巡回が `outcome` `"failed"` または `"timeout"` で終わると、基盤が間もなく 1 回だけ新しい実行で取り直します（実行履歴の `attempt` が 2）。再実行を送る前に、同じ配置・工程の後の実行を確かめてください。取り直しでも失敗したときは、[キュー](#queue)の `sweep_failed` に取り直しの実行が出ます。
- 受け付けると、その失敗は[キュー](#queue)から外れます。
- 新しい実行は、動き始めると実行履歴に出ます。`rerunOf` が元の実行の ID の実行を探してください。
- 受け付けた後に同じ実行をもう一度送ると `409 Conflict`（`already_requested`）です。接続の確認の承認でこの実行が起動し直されたあとも、同じ実行を送ると `409 Conflict`（`already_requested`）です（起動し直しが、この実行の再実行として受け付けられているため）。起動し直した新しい実行は、失敗すれば再実行できます。
- 接続の確認の確認依頼が決まる前にこの実行の再実行を受け付けていると、承認しても起動し直しません。

#### パスパラメータ

| パラメータ         | 型        | 必須 | 説明                                      |
| ------------- | -------- | -- | --------------------------------------- |
| `projectId`   | `string` | 必須 | プロジェクト ID（UUID）                         |
| `executionId` | `string` | 必須 | 巡回の実行の ID（UUID）。workflow の工程の実行は指定できません |

#### リクエスト例

**Rerun 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/rerun \
-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/rerun",
  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/rerun",
{
  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/rerun", 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）

| フィールド            | 型         | 説明           |
| ---------------- | --------- | ------------ |
| `executionId`    | `string`  | 元の実行の ID     |
| `rerunRequested` | `boolean` | 受け付けたとき true |

#### レスポンス例

```json
{
  "executionId": "a1b2c3d4-e5f6-4789-8abc-def012345678",
  "rerunRequested": true
}
```

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

| ステータス | code                     | 説明                                                                                              |
| ----- | ------------------------ | ----------------------------------------------------------------------------------------------- |
| `400` | `invalid_parameter`      | projectId が UUID の形式ではない、executionId が rs:<数値> でも UUID でもない、または executionId が workflow の工程の実行   |
| `400` | `invalid_body`           | ボディが壊れた JSON、または JSON のオブジェクトではない                                                               |
| `403` | `insufficient_scope`     | project:run スコープが不足                                                                             |
| `403` | `forbidden`              | システム連携のトークンで呼び出した                                                                               |
| `403` | `operator_only`          | オーナーでも運用担当でもなく、組織の運用の役割も持たないメンバー                                                                |
| `403` | `sso_required`           | SSO でログインしていない利用者                                                                               |
| `404` | `execution_not_found`    | 実行が存在しない、ほかのプロジェクトの実行、その実行の配置が今はその工程を担当していない（配置を外した・担当工程を変えたなど）、またはメンバーではないプロジェクト               |
| `409` | `not_failed`             | 実行が失敗（incomplete・failed・denied・timeout）で終わっていない                                                 |
| `409` | `already_requested`      | この実行の再実行は受付済み（接続の確認の承認で、この実行が起動し直されたときを含みます）                                                    |
| `409` | `principal`              | プロジェクトの実行の主体（今のプロジェクトの持ち主）を確かめられない                                                              |
| `409` | `relink_required`        | 取り込みで見つからなかった参照をつなぎ直すまで、プロジェクトを始められない・再開できない。直し方は、ワークフローの実行の開始の誤りの表の relink\_required を参照してください |
| `409` | `admin_stopped`          | プロジェクト、または再実行する配置の Agent を、管理者が止めている。再開は管理者に頼む                                                  |
| `409` | `step_disabled`          | この配置の工程が無効になっている。プロジェクトのオーナーに工程を有効に戻してもらってから（工程を変える API で enabled を true）、もう一度動かしてください          |
| `413` | `body_too_large`         | ボディが 16 KiB を超える                                                                                |
| `415` | `unsupported_media_type` | ボディの Content-Type が application/json ではない                                                       |

## ファイル

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

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

| メソッド | エンドポイント                                  | 説明         | スコープ (SaaS)              |
| ---- | ---------------------------------------- | ---------- | ------------------------ |
| GET  | `/v1/projects/{projectId}/files/content` | ファイルの中身を取得 | `project:read / mcp:all` |

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

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

#### パスパラメータ

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

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

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

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

#### リクエスト例

**Get project file content**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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` | `insufficient_scope` | project:read スコープが不足                  |
| `403` | `forbidden`          | システム連携のトークンで呼び出した                     |
| `403` | `sso_required`       | SSO でログインしていない利用者                     |
| `404` | `project_not_found`  | プロジェクトが存在しない、またはメンバーではない              |

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

## ライブラリ

プロジェクトのメンバーで使うファイル（プロジェクトのライブラリ）を扱います。配置の工程に対応づけたファイルは、その工程の実行のときに作業場所に渡され、実行が書き戻すと新しいバージョンになります。会話の側の自分のファイル（[ファイルライブラリ](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference.md#library)）とは別のものです。

- 一覧・バージョンの一覧・登録・取り込み・新しいバージョン・前のバージョンに戻す・元の成果物の新しいバージョンを取り込むは、プロジェクトのメンバーなら呼べます。消すと配置の対応づけは、オーナーだけが呼べます（メンバーは `403 Forbidden`（`owner_only`））。組織の運用の役割を持ち、プロジェクトに参加していない人は、どれも `409 Conflict`（`forbidden_role`）です。
- 消すも `project:write` スコープです（`project:delete` ではありません）。
- 中身は、[ファイルの中身の取得](#get-project-file-content)（`GET /v1/projects/{projectId}/files/content`）に `filepath` を `path` で渡して取ります。前のバージョンは、`version_id` にバージョンの一覧の `versionId` を渡します。
- 送り直しを見分けるキーは受けません。同じ名前のファイルは登録・取り込みできない（`409 Conflict`（`name_taken`））ので、送り直しても 2 つにはなりません。実行の成果物は、`fileId` を付けると、同じ名前のファイルの新しいバージョンとして取り込めます（そのファイルと同じ種類（拡張子）の成果物だけです。同じとみなす拡張子は[新しいバージョンを足す](#add-project-library-version)にあります）。

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

| メソッド   | エンドポイント                                                              | 説明                  | スコープ (SaaS)     |
| ------ | -------------------------------------------------------------------- | ------------------- | --------------- |
| GET    | `/v1/projects/{projectId}/library`                                   | ファイルの一覧を取得          | `project:read`  |
| GET    | `/v1/projects/{projectId}/library/{fileId}/versions`                 | ファイルのバージョンの一覧を取得    | `project:read`  |
| POST   | `/v1/projects/{projectId}/library`                                   | ファイルを登録             | `project:write` |
| POST   | `/v1/projects/{projectId}/library/copy`                              | ファイルを取り込む           | `project:write` |
| PUT    | `/v1/projects/{projectId}/library/{fileId}/content`                  | 新しいバージョンを足す         | `project:write` |
| POST   | `/v1/projects/{projectId}/library/{fileId}/restore`                  | 前のバージョンに戻す          | `project:write` |
| POST   | `/v1/projects/{projectId}/library/{fileId}/import-latest`            | 元の成果物の新しいバージョンを取り込む | `project:write` |
| DELETE | `/v1/projects/{projectId}/library/{fileId}`                          | ファイルを消す             | `project:write` |
| PUT    | `/v1/projects/{projectId}/placements/{placementId}/library-bindings` | 配置の工程にファイルを対応づける    | `project:write` |

### ファイルの項目

一覧の 1 件と、登録・取り込み・新しいバージョン・前のバージョンに戻す・元の成果物の新しいバージョンの取り込みの応答の項目です。

| フィールド              | 型                | 説明                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fileId`           | `string`         | ファイルの ID（UUID）                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `filename`         | `string \| null` | ファイルの名前                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `filepath`         | `string`         | ファイルのパス。ファイルの中身の取得の path にそのまま渡せます                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `source`           | `string`         | "user"（人が登録・取り込み）/ "agent"（実行の成果物から取り込み）                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `sourceFile`       | `object \| null` | 実行の成果物から取り込んだファイルの、元の成果物。executionId はその実行の ID（分からないときは null）、filepath は成果物のパス。後で取り込み（POST /v1/projects/{projectId}/library/copy に fileId を付けて）で別の実行の成果物を新しいバージョンとして入れると、その実行に替わります。元の成果物の新しいバージョンの取り込み（import-latest）では替わりません（中身は見つかったいちばん新しい成果物になり、executionId・filepath は前のまま）。実行の成果物から取り込んでいないファイルは null                                                                                                                                                |
| `sourceFiles`      | `object[]`       | 実行の成果物からこのファイルに入れた記録の並び（executionId・filepath。古い順）。取り込み（POST /v1/projects/{projectId}/library/copy）と、画面の「毎回この名前で保存」の分が入ります。実行の成果物から作ったファイルは、作ったときの組がいつも残り、その後の記録は新しい 50 件まで（最大 51 件）。アップロードなどで作ったファイルは、記録の新しい 50 件まで。それより古い記録から落ちます。中身が同じでバージョンが増えなかった取り込みも入ります。元の成果物の新しいバージョンの取り込み（import-latest）は入りません。ある実行の成果物を取り込みでこのファイルに入れたかは、この並びで分かります。ふつうは最後の要素が sourceFile と同じです。無ければ \[]                                                                         |
| `newerVersionAt`   | `string \| null` | 元の成果物（巡回の成果物から取り込んだファイルは、後の回の同じ filepath の成果物も。下を参照）に、このファイルの最新のバージョンより 1 分を超えて新しいバージョンがあるときの、その時刻（ISO 8601）。無いとき・配置の工程に対応づけたファイル（実行が書き戻します）・照らす成果物をどれも読めないときは null。巡回の成果物から取り込んだファイルは、元の成果物と、同じ配置の同じ工程の巡回が使った作業場所のうち新しい 5 つにある、同じ filepath の成果物を照らし、いちばん新しいものの時刻を返します（周期で動く巡回は同じ作業場所を使い続け、Webhook やメールで動いた巡回と、巡回の再実行は、回ごとに新しい作業場所になります）。ワークフローの工程の成果物から取り込んだファイルは、元の成果物だけを照らします。値が入るのは一覧だけで、書き込みの応答では null。元の成果物が同じ中身のまま新しく書かれたときは、取り込んでもバージョンが増えず、値は残ります |
| `mimeType`         | `string?`        | MIME タイプ。分からないときは含まれません                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `size`             | `number?`        | ファイルサイズ（バイト）。分からないときは含まれません                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `currentVersionId` | `string \| null` | 今のバージョンの ID                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `digest`           | `string`         | 新しいバージョン・前のバージョンに戻す・fileId を付けた取り込み・元の成果物の新しいバージョンの取り込みで baseDigest に送る値                                                                                                                                                                                                                                                                                                                                                                                   |
| `createdAt`        | `string \| null` | 作成日時（ISO 8601）                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `updatedAt`        | `string \| null` | 最終更新日時（ISO 8601）                                                                                                                                                                                                                                                                                                                                                                                                                                           |

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

プロジェクトのライブラリのファイルを、最終更新日時の順に取得します。カーソルベースのページネーションに対応しています。

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

| パラメータ    | 型         | デフォルト    | 説明                             |
| -------- | --------- | -------- | ------------------------------ |
| `source` | `string`  | `—`      | "user" または "agent" で絞り込み       |
| `order`  | `string`  | `"desc"` | "asc"（古い順）または "desc"（新しい順）     |
| `limit`  | `integer` | `50`     | 1 ページの取得件数（1-100）              |
| `cursor` | `string`  | `—`      | 次ページ取得用カーソル（前回レスポンスの cursor 値） |

#### リクエスト例

**List project library files**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library?source=user&limit=20" \
-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/library",
  headers={"Authorization": f"Bearer {token}"},
  params={"source": "user", "limit": "20"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library" + "?source=user&limit=20",
{
  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/library?source=user&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）

| フィールド     | 型         | 説明                                    |
| --------- | --------- | ------------------------------------- |
| `files`   | `array`   | ファイルの配列。1 件の項目は上の「ファイルの項目」            |
| `hasMore` | `boolean` | 次のページが存在するかどうか                        |
| `cursor`  | `string`  | 次ページ取得用カーソル。hasMore が true の場合のみ含まれます |

#### レスポンス例

```json
{
  "files": [
    {
      "fileId": "8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6",
      "filename": "rules.xlsx",
      "filepath": "/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6",
      "source": "user",
      "sourceFile": null,
      "sourceFiles": [],
      "newerVersionAt": null,
      "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "size": 20480,
      "currentVersionId": "3b8a1c5e-7d2f-4e9a-a6c0-1f4d8b2e5a79",
      "digest": "WyIzYjhhMWM1ZS03ZDJmLTRlOWEtYTZjMC0xZjRkOGIyZTVhNzkiLCI1MDE4OTQ4OTEyNGNhODdmYjBkMzdiMjg4Y2E5YjU4OWU3MWEwMTgxMDlmMjk3NWFiYzZlMjRjZTFhMmVlMjI4Il0",
      "createdAt": "2026-11-10T01:00:00.000Z",
      "updatedAt": "2026-11-10T01:00:00.000Z"
    }
  ],
  "hasMore": false
}
```

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

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

### GET`/v1/projects/{projectId}/library/{fileId}/versions`

ファイルのバージョンの一覧を、新しい順に取得します。直近 50 個までで、`hasMore` はいつも `false` です（それより古いバージョンがあっても返りません）。

#### リクエスト例

**List project library file versions**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6/versions \
-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/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6/versions",
  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/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6/versions",
{
  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/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6/versions", 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）

| フィールド                      | 型                | 説明                                                                       |
| -------------------------- | ---------------- | ------------------------------------------------------------------------ |
| `fileId`                   | `string`         | ファイルの ID                                                                 |
| `currentVersionId`         | `string \| null` | 今のバージョンの ID                                                              |
| `digest`                   | `string`         | 新しいバージョン・前のバージョンに戻す・fileId を付けた取り込み・元の成果物の新しいバージョンの取り込みで baseDigest に送る値 |
| `versions`                 | `array`          | バージョンの配列（新しい順）                                                           |
| `versions[].versionId`     | `string \| null` | バージョンの ID。ファイルの中身の取得の version\_id、前のバージョンに戻すの versionId に渡します            |
| `versions[].size`          | `number \| null` | 大きさ（バイト）                                                                 |
| `versions[].createdAt`     | `string \| null` | バージョンができた日時（ISO 8601）                                                    |
| `versions[].isCurrent`     | `boolean`        | 今のバージョンかどうか                                                              |
| `versions[].source`        | `string \| null` | "register"（登録・新しいバージョン）/ "restore"（前のバージョンに戻した）/ "writeback"（実行の書き戻し）    |
| `versions[].contentDigest` | `string \| null` | 中身の sha256                                                               |
| `versions[].createdByKind` | `string \| null` | バージョンを書いたものの種類（"human" / "system"）                                       |
| `versions[].createdByRef`  | `string \| null` | バージョンを書いたもの。人なら利用者 ID、実行の書き戻しなら execution:<実行の ID>                       |
| `versions[].executionId`   | `string \| null` | 書き戻した実行の ID（書き戻しのときだけ）                                                   |
| `hasMore`                  | `boolean`        | いつも false                                                                |

バージョンの記録を読めないときは、`source`・`contentDigest`・`createdByKind`・`createdByRef` が null です。

#### レスポンス例

```json
{
  "fileId": "8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6",
  "currentVersionId": "3b8a1c5e-7d2f-4e9a-a6c0-1f4d8b2e5a79",
  "digest": "WyIzYjhhMWM1ZS03ZDJmLTRlOWEtYTZjMC0xZjRkOGIyZTVhNzkiLCI1MDE4OTQ4OTEyNGNhODdmYjBkMzdiMjg4Y2E5YjU4OWU3MWEwMTgxMDlmMjk3NWFiYzZlMjRjZTFhMmVlMjI4Il0",
  "versions": [
    {
      "versionId": "3b8a1c5e-7d2f-4e9a-a6c0-1f4d8b2e5a79",
      "size": 20480,
      "createdAt": "2026-11-10T01:00:00.000Z",
      "isCurrent": true,
      "source": "register",
      "contentDigest": "50189489124ca87fb0d37b288ca9b589e71a018109f2975abc6e24ce1a2ee228",
      "createdByKind": "human",
      "createdByRef": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
      "executionId": null
    }
  ],
  "hasMore": false
}
```

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

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

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

ファイルを 1 つ登録します。リクエストは `multipart/form-data` で送ります。ファイル名が、そのままライブラリでの名前になります。ファイルの種類（`mimeType`）は、ファイル名の拡張子から決まります（送った部分の `Content-Type` は使いません。拡張子から分からなければ `application/octet-stream`）。

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

| フィールド   | 型      | 必須 | 説明                                                                 |
| ------- | ------ | -- | ------------------------------------------------------------------ |
| `files` | `file` | 必須 | 登録するファイル（1 つだけ。512 MB まで）。ファイル名は前後の空白を除いて 255 文字までで、/・\・制御文字は使えません |

- 応答が届かなかったとき（`504 Gateway Timeout`（`upstream_timeout`）など）は、登録されていることがあります。一覧で確かめてから送り直してください。
- 記録 (証跡) に残ります。

#### リクエスト例

**Register project library file**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library \
-H "Authorization: Bearer <access_token>" \
-F "files=@rules.xlsx"
```

**Python**

```python
import requests

with open("rules.xlsx", "rb") as f:
  response = requests.post(
      "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library",
      headers={"Authorization": f"Bearer {token}"},
      files={"files": f},
      data={},
  )

print(response.json())
```

**TypeScript**

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

const response = await fetch("https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library", {
method: "POST",
headers: { "Authorization": "Bearer " + accessToken },
body: formData,
});

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

**Go**

```go
file, _ := os.Open("rules.xlsx")
defer file.Close()

body := &bytes.Buffer{}
writer := multipart.NewWriter(body)
part, _ := writer.CreateFormFile("files", "rules.xlsx")
io.Copy(part, file)
writer.Close()

req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library", 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）

登録したファイル（上の「ファイルの項目」）を返します。

#### レスポンス例

```json
{
  "fileId": "8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6",
  "filename": "rules.xlsx",
  "filepath": "/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6",
  "source": "user",
  "sourceFile": null,
  "sourceFiles": [],
  "newerVersionAt": null,
  "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  "size": 20480,
  "currentVersionId": "3b8a1c5e-7d2f-4e9a-a6c0-1f4d8b2e5a79",
  "digest": "WyIzYjhhMWM1ZS03ZDJmLTRlOWEtYTZjMC0xZjRkOGIyZTVhNzkiLCI1MDE4OTQ4OTEyNGNhODdmYjBkMzdiMjg4Y2E5YjU4OWU3MWEwMTgxMDlmMjk3NWFiYzZlMjRjZTFhMmVlMjI4Il0",
  "createdAt": "2026-11-10T01:00:00.000Z",
  "updatedAt": "2026-11-10T01:00:00.000Z"
}
```

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

| ステータス | code                              | 説明                                                                |
| ----- | --------------------------------- | ----------------------------------------------------------------- |
| `400` | `invalid_parameter`               | projectId が UUID の形式ではない、または files が無い・2 つ以上・files 以外の項目でファイルを送った |
| `400` | `invalid_filename`                | ファイル名が空・255 文字を超える、または使えない文字を含む                                   |
| `403` | `insufficient_scope`              | project:write スコープが不足                                             |
| `403` | `forbidden`                       | システム連携のトークンで呼び出した                                                 |
| `403` | `sso_required`                    | SSO でログインしていない利用者                                                 |
| `403` | `feature_not_permitted`           | 管理者がファイルの添付を許可していない                                               |
| `404` | `project_not_found`               | プロジェクトが存在しない、またはメンバーではない                                          |
| `409` | `name_taken`                      | 同じ名前のファイルがプロジェクトのライブラリにある                                         |
| `413` | `file_too_large`                  | ファイルが 512 MB を超える                                                 |
| `415` | `unsupported_media_type`          | Content-Type が multipart/form-data ではない                           |
| `503` | `feature_permissions_unavailable` | 機能の許可を確かめられない（時間をおいて送り直す）                                         |

### POST`/v1/projects/{projectId}/library/copy`

自分のファイルライブラリのファイル、またはこのプロジェクトの実行の成果物を、プロジェクトのライブラリに取り込みます。1 回に 1 件です。自分のファイルライブラリのファイルは取り込んだ時点の中身を、実行の成果物はその実行の記録の終わりの時点のバージョンを写します。元のファイルを後で変えても、取り込んだファイルは変わりません。

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

| フィールド         | 型        | 必須 | 説明                                                                                                                     |
| ------------- | -------- | -- | ---------------------------------------------------------------------------------------------------------------------- |
| `filepath`    | `string` | 必須 | 取り込むファイルのパス。自分のファイルライブラリのファイルは GET /v1/library の filepath、実行の成果物は実行の結果の files\[].filepath（1024 文字まで）                   |
| `executionId` | `string` | —  | 実行の成果物を取り込むときの、その実行の ID（rs:<数値> または UUID）。省くと、自分のファイルライブラリのファイルを取り込みます                                                 |
| `fileId`      | `string` | —  | 実行の成果物を、プロジェクトのライブラリにある既存のファイルの新しいバージョンとして取り込むときの、そのファイルの fileId（UUID）。executionId と一緒にだけ送れます。そのファイルと同じ種類（拡張子）の成果物だけです |
| `baseDigest`  | `string` | —  | fileId を送るときは必須。そのファイルの digest（一覧・バージョンの一覧・書き込みの応答の値）                                                                  |

- `fileId` を付けると、そのファイルに新しいバージョンを足します（`name_taken` にはなりません）。取り込む成果物の名前の拡張子が、そのファイルの名前の拡張子と違うと断ります（`409 Conflict`（`type_mismatch`）。同じとみなす拡張子は[新しいバージョンを足す](#add-project-library-version)にあります）。中身が今のバージョンと同じなら、バージョンは増えません。

記録 (証跡) に残ります（`fileId` を付けたときは、バージョンが増えたときだけ）。

#### リクエスト例

**Copy file into project library**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/copy \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "filepath": "/users/11111111-2222-3333-4444-555555555555/plans/550e8400-e29b-41d4-a716-446655440000/deliverables/report.xlsx"
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/copy",
  headers={"Authorization": f"Bearer {token}"},
  json={'filepath': '/users/11111111-2222-3333-4444-555555555555/plans/550e8400-e29b-41d4-a716-446655440000/deliverables/report.xlsx'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/copy",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"filepath": "/users/11111111-2222-3333-4444-555555555555/plans/550e8400-e29b-41d4-a716-446655440000/deliverables/report.xlsx"}),
}
);

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

**Go**

```go
payload := []byte(`{"filepath": "/users/11111111-2222-3333-4444-555555555555/plans/550e8400-e29b-41d4-a716-446655440000/deliverables/report.xlsx"}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/copy", 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 / 200 OK）

取り込んだファイル（上の「ファイルの項目」）を返します。`fileId` を付けないときは `201 Created`、付けたときは `200 OK` です。

#### レスポンス例

```json
{
  "fileId": "4a6c8e0f-2b3d-4e5f-9a1b-7c8d9e0f1a2b",
  "filename": "report.xlsx",
  "filepath": "/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/4a6c8e0f-2b3d-4e5f-9a1b-7c8d9e0f1a2b",
  "source": "user",
  "sourceFile": null,
  "sourceFiles": [],
  "newerVersionAt": null,
  "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  "size": 20480,
  "currentVersionId": "3b8a1c5e-7d2f-4e9a-a6c0-1f4d8b2e5a79",
  "digest": "WyIzYjhhMWM1ZS03ZDJmLTRlOWEtYTZjMC0xZjRkOGIyZTVhNzkiLCI1MDE4OTQ4OTEyNGNhODdmYjBkMzdiMjg4Y2E5YjU4OWU3MWEwMTgxMDlmMjk3NWFiYzZlMjRjZTFhMmVlMjI4Il0",
  "createdAt": "2026-11-10T01:00:00.000Z",
  "updatedAt": "2026-11-10T01:00:00.000Z"
}
```

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

| ステータス | code                     | 説明                                                                                                                                                                                  |
| ----- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | `invalid_parameter`      | projectId が UUID の形式ではない、filepath が無い・空・1024 文字を超える、executionId が rs:<数値> でも UUID でもない、fileId が UUID の形式ではない、executionId 無しで fileId を送った、または fileId を送ったのに baseDigest が無い・空・文字列ではない |
| `400` | `invalid_body`           | ボディが壊れた JSON、または JSON のオブジェクトではない                                                                                                                                                   |
| `400` | `file_not_found`         | filepath のファイルが無い・自分のものではない、またはその実行の成果物に無い                                                                                                                                          |
| `400` | `execution_not_found`    | executionId の実行が無い、またはほかのプロジェクトの実行                                                                                                                                                  |
| `400` | `invalid_filename`       | ファイルの名前が使えない                                                                                                                                                                        |
| `403` | `insufficient_scope`     | project:write スコープが不足                                                                                                                                                               |
| `403` | `forbidden`              | システム連携のトークンで呼び出した                                                                                                                                                                   |
| `403` | `sso_required`           | SSO でログインしていない利用者                                                                                                                                                                   |
| `404` | `project_not_found`      | プロジェクトが存在しない、またはメンバーではない                                                                                                                                                            |
| `404` | `file_not_found`         | fileId のファイルが存在しない・消されている                                                                                                                                                           |
| `409` | `name_taken`             | 同じ名前のファイルがプロジェクトのライブラリにある（実行の成果物なら、そのファイルの fileId と baseDigest を付けて送ると、新しいバージョンとして取り込めます）                                                                                           |
| `409` | `stale_base`             | 取得した後に fileId のファイルのバージョンが変わっている                                                                                                                                                    |
| `409` | `overwritten`            | その実行の記録の時点のバージョンが、後の実行で上書きされて残っていない（それを書いた後の実行の成果物から取り込んでください）                                                                                                                      |
| `409` | `type_mismatch`          | fileId を付けたとき、取り込む成果物の名前の拡張子が、そのファイルの名前の拡張子と違う（同じ拡張子の成果物を選ぶか、fileId と baseDigest を外して新しいファイルとして取り込んでください）                                                                           |
| `413` | `file_too_large`         | 取り込むファイルが 512 MB を超える                                                                                                                                                               |
| `413` | `body_too_large`         | ボディが 16 KiB を超える                                                                                                                                                                    |
| `415` | `unsupported_media_type` | ボディの Content-Type が application/json ではない                                                                                                                                           |

### PUT`/v1/projects/{projectId}/library/{fileId}/content`

ファイルに新しいバージョンを足します。リクエストは `multipart/form-data` で送ります。前のバージョンは残ります。ファイルの種類（`mimeType`）は、ライブラリでの名前の拡張子から決まります（`Content-Type` は使いません）。送ったファイルの名前の拡張子が、ライブラリでの名前の拡張子と違うと断ります（`409 Conflict`（`type_mismatch`）。大文字小文字は区別せず、`jpg` と `jpeg`・`htm` と `html`・`tif` と `tiff`・`yml` と `yaml` は同じ種類として扱います）。ライブラリでの名前は変わりません。

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

| フィールド        | 型        | 必須 | 説明                                  |
| ------------ | -------- | -- | ----------------------------------- |
| `baseDigest` | `string` | 必須 | ファイルの digest（一覧・バージョンの一覧・書き込みの応答の値） |
| `files`      | `file`   | 必須 | 新しいバージョンの中身（1 つだけ。512 MB まで）        |

- 中身が今のバージョンと同じなら、バージョンは増えません（`currentVersionId`・`digest` は変わりません）。
- 送り直すと、1 回目でバージョンが変わっているため `409 Conflict`（`stale_base`）が返ります。バージョンの一覧で確かめてください。
- バージョンが増えたときだけ、記録 (証跡) に残ります。

#### リクエスト例

**Add library file version**

**curl**

```curl
curl -X PUT https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6/content \
-H "Authorization: Bearer <access_token>" \
-F "files=@rules.xlsx" \
-F "baseDigest=WyIzYjhhMWM1ZS03ZDJmLTRlOWEtYTZjMC0xZjRkOGIyZTVhNzkiLCI1MDE4OTQ4OTEyNGNhODdmYjBkMzdiMjg4Y2E5YjU4OWU3MWEwMTgxMDlmMjk3NWFiYzZlMjRjZTFhMmVlMjI4Il0"
```

**Python**

```python
import requests

with open("rules.xlsx", "rb") as f:
  response = requests.put(
      "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6/content",
      headers={"Authorization": f"Bearer {token}"},
      files={"files": f},
      data={"baseDigest": "WyIzYjhhMWM1ZS03ZDJmLTRlOWEtYTZjMC0xZjRkOGIyZTVhNzkiLCI1MDE4OTQ4OTEyNGNhODdmYjBkMzdiMjg4Y2E5YjU4OWU3MWEwMTgxMDlmMjk3NWFiYzZlMjRjZTFhMmVlMjI4Il0"},
  )

print(response.json())
```

**TypeScript**

```typescript
const formData = new FormData();
formData.append("files", file); // File object
formData.append("baseDigest", "WyIzYjhhMWM1ZS03ZDJmLTRlOWEtYTZjMC0xZjRkOGIyZTVhNzkiLCI1MDE4OTQ4OTEyNGNhODdmYjBkMzdiMjg4Y2E5YjU4OWU3MWEwMTgxMDlmMjk3NWFiYzZlMjRjZTFhMmVlMjI4Il0");

const response = await fetch("https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6/content", {
method: "PUT",
headers: { "Authorization": "Bearer " + accessToken },
body: formData,
});

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

**Go**

```go
file, _ := os.Open("rules.xlsx")
defer file.Close()

body := &bytes.Buffer{}
writer := multipart.NewWriter(body)
part, _ := writer.CreateFormFile("files", "rules.xlsx")
io.Copy(part, file)
writer.WriteField("baseDigest", "WyIzYjhhMWM1ZS03ZDJmLTRlOWEtYTZjMC0xZjRkOGIyZTVhNzkiLCI1MDE4OTQ4OTEyNGNhODdmYjBkMzdiMjg4Y2E5YjU4OWU3MWEwMTgxMDlmMjk3NWFiYzZlMjRjZTFhMmVlMjI4Il0")
writer.Close()

req, _ := http.NewRequest("PUT", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6/content", 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)
```

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

新しいバージョンを足した後のファイル（上の「ファイルの項目」）を返します。

#### レスポンス例

```json
{
  "fileId": "8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6",
  "filename": "rules.xlsx",
  "filepath": "/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6",
  "source": "user",
  "sourceFile": null,
  "sourceFiles": [],
  "newerVersionAt": null,
  "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  "size": 20480,
  "currentVersionId": "c4d9e2f1-0a3b-4c6d-8e7f-5a1b2c3d4e6f",
  "digest": "WyJjNGQ5ZTJmMS0wYTNiLTRjNmQtOGU3Zi01YTFiMmMzZDRlNmYiLCIzYjZkYzMyNDY3NWE3YTQxZmExYjFjMzliNmIyYTY3ZGY4NDI0MTRkZTY1ZDg5MzdlOTUyMzM1NDRkNTg3ODJiIl0",
  "createdAt": "2026-11-10T01:00:00.000Z",
  "updatedAt": "2026-11-12T02:00:00.000Z"
}
```

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

| ステータス | code                              | 説明                                                                                                |
| ----- | --------------------------------- | ------------------------------------------------------------------------------------------------- |
| `400` | `invalid_parameter`               | projectId・fileId が UUID の形式ではない、baseDigest が無い・空・文字列ではない、または files が無い・2 つ以上・files 以外の項目でファイルを送った |
| `403` | `insufficient_scope`              | project:write スコープが不足                                                                             |
| `403` | `forbidden`                       | システム連携のトークンで呼び出した                                                                                 |
| `403` | `sso_required`                    | SSO でログインしていない利用者                                                                                 |
| `403` | `feature_not_permitted`           | 管理者がファイルの添付を許可していない                                                                               |
| `404` | `file_not_found`                  | ファイルが存在しない・消されている、またはメンバーではないプロジェクト                                                               |
| `409` | `stale_base`                      | 取得した後にファイルのバージョンが変わっている                                                                           |
| `409` | `type_mismatch`                   | 送ったファイルの名前の拡張子が、ライブラリでの名前の拡張子と違う（同じ拡張子のファイルを送るか、新しいファイルとして登録してください）                               |
| `413` | `file_too_large`                  | ファイルが 512 MB を超える                                                                                 |
| `415` | `unsupported_media_type`          | Content-Type が multipart/form-data ではない                                                           |
| `503` | `feature_permissions_unavailable` | 機能の許可を確かめられない（時間をおいて送り直す）                                                                         |

### POST`/v1/projects/{projectId}/library/{fileId}/restore`

前のバージョンの中身で、新しいバージョンを作ります。前のバージョンは残ります。

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

| フィールド        | 型        | 必須 | 説明                               |
| ------------ | -------- | -- | -------------------------------- |
| `versionId`  | `string` | 必須 | 戻すバージョンの ID（バージョンの一覧の versionId） |
| `baseDigest` | `string` | 必須 | ファイルの digest                     |

中身が今のバージョンと同じならバージョンは増えないこと、送り直しと記録 (証跡) は、新しいバージョンを足すと同じです。

#### リクエスト例

**Restore library file version**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6/restore \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "versionId": "c4d9e2f1-0a3b-4c6d-8e7f-5a1b2c3d4e6f",
  "baseDigest": "WyIzYjhhMWM1ZS03ZDJmLTRlOWEtYTZjMC0xZjRkOGIyZTVhNzkiLCI1MDE4OTQ4OTEyNGNhODdmYjBkMzdiMjg4Y2E5YjU4OWU3MWEwMTgxMDlmMjk3NWFiYzZlMjRjZTFhMmVlMjI4Il0"
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6/restore",
  headers={"Authorization": f"Bearer {token}"},
  json={'versionId': 'c4d9e2f1-0a3b-4c6d-8e7f-5a1b2c3d4e6f', 'baseDigest': 'WyIzYjhhMWM1ZS03ZDJmLTRlOWEtYTZjMC0xZjRkOGIyZTVhNzkiLCI1MDE4OTQ4OTEyNGNhODdmYjBkMzdiMjg4Y2E5YjU4OWU3MWEwMTgxMDlmMjk3NWFiYzZlMjRjZTFhMmVlMjI4Il0'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6/restore",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"versionId": "c4d9e2f1-0a3b-4c6d-8e7f-5a1b2c3d4e6f", "baseDigest": "WyIzYjhhMWM1ZS03ZDJmLTRlOWEtYTZjMC0xZjRkOGIyZTVhNzkiLCI1MDE4OTQ4OTEyNGNhODdmYjBkMzdiMjg4Y2E5YjU4OWU3MWEwMTgxMDlmMjk3NWFiYzZlMjRjZTFhMmVlMjI4Il0"}),
}
);

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

**Go**

```go
payload := []byte(`{"versionId": "c4d9e2f1-0a3b-4c6d-8e7f-5a1b2c3d4e6f", "baseDigest": "WyIzYjhhMWM1ZS03ZDJmLTRlOWEtYTZjMC0xZjRkOGIyZTVhNzkiLCI1MDE4OTQ4OTEyNGNhODdmYjBkMzdiMjg4Y2E5YjU4OWU3MWEwMTgxMDlmMjk3NWFiYzZlMjRjZTFhMmVlMjI4Il0"}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6/restore", 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）

戻した後のファイル（上の「ファイルの項目」）を返します。

#### レスポンス例

```json
{
  "fileId": "8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6",
  "filename": "rules.xlsx",
  "filepath": "/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6",
  "source": "user",
  "sourceFile": null,
  "sourceFiles": [],
  "newerVersionAt": null,
  "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  "size": 20480,
  "currentVersionId": "7a9c1e3f-5b2d-4f6a-8c0e-2d4f6a8c0e1b",
  "digest": "WyI3YTljMWUzZi01YjJkLTRmNmEtOGMwZS0yZDRmNmE4YzBlMWIiLCI0NmE3NTkxOTNmOTYxZjA2ODY2NDY0ZjA2MmFjYTZkYWZhOGM1ZDg4MTA4MjkxZDUyYmUwZjFmNjRiNzc5MjliIl0",
  "createdAt": "2026-11-10T01:00:00.000Z",
  "updatedAt": "2026-11-13T03:00:00.000Z"
}
```

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

| ステータス | code                     | 説明                                                                                   |
| ----- | ------------------------ | ------------------------------------------------------------------------------------ |
| `400` | `invalid_parameter`      | projectId・fileId が UUID の形式ではない、versionId が無い・空・文字列ではない、または baseDigest が無い・空・文字列ではない |
| `400` | `invalid_body`           | ボディが壊れた JSON、または JSON のオブジェクトではない                                                    |
| `400` | `version_not_found`      | versionId のバージョンが無い                                                                  |
| `403` | `insufficient_scope`     | project:write スコープが不足                                                                |
| `403` | `forbidden`              | システム連携のトークンで呼び出した                                                                    |
| `403` | `sso_required`           | SSO でログインしていない利用者                                                                    |
| `404` | `file_not_found`         | ファイルが存在しない・消されている、またはメンバーではないプロジェクト                                                  |
| `409` | `stale_base`             | 取得した後にファイルのバージョンが変わっている                                                              |
| `413` | `body_too_large`         | ボディが 16 KiB を超える                                                                     |
| `415` | `unsupported_media_type` | ボディの Content-Type が application/json ではない                                            |

### POST`/v1/projects/{projectId}/library/{fileId}/import-latest`

実行の成果物から取り込んだファイルに、一覧の newerVersionAt と同じ照らし方で見つけた、いちばん新しい成果物（巡回の成果物なら、後の回の別の作業場所にある同じ filepath の成果物のこともあります）を、新しいバージョンとして足します。一覧の newerVersionAt が入っているときに使います。中身が今のバージョンと同じなら、バージョンは増えず、newerVersionAt も残ります（新しいかは中身ではなく時刻で決まるため。currentVersionId が変わらなければ、同じ中身です）。配置の工程に対応づけたファイルには使えません（実行が書き戻します）。記録 (証跡) に残ります（バージョンが増えたときだけ）。

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

| フィールド        | 型        | 必須 | 説明           |
| ------------ | -------- | -- | ------------ |
| `baseDigest` | `string` | 必須 | ファイルの digest |

#### リクエスト例

**Import latest source version**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/b5c6d7e8-9f0a-4b1c-8d2e-3f4a5b6c7d8e/import-latest \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "baseDigest": "WyIyYzRlNmE4Yi0wZDFmLTRiM2MtOWE1ZS03ZjliMWQzZjVhN2MiLCIwOGJmNTQ1NmFiYmYwZGYxZTE5ZmJhMTYwYzk2NTAwNTgzOWQyYWE2M2YzYThkYjA0M2FjNzgzOThjMGQ0NTE4Il0"
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/b5c6d7e8-9f0a-4b1c-8d2e-3f4a5b6c7d8e/import-latest",
  headers={"Authorization": f"Bearer {token}"},
  json={'baseDigest': 'WyIyYzRlNmE4Yi0wZDFmLTRiM2MtOWE1ZS03ZjliMWQzZjVhN2MiLCIwOGJmNTQ1NmFiYmYwZGYxZTE5ZmJhMTYwYzk2NTAwNTgzOWQyYWE2M2YzYThkYjA0M2FjNzgzOThjMGQ0NTE4Il0'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/b5c6d7e8-9f0a-4b1c-8d2e-3f4a5b6c7d8e/import-latest",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"baseDigest": "WyIyYzRlNmE4Yi0wZDFmLTRiM2MtOWE1ZS03ZjliMWQzZjVhN2MiLCIwOGJmNTQ1NmFiYmYwZGYxZTE5ZmJhMTYwYzk2NTAwNTgzOWQyYWE2M2YzYThkYjA0M2FjNzgzOThjMGQ0NTE4Il0"}),
}
);

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

**Go**

```go
payload := []byte(`{"baseDigest": "WyIyYzRlNmE4Yi0wZDFmLTRiM2MtOWE1ZS03ZjliMWQzZjVhN2MiLCIwOGJmNTQ1NmFiYmYwZGYxZTE5ZmJhMTYwYzk2NTAwNTgzOWQyYWE2M2YzYThkYjA0M2FjNzgzOThjMGQ0NTE4Il0"}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/b5c6d7e8-9f0a-4b1c-8d2e-3f4a5b6c7d8e/import-latest", 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）

取り込んだ後のファイル（上の「ファイルの項目」）を返します。

#### レスポンス例

```json
{
  "fileId": "b5c6d7e8-9f0a-4b1c-8d2e-3f4a5b6c7d8e",
  "filename": "rules.xlsx",
  "filepath": "/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/b5c6d7e8-9f0a-4b1c-8d2e-3f4a5b6c7d8e",
  "source": "agent",
  "sourceFile": {
    "executionId": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
    "filepath": "/plans/550e8400-e29b-41d4-a716-446655440000/deliverables/report.xlsx"
  },
  "sourceFiles": [
    {
      "executionId": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
      "filepath": "/plans/550e8400-e29b-41d4-a716-446655440000/deliverables/report.xlsx"
    }
  ],
  "newerVersionAt": null,
  "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  "size": 20480,
  "currentVersionId": "9b1d3f5a-7c2e-4a6c-8e0f-1b3d5f7a9c2e",
  "digest": "WyI5YjFkM2Y1YS03YzJlLTRhNmMtOGUwZi0xYjNkNWY3YTljMmUiLCI3MTJkYzYzYjIzNzA3YmM1NWQyMWM1M2M0YmFkOWJhN2IxMWRmN2I3MDQ3MzRkZTZjNmVmNmNmNzMwMDMxN2M0Il0",
  "createdAt": "2026-11-10T01:00:00.000Z",
  "updatedAt": "2026-11-12T01:00:00.000Z"
}
```

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

| ステータス | code                     | 説明                                                                                                                                                                        |
| ----- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | `invalid_parameter`      | projectId・fileId が UUID の形式ではない、または baseDigest が無い・空・文字列ではない                                                                                                              |
| `400` | `invalid_body`           | ボディが壊れた JSON、または JSON のオブジェクトではない                                                                                                                                         |
| `403` | `insufficient_scope`     | project:write スコープが不足                                                                                                                                                     |
| `403` | `forbidden`              | システム連携のトークンで呼び出した                                                                                                                                                         |
| `403` | `sso_required`           | SSO でログインしていない利用者                                                                                                                                                         |
| `404` | `file_not_found`         | ファイルが存在しない・消されている、またはメンバーではないプロジェクト                                                                                                                                       |
| `409` | `stale_base`             | 取得した後にファイルのバージョンが変わっている                                                                                                                                                   |
| `409` | `file_in_use`            | 配置の工程に対応づけたファイル                                                                                                                                                           |
| `409` | `no_source_file`         | 実行の成果物から取り込んでいないファイル                                                                                                                                                      |
| `409` | `source_file_missing`    | 照らす成果物（newerVersionAt と同じ照らし方）をどれも読めない、または消えた                                                                                                                             |
| `409` | `type_mismatch`          | 見つかったいちばん新しい成果物の名前の拡張子が、このファイルの名前の拡張子と違う（その成果物は、POST /v1/projects/{projectId}/library/copy に executionId と filepath を付け、fileId と baseDigest は付けずに送って、新しいファイルとして取り込んでください） |
| `413` | `body_too_large`         | ボディが 16 KiB を超える                                                                                                                                                          |
| `415` | `unsupported_media_type` | ボディの Content-Type が application/json ではない                                                                                                                                 |

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

ファイルを消します。オーナーだけが呼べます。

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

| パラメータ   | 型        | デフォルト     | 説明                                                   |
| ------- | -------- | --------- | ---------------------------------------------------- |
| `force` | `string` | `"false"` | "true" で、配置の対応づけで使われていても消します（"true" / "false" のどちらか） |

- 配置の対応づけで使われていれば `409 Conflict`（`file_in_use`）です（使っている配置の工程の数はメッセージに入ります）。`force=true` で消せます。使っているかを確かめてから消すまでの間に対応づけが保存されると、`force` を付けなくても消えることがあります。
- 消しても、配置の対応づけは残ります。消したファイルは、workflow の工程・cycle の巡回とも、次の起動から渡されません。
- 記録 (証跡) に残ります。

#### リクエスト例

**Delete project library file**

**curl**

```curl
curl -X DELETE "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6?force=false" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.delete(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6",
  headers={"Authorization": f"Bearer {token}"},
  params={"force": "false"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6" + "?force=false",
{
  method: "DELETE",
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

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

**Go**

```go
req, _ := http.NewRequest("DELETE", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6?force=false", 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）

| フィールド     | 型         | 説明          |
| --------- | --------- | ----------- |
| `fileId`  | `string`  | 消したファイルの ID |
| `deleted` | `boolean` | true        |

#### レスポンス例

```json
{
  "fileId": "8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6",
  "deleted": true
}
```

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

| ステータス | code                 | 説明                                                              |
| ----- | -------------------- | --------------------------------------------------------------- |
| `400` | `invalid_parameter`  | projectId・fileId が UUID の形式ではない、または force が "true"・"false" ではない |
| `403` | `insufficient_scope` | project:write スコープが不足                                           |
| `403` | `forbidden`          | システム連携のトークンで呼び出した                                               |
| `403` | `owner_only`         | オーナーではないメンバー                                                    |
| `403` | `sso_required`       | SSO でログインしていない利用者                                               |
| `404` | `file_not_found`     | ファイルが存在しない・消されている、またはメンバーではないプロジェクト                             |
| `409` | `file_in_use`        | 配置の対応づけで使われている（force=true で消せます）                                |

### PUT`/v1/projects/{projectId}/placements/{placementId}/library-bindings`

配置の工程に、プロジェクトのライブラリのファイルを対応づけます。対応づけたファイルは、その工程の実行のときに、作業場所に指定した名前で渡されます。オーナーだけが呼べます。

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

| フィールド                      | 型        | 必須 | 説明                                                                                      |
| -------------------------- | -------- | -- | --------------------------------------------------------------------------------------- |
| `baseDigest`               | `string` | 必須 | その配置の digest                                                                            |
| `stepId`                   | `string` | —  | 対応づける工程の ID（配置の担当工程）。担当工程が 1 つの配置では省けます                                                 |
| `bindings`                 | `array`  | 必須 | その工程の対応づけの全部（20 件まで）。送った一覧で置き換えます。\[] で外します                                             |
| `bindings[].fileId`        | `string` | 必須 | プロジェクトのライブラリのファイルの ID                                                                   |
| `bindings[].workspaceName` | `string` | 必須 | 作業場所での名前。ファイル名だけ（フォルダは不可）で、同じ一覧の中で重ねられません。"." で始まる名前や .log など、実行の成果物を集めるときに拾わない名前は使えません |

- 保存すると、その Agent のまだ動き始めていない実行の入力ファイルも作り直されます（次の起動から効きます）。
- 定義の変更として記録 (証跡) に残ります（記録者は呼んだ人。定義の変更に承認が要るテナントでは、承認の流れで残ります）。

#### リクエスト例

**Update placement library bindings**

**curl**

```curl
curl -X PUT https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/library-bindings \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU",
  "bindings": [
    {
      "fileId": "8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6",
      "workspaceName": "rules.xlsx"
    }
  ]
}'
```

**Python**

```python
import requests

response = requests.put(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/library-bindings",
  headers={"Authorization": f"Bearer {token}"},
  json={'baseDigest': 'dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU', 'bindings': [{'fileId': '8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6', 'workspaceName': 'rules.xlsx'}]},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/library-bindings",
{
  method: "PUT",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU", "bindings": [{"fileId": "8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6", "workspaceName": "rules.xlsx"}]}),
}
);

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

**Go**

```go
payload := []byte(`{"baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU", "bindings": [{"fileId": "8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6", "workspaceName": "rules.xlsx"}]}`)
req, _ := http.NewRequest("PUT", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/library-bindings", 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": "経理 Agent",
    "description": "請求書の金額と明細を照合します",
    "goal": "請求書の金額と明細を照合し、差異を報告する",
    "guardrail": "金額を書き換えない",
    "skills": [
      {
        "skillId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
        "name": "請求書の読み取り"
      }
    ],
    "skillCount": 1,
    "playbookId": null,
    "playbookName": null,
    "inputFiles": [],
    "stepIds": [
      "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"
    ],
    "sweeps": [],
    "runtimeConfigs": [
      {
        "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
        "runtimeConfig": null
      }
    ],
    "libraryBindings": [
      {
        "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
        "fileId": "8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6",
        "workspaceName": "rules.xlsx"
      }
    ],
    "memoryOrgId": null,
    "memoryJobId": null,
    "instructionAddendum": null,
    "agentOwnerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "isShared": false,
    "runtimeKind": "autonomous",
    "marketplaceAgentId": null,
    "exclusiveToThisProject": true,
    "agentStopped": false,
    "relink": null,
    "digest": "IZLY0-rGPDZhcpRHsCLwX61hXt7-k8aLazv0kMeuL9U"
  },
  "definitionApproval": null
}
```

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

| ステータス | code                           | 説明                                                                                                           |
| ----- | ------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| `400` | `invalid_parameter`            | projectId・placementId・stepId が UUID の形式ではない、baseDigest が無い・空・文字列ではない、stepId が必要なのに無い、または bindings の形・数・名前の誤り |
| `400` | `invalid_body`                 | ボディが壊れた JSON、または JSON のオブジェクトではない                                                                            |
| `400` | `step_not_found`               | stepId が、この配置の担当工程ではない                                                                                       |
| `400` | `file_not_found`               | bindings のファイルがプロジェクトのライブラリに無い（消されたものを含みます）                                                                  |
| `403` | `insufficient_scope`           | project:write スコープが不足                                                                                        |
| `403` | `forbidden`                    | システム連携のトークンで呼び出した                                                                                            |
| `403` | `owner_only`                   | オーナーではないメンバー                                                                                                 |
| `403` | `sso_required`                 | SSO でログインしていない利用者                                                                                            |
| `404` | `placement_not_found`          | 配置が存在しない、ほかのプロジェクトの配置、またはメンバーではないプロジェクト                                                                      |
| `409` | `stale_base`                   | 取得した後に配置が変わっている。承認待ちがあるときは、既定の取得の digest では合いません。definition=pending で読み直し、その digest を baseDigest に送ってください    |
| `409` | `name_taken`                   | 別の配置が、同じ作業場所の名前を別のファイルに使っている                                                                                 |
| `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`              | 同じ定義の変更が処理中。時間をおいて送り直してください                                                                                  |

## 記録 (証跡)

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

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

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

### 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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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>、外部の送信者のメールは mail:<ハッシュ> など） |
| `events[].decision`    | `string \| null` | 決定・結果                                                                                        |
| `events[].reason`      | `string \| null` | 理由                                                                                           |
| `events[].executionId` | `string \| null` | 実行の ID                                                                                       |
| `events[].runId`       | `string \| null` | ワークフローの実行の ID                                                                                |
| `events[].stepName`    | `string \| null` | 工程の名前                                                                                        |
| `events[].metadata`    | `object`         | 記録ごとの中身。項目名は記録のまま返ります。中身の無い記録は {}                                                            |
| `hasMore`              | `boolean`        | 次のページが存在するかどうか                                                                               |
| `cursor`               | `string`         | 次ページ取得用カーソル。hasMore が true の場合のみ含まれます                                                        |

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

#### レスポンス例

```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` | `insufficient_scope` | project:read スコープが不足                                                                                         |
| `403` | `forbidden`          | システム連携のトークンで呼び出した                                                                                            |
| `403` | `sso_required`       | SSO でログインしていない利用者                                                                                            |
| `404` | `project_not_found`  | プロジェクトが存在しない、またはメンバーではない                                                                                     |

## KPI

画面の概要の「この業務の実行結果」と同じ値を取得します（工程ごとの `steps` は、概要の「ワークフローの形」の「数値」に出る値です。確認工程だけの値は `gates` にもあります）。数え方は[結果リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/project/reference/results-ref.md)を参照してください（工程ごとの値は[工程ごとの数値](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/project/reference/results-ref.md#工程ごとの数値)）。

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

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

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

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

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

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

#### リクエスト例

**Get project KPI**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/kpi?days=30" \
-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/kpi",
  headers={"Authorization": f"Bearer {token}"},
  params={"days": "30"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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 は接続の確認で止めた実行の数で、Agentの完遂率・終了・正常完了・終わった実行の数・結果ごとの数・処理時間のどれにも入れません                                                                   |
| `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"（確認工程）・"automation"（外部の自動化）・"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` | 外部の自動化の工程の送信の件数（total・sent: 送信できた・failed: 送信に失敗した）。Agentの完遂率には入りません                                                                                                                                              |
| `human`                   | `object`         | 確認対応の状況（reviewsPerRun・gateWaitMedianMinutes・interventions・deadlineDecisions）                                                                                                                                     |
| `human.deadlineDecisions` | `object \| null` | 期間に作られた期限のある確認のうち、人が期限までに決めた件数と率（total: 決まったか期限を過ぎた件数・onTime: 人が期限までに決めた件数・rate: onTime / total。total が 0 なら null）。期限による自動の決定は期限内に数えません                                                                          |
| `workSteps`               | `object`         | 請求のステップと同じ数え方の数（executions・billableExecutions・excludedExecutions・toolCalls・steps・stepsUnknown・formulaVersion）。workSteps.steps は請求のステップの数で、工程ごとの実績の steps とは別です                                                   |

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

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

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

#### レスポンス例

```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
    },
    {
      "stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f70819a2b",
      "position": 3,
      "name": "会計システムへの送信",
      "defaultZone": "automation",
      "agent": null,
      "gate": null,
      "automation": {
        "total": 20,
        "sent": 19,
        "failed": 1
      }
    }
  ],
  "human": {
    "reviewsPerRun": 0.7,
    "gateWaitMedianMinutes": 35,
    "interventions": 17,
    "deadlineDecisions": {
      "total": 15,
      "onTime": 14,
      "rate": 0.9333
    }
  },
  "workSteps": {
    "executions": 46,
    "billableExecutions": 44,
    "excludedExecutions": 2,
    "toolCalls": 312,
    "steps": 98,
    "stepsUnknown": 0,
    "formulaVersion": "v2"
  }
}
```

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

KPI の動き（前の期間との比べ・日ごとと週ごとの推移・確認依頼の滞留）を取得します。管理コンソールの「横断 KPI」と同じ数え方で、このプロジェクト 1 つ分を返します。プロジェクトのメンバーと、組織の運用の役割の人が読めます（公開されているプロジェクトでも、どちらでもなければ 404）。期間は選べません（クエリパラメータはありません）。

#### パスパラメータ

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

#### リクエスト例

**Get project KPI trends**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/kpi/trends \
-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/kpi/trends",
  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/kpi/trends",
{
  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/kpi/trends", 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）

| フィールド                          | 型                | 説明                                                   |
| ------------------------------ | ---------------- | ---------------------------------------------------- |
| `week`                         | `object`         | 直近 7 日（current）と、その前の 7 日（previous）の指標               |
| `month`                        | `object`         | 直近 30 日（current）と、その前の 30 日（previous）の指標             |
| `backlog`                      | `object`         | 今の確認依頼の滞留                                            |
| `backlog.assigned`             | `number`         | まだ判断されていない確認依頼の数                                     |
| `backlog.oldestWaitingMinutes` | `number \| null` | そのうち、いちばん長く待っているものの待ち時間（分）。無ければ null                 |
| `backlog.overdue`              | `number`         | そのうち、期限を過ぎたものの数                                      |
| `series`                       | `object`         | 推移                                                   |
| `series.day`                   | `array`          | 日ごとの指標（直近 30 日の 30 点。古い順）                            |
| `series.week`                  | `array`          | 週ごとの指標（直近 12 週の 12 点。週は月曜から。古い順）                     |
| `series.day[].bucket`          | `string`         | その日の日付（YYYY-MM-DD）。series.week\[].bucket は、その週の月曜の日付 |

- `week`・`month` は、呼んだ時刻からさかのぼって数えます。
- `series` の日と週の区切りは日本時間です。数えるものが無い日・週も 0 で返します。今日・今週の点は、呼んだ時刻までの分です。
- 実行とワークフローの実行は始まった時刻、確認依頼はできた時刻、改善案の実施は実施した時刻で、どの期間・どの点に入るかが決まります。

指標（`week`・`month` の `current`・`previous` と、`series` の 1 点）:

| フィールド                       | 型                | 説明                                                                                                                                                                                                                                         |
| --------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `executions`                | `number`         | 終わった実行の数（denominator と、変化なしで終わった実行の合計）                                                                                                                                                                                                     |
| `denominator`               | `number`         | 終了の数（正常完了と「失敗・要対応」の合計。変化なしで終わった実行は入れません）                                                                                                                                                                                                   |
| `succeeded`                 | `number`         | 正常完了の数                                                                                                                                                                                                                                     |
| `successRate`               | `number \| null` | Agentの完遂率（0〜1。succeeded ÷ denominator）。denominator が 0 なら null                                                                                                                                                                             |
| `missing`                   | `number`         | 終わったのに結果が記録されていない実行（記録不足）の数                                                                                                                                                                                                                |
| `excludedConnectionConfirm` | `number`         | 接続の確認で止めた実行の数。executions・denominator・succeeded・missing・durationMedianMinutes・failures のどれにも入れません                                                                                                                                           |
| `runs`                      | `number`         | 始まったワークフローの実行の数                                                                                                                                                                                                                            |
| `humanDecisions`            | `number`         | 確認依頼を人が判断した数（自動で決まったものは入れません）                                                                                                                                                                                                              |
| `interventionRate`          | `number \| null` | humanDecisions ÷ runs。runs が 0 なら null                                                                                                                                                                                                     |
| `improvements`              | `number`         | 改善案を実施した数（記録 (証跡) の improvement.applied の数）                                                                                                                                                                                                |
| `durationMedianMinutes`     | `number \| null` | 終わった実行の所要時間の中央値（分）。結果が記録されていない実行と、stopped・skipped の実行は入れません。無ければ null                                                                                                                                                                      |
| `failures`                  | `object`         | 失敗（incomplete・failed・timeout・denied）を直す先ごとに数えた数。キーは goal・skill・handoff・not\_assigned・connection・rule・guardrail・external・unknown（実行の結果の envelope.completionReport.fixTarget と同じ値）と platform（直す先が無く、基盤側の失敗があるもの）。直す先も基盤側の失敗も無いものは unknown です |

#### レスポンス例

```json
{
  "week": {
    "current": {
      "executions": 12,
      "denominator": 11,
      "succeeded": 10,
      "successRate": 0.9091,
      "missing": 1,
      "excludedConnectionConfirm": 0,
      "runs": 6,
      "humanDecisions": 4,
      "interventionRate": 0.6667,
      "improvements": 1,
      "durationMedianMinutes": 6.5,
      "failures": {
        "goal": 0,
        "skill": 1,
        "handoff": 0,
        "not_assigned": 0,
        "connection": 0,
        "rule": 0,
        "guardrail": 0,
        "external": 0,
        "unknown": 0,
        "platform": 0
      }
    },
    "previous": {
      "executions": 9,
      "denominator": 9,
      "succeeded": 7,
      "successRate": 0.7778,
      "missing": 0,
      "excludedConnectionConfirm": 0,
      "runs": 5,
      "humanDecisions": 5,
      "interventionRate": 1,
      "improvements": 0,
      "durationMedianMinutes": 8,
      "failures": {
        "goal": 1,
        "skill": 0,
        "handoff": 1,
        "not_assigned": 0,
        "connection": 0,
        "rule": 0,
        "guardrail": 0,
        "external": 0,
        "unknown": 0,
        "platform": 0
      }
    }
  },
  "month": {
    "current": {
      "executions": 48,
      "denominator": 46,
      "succeeded": 41,
      "successRate": 0.8913,
      "missing": 2,
      "excludedConnectionConfirm": 0,
      "runs": 24,
      "humanDecisions": 17,
      "interventionRate": 0.7083,
      "improvements": 3,
      "durationMedianMinutes": 7,
      "failures": {
        "goal": 1,
        "skill": 3,
        "handoff": 1,
        "not_assigned": 0,
        "connection": 0,
        "rule": 0,
        "guardrail": 0,
        "external": 0,
        "unknown": 0,
        "platform": 0
      }
    },
    "previous": {
      "executions": 40,
      "denominator": 40,
      "succeeded": 33,
      "successRate": 0.825,
      "missing": 0,
      "excludedConnectionConfirm": 0,
      "runs": 20,
      "humanDecisions": 18,
      "interventionRate": 0.9,
      "improvements": 2,
      "durationMedianMinutes": 8.5,
      "failures": {
        "goal": 3,
        "skill": 1,
        "handoff": 2,
        "not_assigned": 0,
        "connection": 0,
        "rule": 2,
        "guardrail": 0,
        "external": 0,
        "unknown": 0,
        "platform": 0
      }
    }
  },
  "backlog": {
    "assigned": 2,
    "oldestWaitingMinutes": 185,
    "overdue": 1
  },
  "series": {
    "day": [
      {
        "bucket": "2026-11-17",
        "executions": 3,
        "denominator": 3,
        "succeeded": 3,
        "successRate": 1,
        "missing": 0,
        "excludedConnectionConfirm": 0,
        "runs": 2,
        "humanDecisions": 1,
        "interventionRate": 0.5,
        "improvements": 0,
        "durationMedianMinutes": 5,
        "failures": {
          "goal": 0,
          "skill": 1,
          "handoff": 0,
          "not_assigned": 0,
          "connection": 0,
          "rule": 0,
          "guardrail": 0,
          "external": 0,
          "unknown": 0,
          "platform": 0
        }
      },
      {
        "bucket": "2026-11-18",
        "executions": 1,
        "denominator": 1,
        "succeeded": 1,
        "successRate": 1,
        "missing": 0,
        "excludedConnectionConfirm": 0,
        "runs": 1,
        "humanDecisions": 0,
        "interventionRate": 0,
        "improvements": 0,
        "durationMedianMinutes": 4,
        "failures": {
          "goal": 0,
          "skill": 1,
          "handoff": 0,
          "not_assigned": 0,
          "connection": 0,
          "rule": 0,
          "guardrail": 0,
          "external": 0,
          "unknown": 0,
          "platform": 0
        }
      }
    ],
    "week": [
      {
        "bucket": "2026-11-09",
        "executions": 12,
        "denominator": 11,
        "succeeded": 10,
        "successRate": 0.9091,
        "missing": 1,
        "excludedConnectionConfirm": 0,
        "runs": 6,
        "humanDecisions": 4,
        "interventionRate": 0.6667,
        "improvements": 1,
        "durationMedianMinutes": 6.5,
        "failures": {
          "goal": 0,
          "skill": 1,
          "handoff": 0,
          "not_assigned": 0,
          "connection": 0,
          "rule": 0,
          "guardrail": 0,
          "external": 0,
          "unknown": 0,
          "platform": 0
        }
      },
      {
        "bucket": "2026-11-16",
        "executions": 4,
        "denominator": 4,
        "succeeded": 4,
        "successRate": 1,
        "missing": 0,
        "excludedConnectionConfirm": 0,
        "runs": 3,
        "humanDecisions": 1,
        "interventionRate": 0.3333,
        "improvements": 0,
        "durationMedianMinutes": 5,
        "failures": {
          "goal": 0,
          "skill": 1,
          "handoff": 0,
          "not_assigned": 0,
          "connection": 0,
          "rule": 0,
          "guardrail": 0,
          "external": 0,
          "unknown": 0,
          "platform": 0
        }
      }
    ]
  }
}
```

例では、`series.day` と `series.week` の点を 2 点ずつだけ載せています（実際は `series.day` が 30 点、`series.week` が 12 点です）。

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

| ステータス | code                 | 説明                              |
| ----- | -------------------- | ------------------------------- |
| `400` | `invalid_parameter`  | projectId が UUID の形式ではない        |
| `403` | `insufficient_scope` | project:read スコープが不足            |
| `403` | `forbidden`          | システム連携のトークンで呼び出した               |
| `403` | `sso_required`       | SSO でログインしていない利用者               |
| `404` | `project_not_found`  | プロジェクトが存在しない、またはメンバーではない        |
| `504` | `upstream_timeout`   | 集計が時間内に終わらなかった（時間をおいて送り直してください） |

## 確認依頼

確認依頼は、ワークフローが確認工程に入ったとき、または Agent の工程の結果が「ルールにより実行不可」「失敗 (Agent の報告)」になり、その工程が確認を求める設定のときにできます。<!-- -->Agent が人の確認の要る連携先（連携先の `confirmMode`）を使おうとしたときにもできます（接続の確認。workflow の工程でも cycle の巡回でもできます）。<!-- -->確認担当者が、進める・差し戻す・却下するを決めます。<!-- -->接続の確認で決められるのは、進める・却下するだけです。<!-- -->画面の確認依頼と同じものです。

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

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

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

### 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://api.fd.agenticstar.tm.softbank.jp/api/v1/workitems?state=open&limit=20" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/workitems",
  headers={"Authorization": f"Bearer {token}"},
  params={"state": "open", "limit": "20"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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"（担当者の判断を待つ）または "notify\_only"（期限後に自動で進める）         |
| `workitems[].overdue`         | `boolean \| null` | 期限を過ぎたかどうか                                                       |
| `workitems[].decidedAt`       | `string \| null`  | 判断した日時（ISO 8601）                                                 |
| `workitems[].createdAt`       | `string \| null`  | 作成日時（ISO 8601）                                                   |
| `workitems[].updatedAt`       | `string \| null`  | 更新日時（ISO 8601）                                                   |
| `workitems[].canDecide`       | `boolean`         | 自分が判断できるかどうか（確認担当者か、期間中の代理人なら true）                              |
| `hasMore`                     | `boolean`         | 次のページがあるかどうか                                                     |
| `cursor`                      | `string`          | 次のページのカーソル。hasMore が true のときだけ含まれます                             |

#### レスポンス例

```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` | `insufficient_scope` | project:read スコープが不足                                                                                    |
| `403` | `forbidden`          | システム連携のトークンで呼び出した                                                                                       |
| `403` | `sso_required`       | SSO でログインしていない利用者                                                                                       |

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

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

#### パスパラメータ

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

#### リクエスト例

**Get work item**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/workitems/c9d8e7f6-a5b4-4321-8fed-cba098765432 \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/workitems/c9d8e7f6-a5b4-4321-8fed-cba098765432",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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 と同じ形）。cycle の接続の確認では null                                                                                  |
| `workitem.stepId`                       | `string \| null`   | 確認を求めた工程の ID（確認工程、結果によって確認を求めた Agent の工程、または接続の確認で止めた Agent の工程）                                                                                     |
| `workitem.approverUserIds`              | `array`            | 確認担当者の利用者 ID の配列（確認依頼ができたときの担当者）                                                                                                                     |
| `workitem.overdueAction`                | `string \| null`   | 期限を過ぎたら。"none" / "proceed" / "send\_back" / "reject"。接続の確認は "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・sendBackFiles）。completesRun は、進めたときにワークフローの実行が終わったかどうか               |
| `workitem.decisionResult.sendBackFiles` | `object[] \| null` | 差し戻しに添えたファイル（fileId・filename）。添えていなければ null                                                                                                          |
| `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 の工程の結果によって確認を求めたときは、結果とその理由の要約。接続の確認では、連携先を使う目的（Agent が書いたもの）                                                                             |
| `conversationId`   | `string \| null` | 確認する工程の実行の会話の ID                                                                                                                                                               |
| `files`            | `array`          | 確認する工程のファイル（会話 API の deliverables と同じ形。中身はファイルの中身の取得（GET /v1/projects/{projectId}/files/content）に filepath を path で渡して取る）                                                      |
| `gateKind`         | `string \| null` | 確認の種類。"review"（確認）/ "manual"（手作業）/ "connection"（接続の確認。Agent が連携先を使う前に、人の確認を求めたもの。連携先の confirmMode で設定します）                                                                      |
| `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` | 接続の確認で、Agent が使おうとした連携先（kind・connectionId・name。プロジェクトの取得の connectors\[] と同じ形）。連携先の情報を確かめられなかったときは kind・connectionId が null。接続の確認でなければ null                                     |
| `service`          | `string \| null` | 接続の確認で、Agent が使おうとした連携先のサービスの名前。接続の確認でなければ null                                                                                                                                |
| `mode`             | `string \| null` | 接続の確認の設定（"first\_per\_execution" または "always"。連携先の confirmMode と同じ値）。接続の確認でなければ null                                                                                           |
| `tool`             | `string \| null` | 接続の確認で、Agent が使おうとしたツールの名前（分からないときは null）。接続の確認でなければ null                                                                                                                      |
| `waitMinutes`      | `number \| null` | 接続の確認を待つ時間（分）。接続の確認でなければ null                                                                                                                                                  |
| `handoff`          | `array`          | 確認する工程の前の工程ごとに、次の工程に渡した値と資料。1 件は label（前の工程が複数のときの見分けの名前。1 つなら null）と、values・files・missing・truncated（形は実行の取得の steps\[].handoff と同じ）。前の工程に次の工程に渡す値と資料の役割（outputConfig）が無ければ空の配列 |

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

| フィールド                   | 型                 | 説明                                                                                                                                                         |
| ----------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contextVersion`        | `integer \| null` | 確認依頼の版。判断の contextVersion に送ります。版を持たない古い確認依頼では null（そのときは contextVersion を送りません）                                                                           |
| `projectName`           | `string \| null`  | プロジェクト名                                                                                                                                                    |
| `projectType`           | `string \| null`  | プロジェクトの型                                                                                                                                                   |
| `stepId`                | `string \| null`  | 確認を求めた工程の ID                                                                                                                                               |
| `stepName`              | `string \| null`  | 確認を求めた工程の名前                                                                                                                                                |
| `stepPosition`          | `number \| null`  | 確認を求めた工程の位置                                                                                                                                                |
| `nextStep`              | `object \| null`  | 進めたときの次の工程（stepId・name・position）。次の工程が無ければ null                                                                                                            |
| `editableOutput`        | `string \| null`  | 直して進められる種類の確認依頼の、確認した出力の文。この文を直して、判断の editedOutput に送ります。直して進められない種類の確認依頼では null。決められるか（まだ決まっていないか・自分が決められるか）は、この項目ではなく status と workitem.canDecide で見ます   |
| `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,
      "handoff": []
    },
    "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,
    "projectName": "請求書の突合",
    "projectType": "workflow",
    "stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "stepName": "差異の確認",
    "stepPosition": 2,
    "nextStep": {
      "stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
      "name": "差異の報告",
      "position": 3
    },
    "editableOutput": null,
    "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` | `insufficient_scope` | project:read スコープが不足      |
| `403` | `forbidden`          | システム連携のトークンで呼び出した         |
| `403` | `sso_required`       | SSO でログインしていない利用者         |
| `404` | `workitem_not_found` | 確認依頼が存在しない、または読めない        |

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

確認依頼を判断します。確認担当者と期間中の代理人だけが呼べます。

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

| フィールド              | 型          | 必須 | 説明                                                                                                                                                                                  |
| ------------------ | ---------- | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `decision`         | `string`   | 必須 | "proceed"（進める）/ "send\_back"（差し戻す）/ "reject"（却下する）                                                                                                                                  |
| `reason`           | `string`   | —  | 理由（10000 文字まで）。"send\_back"・"reject" のときは必須                                                                                                                                         |
| `sendBackToStepId` | `string`   | —  | 差し戻し先の工程の ID（"send\_back" のとき。gate の sendBackCandidates の工程）。省くと sendBackDefaultStepId の工程に戻します                                                                                     |
| `sendBackFiles`    | `string[]` | —  | 差し戻しのとき、戻り先の工程に添えるプロジェクトのライブラリのファイルの ID（5 件まで）。戻り先の工程が動き直すときに、入力のファイルとして、ライブラリの表示名で作業場所に置かれます（その時点で削除されたファイルは渡りません）                                                                 |
| `destinationId`    | `string`   | —  | 進め先（"proceed" のとき。gate の destinations の destinationId。64 文字まで）。進め先のある確認依頼を進めるときは必須                                                                                                  |
| `editedOutput`     | `string`   | —  | 直して進める文（"proceed" のとき。確認依頼の取得の gate.editableOutput が null でない確認依頼だけ）。次の工程には、確認した出力の代わりにこの文が渡ります。前後の空白を除いて 20000 文字まで（除いた文で保存します）。元の出力は残り、実行の結果の取得の edited で直した文と並べて読めます             |
| `commandId`        | `string`   | —  | 送り直しを見分ける値（128 文字まで）                                                                                                                                                                |
| `contextVersion`   | `integer`  | —  | 判断する前に読んだ確認依頼の gate.contextVersion（1 以上の整数）。確認依頼が変わっていると 409 stale\_context。gate.contextVersion が null の確認依頼では送りません。版を持つ確認依頼（gate.contextVersion が null でない）に editedOutput を送るときは必須 |

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

`contextVersion` を送った判断で、確認依頼を読んだ後に確認依頼が変わっていると `409 Conflict`（`stale_context`）です。確認依頼を取得し直し、新しい `gate.contextVersion` で送り直してください。

#### リクエスト例

**Decide work item**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/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,
  "commandId": "decide-20261118-0001"
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/workitems/c9d8e7f6-a5b4-4321-8fed-cba098765432/decision",
  headers={"Authorization": f"Bearer {token}"},
  json={'decision': 'proceed', 'reason': '差異は税込・税抜の違いだったため', 'contextVersion': 1, 'commandId': 'decide-20261118-0001'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/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, "commandId": "decide-20261118-0001"}),
}
);

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

**Go**

```go
payload := []byte(`{"decision": "proceed", "reason": "差異は税込・税抜の違いだったため", "contextVersion": 1, "commandId": "decide-20261118-0001"}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/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 が空白だけ、editedOutput が文字列ではない・空白だけ・前後の空白を除いて 20000 文字を超える、contextVersion が 1 以上の整数ではない、basisDigest を送った、版を持つ確認依頼に contextVersion なしで editedOutput を送った、または項目の型や長さの誤り |
| `400` | `invalid_parameter`           | sendBackFiles が配列でない・6 件以上・UUID の形式ではない                                                                                                                                                                                                                    |
| `400` | `invalid_send_back_files`     | sendBackFiles のファイルがプロジェクトのライブラリに無い・削除済み                                                                                                                                                                                                                   |
| `400` | `send_back_files_not_allowed` | 差し戻し以外の判断、または接続の確認に sendBackFiles を送った                                                                                                                                                                                                                     |
| `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` | `invalid_decision`            | 接続の確認（evidence.gateKind が "connection"）に "send\_back" を送った。接続の確認は "proceed" と "reject" だけです                                                                                                                                                                |
| `400` | `edited_output_not_allowed`   | "proceed" 以外の判断で editedOutput を送った、または直して進められない確認依頼（合流の確認・接続の確認・Agent の工程の結果から立った確認など）に送った                                                                                                                                                                 |
| `403` | `insufficient_scope`          | project:decide スコープが不足                                                                                                                                                                                                                                     |
| `403` | `forbidden`                   | システム連携のトークンで呼び出した                                                                                                                                                                                                                                          |
| `403` | `sso_required`                | SSO でログインしていない利用者                                                                                                                                                                                                                                          |
| `403` | `not_gate_owner`              | プロジェクトのメンバーだが、確認担当者ではない                                                                                                                                                                                                                                    |
| `404` | `workitem_not_found`          | 確認依頼が存在しない、または読めない                                                                                                                                                                                                                                         |
| `409` | `already_decided`             | すでに判断されている                                                                                                                                                                                                                                                 |
| `409` | `command_conflict`            | 同じ commandId で違う内容を送った                                                                                                                                                                                                                                     |
| `409` | `invalid_state`               | 確認待ちではない（取り消されたなど）                                                                                                                                                                                                                                         |
| `409` | `send_back_limit_exceeded`    | 差し戻せる回数の上限に達している                                                                                                                                                                                                                                           |
| `409` | `stale_context`               | 確認依頼を読んだ後に、確認依頼が変わっている（送ったバージョンと今のバージョンが違う）                                                                                                                                                                                                                |
| `413` | `body_too_large`              | ボディが 3 MiB を超える                                                                                                                                                                                                                                            |
| `415` | `unsupported_media_type`      | ボディの Content-Type が application/json ではない                                                                                                                                                                                                                  |

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

確認依頼の期限（`expiresAt`）を延ばします。確認担当者・期間中の代理人と、オーナー・運用担当（組織の運用の役割の人を含む）が呼べます。延ばすと、期限超過の印（`overdue`）も外れます。<!-- -->接続の確認（`evidence.gateKind` が `"connection"`）の期限は延ばせません。

#### パスパラメータ

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

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

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

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

#### リクエスト例

**Extend work item**

**curl**

```curl
curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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,
      "handoff": []
    },
    "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` | `insufficient_scope`        | project:decide スコープが不足                                                         |
| `403` | `forbidden`                 | システム連携のトークンで呼び出した                                                              |
| `403` | `sso_required`              | SSO でログインしていない利用者                                                              |
| `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`       |
| 失敗した巡回をもう一度動かす        | `POST /v1/projects/{projectId}/executions/{executionId}/rerun` | `executionId` |

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

| メソッド | エンドポイント                          | 説明            | スコープ (SaaS)    |
| ---- | -------------------------------- | ------------- | -------------- |
| GET  | `/v1/projects/{projectId}/queue` | プロジェクトのキューを取得 | `project:read` |
| GET  | `/v1/queue`                      | 自分が担当のキューを取得  | `project:read` |

### 行の種類

`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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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` | `insufficient_scope` | project:read スコープが不足                                        |
| `403` | `forbidden`          | システム連携のトークンで呼び出した                                           |
| `403` | `sso_required`       | SSO でログインしていない利用者                                           |
| `404` | `project_not_found`  | プロジェクトが存在しない、またはメンバーではない                                    |

### GET`/v1/queue`

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

#### リクエスト例

**List my queue**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/queue?kind=gate_pending&limit=20" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/queue",
  headers={"Authorization": f"Bearer {token}"},
  params={"kind": "gate_pending", "limit": "20"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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` | `insufficient_scope` | project:read スコープが不足               |
| `403` | `forbidden`          | システム連携のトークンで呼び出した                  |
| `403` | `sso_required`       | SSO でログインしていない利用者                  |

## 連携先

プロジェクトの実行で使う 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`）です。
- 連携先へのログインは、プロジェクトの画面で行います。

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

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

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

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

#### パスパラメータ

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

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

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

#### リクエスト例

**Get MCP connector**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/connectors/mcp/12?projectId=3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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` | `insufficient_scope`  | project:read スコープが不足                                     |
| `403` | `forbidden`           | システム連携のトークンで呼び出した                                        |
| `403` | `sso_required`        | projectId を付けた呼び出しで、SSO でログインしていない利用者                    |
| `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://api.fd.agenticstar.tm.softbank.jp/api/v1/connectors/a2a/7 \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/connectors/a2a/7",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/connectors/a2a/7",
{
  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/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` | `insufficient_scope`  | project:read スコープが不足           |
| `403` | `forbidden`           | システム連携のトークンで呼び出した              |
| `404` | `connector_not_found` | 連携先が存在しない、または無効                |

## 実行の会話

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

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

## エラーレスポンス

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

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

| ステータス                        | 説明                                                                                                                                                                                        |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`            | リクエストパラメータが不正                                                                                                                                                                             |
| `401 Unauthorized`           | トークンが無効または未指定。管理者に利用を止められた利用者のトークンでも返ります（下の「利用を止められた利用者」）                                                                                                                                 |
| `403 Forbidden`              | リソースへのアクセス権限なし。管理者が公開 API の接続元を制限していて、接続元の IP アドレスが許可の一覧に無いときも返ります（`error.code` は `ip_not_allowed`）                                                                                       |
| `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/personas`・`GET /v1/user`・`PATCH /v1/user`、MCP の `list_personas` と、進行中のタスクが無いときの `cancel_chat`。止められた後も、アクセストークンの有効期限までは呼べます。止められた利用者は、アクセストークンを更新できません。

### 前段の仕組みで止められたとき

API の前段の仕組み（セキュリティの検査など）が HTML のエラー画面を返した場合は、上の共通の形の JSON に置き換えて返します。このときの `error.code` は次のとおりです。

| ステータス           | error.code           | 説明                                                                                                           |
| --------------- | -------------------- | ------------------------------------------------------------------------------------------------------------ |
| 403             | `waf_blocked`        | リクエストが、API の前段にあるセキュリティの検査に止められました。正当なリクエストの場合は、`error.reference`（無い場合は応答ヘッダーの `x-request-id`）を添えてお問い合わせください |
| 403 以外の 4xx・5xx | `upstream_api_error` | リクエストが、API の前段の仕組みで拒否されたか、そこでエラーになりました。続く場合は、`error.reference`（無い場合は応答ヘッダーの `x-request-id`）を添えてお問い合わせください    |

| フィールド             | 型        | 説明                                                  |
| ----------------- | -------- | --------------------------------------------------- |
| `error.reference` | `string` | 前段の仕組みで止められたときの参照番号。お問い合わせのときに添えてください。値が無い場合は含まれません |

```json
{
  "error": {
    "type": "forbidden_error",
    "message": "The request was blocked by a web application firewall before it reached the API.",
    "code": "waf_blocked",
    "suggested_action": "The request matched a firewall rule in front of the API. If the request is legitimate, contact support with the reference.",
    "reference": "20261018T012345Z-0123456789abcdef"
  }
}
```
