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

ユーザー管理、ログ閲覧、マスターデータ管理、共有メモリ検索、プロジェクト操作の API リファレンスです。エンドユーザー向けの Chat / Conversations / Files / Search / 公開マスターデータ API は ユーザー API リファレンス、MCP / A2A の接続方式は 接続方式ガイド を参照してください。

SaaS 版専用

本リファレンスに掲載しているエンドポイントはすべて SaaS 版でのみ提供 されます。Marketplace 版では管理操作は管理画面（Admin Console）からのみ実施可能です。

ベース URL

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

SaaS

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

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

認証

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

Authorization: Bearer <access_token>

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

トークンの取得方法・スコープの詳細については、認証ガイドおよび認証 API リファレンス（SaaS）を参照してください。

ページネーション

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

ページベース

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

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

curl

# 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>"

対応しているのは、ユーザー一覧とログ一覧（監査ログ・LLM ログ・LLM Gateway ログ・アクセスログ・ガードレールアラート）です。

カーソルベース

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

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

対応しているのはプロジェクト一覧です。page は使いません（指定しても無視されます）。

リクエストの扱い

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

• 仕様に無いクエリパラメータやボディのフィールドは無視されます。ただし、このページに載っていない項目でも、サービスが受け付けている項目は、型や値が正しくないと 400 Bad Request になることがあります。
• 仕様にあるクエリパラメータの値が不正な場合は 400 Bad Request が返ります。
• ボディが壊れた JSON の場合は 400 Bad Request（invalid_body）が返ります。
• JSON のボディを受け付けるエンドポイントに、Content-Type: application/json 以外のボディを送ると 415 Unsupported Media Type（unsupported_media_type）が返ります。ただし、ボディの読み取りで 400（壊れた JSON）や 413（サイズの上限を超えた）になる場合は、そちらが先に返ります。
• ボディのフィールドの型が違う場合は 400 Bad Request が返ります。
• レスポンスには x-request-id ヘッダーが付きます。サービス側で採番する値で、リクエストで送った値は使われません。お問い合わせの際はこの値をお知らせください。

共有メモリ 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

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

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

GET/v1/admin/users

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

クエリパラメータ

パラメータ	型	必須	説明
limit	integer	—	取得件数（1〜100、デフォルト: 25）
page	integer	—	ページ番号（1以上、デフォルト: 1）
role	string	—	ロールフィルター。"admin" を指定可能
is_approved	string	—	承認状態フィルター。"true" または "false"
search	string	—	検索文字列（最大100文字）。メールアドレス等で検索
organization	string	—	組織コードフィルター（最大50文字、英数字・ハイフン・アンダースコア）
job_type	string	—	職種コードフィルター（最大50文字、英数字・ハイフン・アンダースコア）

リクエスト例

List users

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

レスポンスフィールド（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"）
users[].organization	object?	所属組織（value: コード、label: 名称）。未設定時はフィールド自体が省略される
users[].jobType	object?	職種（value: コード、label: 名称）。未設定時はフィールド自体が省略される
users[].bio	string?	自己紹介。未設定時はフィールド自体が省略される
users[].createdAt	string	作成日時（ISO 8601形式）
users[].lastLoginAt	string?	最終ログイン日時（ISO 8601形式）。未ログイン時はフィールド自体が省略される
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"
    },
    {
      "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"
    },
    {
      "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"
    }
  ],
  "total": 132,
  "limit": 3,
  "page": 1,
  "hasMore": true
}

エラーレスポンス

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

DELETE/v1/admin/users/:userId

ユーザーを削除します。users:manage スコープが必要です。

パスパラメータ

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

リクエスト例

Delete user

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

レスポンス例（200 OK）

JSON

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

エラーレスポンス

ステータス	説明
403	users:manage スコープが不足
404	指定されたユーザーが見つからない（既に削除済みを含む）

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

ユーザーのロールを変更します。承認済み（approved）のユーザーのみ変更可能です。

ロール変更時の挙動

• user への降格時: 対象ユーザーの既存セッションが無効化され、再ログインが必要になります
• admin への昇格時: 対象ユーザーの既存セッションは継続され、新しい権限が次回 API 呼び出しから有効になります

パスパラメータ

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

リクエストボディ

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

リクエスト例

Change user role

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

レスポンス例（200 OK）

JSON

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

エラーレスポンス

