# システム連携 API リファレンス

ユーザー管理、ログ閲覧、マスターデータ管理、共有メモリ検索、プロジェクト操作の API リファレンスです。エンドユーザー向けの Chat / Conversations / Files / Search / 公開マスターデータ API は [ユーザー API リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference.md)、MCP / A2A の接続方式は [接続方式ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/connection-guide.md) を参照してください。

> **SaaS 版専用**
>
> 本リファレンスに掲載しているエンドポイントはすべて **SaaS 版でのみ提供** されます。Marketplace 版では管理操作は管理コンソールからのみ実施可能です。

## ベース URL

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

SaaS

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

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

## 認証

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

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

トークンが無効または未指定の場合、`401 Unauthorized` が返されます。エンドポイントによっては追加のスコープが必要です。必要なスコープが不足している場合は `403 Forbidden` が返されます。

トークンの取得方法・スコープの詳細については、[認証ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/auth-guide.md)および[認証 API リファレンス（SaaS）](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/auth-saas-ref.md)を参照してください。

## 共通の決まり

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

### リクエストの扱い

このページの API は、リクエストを次のように扱います。エンドポイントごとの扱いは、各エンドポイントの説明とエラーレスポンスを参照してください。

| 送ったもの                                                                                        | 扱い                                                                                  |
| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| 仕様に無いクエリパラメータとボディのフィールド                                                                      | 無視されます。ただし、このページに載っていない項目でも、サービスが受け付けている項目は、型や値が正しくないと `400 Bad Request` になることがあります |
| 仕様にあるクエリパラメータの不正な値                                                                           | `400 Bad Request`                                                                   |
| パスパラメータの値の不正な URL エンコード（`%` の並び）                                                             | `400 Bad Request`（`invalid_parameter`）                                              |
| 壊れた JSON のボディ                                                                                | `400 Bad Request`（`invalid_body`）                                                   |
| JSON のボディを受け付けるエンドポイントへの、`Content-Type: application/json` 以外のボディ、対応していない文字コード（`charset`）のボディ | `415 Unsupported Media Type`（`unsupported_media_type`）                              |
| 型の違うボディのフィールド                                                                                | `400 Bad Request`                                                                   |

ボディの読み取りで `400`（壊れた JSON など）や `413`（サイズの上限を超えたなど）になる場合は、`415` よりそちらが先に返ります。

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

### ページネーション

一覧取得エンドポイントには 2 つの方式があります。エンドポイントごとにどちらかが決まっています。[組織・職種](#admin-master-data)の一覧はページネーション非対応で、常に全件が返されます。

#### ページベース

| パラメータ   | 型         | 説明                             |
| ------- | --------- | ------------------------------ |
| `limit` | `integer` | 1ページあたりの取得件数。1 〜 100（デフォルト 25） |
| `page`  | `integer` | ページ番号。1 以上（デフォルト 1）            |

レスポンスには `total`, `limit`, `page`, `hasMore` が含まれます。`hasMore` が `true` の場合、`page` を 1 増やすことで次ページを取得できます。

```bash
# 1ページ目
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users?limit=25&page=1" \
  -H "Authorization: Bearer <access_token>"

# 2ページ目
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users?limit=25&page=2" \
  -H "Authorization: Bearer <access_token>"
```

対応しているのは、[ユーザー一覧](#admin-users)と[ログ一覧](#admin-logs)（監査ログ・操作監査ログ・LLM ログ・LLM Gateway ログ・LLM Gateway 操作監査・アクセスログ・ガードレールアラート）です。

#### カーソルベース

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

レスポンスには `hasMore` が含まれます。`true` の場合、`cursor` の値を次のリクエストに渡すことで次ページを取得できます。`cursor` は不透明な値のため、内容を解釈せず、前回レスポンスの値をそのまま指定してください。

対応しているのは、[プロジェクト一覧](#projects)と[利用者の操作の監査の一覧](#get-admin-user-action-logs)です。`page` は使いません（指定しても無視されます）。

## 共有メモリ SaaS

組織・職種に基づく共有メモリ（ナレッジ）を検索します。

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

| メソッド | エンドポイント                  | 説明       | スコープ                 |
| ---- | ------------------------ | -------- | -------------------- |
| POST | `/v1/admin/memory/query` | 共有メモリを検索 | `sharedmemory:query` |

### POST`/v1/admin/memory/query`

共有メモリを検索します。

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

| パラメータ     | 型        | 必須 | 説明                                       |
| --------- | -------- | -- | ---------------------------------------- |
| `query`   | `string` | 必須 | 検索クエリ（最大500文字）                           |
| `orgId`   | `string` | —  | 組織ID（最大100文字）。指定すると組織スコープのメモリも検索対象に含まれます |
| `jobRole` | `string` | —  | 職種（最大100文字）。指定すると職種スコープのメモリも検索対象に含まれます   |

#### リクエスト例

**Search shared memory**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/memory/query \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{"query": "売上レポートの作成手順", "orgId": "sales"}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/memory/query",
  headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
  json={"query": "売上レポートの作成手順", "orgId": "sales"},
)

response.raise_for_status()  # 502 / 504 は一時的な障害。時間をおいて再試行する
data = response.json()
for memory in data.get("memories", []):
  print(f"[{memory['type']}] {memory['text']}")
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/memory/query",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "売上レポートの作成手順", orgId: "sales" }),
}
);

if (!response.ok) {
// 502 / 504 は一時的な障害。時間をおいて再試行する
throw new Error(`memory query failed: ${response.status}`);
}

const data = await response.json();
(data.memories ?? []).forEach((m) => {
console.log(`[${m.type}] ${m.text}`);
});
```

**Go**

```go
body, _ := json.Marshal(map[string]string{
  "query": "売上レポートの作成手順",
  "orgId": "sales",
})
req, _ := http.NewRequest("POST",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/memory/query",
  bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")

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）

| フィールド                  | 型                | 説明                                   |
| ---------------------- | ---------------- | ------------------------------------ |
| `memories`             | `array`          | メモリオブジェクトの配列                         |
| `memories[].text`      | `string`         | メモリの内容テキスト                           |
| `memories[].type`      | `string`         | "knowledge"（ナレッジ）                    |
| `memories[].scope`     | `string`         | "organization"、"role"、"global" のいずれか |
| `memories[].createdAt` | `string \| null` | 作成日時（ISO 8601形式）                     |
| `memories[].score`     | `number?`        | 関連度スコア。スコア値がない場合はフィールド自体が省略される       |

#### レスポンスヘッダー

| ヘッダー                    | 説明                       |
| ----------------------- | ------------------------ |
| `X-RateLimit-Limit`     | 月間リクエスト上限数               |
| `X-RateLimit-Remaining` | 残りリクエスト数                 |
| `X-RateLimit-Reset`     | 制限リセット日時（次月初、ISO 8601形式） |

#### レスポンス例

```json
{
  "memories": [
    {
      "text": "売上レポートはダッシュボードの「月次レポート」タブから作成できます",
      "type": "knowledge",
      "scope": "organization",
      "createdAt": "2026-03-15T10:30:00.000Z",
      "score": 0.85
    }
  ]
}
```

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

| ステータス | 説明                                                                            |
| ----- | ----------------------------------------------------------------------------- |
| `400` | query が未指定、空文字、または500文字超過。またはボディが壊れた JSON（`code: "invalid_body"`）             |
| `415` | ボディの Content-Type が application/json ではない（`code: "unsupported_media_type"`）   |
| `403` | sharedmemory:query スコープが不足                                                    |
| `429` | 月間クォータ超過（`error.type: rate_limit_error`、`error.code: monthly_quota_exceeded`） |
| `502` | 上流サービスとの通信エラー（`error.type: upstream_error`）                                   |
| `504` | 上流サービスの応答タイムアウト（`error.type: upstream_error`、`error.code: upstream_timeout`）  |

検索が成立して該当が 0 件の場合は `200` で `memories` が空配列になります。上流障害時は空配列ではなく `502` / `504` を返すため、`200` の空配列を障害として扱う必要はありません。

## ユーザー管理 SaaS

ユーザーの一覧取得・作成・削除・ロール変更・承認・承認取り消し・利用の停止と再開・ロックの解除・所属と職種の変更を行います。

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

| メソッド   | エンドポイント                               | 説明              | スコープ                        |
| ------ | ------------------------------------- | --------------- | --------------------------- |
| GET    | `/v1/admin/users`                     | ユーザー一覧を取得       | `users:read / users:manage` |
| GET    | `/v1/admin/users/:userId/passkeys`    | ユーザーのパスキーの一覧を取得 | `users:read / users:manage` |
| POST   | `/v1/admin/users`                     | ユーザーを作成         | `users:manage`              |
| DELETE | `/v1/admin/users/:userId`             | ユーザーを削除         | `users:manage`              |
| PUT    | `/v1/admin/users/:userId/role`        | ユーザーのロールを変更     | `users:manage`              |
| POST   | `/v1/admin/users/:userId/approve`     | ユーザーを承認         | `users:manage`              |
| POST   | `/v1/admin/users/:userId/reject`      | ユーザーの承認を取り消し    | `users:manage`              |
| POST   | `/v1/admin/users/:userId/suspend`     | ユーザーの利用を止める     | `users:manage`              |
| POST   | `/v1/admin/users/:userId/resume`      | 止めた利用を戻す        | `users:manage`              |
| POST   | `/v1/admin/users/:userId/unlock`      | ユーザーのロックを解く     | `users:manage`              |
| PUT    | `/v1/admin/users/:userId/affiliation` | ユーザーの所属と職種を変える  | `users:manage`              |

### GET`/v1/admin/users`

ユーザー一覧を取得します。ページベースのページネーションに対応しています。`users:read` または `users:manage` スコープのいずれかが必要です（`users:manage` は `users:read` の権限を含みます）。

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

| パラメータ          | 型         | 必須 | 説明                                                      |
| -------------- | --------- | -- | ------------------------------------------------------- |
| `limit`        | `integer` | —  | 取得件数（1〜100、デフォルト: 25）                                   |
| `page`         | `integer` | —  | ページ番号（1以上、デフォルト: 1）                                     |
| `role`         | `string`  | —  | ロールフィルター。"admin"（管理者だけ）または "user"（管理者を除いた利用者だけ）         |
| `is_approved`  | `string`  | —  | 承認状態フィルター。"true" または "false"。停止中の利用者は true に入ります        |
| `search`       | `string`  | —  | 検索文字列（最大100文字）。メールアドレス等で検索                              |
| `organization` | `string`  | —  | 組織コードフィルター（コードの完全一致。大文字と小文字を区別。最大50文字、英数字・ハイフン・アンダースコア） |
| `job_type`     | `string`  | —  | 職種コードフィルター（コードの完全一致。大文字と小文字を区別。最大50文字、英数字・ハイフン・アンダースコア） |
| `order`        | `string`  | —  | 並び順。"asc" または "desc"（デフォルト: "desc"）。登録日時で並べます。ほかの値は 400 |

#### リクエスト例

**List users**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users?limit=10&is_approved=true" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

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

data = response.json()
for user in data["users"]:
  print(f"{user['email']} ({user['role']}, {user['status']})")
```

**TypeScript**

```typescript
const params = new URLSearchParams({ limit: "10", is_approved: "true" });
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users?" + params,
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);

const data = await response.json();
data.users.forEach((user) => {
console.log(user.email + " (" + user.role + ", " + user.status + ")");
});
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users?limit=10&is_approved=true",
  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）

| フィールド                   | 型         | 説明                                                                                                                              |
| ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `users`                 | `array`   | ユーザーオブジェクトの配列                                                                                                                   |
| `users[].userId`        | `string`  | ユーザーID                                                                                                                          |
| `users[].email`         | `string`  | メールアドレス                                                                                                                         |
| `users[].username`      | `string`  | ユーザー名                                                                                                                           |
| `users[].emailVerified` | `boolean` | メールアドレスの検証状態                                                                                                                    |
| `users[].role`          | `string`  | ロール（"admin" または "user"）                                                                                                         |
| `users[].status`        | `string`  | ステータス（"unverified"、"pending"、"approved"、"suspended"）。"suspended" は管理コンソールで利用を停止した承認済みの利用者（ログインできない）                             |
| `users[].organization`  | `object?` | 所属組織（value: コード、label: 名称）。未設定時はフィールド自体が省略される                                                                                   |
| `users[].jobType`       | `object?` | 職種（value: コード、label: 名称）。未設定時はフィールド自体が省略される                                                                                     |
| `users[].bio`           | `string?` | 自己紹介。未設定時はフィールド自体が省略される                                                                                                         |
| `users[].createdAt`     | `string`  | 作成日時（ISO 8601形式）                                                                                                                |
| `users[].lastLoginAt`   | `string?` | 最終ログイン日時（ISO 8601形式）。未ログイン時はフィールド自体が省略される                                                                                       |
| `users[].idpSynced`     | `boolean` | IdP（ID 基盤）から同期している利用者か。true の利用者の設定済みの所属・職種は、PUT /v1/admin/users/:userId/affiliation で変えられない（409 affiliation\_managed\_by\_idp） |
| `total`                 | `integer` | 総件数                                                                                                                             |
| `limit`                 | `integer` | 取得件数                                                                                                                            |
| `page`                  | `integer` | ページ番号                                                                                                                           |
| `hasMore`               | `boolean` | 次ページが存在するか                                                                                                                      |

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

```json
{
  "users": [
    {
      "userId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
      "email": "user1@example.com",
      "username": "user1@example.com",
      "emailVerified": true,
      "role": "user",
      "status": "approved",
      "createdAt": "2026-04-19T13:02:26.198Z",
      "idpSynced": false
    },
    {
      "userId": "90b40fd8-a6b8-42b8-ab61-f3b674169b43",
      "email": "user2@example.com",
      "username": "user2",
      "emailVerified": true,
      "role": "user",
      "status": "approved",
      "organization": { "value": "sales", "label": "営業部" },
      "jobType": { "value": "engineer", "label": "エンジニア" },
      "createdAt": "2026-04-17T07:09:47.484Z",
      "idpSynced": true
    },
    {
      "userId": "463e2c25-5a80-4362-b77e-941df96fb1f2",
      "email": "admin@example.com",
      "username": "admin@example.com",
      "emailVerified": true,
      "role": "admin",
      "status": "approved",
      "createdAt": "2026-04-17T07:02:41.015Z",
      "lastLoginAt": "2026-04-17T07:18:17.488Z",
      "idpSynced": false
    }
  ],
  "total": 132,
  "limit": 3,
  "page": 1,
  "hasMore": true
}
```

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

| ステータス | 説明                                  |
| ----- | ----------------------------------- |
| `400` | クエリパラメータが不正                         |
| `403` | users:read または users:manage スコープが不足 |

### GET`/v1/admin/users/:userId/passkeys`

ユーザーが登録したパスキーの一覧を取得します。`users:read` または `users:manage` スコープのいずれかが必要です。パスキーを消すのは管理コンソールで行います（この API では消せません）。

#### パスパラメータ

| パラメータ    | 型        | 必須 | 説明     |
| -------- | -------- | -- | ------ |
| `userId` | `string` | 必須 | ユーザーID |

#### リクエスト例

**List user passkeys**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/bbbe4306-6975-420b-af47-fb4c8f48b4aa/passkeys \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/bbbe4306-6975-420b-af47-fb4c8f48b4aa/passkeys",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/bbbe4306-6975-420b-af47-fb4c8f48b4aa/passkeys",
{
  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/admin/users/bbbe4306-6975-420b-af47-fb4c8f48b4aa/passkeys", 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)
```

#### レスポンスフィールド

| フィールド                     | 型                | 説明                               |
| ------------------------- | ---------------- | -------------------------------- |
| `passkeys`                | `array`          | パスキーの配列（全件）                      |
| `passkeys[].credentialId` | `string`         | パスキーの ID                         |
| `passkeys[].label`        | `string \| null` | パスキーの名前                          |
| `passkeys[].createdAt`    | `string \| null` | 登録した日時（ISO 8601）                 |
| `passkeys[].lastUsedAt`   | `string \| null` | 最後に使った日時（ISO 8601）。使っていなければ null |
| `hasMore`                 | `boolean`        | いつも false（全件を返します）               |

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

```json
{
  "passkeys": [
    {
      "credentialId": "AbCdEf0123456789_-AbCdEf0123456789_-AbCdEf0",
      "label": "業務用 PC",
      "createdAt": "2026-10-01T02:30:00.000Z",
      "lastUsedAt": "2026-11-17T23:45:10.000Z"
    }
  ],
  "hasMore": false
}
```

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

| ステータス | 説明                                  |
| ----- | ----------------------------------- |
| `403` | users:read または users:manage スコープが不足 |
| `404` | ユーザーが見つからない                         |

### POST`/v1/admin/users`

ユーザーを 1 人作ります。`users:manage` スコープが必要です。作ったユーザーは承認済み（`status` は `"approved"`）で、契約の利用者数に入ります。

- `password` を送らなかったときは一時パスワードを作り、作ったときの応答で 1 回だけ `temporaryPassword` として返します。あとから読むことはできないので、本人に伝えてください。この応答には `Cache-Control: no-store` が付きます。
- 知らせのメール（`sendNotificationEmail`）に、パスワードは入りません。
- 同じメールアドレスのユーザーを同時に作ったり、契約の利用者数の残りが 1 のときに同時に作ったりすると、500 になったり、上限を超えて作られたりすることがあります。1 人ずつ続けて作ってください。

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

| パラメータ                   | 型         | 必須 | 説明                                                                         |
| ----------------------- | --------- | -- | -------------------------------------------------------------------------- |
| `email`                 | `string`  | 必須 | メールアドレス。前後の空白を除いて小文字にします（255 文字まで）                                         |
| `displayName`           | `string`  | 必須 | 表示名（255 文字まで）。前後の空白を除き、< と > は消します                                         |
| `role`                  | `string`  | 必須 | "admin" または "user"                                                         |
| `organization`          | `string`  | 必須 | 組織のコード（GET /v1/organizations の値）                                           |
| `job`                   | `string`  | 必須 | 職種のコード（GET /v1/job-types の値）                                               |
| `bio`                   | `string`  | —  | 自己紹介（255 文字まで）。前後の空白を除き、< と > は消します                                        |
| `password`              | `string`  | —  | 初めのパスワード。パスワードの決まりを満たさないと 400。送らなければ一時パスワードを作り、応答の temporaryPassword で返します |
| `temporary`             | `boolean` | —  | 初めのサインインでパスワードを変えさせるか。省略時は、password を送らなければ true、送れば false                 |
| `sendNotificationEmail` | `boolean` | —  | 作ったことを本人にメールで知らせるか。省略時は true。メールを送れない環境では送られず、応答の emailSent が false になります  |

#### リクエスト例

**Create user**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{"email": "new.user@example.com", "displayName": "新しい利用者", "role": "user", "organization": "ORG001", "job": "JOB01"}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users",
  headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
  json={
      "email": "new.user@example.com",
      "displayName": "新しい利用者",
      "role": "user",
      "organization": "ORG001",
      "job": "JOB01",
  },
)
```

**TypeScript**

```typescript
const response = await fetch("https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users", {
method: "POST",
headers: {
  "Authorization": "Bearer " + accessToken,
  "Content-Type": "application/json",
},
body: JSON.stringify({
  email: "new.user@example.com",
  displayName: "新しい利用者",
  role: "user",
  organization: "ORG001",
  job: "JOB01",
}),
});
```

**Go**

```go
body, _ := json.Marshal(map[string]string{
  "email":        "new.user@example.com",
  "displayName":  "新しい利用者",
  "role":         "user",
  "organization": "ORG001",
  "job":          "JOB01",
})
req, _ := http.NewRequest("POST",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users",
  bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
```

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

| フィールド               | 型         | 説明                                                                      |
| ------------------- | --------- | ----------------------------------------------------------------------- |
| `user`              | `object`  | 作ったユーザー。ユーザー一覧の users\[] と同じ項目です（status は "approved"、idpSynced は false） |
| `emailSent`         | `boolean` | 知らせのメールを送ったか                                                            |
| `temporaryPassword` | `string?` | password を送らなかったときだけ。作った一時パスワード（この応答で 1 回だけ返ります）                        |

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

```json
{
  "user": {
    "userId": "5d1c9b2e-8f4a-4c3b-9e7d-1a2b3c4d5e6f",
    "email": "new.user@example.com",
    "username": "new.user@example.com",
    "emailVerified": true,
    "role": "user",
    "status": "approved",
    "organization": { "value": "ORG001", "label": "営業部" },
    "jobType": { "value": "JOB01", "label": "エンジニア" },
    "createdAt": "2026-11-10T09:00:00.000Z",
    "idpSynced": false
  },
  "emailSent": true,
  "temporaryPassword": "<一時パスワード>"
}
```

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

| ステータス         | 説明                                                                                                                                                                                                                                                                                                                     |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`         | email・displayName・role・organization・job が無い、これらと bio が文字列ではない・空・空白だけ（displayName・organization・job・bio は < と > を消すと空白だけになる値も）、role が "admin"・"user" 以外、displayName・bio が 255 文字を超える、password が空・空白だけ、temporary・sendNotificationEmail が真偽値ではない、メールアドレスの形が違う、組織・職種のコードが違う、またはパスワードが決まりを満たさない（`code: "invalid_parameter"`） |
| `400`         | ボディが壊れた JSON、または JSON のオブジェクトではない（`code: "invalid_body"`）                                                                                                                                                                                                                                                              |
| `415`         | ボディの Content-Type が application/json ではない（`code: "unsupported_media_type"`）                                                                                                                                                                                                                                            |
| `401`         | トークンが無効または未指定（`code: "invalid_token"`）                                                                                                                                                                                                                                                                                 |
| `403`         | users:manage スコープが不足（`code: "insufficient_scope"`）                                                                                                                                                                                                                                                                     |
| `409`         | 同じメールアドレスのユーザーがいる（`code: "user_exists"`。`param` は `email`）。別のメールアドレスで作ってください                                                                                                                                                                                                                                           |
| `409`         | 契約の利用者数の上限に達した（`code: "conflict"`）                                                                                                                                                                                                                                                                                     |
| `429`         | 送り元の IP ごとの回数の上限（1 時間に 30 回）を超えた（`code: "rate_limit_exceeded"`）。少し待ってから送り直してください                                                                                                                                                                                                                                       |
| `500・502・504` | ユーザーが作られたかもしれない。`GET /v1/admin/users?search=<email>` で確かめてから送り直してください（作られていれば、送り直すと 409 `user_exists`）。作られていて一時パスワードを受け取れなかったときは、本人がサインインの画面の「パスワードを忘れた方はこちら」から設定します。メールを送れない環境では、管理コンソールでパスワードを設定し直します                                                                                                                |
| `503`         | 契約の利用者数の上限を確かめられない。少し待ってから送り直してください                                                                                                                                                                                                                                                                                    |

### DELETE`/v1/admin/users/:userId`

ユーザーを削除します。削除したユーザーは、管理コンソール・チャットの画面と API から消え、元に戻せません。アーカイブした会話・会話ごとの作業のメモ・利用者ごとの設定の記録の削除を希望する場合は、[管理者ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/admin/guide/login-sso-guide.md#%E5%88%A9%E7%94%A8%E8%80%85%E3%82%92%E6%AD%A2%E3%82%81%E3%82%8B%E6%88%BB%E3%81%99)を参照してください。`users:manage` スコープが必要です。削除の前にそのユーザーに発行されていたアクセストークンは、削除の後も、有効期限（トークンを取得したときの `expires_in`）まで使えることがあります。

#### パスパラメータ

| パラメータ    | 型        | 必須 | 説明     |
| -------- | -------- | -- | ------ |
| `userId` | `string` | 必須 | ユーザーID |

#### リクエスト例

**Delete user**

**curl**

```curl
curl -X DELETE https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.delete(
  f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/{user_id}",
  headers={"Authorization": f"Bearer {token}"},
)
```

**TypeScript**

```typescript
const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/${userId}`,
{
  method: "DELETE",
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("DELETE",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/"+userID,
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
```

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

```json
{ "userId": "abc123", "deleted": true }
```

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

| ステータス | 説明                                                                                    |
| ----- | ------------------------------------------------------------------------------------- |
| `403` | users:manage スコープが不足                                                                  |
| `404` | 指定されたユーザーが見つからない（既に削除済みを含む）                                                           |
| `429` | 送り元の IP ごとの回数の上限（1 分に 10 回）を超えた（`code: "rate_limit_exceeded"`）。少し待ってから送り直してください       |
| `500` | 利用者のデータの一部を消せなかったため、削除を止めた（`code: "user_delete_incomplete"`）。ユーザーは残っています。もう一度削除してください |

### PUT`/v1/admin/users/:userId/role`

ユーザーのロールを変更します。ステータスが approved のユーザーと、`emailVerified` が true の suspended のユーザーのみ変更可能です。

> **ロール変更時の挙動**
>
> - **`user` への降格時**: 対象ユーザーのログイン中のセッションは自動では終わりません。すでに発行されたアクセストークンの権限は、有効期限まで変わりません
> - **`admin` への昇格時**: 対象ユーザーのセッションは継続され、新しい権限は、昇格の後に発行されるトークンから有効になります

#### パスパラメータ

| パラメータ    | 型        | 必須 | 説明     |
| -------- | -------- | -- | ------ |
| `userId` | `string` | 必須 | ユーザーID |

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

| パラメータ  | 型        | 必須 | 説明                         |
| ------ | -------- | -- | -------------------------- |
| `role` | `string` | 必須 | 変更先のロール。"admin" または "user" |

#### リクエスト例

**Change user role**

**curl**

```curl
curl -X PUT https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/role \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{"role": "admin"}'
```

**Python**

```python
import requests

response = requests.put(
  f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/{user_id}/role",
  headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
  json={"role": "admin"},
)
```

**TypeScript**

```typescript
const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/${userId}/role`,
{
  method: "PUT",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ role: "admin" }),
}
);
```

**Go**

```go
body, _ := json.Marshal(map[string]string{"role": "admin"})
req, _ := http.NewRequest("PUT",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/"+userID+"/role",
  bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
```

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

```json
{ "userId": "abc123", "changed": true }
```

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

| ステータス | 説明                                                                                                                       |
| ----- | ------------------------------------------------------------------------------------------------------------------------ |
| `400` | role が未指定または不正、ボディが壊れた JSON（`code: "invalid_body"`）、または対象ユーザーが、ステータス approved でも、`emailVerified` が true の suspended でもない |
| `415` | ボディの Content-Type が application/json ではない（`code: "unsupported_media_type"`）                                              |
| `403` | users:manage スコープが不足                                                                                                     |
| `404` | ユーザーが見つからない                                                                                                              |
| `409` | 同じ利用者のほかの更新（承認・ロールの変更・プロフィールの更新など）の処理中（`code: "conflict"`）。少し待ってから送り直してください                                              |
| `429` | 送り元の IP ごとの回数の上限（1 分に 100 回）を超えた（`code: "rate_limit_exceeded"`）。少し待ってから送り直してください                                         |
| `500` | ロールの変更を終えられなかった（`code: "internal_error"`）。ユーザーを取得し直して今のロールを確かめ、必要なら同じ変更をもう一度送ってください                                      |

### POST`/v1/admin/users/:userId/approve`

ユーザーを承認します。ステータスが pending のユーザーのみ承認可能です。承認を取り消した（止めた）ユーザーも pending と表示され、承認できます。承認するとログインできるようになり、データも残っていますが、取り消しで止まった物（実行中の会話・個人の定期の実行・持ち主のプロジェクトの巡回と実行）と削除した外部サービスへの接続は、自動では戻りません。

> **注記**
>
> 承認処理が成功すると、対象ユーザーのメールアドレス宛に承認通知メールが自動送信されます。

#### パスパラメータ

| パラメータ    | 型        | 必須 | 説明     |
| -------- | -------- | -- | ------ |
| `userId` | `string` | 必須 | ユーザーID |

#### リクエストボディ（任意）

| パラメータ    | 型        | 必須 | 説明                          |
| -------- | -------- | -- | --------------------------- |
| `reason` | `string` | —  | 承認の理由。空でない場合は、利用者の情報に記録されます |

#### リクエスト例

**Approve user**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/approve \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.post(
  f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/{user_id}/approve",
  headers={"Authorization": f"Bearer {token}"},
)
```

**TypeScript**

```typescript
const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/${userId}/approve`,
{
  method: "POST",
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("POST",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/"+userID+"/approve",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
```

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

```json
{ "userId": "abc123", "approved": true }
```

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

| ステータス | 説明                                                                                                             |
| ----- | -------------------------------------------------------------------------------------------------------------- |
| `400` | ユーザーのステータスが pending 以外（承認不可。メールを確かめていない、または承認済み〈停止中を含む〉）                                                       |
| `400` | reason が文字列ではない、またはボディが壊れた JSON・JSON のオブジェクトではない（`code: "invalid_body"`）                                       |
| `415` | ボディの Content-Type が application/json ではない（`code: "unsupported_media_type"`）                                    |
| `403` | users:manage スコープが不足                                                                                           |
| `404` | ユーザーが見つからない                                                                                                    |
| `429` | 送り元の IP ごとの回数の上限（1 分に 10 回）を超えた（`code: "rate_limit_exceeded"`）。少し待ってから送り直してください                                |
| `409` | 取得した後に別の操作で承認された、契約の利用者数の上限に達した、または同じ利用者のほかの更新の処理中（`code: "conflict"`）                                         |
| `500` | 承認を反映できなかった（変更をチャットに伝えられなかった。ユーザーはまだ承認されていない）（`code: "user_suspension_incomplete"`）。同じ要求を送り直してください（何度でも送り直せます） |

### POST`/v1/admin/users/:userId/reject`

ユーザーの承認を取り消します。ステータスが approved のユーザーと、`emailVerified` が true の suspended のユーザーのみ取り消し可能です（取り消し済みのユーザーも、もう一度取り消せます。やり直しです）。取り消すと、ユーザーは無効になり、ログインできなくなります。契約のアカウント数から外れます。会話・ファイル・スケジュールなどのデータは残ります。止めるもの（実行中の会話と個人の定期の実行、持ち主のプロジェクトの巡回と開いている実行、本人の外部サービスへの接続の削除）は停止（`/suspend`）と同じで、再承認（`approve`）してもそれらは自動では戻りません。停止（`/suspend`）はアカウント数に数えたまま、取り消しは数から外れます。取り消し後のステータスは pending と表示されます。取り消しの前にそのユーザーに発行されていたアクセストークンは、取り消しの後も、有効期限（トークンを取得したときの `expires_in`）まで使えることがあります。

> **注記**
>
> 承認済みのユーザーを取り消したときに、1 度だけ、対象ユーザーのメールアドレス宛に通知メールが自動送信されます。

#### パスパラメータ

| パラメータ    | 型        | 必須 | 説明     |
| -------- | -------- | -- | ------ |
| `userId` | `string` | 必須 | ユーザーID |

#### リクエスト例

**Reject user**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/reject \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.post(
  f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/{user_id}/reject",
  headers={"Authorization": f"Bearer {token}"},
)
```

**TypeScript**

```typescript
const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/${userId}/reject`,
{
  method: "POST",
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("POST",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/"+userID+"/reject",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
```

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

```json
{ "userId": "abc123", "status": "pending" }
```

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

| ステータス | 説明                                                                                                              |
| ----- | --------------------------------------------------------------------------------------------------------------- |
| `400` | ユーザーが、ステータス approved でも、`emailVerified` が true の suspended でもない（取り消し不可）。取り消し済みのユーザーも、もう一度取り消せます（やり直し。メールは送りません） |
| `403` | users:manage スコープが不足                                                                                            |
| `404` | ユーザーが見つからない                                                                                                     |
| `429` | 送り元の IP ごとの回数の上限（1 分に 10 回）を超えた（`code: "rate_limit_exceeded"`）。少し待ってから送り直してください                                 |
| `409` | 同じ利用者のほかの更新の処理中（`code: "conflict"`）                                                                             |
| `500` | 承認は取り消されているが、利用の停止をチャットに伝えられなかった（`code: "user_suspension_incomplete"`）。ユーザーは無効・承認なしのままです。同じ要求を送り直すと、停止をやり直します   |

### POST`/v1/admin/users/:userId/suspend`

ユーザーの利用を止めます。承認の状態とデータは残り、一覧の status が "suspended" になります。止めたユーザーはログインできません。ログイン中のセッションの終了も試みます（終わらせられなかったときも停止は成功として返り、同じ要求を送り直すともう一度試みます）。止めると、そのユーザーが実行中の会話と個人の定期の実行が止まり、そのユーザー本人の外部サービスへの接続が削除され（プロジェクトの接続は残ります）、そのユーザーが持ち主のプロジェクトの巡回と開いているワークフローの実行も止まります（プロジェクトの定義は残ります）。止めを解いても、止まったものは自動では元に戻りません。止めたユーザーが持ち主のプロジェクトでは、ワークフローの実行の開始と閉じた実行の再開が `409 Conflict`（`principal_suspended`）で断られます。止められるのは承認済みのユーザーだけです。同じ操作を何度送っても結果は同じです。テナント経由で発行したトークンは、そのトークンの idp.sub のユーザー自身を止められません（409）。

#### パスパラメータ

| パラメータ    | 型        | 必須 | 説明     |
| -------- | -------- | -- | ------ |
| `userId` | `string` | 必須 | ユーザーID |

ボディは要りません（送っても使いません）。

#### リクエスト例

**Suspend user**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/suspend \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.post(
  f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/{user_id}/suspend",
  headers={"Authorization": f"Bearer {token}"},
)
```

**TypeScript**

```typescript
const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/${userId}/suspend`,
{
  method: "POST",
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("POST",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/"+userID+"/suspend",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
```

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

```json
{ "userId": "abc123", "suspended": true }
```

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

| ステータス | 説明                                                                                                                                 |
| ----- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `400` | ボディが壊れた JSON（`code: "invalid_body"`）                                                                                               |
| `401` | トークンが無効または未指定（`code: "invalid_token"`）                                                                                             |
| `403` | users:manage スコープが不足（`code: "insufficient_scope"`）                                                                                 |
| `404` | ユーザーが見つからない（`code: "user_not_found"`）                                                                                              |
| `409` | 止められないユーザー（承認済みでない・削除済み・恒久的にロックされている）、トークンの idp.sub のユーザー自身を止めようとした、または同じ利用者のほかの更新の処理中（`code: "conflict"`）。どれに当たるかは、エラーの文と案内で分かります |
| `429` | 送り元の IP ごとの回数の上限（1 分に 10 回）を超えた（`code: "rate_limit_exceeded"`）。少し待ってから送り直してください                                                    |
| `500` | 停止を最後まで終えられなかった（ログインは止めたが、チャットへの反映が終わらなかった）（`code: "user_suspension_incomplete"`）。同じ要求を送り直してください                                   |
| `500` | そのほかの誤り（`code: "internal_error"`）。同じ要求を送り直してください                                                                                   |

### POST`/v1/admin/users/:userId/resume`

止めたユーザーの利用を戻します。同じ操作を何度送っても結果は同じです。

#### パスパラメータ

| パラメータ    | 型        | 必須 | 説明     |
| -------- | -------- | -- | ------ |
| `userId` | `string` | 必須 | ユーザーID |

ボディは要りません（送っても使いません）。

#### リクエスト例

**Resume user**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/resume \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.post(
  f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/{user_id}/resume",
  headers={"Authorization": f"Bearer {token}"},
)
```

**TypeScript**

```typescript
const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/${userId}/resume`,
{
  method: "POST",
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("POST",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/"+userID+"/resume",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
```

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

```json
{ "userId": "abc123", "suspended": false }
```

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

| ステータス | 説明                                                                                                 |
| ----- | -------------------------------------------------------------------------------------------------- |
| `400` | ボディが壊れた JSON（`code: "invalid_body"`）                                                               |
| `401` | トークンが無効または未指定（`code: "invalid_token"`）                                                             |
| `403` | users:manage スコープが不足（`code: "insufficient_scope"`）                                                 |
| `404` | ユーザーが見つからない（`code: "user_not_found"`）                                                              |
| `409` | 戻せないユーザー（承認済みでない・削除済み・恒久的にロックされている）、または同じ利用者のほかの更新の処理中（`code: "conflict"`）。どれに当たるかは、エラーの文と案内で分かります |
| `429` | 送り元の IP ごとの回数の上限（1 分に 10 回）を超えた（`code: "rate_limit_exceeded"`）。少し待ってから送り直してください                    |
| `500` | 戻すのを最後まで終えられず、まだ止まったまま（`code: "user_suspension_incomplete"`）。同じ要求を送り直してください                        |
| `500` | そのほかの誤り。チャットの側は戻したがログインの側を戻せなかったときも、これになります（`code: "internal_error"`）。同じ要求を送り直してください               |

### POST`/v1/admin/users/:userId/unlock`

ログインの失敗でロックされたユーザーのロックを解きます。ロックされていなかったときは何も変えず、wasLocked が false になります。

#### パスパラメータ

| パラメータ    | 型        | 必須 | 説明     |
| -------- | -------- | -- | ------ |
| `userId` | `string` | 必須 | ユーザーID |

ボディは要りません（送っても使いません）。

#### リクエスト例

**Unlock user**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/unlock \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.post(
  f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/{user_id}/unlock",
  headers={"Authorization": f"Bearer {token}"},
)
```

**TypeScript**

```typescript
const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/${userId}/unlock`,
{
  method: "POST",
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("POST",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/"+userID+"/unlock",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
```

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

```json
{ "userId": "abc123", "wasLocked": true }
```

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

| ステータス | 説明                                                                               |
| ----- | -------------------------------------------------------------------------------- |
| `400` | ボディが壊れた JSON（`code: "invalid_body"`）                                             |
| `401` | トークンが無効または未指定（`code: "invalid_token"`）                                           |
| `403` | users:manage スコープが不足（`code: "insufficient_scope"`）                               |
| `404` | ユーザーが見つからない（`code: "user_not_found"`）                                            |
| `409` | 同じ利用者のほかの更新の処理中（`code: "conflict"`）。少し待ってから送り直してください                             |
| `429` | 送り元の IP ごとの回数の上限（1 分に 100 回）を超えた（`code: "rate_limit_exceeded"`）。少し待ってから送り直してください |
| `500` | ロックの解除を終えられなかった（`code: "internal_error"`）。同じ要求を送り直してください                         |

### PUT`/v1/admin/users/:userId/affiliation`

ユーザーの所属（組織のコード）と職種（職種のコード）を変えます。どちらも要ります。コードは GET /v1/organizations・GET /v1/job-types で引けます。答えに変える前と後の値が入ります（前の値が未設定なら null）。所属を変えると、新しい所属以外の組織の、組織管理者と組織の運用の役割は外れます（監査役は外れません）。500 のときは、所属と職種がもう変わっていることがあります。同じ要求を送り直すと、組織の役割の整理がやり直されます。IdP から同期している利用者（GET /v1/admin/users の `users[].idpSynced` が `true` の利用者）の、設定済みの所属・職種は変えられません（409 `affiliation_managed_by_idp`）。利用者を同期している ID 基盤（IdP）で変えてください。未設定の方だけを埋めるときは、設定済みの方に今の値（GET /v1/admin/users の `users[].organization.value`・`users[].jobType.value`）を送ります。無効なコードは、この判定より先に 400 になります。

#### パスパラメータ

| パラメータ    | 型        | 必須 | 説明     |
| -------- | -------- | -- | ------ |
| `userId` | `string` | 必須 | ユーザーID |

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

| パラメータ          | 型        | 必須 | 説明                               |
| -------------- | -------- | -- | -------------------------------- |
| `organization` | `string` | 必須 | 組織のコード（GET /v1/organizations の値） |
| `job`          | `string` | 必須 | 職種のコード（GET /v1/job-types の値）     |

#### リクエスト例

**Change user affiliation**

**curl**

```curl
curl -X PUT https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/affiliation \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{"organization": "ORG002", "job": "JOB01"}'
```

**Python**

```python
import requests

response = requests.put(
  f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/{user_id}/affiliation",
  headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
  json={"organization": "ORG002", "job": "JOB01"},
)
```

**TypeScript**

```typescript
const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/${userId}/affiliation`,
{
  method: "PUT",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ organization: "ORG002", job: "JOB01" }),
}
);
```

**Go**

```go
body, _ := json.Marshal(map[string]string{"organization": "ORG002", "job": "JOB01"})
req, _ := http.NewRequest("PUT",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/"+userID+"/affiliation",
  bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
```

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

```json
{
  "userId": "abc123",
  "previous": { "organization": "ORG001", "job": null },
  "current": { "organization": "ORG002", "job": "JOB01" }
}
```

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

| ステータス | 説明                                                                                                                                      |
| ----- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | organization・job が無い、文字列ではない、または組織・職種のコードが違う（`code: "invalid_parameter"`）                                                               |
| `400` | ボディが壊れた JSON、または JSON のオブジェクトではない（`code: "invalid_body"`）                                                                               |
| `415` | ボディの Content-Type が application/json ではない（`code: "unsupported_media_type"`）                                                             |
| `401` | トークンが無効または未指定（`code: "invalid_token"`）                                                                                                  |
| `403` | users:manage スコープが不足（`code: "insufficient_scope"`）                                                                                      |
| `404` | ユーザーが見つからない（`code: "user_not_found"`）                                                                                                   |
| `409` | 同じ利用者のほかの更新の処理中（`code: "conflict"`）。少し待ってから送り直してください                                                                                    |
| `409` | この利用者の所属・職種は IdP から同期しているので変えられない（`code: "affiliation_managed_by_idp"`）。利用者を同期している ID 基盤（IdP）で変えてください。未設定の方だけを埋めるときは、設定済みの方に今の値を送ってください |
| `429` | 送り元の IP ごとの回数の上限（1 分に 100 回）を超えた（`code: "rate_limit_exceeded"`）。少し待ってから送り直してください                                                        |
| `500` | 所属と職種の変更を最後まで終えられなかった（`code: "internal_error"`）。所属と職種がもう変わっていることがあります。同じ要求を送り直すと、組織の役割の整理がやり直されます                                       |

## ログ SaaS

監査ログ・操作監査ログ・利用者の操作の監査・LLMログ・LLM Gateway ログ・LLM Gateway 操作監査・アクセスログ（外部への通信を許可・遮断した記録）・ガードレールアラートの閲覧を行います。一覧は、利用者の操作の監査だけがカーソルベース、ほかはページベースのページネーションに対応し、日付範囲フィルターが利用可能です。

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

| メソッド | エンドポイント                             | 説明                     | スコープ        |
| ---- | ----------------------------------- | ---------------------- | ----------- |
| GET  | `/v1/admin/audit-logs`              | 監査ログ一覧を取得              | `logs:read` |
| GET  | `/v1/admin/user-action-logs`        | 利用者の操作の監査の一覧を取得        | `logs:read` |
| GET  | `/v1/admin/action-audit-logs`       | 操作監査ログ一覧を取得            | `logs:read` |
| GET  | `/v1/admin/llm-logs`                | LLMログ一覧を取得             | `logs:read` |
| GET  | `/v1/admin/llm-gateway-logs`        | LLM Gateway ログ一覧を取得    | `logs:read` |
| GET  | `/v1/admin/llm-gateway-action-logs` | LLM Gateway 操作監査の一覧を取得 | `logs:read` |
| GET  | `/v1/admin/access-logs`             | アクセスログ一覧を取得            | `logs:read` |
| GET  | `/v1/admin/guardrail-alerts`        | ガードレールアラート一覧を取得        | `logs:read` |

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

| パラメータ   | 型         | 必須 | 説明                                                                                                |
| ------- | --------- | -- | ------------------------------------------------------------------------------------------------- |
| `limit` | `integer` | —  | 取得件数（1〜100、デフォルト: 25。利用者の操作の監査はデフォルト: 50）                                                         |
| `page`  | `integer` | —  | ページ番号（1以上、デフォルト: 1）。利用者の操作の監査は使いません（cursor を使います）                                                 |
| `from`  | `string`  | —  | 開始日（YYYY-MM-DD形式の実在する日付、UTC基準）。形式が違う値・実在しない日付・文字列ではない値は 400                                       |
| `to`    | `string`  | —  | 終了日（YYYY-MM-DD形式の実在する日付、UTC基準）。指定した日の終わりまでを含みます。形式が違う値・実在しない日付・文字列ではない値は 400                      |
| `order` | `string`  | —  | 並び順。"asc" または "desc"（デフォルト: "desc"）。各ログの時刻の列で並べます。ほかの値は 400。アクセスログと利用者の操作の監査は新しい順の固定で、指定しても無視されます |

### GET`/v1/admin/audit-logs`

監査ログ一覧を取得します。既定は作成日時の降順です（order で昇順にできます）。

#### 絞り込みのクエリパラメータ

| パラメータ      | 型        | 必須 | 説明                       |
| ---------- | -------- | -- | ------------------------ |
| `resource` | `string` | —  | リソース（resource）の完全一致      |
| `action`   | `string` | —  | 操作（action）の完全一致          |
| `user_id`  | `string` | —  | 操作した利用者の ID（userId）の完全一致 |

#### リクエスト例

**List audit logs**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/audit-logs?limit=10&from=2026-04-01&to=2026-04-15" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/audit-logs",
  headers={"Authorization": f"Bearer {token}"},
  params={"limit": 10, "from": "2026-04-01", "to": "2026-04-15"},
)
```

**TypeScript**

```typescript
const params = new URLSearchParams({ limit: "10", from: "2026-04-01", to: "2026-04-15" });
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/audit-logs?" + params,
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/audit-logs?limit=10&from=2026-04-01&to=2026-04-15",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
```

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

| フィールド                    | 型                | 説明                                                                                                                                  |
| ------------------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `auditLogs`              | `array`          | 監査ログオブジェクトの配列                                                                                                                       |
| `auditLogs[].auditLogId` | `string`         | 監査ログID                                                                                                                              |
| `auditLogs[].resource`   | `string`         | 操作対象リソース（例: users/show, config/organizations/create, config/job-types/edit）                                                         |
| `auditLogs[].action`     | `string`         | 操作アクション（approve / reject / promote / demote / create / update / delete / reset-password など）。meta に action がある記録は、その値（管理コンソールの表示と同じ） |
| `auditLogs[].meta`       | `object \| null` | 追加メタデータ                                                                                                                             |
| `auditLogs[].userId`     | `string`         | 操作ユーザーID。システム連携（Client Credentials フロー）のトークンでの操作は client:<クライアント ID>                                                                |
| `auditLogs[].userEmail`  | `string \| null` | 操作ユーザーのメールアドレス                                                                                                                      |
| `auditLogs[].userName`   | `string \| null` | 操作ユーザーの表示名。システム連携（Client Credentials フロー）のトークンでの操作はクライアント名                                                                          |
| `auditLogs[].ipAddress`  | `string \| null` | IPアドレス                                                                                                                              |
| `auditLogs[].userAgent`  | `string \| null` | User-Agent                                                                                                                          |
| `auditLogs[].createdAt`  | `string`         | 作成日時（ISO 8601形式）                                                                                                                    |
| `total`                  | `integer`        | 総件数                                                                                                                                 |
| `limit`                  | `integer`        | 取得件数                                                                                                                                |
| `page`                   | `integer`        | ページ番号                                                                                                                               |
| `hasMore`                | `boolean`        | 次ページが存在するか                                                                                                                          |

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

```json
{
  "auditLogs": [
    {
      "auditLogId": "6b4366a3-791d-4f60-a9ef-24bdb3303e36",
      "resource": "users/list",
      "action": "approve",
      "meta": {
        "userName": "user2@example.com",
        "timestamp": "2026-04-19T13:03:27.238Z",
        "isApproved": true
      },
      "userId": "41b9fcf1-958d-4a86-a863-804b69224a1d",
      "userEmail": "admin@example.com",
      "userName": "admin@example.com",
      "ipAddress": "203.0.113.140",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36",
      "createdAt": "2026-04-19T13:03:27.479Z"
    },
    {
      "auditLogId": "c14d6065-7c35-44f6-8eea-033ede09bf3a",
      "resource": "users/show",
      "action": "delete",
      "meta": {
        "userName": "user1@example.com",
        "timestamp": "2026-04-19T05:04:19.745Z",
        "userEmail": "user1@example.com"
      },
      "userId": "client:billing-integration",
      "userEmail": "service-account-client@federation.invalid",
      "userName": "請求システム連携",
      "ipAddress": "198.51.100.23",
      "userAgent": "Mozilla/5.0 (...)",
      "createdAt": "2026-04-19T05:04:19.876Z"
    },
    {
      "auditLogId": "f84ef377-9d75-4875-9958-b084c91a3c9b",
      "resource": "organizations",
      "action": "delete",
      "meta": {},
      "userId": "client:billing-integration",
      "userEmail": "service-account-client@federation.invalid",
      "userName": "請求システム連携",
      "ipAddress": "198.51.100.23",
      "userAgent": "Mozilla/5.0 (...)",
      "createdAt": "2026-04-19T05:02:01.736Z"
    }
  ],
  "total": 1537,
  "limit": 3,
  "page": 1,
  "hasMore": true
}
```

### GET`/v1/admin/user-action-logs`

利用者の操作の監査の一覧を取得します。利用者がチャット画面で行った操作（会話・ファイル・共有などを開いた・作った・消したなど）の記録です。新しい順の固定で、[カーソルベース](#%E3%82%AB%E3%83%BC%E3%82%BD%E3%83%AB%E3%83%99%E3%83%BC%E3%82%B9)のページネーションです（`limit` は 1〜100、デフォルト 50）。本文は記録されません。画面の「付加情報」（伏せた IP アドレス・UA など）は返しません。

- 期間（`from`・`to`）を省くと直近 30 日です。`from` だけを省くと `to` の日までの 30 日、`to` だけを省くと今までです。`from` が `to` より後は 400 です。
- 2 ページ目からも、1 ページ目と同じ `user_id`・`action` を `cursor` と一緒に送ってください。条件を変えると対象範囲が変わり、項目の重複や取りこぼしが起きます。期間は `cursor` が 1 ページ目のものを持つので、2 ページ目から送った `from`・`to` では変わりません。
- 返る件数が `limit` より少なくても、`hasMore` が `true` なら続きがあります。

#### 絞り込みのクエリパラメータ

| パラメータ     | 型        | 必須 | 説明                                 |
| --------- | -------- | -- | ---------------------------------- |
| `user_id` | `string` | —  | 操作した利用者の ID（userId）の完全一致（128 文字まで） |
| `action`  | `string` | —  | 操作（action）の完全一致（64 文字まで）           |

空の値は絞り込みません。空白だけの値・前後に空白がある値・長すぎる値・2 つ以上の指定は 400 です。

#### リクエスト例

**List user action logs**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/user-action-logs?limit=50&from=2026-11-01&to=2026-11-10&action=export" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/user-action-logs",
  headers={"Authorization": f"Bearer {token}"},
  params={"limit": 50, "from": "2026-11-01", "to": "2026-11-10", "action": "export"},
)
```

**TypeScript**

```typescript
const params = new URLSearchParams({ limit: "50", from: "2026-11-01", to: "2026-11-10", action: "export" });
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/user-action-logs?" + params,
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/user-action-logs?limit=50&from=2026-11-01&to=2026-11-10&action=export",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
```

2 ページ目は、1 ページ目のレスポンスの `cursor` と、同じ絞り込み（この例では `action`）を送ります。

```bash
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/user-action-logs?limit=50&action=export&cursor=<前回のレスポンスの cursor>" \
  -H "Authorization: Bearer <access_token>"
```

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

| フィールド                              | 型                | 説明                                                                            |
| ---------------------------------- | ---------------- | ----------------------------------------------------------------------------- |
| `userActionLogs`                   | `array`          | 利用者の操作の監査の配列                                                                  |
| `userActionLogs[].userActionLogId` | `string`         | 利用者の操作の監査の ID                                                                 |
| `userActionLogs[].occurredAt`      | `string`         | 操作した日時（ISO 8601形式）                                                            |
| `userActionLogs[].eventType`       | `string`         | 種類。user\_action.\<resource>.\<action> の形（例: user\_action.conversation.export） |
| `userActionLogs[].userId`          | `string \| null` | 操作した利用者の ID。分からない記録は null                                                     |
| `userActionLogs[].actorKind`       | `string`         | 操作した主体（human: 利用者 / unknown: 利用者が分からない記録）                                     |
| `userActionLogs[].resource`        | `string \| null` | 対象（例: conversation・share・session）                                             |
| `userActionLogs[].action`          | `string \| null` | 操作（例: export・delete）                                                          |
| `userActionLogs[].decision`        | `string`         | 結果（例: allow・deny・rejected・not\_found・error・aborted）                           |
| `userActionLogs[].requestId`       | `string \| null` | 要求 ID                                                                         |
| `userActionLogs[].conversationId`  | `string \| null` | 会話 ID                                                                         |
| `userActionLogs[].systemVersion`   | `string \| null` | 記録したときのシステムの版                                                                 |
| `hasMore`                          | `boolean`        | 次ページが存在するか                                                                    |
| `cursor`                           | `string?`        | hasMore が true のときだけ。次のページを取得するためのカーソル値                                       |

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

```json
{
  "userActionLogs": [
    {
      "userActionLogId": "48213",
      "occurredAt": "2026-11-10T02:15:30.123Z",
      "eventType": "user_action.conversation.export",
      "userId": "41b9fcf1-958d-4a86-a863-804b69224a1d",
      "actorKind": "human",
      "resource": "conversation",
      "action": "export",
      "decision": "allow",
      "requestId": "7f3c2a1e-9b8d-4c6f-a5e4-3d2c1b0a9f8e",
      "conversationId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
      "systemVersion": "3.4.0"
    }
  ],
  "hasMore": true,
  "cursor": "eyJjIjoiTWpBeU5pMHhNUzB4TUZRd01qb3hOVG96TUM0eE1qTmFmRFE0TWpFeiIsImYiOiIyMDI2LTExLTAxVDAwOjAwOjAwLjAwMFoiLCJ0IjoiMjAyNi0xMS0xMVQwMDowMDowMC4wMDBaIiwiZSI6dHJ1ZX0"
}
```

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

| ステータス | 説明                                                                                                                                                                     |
| ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | limit が 1〜100 ではない、from・to が YYYY-MM-DD 形式の実在する日付ではない、from が to より後、user\_id・action が空白だけ・前後に空白がある・長すぎる・2 つ以上、または cursor が不正（前回レスポンスの値以外）（`code: "invalid_parameter"`） |
| `400` | サービス側で期間を受け付けなかった（例: to を省いて、from に今日より後の日を指定した）（`code: "bad_request"`）                                                                                                |
| `403` | logs:read スコープが不足（`code: "insufficient_scope"`）                                                                                                                        |

### GET`/v1/admin/action-audit-logs`

操作監査ログの一覧を取得します。Agent のツールの呼び出し、実行ルールでの許可・拒否、承認など、利用者・Agent・システムが実行したことの記録です。既定は発生日時の降順です（order で昇順にできます）。本文は記録されません。画面の「記録内容の整合性確認用ハッシュ」・「行ハッシュ」・「メタデータ」は返しません。

#### 絞り込みのクエリパラメータ

| パラメータ               | 型        | 必須 | 説明                                                                                                         |
| ------------------- | -------- | -- | ---------------------------------------------------------------------------------------------------------- |
| `event_type`        | `string` | —  | イベント種別（eventType）の完全一致（例: "tool.invoked"・"approval.resolved"・"gate.resolved"・"run.started"・"agent.copied"） |
| `decision`          | `string` | —  | 判定（decision）の完全一致（例: "allow"・"deny"・"completed"・"failed"・"copied"）                                         |
| `source`            | `string` | —  | 記録元（source）の完全一致（例: "worker"・"cli-api"・"front"・"admin"・"login"・"agent\_executor"）                          |
| `actor_type`        | `string` | —  | 実行者の種類（actorType）の完全一致（例: "human"・"agent"・"system"）                                                        |
| `actor_kind`        | `string` | —  | 実行者の区分（actorKind）の完全一致（例: "human"・"human\_external"・"system"・"agent"・"unknown"）                            |
| `actor_ref`         | `string` | —  | 実行者（actorRef）の完全一致                                                                                         |
| `conversation_id`   | `string` | —  | 会話 ID（conversationId）の完全一致                                                                                 |
| `execution_id`      | `string` | —  | 実行 ID（executionId）の完全一致                                                                                    |
| `root_execution_id` | `string` | —  | 一連の実行 ID（rootExecutionId）の完全一致                                                                             |
| `project_id`        | `string` | —  | プロジェクト ID（projectId）の完全一致。UUID ではない値は 400                                                                  |
| `request_id`        | `string` | —  | リクエスト ID（requestId）の完全一致                                                                                   |

値は縛らず、知らない値は該当なしになります。空の値は絞り込みません。空白だけの値・前後に空白がある値・2 つ以上の指定は 400 です。

#### リクエスト例

**List action audit logs**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/action-audit-logs?limit=10&from=2026-11-01&to=2026-11-10&source=front" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/action-audit-logs",
  headers={"Authorization": f"Bearer {token}"},
  params={"limit": 10, "from": "2026-11-01", "to": "2026-11-10", "source": "front"},
)
```

**TypeScript**

```typescript
const params = new URLSearchParams({ limit: "10", from: "2026-11-01", to: "2026-11-10", source: "front" });
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/action-audit-logs?" + params,
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/action-audit-logs?limit=10&from=2026-11-01&to=2026-11-10&source=front",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
```

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

| フィールド                                | 型                | 説明                                                                |
| ------------------------------------ | ---------------- | ----------------------------------------------------------------- |
| `actionAuditLogs`                    | `array`          | 操作監査ログオブジェクトの配列                                                   |
| `actionAuditLogs[].actionAuditLogId` | `string`         | 操作監査ログID                                                          |
| `actionAuditLogs[].occurredAt`       | `string \| null` | 発生日時（ISO 8601形式）                                                  |
| `actionAuditLogs[].source`           | `string \| null` | 記録元（例: worker・cli-api・front・admin・login・agent\_executor）          |
| `actionAuditLogs[].eventType`        | `string \| null` | イベント種別                                                            |
| `actionAuditLogs[].actorType`        | `string \| null` | 実行者の種類（例: human・agent・system）                                     |
| `actionAuditLogs[].actorKind`        | `string \| null` | 実行者の区分（例: human・human\_external・system・agent・unknown）。古い記録では null |
| `actionAuditLogs[].actorRef`         | `string \| null` | 実行者                                                               |
| `actionAuditLogs[].onBehalfOfRef`    | `string \| null` | 代理元（誰の代わりに実行したか）                                                  |
| `actionAuditLogs[].resource`         | `string \| null` | 対象                                                                |
| `actionAuditLogs[].action`           | `string \| null` | 操作                                                                |
| `actionAuditLogs[].decision`         | `string \| null` | 判定                                                                |
| `actionAuditLogs[].reason`           | `string \| null` | 理由コード                                                             |
| `actionAuditLogs[].policyId`         | `string \| null` | 実行ルールID                                                           |
| `actionAuditLogs[].policyVersion`    | `string \| null` | 実行ルールの版                                                           |
| `actionAuditLogs[].executionId`      | `string \| null` | 実行ID                                                              |
| `actionAuditLogs[].rootExecutionId`  | `string \| null` | 一連の実行ID。古い記録では null                                               |
| `actionAuditLogs[].conversationId`   | `string \| null` | 会話ID                                                              |
| `actionAuditLogs[].projectId`        | `string \| null` | プロジェクトID。古い記録では null                                              |
| `actionAuditLogs[].messageId`        | `string \| null` | メッセージID                                                           |
| `actionAuditLogs[].requestId`        | `string \| null` | リクエストID                                                           |
| `actionAuditLogs[].systemVersion`    | `string \| null` | システムバージョン                                                         |
| `total`                              | `integer`        | 総件数                                                               |
| `limit`                              | `integer`        | 取得件数                                                              |
| `page`                               | `integer`        | ページ番号                                                             |
| `hasMore`                            | `boolean`        | 次ページが存在するか                                                        |

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

```json
{
  "actionAuditLogs": [
    {
      "actionAuditLogId": "1203344",
      "occurredAt": "2026-11-10T03:00:12.456Z",
      "source": "front",
      "eventType": "agent.copied",
      "actorType": "human",
      "actorKind": "human",
      "actorRef": "41b9fcf1-958d-4a86-a863-804b69224a1d",
      "onBehalfOfRef": null,
      "resource": "agent:9c8b7a6f-5e4d-4c3b-8a2f-1e0d9c8b7a6f",
      "action": null,
      "decision": "copied",
      "reason": null,
      "policyId": null,
      "policyVersion": null,
      "executionId": null,
      "rootExecutionId": null,
      "conversationId": null,
      "projectId": null,
      "messageId": null,
      "requestId": null,
      "systemVersion": "3.4.0"
    }
  ],
  "total": 128,
  "limit": 1,
  "page": 1,
  "hasMore": true
}
```

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

| ステータス | 説明                                                                                                               |
| ----- | ---------------------------------------------------------------------------------------------------------------- |
| `400` | limit・page・from・to・order が不正、絞り込みの値が空白だけ・前後に空白がある・2 つ以上、または project\_id が UUID ではない（`code: "invalid_parameter"`） |
| `403` | logs:read スコープが不足（`code: "insufficient_scope"`）                                                                  |

### GET`/v1/admin/llm-logs`

LLMログ一覧を取得します。既定はタイムスタンプの降順です（order で昇順にできます）。

#### 絞り込みのクエリパラメータ

| パラメータ             | 型        | 必須 | 説明                                  |
| ----------------- | -------- | -- | ----------------------------------- |
| `conversation_id` | `string` | —  | 会話 ID（conversationId）の完全一致          |
| `service`         | `string` | —  | サービス（service）の完全一致                  |
| `operation`       | `string` | —  | 操作（operation）の完全一致                  |
| `success`         | `string` | —  | "true"（成功）または "false"（失敗）。ほかの値は 400 |

#### リクエスト例

**List LLM logs**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-logs?limit=10" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-logs",
  headers={"Authorization": f"Bearer {token}"},
  params={"limit": 10},
)
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-logs?limit=10",
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-logs?limit=10",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
```

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

| フィールド                         | 型                 | 説明                                                                                                                          |
| ----------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `llmLogs`                     | `array`           | LLMログオブジェクトの配列                                                                                                              |
| `llmLogs[].llmLogId`          | `string`          | LLMログID                                                                                                                     |
| `llmLogs[].timestamp`         | `string \| null`  | タイムスタンプ                                                                                                                     |
| `llmLogs[].service`           | `string \| null`  | サービス名                                                                                                                       |
| `llmLogs[].operation`         | `string \| null`  | オペレーション名                                                                                                                    |
| `llmLogs[].durationMs`        | `number \| null`  | 処理時間（ミリ秒）                                                                                                                   |
| `llmLogs[].conversationId`    | `string \| null`  | 会話ID                                                                                                                        |
| `llmLogs[].intentType`        | `string \| null`  | 意図タイプ                                                                                                                       |
| `llmLogs[].confidenceScore`   | `number \| null`  | 信頼度スコア                                                                                                                      |
| `llmLogs[].toolsUsed`         | `number \| null`  | ツール呼び出し回数（ツール名の一覧でも、使ったツールの種類数でもない。同じツールを 5 回呼べば 5）。`null` は未計測、`0` は計測した上で一度も呼ばなかった実行。両者は区別されるため、`0` を `null` と同一視しないでください |
| `llmLogs[].success`           | `boolean \| null` | 成功/失敗                                                                                                                       |
| `llmLogs[].agentType`         | `string \| null`  | エージェントタイプ                                                                                                                   |
| `llmLogs[].agentLevel`        | `string \| null`  | エージェントレベル                                                                                                                   |
| `llmLogs[].taskComplexity`    | `string \| null`  | タスクの複雑度                                                                                                                     |
| `llmLogs[].currentMessage`    | `string \| null`  | 現在のメッセージ                                                                                                                    |
| `llmLogs[].contextSummary`    | `string \| null`  | コンテキスト要約                                                                                                                    |
| `llmLogs[].suggestedApproach` | `string \| null`  | 提案された進め方                                                                                                                    |
| `llmLogs[].conversationGoal`  | `string \| null`  | 会話のゴール                                                                                                                      |
| `llmLogs[].finalContent`      | `string \| null`  | 最終出力内容                                                                                                                      |
| `llmLogs[].metadata`          | `object \| null`  | オペレーションごとに異なる付随メタデータ（キーは可変）                                                                                                 |
| `llmLogs[].createdAt`         | `string \| null`  | 作成日時                                                                                                                        |
| `total`                       | `integer`         | 総件数                                                                                                                         |
| `limit`                       | `integer`         | 取得件数                                                                                                                        |
| `page`                        | `integer`         | ページ番号                                                                                                                       |
| `hasMore`                     | `boolean`         | 次ページが存在するか                                                                                                                  |

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

```json
{
  "llmLogs": [
    {
      "llmLogId": "33098",
      "timestamp": "2026-04-19T04:12:51.102Z",
      "service": "agent-executor",
      "operation": "agent.intent.completed",
      "durationMs": 5574.6,
      "conversationId": "3b72544d-d6b5-4577-b5f3-c39293124a57",
      "intentType": "complex_task",
      "confidenceScore": 0.95,
      "toolsUsed": null,
      "success": null,
      "agentType": "intent",
      "agentLevel": "default",
      "taskComplexity": null,
      "currentMessage": "このURLについて教えて https://example.com/path",
      "contextSummary": "ユーザーがURLについての情報を求めている。",
      "suggestedApproach": "execute_single_tool",
      "conversationGoal": "指定されたURLの内容や目的についての情報",
      "finalContent": null,
      "metadata": {
        "message.id": "02038f42-154b-4363-9beb-d31512934ec5",
        "task.complexity": "moderate",
        "detected_language": "ja",
        "requires_planning": true
      },
      "createdAt": "2026-04-18T19:16:16.964Z"
    },
    {
      "llmLogId": "33097",
      "timestamp": "2026-04-19T04:12:48.730Z",
      "service": "agent-executor",
      "operation": "agent.guardrail.completed",
      "durationMs": 3170.34,
      "conversationId": "3b72544d-d6b5-4577-b5f3-c39293124a57",
      "intentType": null,
      "confidenceScore": null,
      "toolsUsed": null,
      "success": null,
      "agentType": "intent.guardrails",
      "agentLevel": null,
      "taskComplexity": null,
      "currentMessage": null,
      "contextSummary": null,
      "suggestedApproach": null,
      "conversationGoal": null,
      "finalContent": null,
      "metadata": { "guardrail_detected": false },
      "createdAt": "2026-04-18T19:16:14.619Z"
    },
    {
      "llmLogId": "33096",
      "timestamp": "2026-04-19T04:12:33.662Z",
      "service": "agent-executor",
      "operation": "agent.intent.completed",
      "durationMs": 4213.47,
      "conversationId": "4d7c798d-2e3e-4d40-86ab-cbb6c685a3fb",
      "intentType": "conversation",
      "confidenceScore": 1,
      "toolsUsed": null,
      "success": null,
      "agentType": "intent",
      "agentLevel": "default",
      "taskComplexity": null,
      "currentMessage": "こんにちは",
      "contextSummary": "新規会話開始。ユーザーが挨拶",
      "suggestedApproach": "conversational_response",
      "conversationGoal": "AIアシスタントとの挨拶交流",
      "finalContent": null,
      "metadata": {
        "message.id": "cea9dbcc-4723-452a-bdcd-aa5f3a0e9ca6",
        "task.complexity": "simple",
        "detected_language": "ja",
        "requires_planning": false
      },
      "createdAt": "2026-04-18T19:15:59.681Z"
    }
  ],
  "total": 33098,
  "limit": 3,
  "page": 1,
  "hasMore": true
}
```

### GET`/v1/admin/llm-gateway-logs`

LLM Gateway ログ一覧を取得します。既定は作成日時の降順です（order で昇順にできます）。1 リクエスト = 1 行で、モデル・プロバイダ・トークン・コスト・レイテンシ等の利用状況を記録します。

#### 絞り込みのクエリパラメータ

| パラメータ        | 型        | 必須 | 説明                                             |
| ------------ | -------- | -- | ---------------------------------------------- |
| `provider`   | `string` | —  | プロバイダ（provider）の完全一致                           |
| `model_name` | `string` | —  | モデル名の完全一致（modelName が無い行は resolvedModel で比べます） |
| `success`    | `string` | —  | "true"（成功）または "false"（失敗）。ほかの値は 400            |

#### リクエスト例

**List LLM gateway logs**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-gateway-logs?limit=10" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-gateway-logs",
  headers={"Authorization": f"Bearer {token}"},
  params={"limit": 10},
)
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-gateway-logs?limit=10",
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-gateway-logs?limit=10",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
```

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

| フィールド                                      | 型                        | 説明                      |
| ------------------------------------------ | ------------------------ | ----------------------- |
| llmGatewayLogs                             | array                    | LLM Gateway ログオブジェクトの配列 |
| llmGatewayLogs\[].llmGatewayLogId          | string                   | LLM Gateway ログID        |
| llmGatewayLogs\[].createdAt                | string \| null           | 作成日時                    |
| llmGatewayLogs\[].virtualKeyId             | string \| null           | 仮想キーID（呼び出し元クライアント）     |
| llmGatewayLogs\[].clientSessionId          | string \| null           | クライアントセッションID           |
| llmGatewayLogs\[].clientAgentId            | string \| null           | クライアントエージェントID          |
| llmGatewayLogs\[].apiFlavor                | string \| null           | API フレーバー               |
| llmGatewayLogs\[].modelName                | string \| null           | モデル名（リクエスト指定）           |
| llmGatewayLogs\[].resolvedModel            | string \| null           | 解決後モデル名                 |
| llmGatewayLogs\[].provider                 | string \| null           | プロバイダ                   |
| llmGatewayLogs\[].deployment               | string \| null           | デプロイメント                 |
| llmGatewayLogs\[].tier                     | string \| null           | ティア                     |
| llmGatewayLogs\[].stream                   | boolean \| null          | ストリーミング有無               |
| llmGatewayLogs\[].success                  | boolean \| null          | 成功/失敗                   |
| llmGatewayLogs\[].httpStatus               | number \| null           | HTTP ステータス              |
| llmGatewayLogs\[].errorType                | string \| null           | エラータイプ                  |
| llmGatewayLogs\[].errorCode                | string \| null           | エラーコード                  |
| llmGatewayLogs\[].usageStatus              | string \| null           | 使用量ステータス                |
| llmGatewayLogs\[].latencyMs                | number \| null           | レイテンシ（ミリ秒）              |
| llmGatewayLogs\[].inputTokens              | number \| null           | 入力トークン数                 |
| llmGatewayLogs\[].outputTokens             | number \| null           | 出力トークン数                 |
| llmGatewayLogs\[].totalTokens              | number \| null           | 合計トークン数                 |
| llmGatewayLogs\[].cachedTokens             | number \| null           | キャッシュトークン数              |
| llmGatewayLogs\[].cacheCreationInputTokens | number \| null           | キャッシュ作成入力トークン数          |
| llmGatewayLogs\[].reasoningTokens          | number \| null           | 推論トークン数                 |
| llmGatewayLogs\[].costUsd                  | number \| string \| null | コスト（USD）                |
| llmGatewayLogs\[].currency                 | string \| null           | 通貨                      |
| llmGatewayLogs\[].metadata                 | object \| null           | 付随メタデータ（キーは可変）          |
| total                                      | integer                  | 総件数                     |
| limit                                      | integer                  | 取得件数                    |
| page                                       | integer                  | ページ番号                   |
| hasMore                                    | boolean                  | 次ページが存在するか              |

### GET`/v1/admin/llm-gateway-action-logs`

LLM Gateway 操作監査の一覧を取得します。LLM Gateway 経由で実行された操作の記録で、LLM Gateway を使っていなければ記録はありません。既定は発生日時の降順です（order で昇順にできます）。画面の「リクエストID」・「詳細ダイジェスト」・「行ハッシュ」・「メタデータ」は返しません。

#### 絞り込みのクエリパラメータ

| パラメータ            | 型        | 必須 | 説明                                                                                                                                                       |
| ---------------- | -------- | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `event_type`     | `string` | —  | イベント種別（eventType）の完全一致（例: "auth.denied"・"guardrail.blocked"・"policy.pii\_blocked"・"policy.mcp\_stripped"・"limit.rpm\_exceeded"・"limit.budget\_exceeded"） |
| `decision`       | `string` | —  | 判定（decision）の完全一致（例: "allowed"・"denied"・"blocked"・"degraded"・"stripped"・"throttled"）                                                                     |
| `api_flavor`     | `string` | —  | API フレーバー（apiFlavor）の完全一致（例: "chat"・"responses"・"messages"・"embeddings"）                                                                                 |
| `virtual_key_id` | `string` | —  | 仮想キーID（virtualKeyId）の完全一致                                                                                                                                |

値は縛らず、知らない値は該当なしになります。空の値は絞り込みません。空白だけの値・前後に空白がある値・2 つ以上の指定は 400 です。

#### リクエスト例

**List LLM gateway action logs**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-gateway-action-logs?limit=10&event_type=guardrail.blocked" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-gateway-action-logs",
  headers={"Authorization": f"Bearer {token}"},
  params={"limit": 10, "event_type": "guardrail.blocked"},
)
```

**TypeScript**

```typescript
const params = new URLSearchParams({ limit: "10", event_type: "guardrail.blocked" });
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-gateway-action-logs?" + params,
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-gateway-action-logs?limit=10&event_type=guardrail.blocked",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
```

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

| フィールド                                          | 型                | 説明                        |
| ---------------------------------------------- | ---------------- | ------------------------- |
| `llmGatewayActionLogs`                         | `array`          | LLM Gateway 操作監査オブジェクトの配列 |
| `llmGatewayActionLogs[].llmGatewayActionLogId` | `string`         | LLM Gateway 操作監査ID        |
| `llmGatewayActionLogs[].occurredAt`            | `string \| null` | 発生日時（ISO 8601形式）          |
| `llmGatewayActionLogs[].virtualKeyId`          | `string \| null` | 仮想キーID（呼び出し元クライアント）       |
| `llmGatewayActionLogs[].externalRequestId`     | `string \| null` | 外部リクエストID                 |
| `llmGatewayActionLogs[].apiFlavor`             | `string \| null` | API フレーバー                 |
| `llmGatewayActionLogs[].eventType`             | `string \| null` | イベント種別                    |
| `llmGatewayActionLogs[].decision`              | `string \| null` | 判定                        |
| `llmGatewayActionLogs[].reason`                | `string \| null` | 理由コード                     |
| `llmGatewayActionLogs[].modelName`             | `string \| null` | モデル名（リクエスト指定）             |
| `llmGatewayActionLogs[].resolvedModel`         | `string \| null` | 解決後モデル名                   |
| `llmGatewayActionLogs[].systemVersion`         | `string \| null` | システムバージョン                 |
| `total`                                        | `integer`        | 総件数                       |
| `limit`                                        | `integer`        | 取得件数                      |
| `page`                                         | `integer`        | ページ番号                     |
| `hasMore`                                      | `boolean`        | 次ページが存在するか                |

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

```json
{
  "llmGatewayActionLogs": [
    {
      "llmGatewayActionLogId": "88412",
      "occurredAt": "2026-11-10T04:21:07.318Z",
      "virtualKeyId": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
      "externalRequestId": null,
      "apiFlavor": "chat",
      "eventType": "guardrail.blocked",
      "decision": "blocked",
      "reason": null,
      "modelName": "<モデル ID>",
      "resolvedModel": "<モデル ID>",
      "systemVersion": "3.4.0"
    }
  ],
  "total": 3,
  "limit": 10,
  "page": 1,
  "hasMore": false
}
```

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

| ステータス | 説明                                                                                      |
| ----- | --------------------------------------------------------------------------------------- |
| `400` | limit・page・from・to・order が不正、または絞り込みの値が空白だけ・前後に空白がある・2 つ以上（`code: "invalid_parameter"`） |
| `403` | logs:read スコープが不足（`code: "insufficient_scope"`）                                         |

### GET`/v1/admin/access-logs`

アクセスログ一覧を取得します。アクセスログは、外部への通信を許可・遮断した記録です。タイムスタンプの降順で返されます（order は指定できません）。

#### 絞り込みのクエリパラメータ

| パラメータ          | 型        | 必須 | 説明                                      |
| -------------- | -------- | -- | --------------------------------------- |
| `authz_result` | `string` | —  | "allowed"（許可）または "denied"（拒否）。ほかの値は 400 |

#### リクエスト例

**List access logs**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/access-logs?limit=10" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/access-logs",
  headers={"Authorization": f"Bearer {token}"},
  params={"limit": 10},
)
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/access-logs?limit=10",
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/access-logs?limit=10",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
```

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

| フィールド                          | 型                | 説明                                                     |
| ------------------------------ | ---------------- | ------------------------------------------------------ |
| `accessLogs`                   | `array`          | アクセスログオブジェクトの配列                                        |
| `accessLogs[].timestamp`       | `string`         | タイムスタンプ                                                |
| `accessLogs[].sourceNamespace` | `string \| null` | ソース名前空間                                                |
| `accessLogs[].sourceIp`        | `string \| null` | ソースIPアドレス                                              |
| `accessLogs[].method`          | `string \| null` | HTTPメソッド                                               |
| `accessLogs[].host`            | `string \| null` | ホスト名                                                   |
| `accessLogs[].path`            | `string \| null` | リクエストパス                                                |
| `accessLogs[].userAgent`       | `string \| null` | User-Agent                                             |
| `accessLogs[].statusCode`      | `number \| null` | HTTPステータスコード                                           |
| `accessLogs[].durationMs`      | `number \| null` | 処理時間（ミリ秒）                                              |
| `accessLogs[].authzResult`     | `string \| null` | 認可結果                                                   |
| `accessLogs[].authzReason`     | `string \| null` | 認可理由                                                   |
| `total`                        | `integer`        | 総件数                                                    |
| `limit`                        | `integer`        | 取得件数                                                   |
| `page`                         | `integer`        | ページ番号                                                  |
| `hasMore`                      | `boolean`        | 次ページが存在するか                                             |
| `skippedCount`                 | `integer`        | このページで読めなかったログの行の数（accessLogs には入りません。total はこの行も数えます） |

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

```json
{
  "accessLogs": [
    {
      "timestamp": "2026-04-19T05:17:36.735896",
      "sourceNamespace": "autonomous-agent",
      "sourceIp": "127.0.0.1",
      "method": "CONNECT",
      "host": "optimizationguide-pa.googleapis.com:443",
      "path": "",
      "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36",
      "statusCode": 200,
      "durationMs": 1,
      "authzResult": "allowed",
      "authzReason": "allowed:  All allow"
    },
    {
      "timestamp": "2026-04-19T03:50:36.766451",
      "sourceNamespace": "autonomous-agent",
      "sourceIp": "127.0.0.1",
      "method": "CONNECT",
      "host": "update.googleapis.com:443",
      "path": "",
      "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36",
      "statusCode": 200,
      "durationMs": 6,
      "authzResult": "allowed",
      "authzReason": "allowed:  All allow"
    },
    {
      "timestamp": "2026-04-19T03:45:48.481023",
      "sourceNamespace": "autonomous-agent",
      "sourceIp": "127.0.0.1",
      "method": "CONNECT",
      "host": "optimizationguide-pa.googleapis.com:443",
      "path": "",
      "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36",
      "statusCode": 200,
      "durationMs": 0,
      "authzResult": "allowed",
      "authzReason": "allowed:  All allow"
    }
  ],
  "total": 57806,
  "limit": 3,
  "page": 1,
  "hasMore": true,
  "skippedCount": 0
}
```

### GET`/v1/admin/guardrail-alerts`

ガードレールアラート一覧を取得します。既定は検知日時の降順です（order で昇順にできます）。

#### 絞り込みのクエリパラメータ

| パラメータ                 | 型        | 必須 | 説明                                                                                                                                                                               |
| --------------------- | -------- | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`              | `string` | —  | "open" / "investigating" / "escalated" / "closed" / "false\_positive"                                                                                                            |
| `source_surface`      | `string` | —  | "agent\_executor" / "llm\_gateway" / "agent\_worker"                                                                                                                             |
| `resolution_code`     | `string` | —  | "policy\_violation\_confirmed" / "no\_action\_required" / "escalated\_externally" / "detection\_error" / "benign\_context" / "test\_or\_synthetic" / "insufficient\_information" |
| `detection_type`      | `string` | —  | 検知の種類（detectionTypes の値。例: "jailbreak\_attack"・"harmful\_content"）                                                                                                               |
| `moderation_category` | `string` | —  | 有害表現のカテゴリ（moderationCategories のキー。例: "Hate"・"Violence"・"Sexual"）                                                                                                                |
| `shield_origin`       | `string` | —  | "userPrompt" / "documents" / "both" / "unknown"                                                                                                                                  |
| `policy_category`     | `string` | —  | 攻撃方式の分類（policyCategory の値）                                                                                                                                                       |

status・source\_surface・resolution\_code・shield\_origin に上の値以外を指定すると 400 です。detection\_type・moderation\_category・policy\_category は値を縛らず、知らない値は該当なしになります。

Prompt Shield（プロンプトインジェクション・ジェイルブレイク）と Text Moderation（有害表現）で検知し、実行を停止した記録です。検知面（`sourceSurface`）は AI エージェント実行時（`agent_executor`）と LLM Gateway 経由（`llm_gateway`）の 2 種類があります。

#### リクエスト例

**List guardrail alerts**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/guardrail-alerts?limit=10&from=2026-08-01&to=2026-08-15" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/guardrail-alerts",
  headers={"Authorization": f"Bearer {token}"},
  params={"limit": 10, "from": "2026-08-01", "to": "2026-08-15"},
)
```

**TypeScript**

```typescript
const params = new URLSearchParams({ limit: "10", from: "2026-08-01", to: "2026-08-15" });
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/guardrail-alerts?" + params,
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/guardrail-alerts?limit=10&from=2026-08-01&to=2026-08-15",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
```

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

| フィールド                                    | 型                 | 説明                                                                                                |
| ---------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------- |
| `guardrailAlerts`                        | `array`           | ガードレールアラートオブジェクトの配列                                                                               |
| `guardrailAlerts[].guardrailAlertId`     | `string`          | ガードレールアラートID                                                                                      |
| `guardrailAlerts[].detectedAt`           | `string`          | 検知日時（ISO 8601形式）                                                                                  |
| `guardrailAlerts[].sourceSurface`        | `string`          | 検知面（agent\_executor: AIエージェント実行時 / llm\_gateway: LLM Gateway経由 / agent\_worker: 会話 Pod の中）        |
| `guardrailAlerts[].detectionTypes`       | `array`           | 検知種別（jailbreak\_attack: プロンプトインジェクション / harmful\_content: 有害表現）                                   |
| `guardrailAlerts[].promptShieldOrigin`   | `object \| null`  | Prompt Shield の検知箇所。user\_prompt（利用者の入力）と document\_indexes（添付文書の位置）を持つ。文書の内容は含まれません              |
| `guardrailAlerts[].moderationCategories` | `object \| null`  | カテゴリ別の深刻度。Hate / Sexual / SelfHarm / Violence を 0・2・4・6 の4段階で表す                                   |
| `guardrailAlerts[].moderationThreshold`  | `integer \| null` | 判定に使用したしきい値                                                                                       |
| `guardrailAlerts[].policyOutcome`        | `string`          | 判定結果。現在は blocked（実行を停止）のみ                                                                         |
| `guardrailAlerts[].policyCategory`       | `string \| null`  | 攻撃方式の分類（例: prompt\_injection・system\_prompt\_extraction・credential\_request）。この分類を持たない検知では null   |
| `guardrailAlerts[].responseTemplateCode` | `string \| null`  | 利用者へ返した定型応答のコード                                                                                   |
| `guardrailAlerts[].status`               | `string`          | 対応状況（open: 未対応 / investigating: 調査中 / escalated: エスカレーション中 / closed: 対応済み / false\_positive: 誤検知） |
| `guardrailAlerts[].resolutionCode`       | `string \| null`  | 対応結果コード                                                                                           |
| `guardrailAlerts[].resolvedAt`           | `string \| null`  | 対応完了日時（ISO 8601形式）                                                                                |
| `guardrailAlerts[].resolvedBy`           | `string \| null`  | 対応を完了した管理者のユーザーID                                                                                 |
| `guardrailAlerts[].createdAt`            | `string`          | 作成日時（ISO 8601形式）                                                                                  |
| `guardrailAlerts[].updatedAt`            | `string`          | 更新日時（ISO 8601形式）                                                                                  |
| `total`                                  | `integer`         | 総件数                                                                                               |
| `limit`                                  | `integer`         | 取得件数                                                                                              |
| `page`                                   | `integer`         | ページ番号                                                                                             |
| `hasMore`                                | `boolean`         | 次ページが存在するか                                                                                        |

> **検知された利用者の情報について**
>
> 本APIは、検知された利用者を特定する情報（利用者ID・会話ID・メッセージID）を返しません。ガードレールの品質確認と安全対応の状況把握を目的としたAPIであり、利用者個人の行動追跡には使用できません。
>
> また、`SelfHarm`（自傷）のみを検知した事象はアラートとして記録されません。

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

```json
{
  "guardrailAlerts": [
    {
      "guardrailAlertId": "1f2e3d4c-5b6a-4789-8c9d-0e1f2a3b4c5d",
      "detectedAt": "2026-08-13T02:10:00.000Z",
      "sourceSurface": "agent_executor",
      "detectionTypes": ["harmful_content"],
      "promptShieldOrigin": null,
      "moderationCategories": {
        "Hate": 4,
        "Sexual": 0,
        "SelfHarm": 0,
        "Violence": 0
      },
      "moderationThreshold": 2,
      "policyOutcome": "blocked",
      "responseTemplateCode": null,
      "status": "open",
      "resolutionCode": null,
      "resolvedAt": null,
      "resolvedBy": null,
      "createdAt": "2026-08-13T02:10:00.100Z",
      "updatedAt": "2026-08-13T02:10:00.100Z"
    },
    {
      "guardrailAlertId": "2a3b4c5d-6e7f-4890-9a1b-2c3d4e5f6a7b",
      "detectedAt": "2026-08-12T09:32:11.000Z",
      "sourceSurface": "llm_gateway",
      "detectionTypes": ["jailbreak_attack"],
      "promptShieldOrigin": {
        "user_prompt": true,
        "document_indexes": []
      },
      "moderationCategories": null,
      "moderationThreshold": null,
      "policyOutcome": "blocked",
      "responseTemplateCode": null,
      "status": "closed",
      "resolutionCode": "policy_violation_confirmed",
      "resolvedAt": "2026-08-12T11:05:00.000Z",
      "resolvedBy": "8f14e45f-ceea-4d3c-9b2a-1a2b3c4d5e6f",
      "createdAt": "2026-08-12T09:32:11.050Z",
      "updatedAt": "2026-08-12T11:05:00.000Z"
    }
  ],
  "total": 14,
  "limit": 2,
  "page": 1,
  "hasMore": true
}
```

## マスターデータ管理 SaaS

組織・職種の CRUD 操作を行います。読み取り専用のマスターデータ取得（`/v1/organizations`、`/v1/job-types`）とは異なり、作成・更新・削除には `master:manage` スコープが必要です。

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

| メソッド   | エンドポイント                               | 説明      | スコープ            |
| ------ | ------------------------------------- | ------- | --------------- |
| GET    | `/v1/admin/organizations`             | 組織一覧を取得 | `master:manage` |
| POST   | `/v1/admin/organizations`             | 組織を作成   | `master:manage` |
| GET    | `/v1/admin/organizations/:identifier` | 組織詳細を取得 | `master:manage` |
| PATCH  | `/v1/admin/organizations/:identifier` | 組織を更新   | `master:manage` |
| DELETE | `/v1/admin/organizations/:identifier` | 組織を削除   | `master:manage` |
| GET    | `/v1/admin/job-types`                 | 職種一覧を取得 | `master:manage` |
| POST   | `/v1/admin/job-types`                 | 職種を作成   | `master:manage` |
| GET    | `/v1/admin/job-types/:identifier`     | 職種詳細を取得 | `master:manage` |
| PATCH  | `/v1/admin/job-types/:identifier`     | 職種を更新   | `master:manage` |
| DELETE | `/v1/admin/job-types/:identifier`     | 職種を削除   | `master:manage` |

### GET`/v1/admin/organizations`

組織一覧を取得します。全件取得（ページネーションなし）です。

#### リクエスト例

**List organizations (admin)**

**curl**

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

**Python**

```python
import requests

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

data = response.json()
for org in data["organizations"]:
  print(f"{org['code']}: {org['name']}")
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations",
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);

const data = await response.json();
data.organizations.forEach((org) => {
console.log(org.code + ": " + org.name);
});
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/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[].code`         | `string`  | 組織コード              |
| `organizations[].name`         | `string`  | 組織名                |
| `organizations[].displayOrder` | `integer` | 表示順                |
| `organizations[].isActive`     | `boolean` | 有効/無効              |
| `organizations[].createdAt`    | `string`  | 作成日時               |
| `organizations[].updatedAt`    | `string`  | 更新日時               |
| `hasMore`                      | `boolean` | いつも false（全件を返します） |

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

```json
{
  "organizations": [
    {
      "code": "sample_org",
      "name": "組織（サンプル）",
      "displayOrder": 0,
      "isActive": true,
      "createdAt": "2025-12-12T10:40:45.220Z",
      "updatedAt": "2026-04-13T01:21:57.695Z"
    },
    {
      "code": "sales",
      "name": "営業統括部",
      "displayOrder": 1,
      "isActive": true,
      "createdAt": "2025-12-24T19:26:37.000Z",
      "updatedAt": "2025-12-24T19:26:37.000Z"
    },
    {
      "code": "engineering",
      "name": "エンジニアリング統括部",
      "displayOrder": 2,
      "isActive": true,
      "createdAt": "2025-12-24T19:26:37.000Z",
      "updatedAt": "2025-12-24T19:26:37.000Z"
    },
    {
      "code": "other",
      "name": "その他",
      "displayOrder": -1,
      "isActive": false,
      "createdAt": "2025-12-24T19:26:38.000Z",
      "updatedAt": "2026-01-17T19:08:21.630Z"
    }
  ],
  "hasMore": false
}
```

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

| ステータス | 説明                    |
| ----- | --------------------- |
| `403` | master:manage スコープが不足 |

### POST`/v1/admin/organizations`

組織を作成します。

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

| パラメータ          | 型         | 必須 | 説明                                                                                        |
| -------------- | --------- | -- | ----------------------------------------------------------------------------------------- |
| `code`         | `string`  | 必須 | 組織コード（一意）。英小文字・数字・アンダースコア（\`\_\`）だけで、255 文字まで。前後の空白は除かれます                                 |
| `name`         | `string`  | 必須 | 組織名（255 文字まで）                                                                             |
| `displayOrder` | `integer` | —  | 表示順。省略した場合は、表示順が正の項目のいちばん大きい値に 1 を足した値になります（\`code\` が \`other\` のときは -1 で、いちばん後ろに表示されます） |
| `isActive`     | `boolean` | —  | 有効/無効（デフォルト: true）                                                                        |

#### リクエスト例

**Create organization**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "code": "marketing",
  "name": "マーケティング統括部",
  "displayOrder": 3,
  "isActive": true
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations",
  headers={"Authorization": f"Bearer {token}"},
  json={'code': 'marketing', 'name': 'マーケティング統括部', 'displayOrder': 3, 'isActive': True},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"code": "marketing", "name": "マーケティング統括部", "displayOrder": 3, "isActive": true}),
}
);

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

**Go**

```go
payload := []byte(`{"code": "marketing", "name": "マーケティング統括部", "displayOrder": 3, "isActive": true}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations", 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）

```json
{
  "code": "marketing",
  "name": "マーケティング統括部",
  "displayOrder": 3,
  "isActive": true,
  "createdAt": "2026-04-19T02:15:32.000Z",
  "updatedAt": "2026-04-19T02:15:32.000Z"
}
```

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

| ステータス | 説明                                                                                                                                                                                                                   |
| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | リクエストボディが不正（`code` / `name` 未指定、`code`・`name` が文字列ではない、`isActive` が真偽値ではない、`displayOrder` が整数ではない、`code` に英小文字・数字・アンダースコア以外が含まれる、`code`・`name` が 255 文字を超える、ボディが壊れた JSON・JSON のオブジェクトではない（`code: "invalid_body"`）など） |
| `415` | ボディの Content-Type が application/json ではない（`code: "unsupported_media_type"`）                                                                                                                                          |
| `403` | master:manage スコープが不足                                                                                                                                                                                                |
| `409` | 同じ `code` を持つ組織が既に存在する                                                                                                                                                                                               |

### GET`/v1/admin/organizations/:identifier`

組織の詳細を取得します。UUID または組織コードで指定できます。

#### パスパラメータ

| パラメータ        | 型        | 必須 | 説明              |
| ------------ | -------- | -- | --------------- |
| `identifier` | `string` | 必須 | 組織のUUIDまたは組織コード |

#### リクエスト例

**Get organization**

**curl**

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

**Python**

```python
import requests

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

**TypeScript**

```typescript
const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/${identifier}`,
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/"+identifier,
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
```

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

```json
{
  "code": "sales",
  "name": "営業統括部",
  "displayOrder": 1,
  "isActive": true,
  "createdAt": "2025-12-24T19:26:37.000Z",
  "updatedAt": "2025-12-24T19:26:37.000Z"
}
```

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

| ステータス | 説明                    |
| ----- | --------------------- |
| `403` | master:manage スコープが不足 |
| `404` | 指定された組織が見つからない        |

### PATCH`/v1/admin/organizations/:identifier`

組織を更新します。更新可能なフィールドは name と isActive のみです。

#### パスパラメータ

| パラメータ        | 型        | 必須 | 説明              |
| ------------ | -------- | -- | --------------- |
| `identifier` | `string` | 必須 | 組織のUUIDまたは組織コード |

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

| パラメータ      | 型         | 必須 | 説明    |
| ---------- | --------- | -- | ----- |
| `name`     | `string`  | —  | 組織名   |
| `isActive` | `boolean` | —  | 有効/無効 |

#### リクエスト例

**Update organization**

**curl**

```curl
curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/sales \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "name": "営業統括部",
  "isActive": true
}'
```

**Python**

```python
import requests

response = requests.patch(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/sales",
  headers={"Authorization": f"Bearer {token}"},
  json={'name': '営業統括部', 'isActive': True},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/sales",
{
  method: "PATCH",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"name": "営業統括部", "isActive": true}),
}
);

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

**Go**

```go
payload := []byte(`{"name": "営業統括部", "isActive": true}`)
req, _ := http.NewRequest("PATCH", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/sales", 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
{
  "code": "sales",
  "name": "営業統括部",
  "displayOrder": 1,
  "isActive": true,
  "createdAt": "2025-12-24T19:26:37.000Z",
  "updatedAt": "2026-04-19T02:18:40.000Z"
}
```

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

| ステータス | 説明                                                                                                                                                                                          |
| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | リクエストボディが不正（`name` が 255 文字超過、`name` / `isActive` のどちらも未指定、`name` が文字列ではない・`isActive` が真偽値ではない、ボディが壊れた JSON・JSON のオブジェクトではない（`code: "invalid_body"`）など）。`name` / `isActive` 以外のフィールドは無視されます |
| `415` | ボディの Content-Type が application/json ではない（`code: "unsupported_media_type"`）                                                                                                                 |
| `403` | master:manage スコープが不足                                                                                                                                                                       |
| `404` | 指定された組織が見つからない                                                                                                                                                                              |

### DELETE`/v1/admin/organizations/:identifier`

組織を削除します。

#### パスパラメータ

| パラメータ        | 型        | 必須 | 説明              |
| ------------ | -------- | -- | --------------- |
| `identifier` | `string` | 必須 | 組織のUUIDまたは組織コード |

#### リクエスト例

**Delete organization**

**curl**

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

**Python**

```python
import requests

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

**TypeScript**

```typescript
const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/${identifier}`,
{
  method: "DELETE",
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("DELETE",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/"+identifier,
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
```

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

```json
{ "code": "sales", "deleted": true }
```

| フィールド     | 型         | 説明                                       |
| --------- | --------- | ---------------------------------------- |
| `code`    | `string`  | 削除した組織コード（パスパラメータの `identifier` をそのまま返す） |
| `deleted` | `boolean` | 常に `true`                                |

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

| ステータス | 説明                    |
| ----- | --------------------- |
| `403` | master:manage スコープが不足 |
| `404` | 指定された組織が見つからない        |

### GET`/v1/admin/job-types`

職種一覧を取得します。全件取得（ページネーションなし）です。レスポンスフィールドは組織一覧と同一構造です（organizations → jobTypes、組織コード → 職種コード）。

#### リクエスト例

**List job types**

**curl**

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

**Python**

```python
import requests

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

print(response.json())
```

**TypeScript**

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

| フィールド                     | 型         | 説明                 |
| ------------------------- | --------- | ------------------ |
| `jobTypes`                | `array`   | 職種オブジェクトの配列        |
| `jobTypes[].code`         | `string`  | 職種コード              |
| `jobTypes[].name`         | `string`  | 職種名                |
| `jobTypes[].displayOrder` | `integer` | 表示順                |
| `jobTypes[].isActive`     | `boolean` | 有効/無効              |
| `jobTypes[].createdAt`    | `string`  | 作成日時               |
| `jobTypes[].updatedAt`    | `string`  | 更新日時               |
| `hasMore`                 | `boolean` | いつも false（全件を返します） |

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

```json
{
  "jobTypes": [
    {
      "code": "engineer",
      "name": "エンジニア",
      "displayOrder": 1,
      "isActive": true,
      "createdAt": "2025-12-24T19:26:37.000Z",
      "updatedAt": "2025-12-24T19:26:37.000Z"
    },
    {
      "code": "sales",
      "name": "営業",
      "displayOrder": 2,
      "isActive": true,
      "createdAt": "2025-12-24T19:26:37.000Z",
      "updatedAt": "2025-12-24T19:26:37.000Z"
    },
    {
      "code": "other",
      "name": "その他",
      "displayOrder": -1,
      "isActive": false,
      "createdAt": "2025-12-24T19:26:38.000Z",
      "updatedAt": "2026-01-17T19:08:21.630Z"
    }
  ],
  "hasMore": false
}
```

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

| ステータス | 説明                    |
| ----- | --------------------- |
| `403` | master:manage スコープが不足 |

### POST`/v1/admin/job-types`

職種を作成します。リクエストボディは組織作成と同一構造です。

#### リクエスト例

**Create job type**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "code": "manager",
  "name": "管理職",
  "displayOrder": 3,
  "isActive": true
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types",
  headers={"Authorization": f"Bearer {token}"},
  json={'code': 'manager', 'name': '管理職', 'displayOrder': 3, 'isActive': True},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"code": "manager", "name": "管理職", "displayOrder": 3, "isActive": true}),
}
);

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