ステータス	説明
400	role が未指定または不正、ボディが壊れた JSON（code: "invalid_body"）、または対象ユーザーが未承認
415	ボディの Content-Type が application/json ではない（code: "unsupported_media_type"）
403	users:manage スコープが不足
404	ユーザーが見つからない

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

ユーザーを承認します。ステータスが pending のユーザーのみ承認可能です。

注記

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

パスパラメータ

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

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

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

リクエスト例

Approve user

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

レスポンス例（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	ユーザーが見つからない

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

ユーザーの承認を取り消します。ステータスが approved のユーザーのみ取り消し可能です。取り消し後、ステータスは pending に戻ります。

注記

取り消し処理が成功すると、対象ユーザーのメールアドレス宛に通知メールが自動送信されます。

パスパラメータ

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

リクエスト例

Reject user

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

レスポンス例（200 OK）

JSON

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

エラーレスポンス

ステータス	説明
400	ユーザーのステータスが approved 以外（取り消し不可）
403	users:manage スコープが不足
404	ユーザーが見つからない

ログ SaaS

監査ログ・LLMログ・LLM Gateway ログ・アクセスログ・ガードレールアラートの閲覧を行います。一覧はすべてページベースのページネーションに対応し、日付範囲フィルターが利用可能です。

エンドポイント一覧

メソッド	エンドポイント	説明	スコープ
GET	/v1/admin/audit-logs	監査ログ一覧を取得	logs:read
GET	/v1/admin/audit-logs/:id	監査ログ詳細を取得	logs:read
GET	/v1/admin/llm-logs	LLMログ一覧を取得	logs:read
GET	/v1/admin/llm-gateway-logs	LLM Gateway ログ一覧を取得	logs:read
GET	/v1/admin/access-logs	アクセスログ一覧を取得	logs:read
GET	/v1/admin/access-logs/stats	アクセスログの集計を取得	logs:read
GET	/v1/admin/guardrail-alerts	ガードレールアラート一覧を取得	logs:read

共通クエリパラメータ

パラメータ	型	必須	説明
limit	integer	—	取得件数（1〜100、デフォルト: 25）
page	integer	—	ページ番号（1以上、デフォルト: 1）
from	string	—	開始日（YYYY-MM-DD形式の実在する日付、UTC基準）。形式が違う値・実在しない日付・文字列ではない値は 400
to	string	—	終了日（YYYY-MM-DD形式の実在する日付、UTC基準）。指定した日の終わりまでを含みます。形式が違う値・実在しない日付・文字列ではない値は 400

GET/v1/admin/audit-logs

監査ログ一覧を取得します。作成日時の降順で返されます。

リクエスト例

List audit logs

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

レスポンスフィールド（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 など）
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/audit-logs/:id

監査ログを 1 件取得します。

パスパラメータ

パラメータ	型	必須	説明
id	string	必須	監査ログID（一覧の auditLogId）

リクエスト例

Get audit log

1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/audit-logs/c14d6065-7c35-44f6-8eea-033ede09bf3a \
2-H "Authorization: Bearer <access_token>"

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

フィールド	型	説明
auditLogId	string	監査ログID
resource	string	操作対象リソース（例: users/show, config/organizations/create, config/job-types/edit）
action	string	操作アクション（approve / reject / promote / demote / create / update / delete など）
meta	object | null	追加メタデータ
userId	string	操作ユーザーID。システム連携（Client Credentials フロー）のトークンでの操作は client:<クライアント ID>
userEmail	string | null	操作ユーザーのメールアドレス
userName	string | null	操作ユーザーの表示名。システム連携（Client Credentials フロー）のトークンでの操作はクライアント名
ipAddress	string | null	IPアドレス
userAgent	string | null	User-Agent
createdAt	string	作成日時（ISO 8601形式）

レスポンス例（200 OK）

JSON

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

エラーレスポンス

ステータス	説明
403	logs:read スコープが不足
404	指定された監査ログが見つからない

GET/v1/admin/llm-logs

LLMログ一覧を取得します。タイムスタンプの降順で返されます。

リクエスト例

List LLM logs

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

レスポンスフィールド（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 ログ一覧を取得します。作成日時の降順で返されます。1 リクエスト = 1 行で、モデル・プロバイダ・トークン・コスト・レイテンシ等の利用状況を記録します。

リクエスト例

List LLM gateway logs

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

レスポンスフィールド（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/access-logs

アクセスログ一覧を取得します。タイムスタンプの降順で返されます。