**Go**

```go
payload := []byte(`{"code": "manager", "name": "管理職", "displayOrder": 3, "isActive": true}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types", 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）

```json
{
  "code": "manager",
  "name": "管理職",
  "displayOrder": 3,
  "isActive": true,
  "createdAt": "2026-04-19T02:20:15.000Z",
  "updatedAt": "2026-04-19T02:20:15.000Z"
}
```

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

| ステータス | 説明                                                                                                                                                                                                                   |
| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | リクエストボディが不正（`code` / `name` 未指定、`code`・`name` が文字列ではない、`isActive` が真偽値ではない、`displayOrder` が整数ではない、`code` に英小文字・数字・アンダースコア以外が含まれる、`code`・`name` が 255 文字を超える、ボディが壊れた JSON・JSON のオブジェクトではない（`code: "invalid_body"`）など） |
| `415` | ボディの Content-Type が application/json ではない（`code: "unsupported_media_type"`）                                                                                                                                          |
| `403` | master:manage スコープが不足                                                                                                                                                                                                |
| `409` | 同じ `code` を持つ職種が既に存在する                                                                                                                                                                                               |

### GET`/v1/admin/job-types/:identifier`

職種の詳細を取得します。UUID または職種コードで指定できます。

#### パスパラメータ

| パラメータ        | 型        | 必須 | 説明              |
| ------------ | -------- | -- | --------------- |
| `identifier` | `string` | 必須 | 職種のUUIDまたは職種コード |