リクエスト例

List access logs

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

レスポンスフィールド（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/access-logs/stats

アクセスログの集計（リクエストの数・許可と拒否の数・拒否の多いパスとホスト）を取得します。期間は共通クエリパラメータの from・to で指定します（どちらも指定した日を含みます）。指定しなければ全期間です。limit・page は使いません。

リクエスト例

Get access log stats

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

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

フィールド	型	説明
totalRequests	integer	期間内のリクエストの数（認可の結果が記録されたもの）
allowedRequests	integer	許可されたリクエストの数
deniedRequests	integer	拒否されたリクエストの数
blockRate	number	拒否の割合（deniedRequests ÷ totalRequests を小数第 4 位に丸めた値。0〜1。リクエストが無い期間は 0）
topBlockedPaths	array	拒否の多いリクエストパス（多い順に最大 10 件）
topBlockedPaths[].path	string | null	リクエストパス。ログに記録されていない場合は null
topBlockedPaths[].count	integer	拒否された数
topBlockedHosts	array	拒否の多いホスト（多い順に最大 10 件）
topBlockedHosts[].host	string | null	ホスト名。ログに記録されていない場合は null
topBlockedHosts[].count	integer	拒否された数

レスポンス例（200 OK）

JSON

{
  "totalRequests": 57806,
  "allowedRequests": 57790,
  "deniedRequests": 16,
  "blockRate": 0.0003,
  "topBlockedPaths": [
    { "path": "/upload", "count": 9 },
    { "path": "/", "count": 7 }
  ],
  "topBlockedHosts": [
    { "host": "files.example.com:443", "count": 12 },
    { "host": "api.example.net:443", "count": 4 }
  ]
}

GET/v1/admin/guardrail-alerts

ガードレールアラート一覧を取得します。検知日時の降順で返されます。

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

リクエスト例

List guardrail alerts

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

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

フィールド	型	説明
guardrailAlerts	array	ガードレールアラートオブジェクトの配列
guardrailAlerts[].guardrailAlertId	string	ガードレールアラートID
guardrailAlerts[].detectedAt	string	検知日時（ISO 8601形式）
guardrailAlerts[].sourceSurface	string	検知面（agent_executor: AIエージェント実行時 / llm_gateway: LLM Gateway経由）
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[].responseTemplateCode	string | null	利用者へ返した定型応答のコード
guardrailAlerts[].status	string	対応状況（open: 未対応 / 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)

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

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

フィールド	型	説明
organizations	array	部署オブジェクトの配列
organizations[].code	string	部署コード
organizations[].name	string	部署名
organizations[].displayOrder	integer	表示順
organizations[].isActive	boolean	有効/無効
organizations[].createdAt	string	作成日時
organizations[].updatedAt	string	更新日時

レスポンス例（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"
    }
  ]
}

エラーレスポンス

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

POST/v1/admin/organizations

部署を作成します。

リクエストボディ

パラメータ	型	必須	説明
code	string	必須	部署コード（一意）
name	string	必須	部署名
displayOrder	integer	—	表示順。省略した場合は、既存項目の末尾に追加されます
isActive	boolean	—	有効/無効（デフォルト: true）

レスポンス例（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 が整数ではない、ボディが壊れた 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

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

レスポンス例（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	—	有効/無効

レスポンス例（200 OK）

JSON

{
  "code": "sales",
  "name": "営業統括部",
  "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

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

レスポンス例（200 OK）

JSON

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

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

エラーレスポンス

ステータス	説明
403	master:manage スコープが不足
404	指定された部署が見つからない

GET/v1/admin/job-types

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

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

フィールド	型	説明
jobTypes	array	職種オブジェクトの配列
jobTypes[].code	string	職種コード
jobTypes[].name	string	職種名
jobTypes[].displayOrder	integer	表示順
jobTypes[].isActive	boolean	有効/無効
jobTypes[].createdAt	string	作成日時
jobTypes[].updatedAt	string	更新日時

レスポンス例（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"
    }
  ]
}

エラーレスポンス

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

POST/v1/admin/job-types

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

レスポンス例（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 が整数ではない、ボディが壊れた 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

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

レスポンス例（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

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

レスポンス例（200 OK）

JSON

{
  "code": "engineer",
  "name": "シニアエンジニア",
  "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

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

レスポンス例（200 OK）

JSON

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

エラーレスポンス

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

プロジェクト SaaS

ここでは、システム連携（Client Credentials フロー）のトークンで呼ぶときの仕様を説明します。アプリケーション（Authorization Code フロー）のトークンで呼ぶときは、ユーザー API リファレンス（プロジェクト）を参照してください。

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

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

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

操作できる範囲

操作できるプロジェクトは、Console で設定したプロジェクト制限の範囲に限られます（Consoleガイド — プロジェクト制限の設定）。範囲外のプロジェクト ID を指定した場合は、存在しない場合と同じ 404 Not Found が返ります。システム連携のトークンで呼べるプロジェクトの API は、ここにある 4 つのエンドポイントだけです。ほかのプロジェクトの 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

GET/v1/projects

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

クエリパラメータ

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

上記以外のクエリパラメータは無視されます。 myRole は利用者のトークンでのみ使えるパラメータのため、指定しても無視されます。

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

フィールド	型	説明
projects	array	プロジェクトオブジェクトの配列
projects[].projectId	string	プロジェクト ID（UUID）
projects[].name	string	プロジェクト名
projects[].type	string	"workflow" または "cycle"
projects[].status	string	プロジェクトの状態。"active" / "paused" / "archived" のいずれか
projects[].tags	array	タグの配列。設定されていない場合は空の配列
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 のオブジェクトにしてください。含めたフィールドは無視されます。

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

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

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

リクエスト例

curl

curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/runs \
  -H "Authorization: Bearer <access_token>" \
  -H "Idempotency-Key: nightly-batch-20260917" \
  -H "Content-Type: application/json" \
  -d '{}'

レスポンス例

JSON

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

Idempotency-Key の扱い

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

エラーレスポンス

ステータス	code	説明
400	idempotency_key_required	Idempotency-Key ヘッダーが無い
400	idempotency_key_invalid	Idempotency-Key の長さまたは文字種が不正
400	invalid_parameter	projectId が UUID の形式ではない
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	unsupported_runtime	プロジェクト内のエージェントの実行環境が混在しているなど、実行できない構成
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 文字を超える部分は省略されます

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

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

フィールド	型	説明
runId	string	実行の ID（UUID）
status	string	実行の状態。"running"（実行中）/ "waiting_gate"（確認待ち）/ "closed_done"（完了）/ "closed_rejected"（却下で終了）/ "closed_failed"（失敗で終了）/ "cancelled"（中断）のいずれか。"running" と "waiting_gate" 以外は、実行が終わったことを表します
originType	string | null	実行の始まり方。"manual"（画面から開始）/ "api"（API で開始）/ "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
summary	string | null	完了した実行で、出力が記録された最後の完了した工程の出力（先頭 2,000 文字）。そうした工程が無い場合と、完了していない実行では null
runtimeKind	string | null	実行環境の種類（"autonomous"）。古い実行では null の場合があります
cancelRequestedAt	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 を動かし始めると付きます
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	結果の理由コード
steps[].held	boolean	プロジェクトの一時停止で止めていて、再開を待っているか
steps[].visit	number | null	この工程に来た何回目か（差し戻しで増えます）。記録の無い行では null
steps[].reworkReason	string | null	差し戻しの理由
steps[].gateFor	string | null	この確認の行が、どの工程の実行（runStepId）のために立ったか
steps[].routedFrom	string | null	行き先を決めて工程を飛ばしたとき、行き先を決めた工程の実行（runStepId）
steps[].late	string | null	結果が遅れて届き、進行に使わなかった理由
steps[].gate	object | null	確認の工程の要約。確認の工程ではない行では null
steps[].gate.decision	string | null	"proceed"（進める）/ "send_back"（差し戻す）/ "reject"（却下）のいずれか。決まっていなければ null
steps[].gate.waitSource	string | null	何を待つ確認か。"human"（人の判断）/ "external"（外部の条件）
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": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "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,
  "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
    }
  ],
  "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	実行が存在しない、別のプロジェクトの実行を指定した、またはアクセス権が無い

プロジェクト 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 と同じ本文でそのまま再送してください。

エラーレスポンス

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

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

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

リソース	操作	action
ユーザー	ロール変更（管理者へ昇格）	promote
ユーザー	ロール変更（一般へ降格）	demote
ユーザー	承認	approve
ユーザー	承認取消	reject
ユーザー	削除	delete
部署	作成	create
部署	更新	update
部署	削除	delete
職種	作成	create
職種	更新	update
職種	削除	delete