#### リクエスト例

**Get job type**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/engineer \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/{identifier}",
  headers={"Authorization": f"Bearer {token}"},
)
```

**TypeScript**

```typescript
const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/${identifier}`,
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/"+identifier,
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
```

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

```json
{
  "code": "engineer",
  "name": "エンジニア",
  "displayOrder": 1,
  "isActive": true,
  "createdAt": "2025-12-24T19:26:37.000Z",
  "updatedAt": "2025-12-24T19:26:37.000Z"
}
```

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

| ステータス | 説明                    |
| ----- | --------------------- |
| `403` | master:manage スコープが不足 |
| `404` | 指定された職種が見つからない        |

### PATCH`/v1/admin/job-types/:identifier`

職種を更新します。更新可能なフィールドは name と isActive のみです。

#### パスパラメータ

| パラメータ        | 型        | 必須 | 説明              |
| ------------ | -------- | -- | --------------- |
| `identifier` | `string` | 必須 | 職種のUUIDまたは職種コード |

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

| パラメータ      | 型         | 必須 | 説明    |
| ---------- | --------- | -- | ----- |
| `name`     | `string`  | —  | 職種名   |
| `isActive` | `boolean` | —  | 有効/無効 |

#### リクエスト例

**Update job type**

**curl**

```curl
curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/engineer \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{"name": "Senior Engineer", "isActive": true}'
```

**Python**

```python
import requests

response = requests.patch(
  f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/{identifier}",
  headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
  json={"name": "Senior Engineer", "isActive": True},
)
```

**TypeScript**

```typescript
const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/${identifier}`,
{
  method: "PATCH",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Senior Engineer", isActive: true }),
}
);
```

**Go**

```go
body, _ := json.Marshal(map[string]interface{}{"name": "Senior Engineer", "isActive": true})
req, _ := http.NewRequest("PATCH",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/"+identifier,
  bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
```

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

```json
{
  "code": "engineer",
  "name": "シニアエンジニア",
  "displayOrder": 1,
  "isActive": true,
  "createdAt": "2025-12-24T19:26:37.000Z",
  "updatedAt": "2026-04-19T02:22:55.000Z"
}
```

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

| ステータス | 説明                                                                                                                                                                                          |
| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | リクエストボディが不正（`name` が 255 文字超過、`name` / `isActive` のどちらも未指定、`name` が文字列ではない・`isActive` が真偽値ではない、ボディが壊れた JSON・JSON のオブジェクトではない（`code: "invalid_body"`）など）。`name` / `isActive` 以外のフィールドは無視されます |
| `415` | ボディの Content-Type が application/json ではない（`code: "unsupported_media_type"`）                                                                                                                 |
| `403` | master:manage スコープが不足                                                                                                                                                                       |
| `404` | 指定された職種が見つからない                                                                                                                                                                              |

### DELETE`/v1/admin/job-types/:identifier`

職種を削除します。レスポンス構造は組織削除と同一です。

#### パスパラメータ

| パラメータ        | 型        | 必須 | 説明              |
| ------------ | -------- | -- | --------------- |
| `identifier` | `string` | 必須 | 職種のUUIDまたは職種コード |

#### リクエスト例

**Delete job type**

**curl**

```curl
curl -X DELETE https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/engineer \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.delete(
  f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/{identifier}",
  headers={"Authorization": f"Bearer {token}"},
)
```

**TypeScript**

```typescript
const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/${identifier}`,
{
  method: "DELETE",
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("DELETE",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/"+identifier,
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
```

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

```json
{ "code": "engineer", "deleted": true }
```

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

| ステータス | 説明                    |
| ----- | --------------------- |
| `403` | master:manage スコープが不足 |
| `404` | 指定された職種が見つからない        |

## プロジェクト SaaS

ここでは、システム連携（Client Credentials フロー）のトークンで呼ぶときの仕様を説明します。アプリケーション（Authorization Code フロー）のトークンで呼ぶときは、[ユーザー API リファレンス（プロジェクト）](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference-projects.md)を参照してください。

プロジェクトは、複数のエージェントを配置して業務を進める単位です。外部システムから、プロジェクトの一覧取得・実行の開始・実行状況の確認<!-- -->ができます。

プロジェクトには 2 つの型があり、実行の起こし方が異なります。

| 型          | 説明                                                      | 実行の起こし方                                                   |
| ---------- | ------------------------------------------------------- | --------------------------------------------------------- |
| `workflow` | 工程を順に進める型。最初の有効な工程から実行を開始します。                           | `POST /v1/projects/{projectId}/runs`                      |
| `cycle`    | 複数のエージェントをそれぞれのスケジュールで動かし続ける型。外部イベントによる臨時の 1 回を上乗せできます。 | `POST /v1/projects/{projectId}/triggers/{triggerId}/fire` |

> **操作できる範囲**
>
> 操作できるプロジェクトは、Console で設定したプロジェクト制限の範囲に限られます（[Consoleガイド — プロジェクト制限の設定](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/console-guide.md#project-restriction)）。範囲外のプロジェクト ID を指定した場合は、存在しない場合と同じ `404 Not Found` が返ります。システム連携のトークンで呼べるプロジェクトの API は、ここにある 5 つのエンドポイントだけです。ほかのプロジェクトの API を呼ぶと `403 Forbidden`（`forbidden`）が返ります。

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

| メソッド | エンドポイント                                              | 説明                 | スコープ (SaaS)    |
| ---- | ---------------------------------------------------- | ------------------ | -------------- |
| GET  | `/v1/projects`                                       | プロジェクト一覧を取得        | `project:read` |
| POST | `/v1/projects/{projectId}/runs`                      | プロジェクトの実行を開始       | `project:run`  |
| POST | `/v1/projects/{projectId}/triggers/{triggerId}/fire` | トリガーを発火して臨時に 1 回実行 | `project:run`  |
| GET  | `/v1/projects/{projectId}/runs/{runId}`              | 実行状況を取得            | `project:read` |
| POST | `/v1/projects/{projectId}/runs/{runId}/cancel`       | ワークフローの実行を中断       | `project:run`  |

### GET`/v1/projects`

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

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

| パラメータ    | 型         | デフォルト | 説明                             |
| -------- | --------- | ----- | ------------------------------ |
| `limit`  | `integer` | `50`  | 取得件数（1〜100）                    |
| `cursor` | `string`  | `—`   | 次ページ取得用カーソル（前回レスポンスの 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`   | タグの配列。設定されていない場合は空の配列                                                      |
| `hasMore`              | `boolean` | 次のページが存在するかどうか                                                             |
| `cursor`               | `string`  | 次ページ取得用カーソル。hasMore が true の場合のみ含まれます                                      |

#### レスポンス例

<!-- -->

<!-- -->

```json
{
  "projects": [
    {
      "projectId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "受注処理フロー",
      "type": "workflow",
      "status": "active",
      "tags": []
    },
    {
      "projectId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "問い合わせ常時対応",
      "type": "cycle",
      "status": "active",
      "tags": []
    }
  ],
  "hasMore": false
}
```

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

| ステータス | 説明                                                                                              |
| ----- | ----------------------------------------------------------------------------------------------- |
| `400` | limit（1〜100 の範囲外）または cursor が不正（code は invalid\_parameter）                                      |
| `403` | project:read スコープが不足、またはプロジェクト制限が未設定・不正（code は insufficient\_scope または invalid\_project\_grant） |

### 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 スコープが不足                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `403` | `invalid_project_grant`           | プロジェクト制限が未設定、または設定内容が不正                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `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 件）に達している                                                                                                                                                                                                                                                                                                                                                                                                          |

### 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 スコープが不足                                                           |
| `403` | `invalid_project_grant`  | プロジェクト制限が未設定、または設定内容が不正                                                       |
| `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}/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                                                                                                                                                                                                                                         |
| `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` | 工程の出力の要約                                                                                                                                                                                                                                                                                                        |
| `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 スコープが不足                  |
| `403` | `invalid_project_grant` | プロジェクト制限が未設定、または設定内容が不正               |
| `404` | `run_not_found`         | 実行が存在しない、別のプロジェクトの実行を指定した、またはアクセス権が無い |

### 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` | `invalid_project_grant`  | プロジェクト制限が未設定、または設定内容が不正                                                          |
| `404` | `run_not_found`          | ワークフローの実行が存在しない、ほかのプロジェクトのもの、またはアクセス権の無いプロジェクト                                   |
| `413` | `body_too_large`         | ボディが 16 KiB を超える                                                                 |
| `415` | `unsupported_media_type` | ボディの Content-Type が application/json ではない                                        |

<!-- -->

<!-- -->

<!-- -->

### プロジェクト API の注意事項

| 項目             | 内容                                                                                                                                                                                                        |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 404 の意味        | プロジェクトが存在しない場合とアクセス権が無い場合は、どのエンドポイントでも同じ `404 Not Found` が返り、どちらであるかは応答から区別できません。code はエンドポイントごとに決まっていて、実行の開始は `project_not_found`、トリガーの発火は `trigger_not_found`、実行状況の取得とワークフローの実行の中断は `run_not_found` です。 |
| 型が対象外の場合       | 発火を `workflow` に対して呼んだ場合、および実行状況の取得とワークフローの実行の中断を `cycle` のプロジェクトに対して呼んだ場合は `404` です。実行の開始を `cycle` に対して呼んだ場合だけは例外で、`409 unsupported_project_type` が返ります。                                                 |
| リクエストボディ       | ボディを送る場合は、JSON オブジェクトにしてください。`Content-Type: application/json` 以外は `415`、壊れた JSON や JSON のオブジェクトではないボディは `400`（`invalid_body`）、16 KiB を超えるボディは `413` が返ります。                                                |
| 未知のフィールド / クエリ | 仕様に無いフィールドやクエリパラメータは無視されます。仕様にあるクエリパラメータの値が不正な場合と、読めない `cursor` を指定した場合は `400 Bad Request` が返ります。                                                                                                         |
| タイムアウト         | `504 Gateway Timeout` は「実行されなかったこと」を意味しません。実行の開始は同じ `Idempotency-Key` で、発火は同じ `eventId` と同じ本文で、ワークフローの実行の中断は同じ `commandId` で、そのまま再送してください。                                                                |

## エラーレスポンス

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

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

| ステータス                        | 説明                                |
| ---------------------------- | --------------------------------- |
| `400 Bad Request`            | リクエストパラメータが不正                     |
| `401 Unauthorized`           | トークンが無効または未指定                     |
| `403 Forbidden`              | リソースへのアクセス権限なし                    |
| `404 Not Found`              | リソースが存在しない                        |
| `409 Conflict`               | リソースが競合（例: 既存コードとの重複）             |
| `413 Payload Too Large`      | リクエストボディがサイズ上限を超過                 |
| `415 Unsupported Media Type` | リクエストボディの形式（Content-Type）に対応していない |
| `429 Too Many Requests`      | レート制限を超過                          |
| `500 Internal Server Error`  | サーバー内部エラー                         |
| `502 Bad Gateway`            | 上流サービスとの通信エラー                     |
| `503 Service Unavailable`    | サービス一時利用不可                        |
| `504 Gateway Timeout`        | 上流サービスの応答タイムアウト                   |

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

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

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

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

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

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"
  }
}
```

## 自動記録される管理操作 SaaS

以下の管理操作を実行すると、監査ログが自動的に記録されます。

| リソース | 操作                                                           | action    |
| ---- | ------------------------------------------------------------ | --------- |
| ユーザー | 作成                                                           | `create`  |
| ユーザー | ロール変更（管理者へ昇格）                                                | `promote` |
| ユーザー | ロール変更（一般へ降格）                                                 | `demote`  |
| ユーザー | 承認                                                           | `approve` |
| ユーザー | 承認取消                                                         | `reject`  |
| ユーザー | 削除                                                           | `delete`  |
| 組織   | 作成                                                           | `create`  |
| 組織   | 更新                                                           | `update`  |
| 組織   | 削除                                                           | `delete`  |
| 職種   | 作成                                                           | `create`  |
| 職種   | 更新                                                           | `update`  |
| 職種   | 削除                                                           | `delete`  |
| ユーザー | 利用の停止・再開・ロックの解除（`meta.action` は `suspend`・`resume`・`unlock`） | `update`  |
| ユーザー | 所属・職種の変更（`meta.action` は `update-affiliation`）               | `update`  |
