メインコンテンツまでスキップ

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

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

SaaS 版専用

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

ベース 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)を参照してください。

共通の決まり​

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

ページベース​

パラメータ型説明
limitinteger1ページあたりの取得件数。1 〜 100(デフォルト 25)
pageintegerページ番号。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 ログ・LLM Gateway 操作監査・アクセスログ・ガードレールアラート)です。

カーソルベース​

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

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

対応しているのは、プロジェクト一覧と利用者の操作の監査の一覧です。page は使いません(指定しても無視されます)。

共有メモリ SaaS​

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

エンドポイント一覧​

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

POST/v1/admin/memory/query

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

リクエストボディ​

パラメータ型必須説明
querystring必須検索クエリ(最大500文字)
orgIdstring—組織ID(最大100文字)。指定すると組織スコープのメモリも検索対象に含まれます
jobRolestring—職種(最大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)​

フィールド型説明
memoriesarrayメモリオブジェクトの配列
memories[].textstringメモリの内容テキスト
memories[].typestring"knowledge"(ナレッジ)
memories[].scopestring"organization"、"role"、"global" のいずれか
memories[].createdAtstring | null作成日時(ISO 8601形式)
memories[].scorenumber?関連度スコア。スコア値がない場合はフィールド自体が省略される

レスポンスヘッダー​

ヘッダー説明
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
}
]
}

エラーレスポンス​

ステータス説明
400query が未指定、空文字、または500文字超過。またはボディが壊れた JSON(code: "invalid_body")
415ボディの Content-Type が application/json ではない(code: "unsupported_media_type")
403sharedmemory: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 の権限を含みます)。

クエリパラメータ​

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

リクエスト例​

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)​

フィールド型説明
usersarrayユーザーオブジェクトの配列
users[].userIdstringユーザーID
users[].emailstringメールアドレス
users[].usernamestringユーザー名
users[].emailVerifiedbooleanメールアドレスの検証状態
users[].rolestringロール("admin" または "user")
users[].statusstringステータス("unverified"、"pending"、"approved"、"suspended")。"suspended" は管理コンソールで利用を停止した承認済みの利用者(ログインできない)
users[].organizationobject?所属組織(value: コード、label: 名称)。未設定時はフィールド自体が省略される
users[].jobTypeobject?職種(value: コード、label: 名称)。未設定時はフィールド自体が省略される
users[].biostring?自己紹介。未設定時はフィールド自体が省略される
users[].createdAtstring作成日時(ISO 8601形式)
users[].lastLoginAtstring?最終ログイン日時(ISO 8601形式)。未ログイン時はフィールド自体が省略される
users[].idpSyncedbooleanIdP(ID 基盤)から同期している利用者か。true の利用者の設定済みの所属・職種は、PUT /v1/admin/users/:userId/affiliation で変えられない(409 affiliation_managed_by_idp)
totalinteger総件数
limitinteger取得件数
pageintegerページ番号
hasMoreboolean次ページが存在するか
レスポンス例(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クエリパラメータが不正
403users:read または users:manage スコープが不足

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

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

パスパラメータ​

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

リクエスト例​

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

レスポンスフィールド​

フィールド型説明
passkeysarrayパスキーの配列(全件)
passkeys[].credentialIdstringパスキーの ID
passkeys[].labelstring | nullパスキーの名前
passkeys[].createdAtstring | null登録した日時(ISO 8601)
passkeys[].lastUsedAtstring | null最後に使った日時(ISO 8601)。使っていなければ null
hasMorebooleanいつも 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
}

エラーレスポンス​

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

POST/v1/admin/users

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

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

リクエストボディ​

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

リクエスト例​

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

レスポンスフィールド(201 Created)​

フィールド型説明
userobject作ったユーザー。ユーザー一覧の users[] と同じ項目です(status は "approved"、idpSynced は false)
emailSentboolean知らせのメールを送ったか
temporaryPasswordstring?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": "<一時パスワード>"
}

エラーレスポンス​

ステータス説明
400email・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")
403users: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 から消え、元に戻せません。アーカイブした会話・会話ごとの作業のメモ・利用者ごとの設定の記録の削除を希望する場合は、管理者ガイドを参照してください。users:manage スコープが必要です。削除の前にそのユーザーに発行されていたアクセストークンは、削除の後も、有効期限(トークンを取得したときの expires_in)まで使えることがあります。

パスパラメータ​

パラメータ型必須説明
userIdstring必須ユーザー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 }

エラーレスポンス​

ステータス説明
403users: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 への昇格時: 対象ユーザーのセッションは継続され、新しい権限は、昇格の後に発行されるトークンから有効になります

パスパラメータ​

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

リクエストボディ​

パラメータ型必須説明
rolestring必須変更先のロール。"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 }

エラーレスポンス​

ステータス説明
400role が未指定または不正、ボディが壊れた JSON(code: "invalid_body")、または対象ユーザーが、ステータス approved でも、emailVerified が true の suspended でもない
415ボディの Content-Type が application/json ではない(code: "unsupported_media_type")
403users: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 と表示され、承認できます。承認するとログインできるようになり、データも残っていますが、取り消しで止まった物(実行中の会話・個人の定期の実行・持ち主のプロジェクトの巡回と実行)と削除した外部サービスへの接続は、自動では戻りません。

注記

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

パスパラメータ​

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

リクエストボディ(任意)​

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

リクエスト例​

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 以外(承認不可。メールを確かめていない、または承認済み〈停止中を含む〉)
400reason が文字列ではない、またはボディが壊れた JSON・JSON のオブジェクトではない(code: "invalid_body")
415ボディの Content-Type が application/json ではない(code: "unsupported_media_type")
403users: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 度だけ、対象ユーザーのメールアドレス宛に通知メールが自動送信されます。

パスパラメータ​

パラメータ型必須説明
userIdstring必須ユーザー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 でも、emailVerified が true の suspended でもない(取り消し不可)。取り消し済みのユーザーも、もう一度取り消せます(やり直し。メールは送りません)
403users: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)。

パスパラメータ​

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

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

リクエスト例​

Suspend user
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/suspend \
2-H "Authorization: Bearer <access_token>"
レスポンス例(200 OK)​
JSON
{ "userId": "abc123", "suspended": true }

エラーレスポンス​

ステータス説明
400ボディが壊れた JSON(code: "invalid_body")
401トークンが無効または未指定(code: "invalid_token")
403users: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

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

パスパラメータ​

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

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

リクエスト例​

Resume user
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/resume \
2-H "Authorization: Bearer <access_token>"
レスポンス例(200 OK)​
JSON
{ "userId": "abc123", "suspended": false }

エラーレスポンス​

ステータス説明
400ボディが壊れた JSON(code: "invalid_body")
401トークンが無効または未指定(code: "invalid_token")
403users: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 になります。

パスパラメータ​

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

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

リクエスト例​

Unlock user
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/unlock \
2-H "Authorization: Bearer <access_token>"
レスポンス例(200 OK)​
JSON
{ "userId": "abc123", "wasLocked": true }

エラーレスポンス​

ステータス説明
400ボディが壊れた JSON(code: "invalid_body")
401トークンが無効または未指定(code: "invalid_token")
403users: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 になります。

パスパラメータ​

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

リクエストボディ​

パラメータ型必須説明
organizationstring必須組織のコード(GET /v1/organizations の値)
jobstring必須職種のコード(GET /v1/job-types の値)

リクエスト例​

Change user affiliation
1curl -X PUT https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/affiliation \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{"organization": "ORG002", "job": "JOB01"}'
レスポンス例(200 OK)​
JSON
{
"userId": "abc123",
"previous": { "organization": "ORG001", "job": null },
"current": { "organization": "ORG002", "job": "JOB01" }
}

エラーレスポンス​

ステータス説明
400organization・job が無い、文字列ではない、または組織・職種のコードが違う(code: "invalid_parameter")
400ボディが壊れた JSON、または JSON のオブジェクトではない(code: "invalid_body")
415ボディの Content-Type が application/json ではない(code: "unsupported_media_type")
401トークンが無効または未指定(code: "invalid_token")
403users: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-logsLLMログ一覧を取得logs:read
GET/v1/admin/llm-gateway-logsLLM Gateway ログ一覧を取得logs:read
GET/v1/admin/llm-gateway-action-logsLLM Gateway 操作監査の一覧を取得logs:read
GET/v1/admin/access-logsアクセスログ一覧を取得logs:read
GET/v1/admin/guardrail-alertsガードレールアラート一覧を取得logs:read

共通クエリパラメータ​

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

GET/v1/admin/audit-logs

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

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

パラメータ型必須説明
resourcestring—リソース(resource)の完全一致
actionstring—操作(action)の完全一致
user_idstring—操作した利用者の ID(userId)の完全一致

リクエスト例​

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)​

フィールド型説明
auditLogsarray監査ログオブジェクトの配列
auditLogs[].auditLogIdstring監査ログID
auditLogs[].resourcestring操作対象リソース(例: users/show, config/organizations/create, config/job-types/edit)
auditLogs[].actionstring操作アクション(approve / reject / promote / demote / create / update / delete / reset-password など)。meta に action がある記録は、その値(管理コンソールの表示と同じ)
auditLogs[].metaobject | null追加メタデータ
auditLogs[].userIdstring操作ユーザーID。システム連携(Client Credentials フロー)のトークンでの操作は client:<クライアント ID>
auditLogs[].userEmailstring | null操作ユーザーのメールアドレス
auditLogs[].userNamestring | null操作ユーザーの表示名。システム連携(Client Credentials フロー)のトークンでの操作はクライアント名
auditLogs[].ipAddressstring | nullIPアドレス
auditLogs[].userAgentstring | nullUser-Agent
auditLogs[].createdAtstring作成日時(ISO 8601形式)
totalinteger総件数
limitinteger取得件数
pageintegerページ番号
hasMoreboolean次ページが存在するか
レスポンス例(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

利用者の操作の監査の一覧を取得します。利用者がチャット画面で行った操作(会話・ファイル・共有などを開いた・作った・消したなど)の記録です。新しい順の固定で、カーソルベースのページネーションです(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_idstring—操作した利用者の ID(userId)の完全一致(128 文字まで)
actionstring—操作(action)の完全一致(64 文字まで)

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

リクエスト例​

List user action logs
1curl "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" \
2-H "Authorization: Bearer <access_token>"

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

curl
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)​

フィールド型説明
userActionLogsarray利用者の操作の監査の配列
userActionLogs[].userActionLogIdstring利用者の操作の監査の ID
userActionLogs[].occurredAtstring操作した日時(ISO 8601形式)
userActionLogs[].eventTypestring種類。user_action.<resource>.<action> の形(例: user_action.conversation.export)
userActionLogs[].userIdstring | null操作した利用者の ID。分からない記録は null
userActionLogs[].actorKindstring操作した主体(human: 利用者 / unknown: 利用者が分からない記録)
userActionLogs[].resourcestring | null対象(例: conversation・share・session)
userActionLogs[].actionstring | null操作(例: export・delete)
userActionLogs[].decisionstring結果(例: allow・deny・rejected・not_found・error・aborted)
userActionLogs[].requestIdstring | null要求 ID
userActionLogs[].conversationIdstring | null会話 ID
userActionLogs[].systemVersionstring | null記録したときのシステムの版
hasMoreboolean次ページが存在するか
cursorstring?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"
}

エラーレスポンス​

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

GET/v1/admin/action-audit-logs

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

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

パラメータ型必須説明
event_typestring—イベント種別(eventType)の完全一致(例: "tool.invoked"・"approval.resolved"・"gate.resolved"・"run.started"・"agent.copied")
decisionstring—判定(decision)の完全一致(例: "allow"・"deny"・"completed"・"failed"・"copied")
sourcestring—記録元(source)の完全一致(例: "worker"・"cli-api"・"front"・"admin"・"login"・"agent_executor")
actor_typestring—実行者の種類(actorType)の完全一致(例: "human"・"agent"・"system")
actor_kindstring—実行者の区分(actorKind)の完全一致(例: "human"・"human_external"・"system"・"agent"・"unknown")
actor_refstring—実行者(actorRef)の完全一致
conversation_idstring—会話 ID(conversationId)の完全一致
execution_idstring—実行 ID(executionId)の完全一致
root_execution_idstring—一連の実行 ID(rootExecutionId)の完全一致
project_idstring—プロジェクト ID(projectId)の完全一致。UUID ではない値は 400
request_idstring—リクエスト ID(requestId)の完全一致

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

リクエスト例​

List action audit logs
1curl "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" \
2-H "Authorization: Bearer <access_token>"

レスポンスフィールド(200 OK)​

フィールド型説明
actionAuditLogsarray操作監査ログオブジェクトの配列
actionAuditLogs[].actionAuditLogIdstring操作監査ログID
actionAuditLogs[].occurredAtstring | null発生日時(ISO 8601形式)
actionAuditLogs[].sourcestring | null記録元(例: worker・cli-api・front・admin・login・agent_executor)
actionAuditLogs[].eventTypestring | nullイベント種別
actionAuditLogs[].actorTypestring | null実行者の種類(例: human・agent・system)
actionAuditLogs[].actorKindstring | null実行者の区分(例: human・human_external・system・agent・unknown)。古い記録では null
actionAuditLogs[].actorRefstring | null実行者
actionAuditLogs[].onBehalfOfRefstring | null代理元(誰の代わりに実行したか)
actionAuditLogs[].resourcestring | null対象
actionAuditLogs[].actionstring | null操作
actionAuditLogs[].decisionstring | null判定
actionAuditLogs[].reasonstring | null理由コード
actionAuditLogs[].policyIdstring | null実行ルールID
actionAuditLogs[].policyVersionstring | null実行ルールの版
actionAuditLogs[].executionIdstring | null実行ID
actionAuditLogs[].rootExecutionIdstring | null一連の実行ID。古い記録では null
actionAuditLogs[].conversationIdstring | null会話ID
actionAuditLogs[].projectIdstring | nullプロジェクトID。古い記録では null
actionAuditLogs[].messageIdstring | nullメッセージID
actionAuditLogs[].requestIdstring | nullリクエストID
actionAuditLogs[].systemVersionstring | nullシステムバージョン
totalinteger総件数
limitinteger取得件数
pageintegerページ番号
hasMoreboolean次ページが存在するか
レスポンス例(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
}

エラーレスポンス​

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

GET/v1/admin/llm-logs

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

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

パラメータ型必須説明
conversation_idstring—会話 ID(conversationId)の完全一致
servicestring—サービス(service)の完全一致
operationstring—操作(operation)の完全一致
successstring—"true"(成功)または "false"(失敗)。ほかの値は 400

リクエスト例​

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)​

フィールド型説明
llmLogsarrayLLMログオブジェクトの配列
llmLogs[].llmLogIdstringLLMログID
llmLogs[].timestampstring | nullタイムスタンプ
llmLogs[].servicestring | nullサービス名
llmLogs[].operationstring | nullオペレーション名
llmLogs[].durationMsnumber | null処理時間(ミリ秒)
llmLogs[].conversationIdstring | null会話ID
llmLogs[].intentTypestring | null意図タイプ
llmLogs[].confidenceScorenumber | null信頼度スコア
llmLogs[].toolsUsednumber | nullツール呼び出し回数(ツール名の一覧でも、使ったツールの種類数でもない。同じツールを 5 回呼べば 5)。null は未計測、0 は計測した上で一度も呼ばなかった実行。両者は区別されるため、0 を null と同一視しないでください
llmLogs[].successboolean | null成功/失敗
llmLogs[].agentTypestring | nullエージェントタイプ
llmLogs[].agentLevelstring | nullエージェントレベル
llmLogs[].taskComplexitystring | nullタスクの複雑度
llmLogs[].currentMessagestring | null現在のメッセージ
llmLogs[].contextSummarystring | nullコンテキスト要約
llmLogs[].suggestedApproachstring | null提案された進め方
llmLogs[].conversationGoalstring | null会話のゴール
llmLogs[].finalContentstring | null最終出力内容
llmLogs[].metadataobject | nullオペレーションごとに異なる付随メタデータ(キーは可変)
llmLogs[].createdAtstring | null作成日時
totalinteger総件数
limitinteger取得件数
pageintegerページ番号
hasMoreboolean次ページが存在するか
レスポンス例(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 行で、モデル・プロバイダ・トークン・コスト・レイテンシ等の利用状況を記録します。

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

パラメータ型必須説明
providerstring—プロバイダ(provider)の完全一致
model_namestring—モデル名の完全一致(modelName が無い行は resolvedModel で比べます)
successstring—"true"(成功)または "false"(失敗)。ほかの値は 400

リクエスト例​

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)​

フィールド型説明
llmGatewayLogsarrayLLM Gateway ログオブジェクトの配列
llmGatewayLogs[].llmGatewayLogIdstringLLM Gateway ログID
llmGatewayLogs[].createdAtstring | null作成日時
llmGatewayLogs[].virtualKeyIdstring | null仮想キーID(呼び出し元クライアント)
llmGatewayLogs[].clientSessionIdstring | nullクライアントセッションID
llmGatewayLogs[].clientAgentIdstring | nullクライアントエージェントID
llmGatewayLogs[].apiFlavorstring | nullAPI フレーバー
llmGatewayLogs[].modelNamestring | nullモデル名(リクエスト指定)
llmGatewayLogs[].resolvedModelstring | null解決後モデル名
llmGatewayLogs[].providerstring | nullプロバイダ
llmGatewayLogs[].deploymentstring | nullデプロイメント
llmGatewayLogs[].tierstring | nullティア
llmGatewayLogs[].streamboolean | nullストリーミング有無
llmGatewayLogs[].successboolean | null成功/失敗
llmGatewayLogs[].httpStatusnumber | nullHTTP ステータス
llmGatewayLogs[].errorTypestring | nullエラータイプ
llmGatewayLogs[].errorCodestring | nullエラーコード
llmGatewayLogs[].usageStatusstring | null使用量ステータス
llmGatewayLogs[].latencyMsnumber | nullレイテンシ(ミリ秒)
llmGatewayLogs[].inputTokensnumber | null入力トークン数
llmGatewayLogs[].outputTokensnumber | null出力トークン数
llmGatewayLogs[].totalTokensnumber | null合計トークン数
llmGatewayLogs[].cachedTokensnumber | nullキャッシュトークン数
llmGatewayLogs[].cacheCreationInputTokensnumber | nullキャッシュ作成入力トークン数
llmGatewayLogs[].reasoningTokensnumber | null推論トークン数
llmGatewayLogs[].costUsdnumber | string | nullコスト(USD)
llmGatewayLogs[].currencystring | null通貨
llmGatewayLogs[].metadataobject | null付随メタデータ(キーは可変)
totalinteger総件数
limitinteger取得件数
pageintegerページ番号
hasMoreboolean次ページが存在するか

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

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

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

パラメータ型必須説明
event_typestring—イベント種別(eventType)の完全一致(例: "auth.denied"・"guardrail.blocked"・"policy.pii_blocked"・"policy.mcp_stripped"・"limit.rpm_exceeded"・"limit.budget_exceeded")
decisionstring—判定(decision)の完全一致(例: "allowed"・"denied"・"blocked"・"degraded"・"stripped"・"throttled")
api_flavorstring—API フレーバー(apiFlavor)の完全一致(例: "chat"・"responses"・"messages"・"embeddings")
virtual_key_idstring—仮想キーID(virtualKeyId)の完全一致

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

リクエスト例​

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

レスポンスフィールド(200 OK)​

フィールド型説明
llmGatewayActionLogsarrayLLM Gateway 操作監査オブジェクトの配列
llmGatewayActionLogs[].llmGatewayActionLogIdstringLLM Gateway 操作監査ID
llmGatewayActionLogs[].occurredAtstring | null発生日時(ISO 8601形式)
llmGatewayActionLogs[].virtualKeyIdstring | null仮想キーID(呼び出し元クライアント)
llmGatewayActionLogs[].externalRequestIdstring | null外部リクエストID
llmGatewayActionLogs[].apiFlavorstring | nullAPI フレーバー
llmGatewayActionLogs[].eventTypestring | nullイベント種別
llmGatewayActionLogs[].decisionstring | null判定
llmGatewayActionLogs[].reasonstring | null理由コード
llmGatewayActionLogs[].modelNamestring | nullモデル名(リクエスト指定)
llmGatewayActionLogs[].resolvedModelstring | null解決後モデル名
llmGatewayActionLogs[].systemVersionstring | nullシステムバージョン
totalinteger総件数
limitinteger取得件数
pageintegerページ番号
hasMoreboolean次ページが存在するか
レスポンス例(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
}

エラーレスポンス​

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

GET/v1/admin/access-logs

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

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

パラメータ型必須説明
authz_resultstring—"allowed"(許可)または "denied"(拒否)。ほかの値は 400

リクエスト例​

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)​

フィールド型説明
accessLogsarrayアクセスログオブジェクトの配列
accessLogs[].timestampstringタイムスタンプ
accessLogs[].sourceNamespacestring | nullソース名前空間
accessLogs[].sourceIpstring | nullソースIPアドレス
accessLogs[].methodstring | nullHTTPメソッド
accessLogs[].hoststring | nullホスト名
accessLogs[].pathstring | nullリクエストパス
accessLogs[].userAgentstring | nullUser-Agent
accessLogs[].statusCodenumber | nullHTTPステータスコード
accessLogs[].durationMsnumber | null処理時間(ミリ秒)
accessLogs[].authzResultstring | null認可結果
accessLogs[].authzReasonstring | null認可理由
totalinteger総件数
limitinteger取得件数
pageintegerページ番号
hasMoreboolean次ページが存在するか
skippedCountintegerこのページで読めなかったログの行の数(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 で昇順にできます)。

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

パラメータ型必須説明
statusstring—"open" / "investigating" / "escalated" / "closed" / "false_positive"
source_surfacestring—"agent_executor" / "llm_gateway" / "agent_worker"
resolution_codestring—"policy_violation_confirmed" / "no_action_required" / "escalated_externally" / "detection_error" / "benign_context" / "test_or_synthetic" / "insufficient_information"
detection_typestring—検知の種類(detectionTypes の値。例: "jailbreak_attack"・"harmful_content")
moderation_categorystring—有害表現のカテゴリ(moderationCategories のキー。例: "Hate"・"Violence"・"Sexual")
shield_originstring—"userPrompt" / "documents" / "both" / "unknown"
policy_categorystring—攻撃方式の分類(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
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)​

フィールド型説明
guardrailAlertsarrayガードレールアラートオブジェクトの配列
guardrailAlerts[].guardrailAlertIdstringガードレールアラートID
guardrailAlerts[].detectedAtstring検知日時(ISO 8601形式)
guardrailAlerts[].sourceSurfacestring検知面(agent_executor: AIエージェント実行時 / llm_gateway: LLM Gateway経由 / agent_worker: 会話 Pod の中)
guardrailAlerts[].detectionTypesarray検知種別(jailbreak_attack: プロンプトインジェクション / harmful_content: 有害表現)
guardrailAlerts[].promptShieldOriginobject | nullPrompt Shield の検知箇所。user_prompt(利用者の入力)と document_indexes(添付文書の位置)を持つ。文書の内容は含まれません
guardrailAlerts[].moderationCategoriesobject | nullカテゴリ別の深刻度。Hate / Sexual / SelfHarm / Violence を 0・2・4・6 の4段階で表す
guardrailAlerts[].moderationThresholdinteger | null判定に使用したしきい値
guardrailAlerts[].policyOutcomestring判定結果。現在は blocked(実行を停止)のみ
guardrailAlerts[].policyCategorystring | null攻撃方式の分類(例: prompt_injection・system_prompt_extraction・credential_request)。この分類を持たない検知では null
guardrailAlerts[].responseTemplateCodestring | null利用者へ返した定型応答のコード
guardrailAlerts[].statusstring対応状況(open: 未対応 / investigating: 調査中 / escalated: エスカレーション中 / closed: 対応済み / false_positive: 誤検知)
guardrailAlerts[].resolutionCodestring | null対応結果コード
guardrailAlerts[].resolvedAtstring | null対応完了日時(ISO 8601形式)
guardrailAlerts[].resolvedBystring | null対応を完了した管理者のユーザーID
guardrailAlerts[].createdAtstring作成日時(ISO 8601形式)
guardrailAlerts[].updatedAtstring更新日時(ISO 8601形式)
totalinteger総件数
limitinteger取得件数
pageintegerページ番号
hasMoreboolean次ページが存在するか
検知された利用者の情報について

本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)​

フィールド型説明
organizationsarray組織オブジェクトの配列
organizations[].codestring組織コード
organizations[].namestring組織名
organizations[].displayOrderinteger表示順
organizations[].isActiveboolean有効/無効
organizations[].createdAtstring作成日時
organizations[].updatedAtstring更新日時
hasMorebooleanいつも 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
}

エラーレスポンス​

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

POST/v1/admin/organizations

組織を作成します。

リクエストボディ​

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

リクエスト例​

Create organization
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "code": "marketing",
6 "name": "マーケティング統括部",
7 "displayOrder": 3,
8 "isActive": true
9}'
レスポンス例(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")
403master:manage スコープが不足
409同じ code を持つ組織が既に存在する

GET/v1/admin/organizations/:identifier

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

パスパラメータ​

パラメータ型必須説明
identifierstring必須組織の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"
}

エラーレスポンス​

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

PATCH/v1/admin/organizations/:identifier

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

パスパラメータ​

パラメータ型必須説明
identifierstring必須組織のUUIDまたは組織コード

リクエストボディ​

パラメータ型必須説明
namestring—組織名
isActiveboolean—有効/無効

リクエスト例​

Update organization
1curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/sales \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "name": "営業統括部",
6 "isActive": true
7}'
レスポンス例(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")
403master:manage スコープが不足
404指定された組織が見つからない

DELETE/v1/admin/organizations/:identifier

組織を削除します。

パスパラメータ​

パラメータ型必須説明
identifierstring必須組織の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 }
フィールド型説明
codestring削除した組織コード(パスパラメータの identifier をそのまま返す)
deletedboolean常に true

エラーレスポンス​

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

GET/v1/admin/job-types

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

リクエスト例​

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

レスポンスフィールド(200 OK)​

フィールド型説明
jobTypesarray職種オブジェクトの配列
jobTypes[].codestring職種コード
jobTypes[].namestring職種名
jobTypes[].displayOrderinteger表示順
jobTypes[].isActiveboolean有効/無効
jobTypes[].createdAtstring作成日時
jobTypes[].updatedAtstring更新日時
hasMorebooleanいつも 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
}

エラーレスポンス​

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

POST/v1/admin/job-types

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

リクエスト例​

Create job type
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "code": "manager",
6 "name": "管理職",
7 "displayOrder": 3,
8 "isActive": true
9}'
レスポンス例(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")
403master:manage スコープが不足
409同じ code を持つ職種が既に存在する

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

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

パスパラメータ​

パラメータ型必須説明
identifierstring必須職種の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"
}

エラーレスポンス​

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

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

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

パスパラメータ​

パラメータ型必須説明
identifierstring必須職種のUUIDまたは職種コード

リクエストボディ​

パラメータ型必須説明
namestring—職種名
isActiveboolean—有効/無効

リクエスト例​

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": "シニアエンジニア",
"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")
403master:manage スコープが不足
404指定された職種が見つからない

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

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

パスパラメータ​

パラメータ型必須説明
identifierstring必須職種の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 }

エラーレスポンス​

ステータス説明
403master: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 は、ここにある 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)の対象にはなりません。

クエリパラメータ​

パラメータ型デフォルト説明
limitinteger50取得件数(1〜100)
cursorstring—次ページ取得用カーソル(前回レスポンスの cursor 値)

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

リクエスト例​

List projects
1curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects?limit=20" \
2-H "Authorization: Bearer <access_token>"

レスポンスフィールド(200 OK)​

フィールド型説明
projectsarrayプロジェクトオブジェクトの配列
projects[].projectIdstringプロジェクト ID(UUID)
projects[].namestringプロジェクト名
projects[].typestring"workflow" または "cycle"
projects[].statusstringプロジェクトの状態。"active" / "paused" / "archived" / "admin_stopped"(管理者が停止)のいずれか
projects[].tagsarrayタグの配列。設定されていない場合は空の配列
hasMoreboolean次のページが存在するかどうか
cursorstring次ページ取得用カーソル。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
}

エラーレスポンス​

ステータス説明
400limit(1〜100 の範囲外)または cursor が不正(code は invalid_parameter)
403project:read スコープが不足、またはプロジェクト制限が未設定・不正(code は insufficient_scope または invalid_project_grant)

POST/v1/projects/{projectId}/runs

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

リクエストヘッダー​

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

パスパラメータ​

パラメータ型必須説明
projectIdstring必須プロジェクトの ID(UUID)

リクエストボディ​

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

パラメータ型必須説明
payloadany—実行の依頼。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)​

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

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

リクエスト例​

Start run
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs \
2-H "Authorization: Bearer <access_token>" \
3-H "Idempotency-Key: nightly-batch-20260917" \
4-H "Content-Type: application/json" \
5-d '{
6 "payload": {
7 "ticketId": "INC-1024",
8 "summary": "ログインできない利用者がいる"
9 }
10}'

レスポンス例​

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

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

エラーレスポンス​

ステータスcode説明
400idempotency_key_requiredIdempotency-Key ヘッダーが無い
400idempotency_key_invalidIdempotency-Key の長さまたは文字種が不正
400invalid_parameterprojectId が UUID の形式ではない、または config を送った(この API では受け付けない。param は config)
400payload_too_largepayload を JSON の文字列にした長さが 8,000 文字を超える
400invalid_bodyリクエストボディが壊れた JSON、または JSON のオブジェクトではない
413body_too_largeリクエストボディが 16 KiB を超過
415unsupported_media_typeリクエストボディがあるのに、Content-Type が application/json ではない
403insufficient_scopeproject:run スコープが不足
403invalid_project_grantプロジェクト制限が未設定、または設定内容が不正
404project_not_foundプロジェクトが存在しない、またはアクセス権が無い
400approvers_required有効な確認工程に確認担当者が設定されていない
409unsupported_project_typecycle 型のプロジェクトを指定した
409project_inactiveプロジェクトが有効な状態ではない(一時停止中、またはアーカイブ済み)
409principal_suspendedプロジェクトを実行する人の利用を、管理者が止めている。管理者に、プロジェクトの持ち主を変更するか、利用の停止を解くよう頼む
409start_step_in_branch_lane開始の工程が条件分岐のレーンの中にある。時間トリガーの開始する工程を、条件分岐のレーンの外の工程にしてください
409definition_pendingプロジェクトの最初の定義が承認待ちの間は始められない。承認する人(ほかのオーナーか組織の管理者)が製品の画面で承認してから始めてください
409relink_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 で消せますが、それだけでは始められません
409branch_ai_unavailableAI に判定させる条件分岐の工程を、この環境では実行できない。管理者に判定の設定を頼むか、製品の画面でその工程を止めてから、新しく始めてください
409automation_dlp_enabledDLP 連携が有効な間は、外部の自動化の工程を保存・実行できない。管理者に DLP 連携を切ってもらってください。それまでは、外部の自動化の工程を止めるか外せば始められます
409automation_destination_missing外部の自動化の工程の宛先が見つからない。工程を変える API で automationConfig.destinationId を宛先の一覧(GET /v1/projects/automation-destinations)の有効な宛先にするか、その工程を止めてください。一覧に宛先が無いときは、管理者に頼んでください
409automation_destination_inactive外部の自動化の工程の宛先が無効。管理者に宛先を有効にしてもらうか、工程を変える API で automationConfig.destinationId を宛先の一覧(GET /v1/projects/automation-destinations)の別の有効な宛先にするか、その工程を止めてください
409admin_stoppedプロジェクトを、管理者が止めている。再開は管理者に頼む(この API では再開できない)
409unsupported_runtimeプロジェクト内のエージェントの実行環境が混在しているなど、実行できない構成
409origin_conflict同じ Idempotency-Key で、違う payload を送った
429too_many_active_runs同じプロジェクトで、実行中と確認待ちの実行が合わせて上限(3 件)に達している

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

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

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

パスパラメータ​

パラメータ型必須説明
projectIdstring必須プロジェクトの ID(UUID)
triggerIdstring必須発火するトリガーの ID(UUID)

リクエストボディ​

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

リクエスト例​

Fire trigger
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/triggers/d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70/fire \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "eventId": "order-20261118-0001",
6 "payload": {
7 "orderId": "A-1024"
8 }
9}'

レスポンスフィールド(202 Accepted)​

フィールド型説明
resultstring"accepted"(新しく受け付けた)または "duplicate"(同じ eventId で受付済み)
jobIdstring受付先のジョブ 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説明
400invalid_event_ideventId が無い、または形式が不正
400invalid_parameterprojectId または triggerId が UUID の形式ではない
400invalid_bodyリクエストボディが壊れた JSON、または JSON のオブジェクトではない
415unsupported_media_typeリクエストボディがあるのに、Content-Type が application/json ではない
403insufficient_scopeproject:run スコープが不足
403invalid_project_grantプロジェクト制限が未設定、または設定内容が不正
404trigger_not_foundプロジェクト・トリガーが存在しない、アクセス権が無い、Webhook ではないトリガーを指定した、または workflow 型のプロジェクトを指定した
409trigger_disabledトリガーが無効化されている
409project_not_activeプロジェクトが実行可能な状態にない
409principal_suspendedプロジェクトを実行する人の利用を、管理者が止めている。管理者に、プロジェクトの持ち主を変更するか、利用の停止を解くよう頼む
409admin_stoppedプロジェクト、または発火で動かす配置の Agent を、管理者が止めている。再開は管理者に頼む
409placement_unavailable発火対象のエージェント配置が存在しない、実行主体が未設定、または配置の工程が無効(工程を有効に戻せるのはプロジェクトのオーナー。有効に戻してから送り直す)
409event_conflict同じ eventId で payload が異なる
413body_too_largeリクエストボディが 16 KiB を超過

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

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

パスパラメータ​

パラメータ型必須説明
projectIdstring必須プロジェクトの ID(UUID)
runIdstring必須実行の ID(UUID)

リクエスト例​

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

レスポンスフィールド(200 OK)​

フィールド型説明
runIdstring実行の ID(UUID)
statusstring実行の状態。"running"(実行中)/ "waiting_gate"(確認待ち)/ "closed_done"(完了)/ "closed_rejected"(却下で終了)/ "closed_failed"(失敗で終了)/ "cancelled"(中断)のいずれか。"running" と "waiting_gate" 以外は、実行が終わったことを表します。ただし "closed_rejected" と "closed_failed" は、オーナーか運用担当(組織の運用の役割の人を含む)が再開すると、同じ実行が "running" に戻ります(endedAt も null に戻ります)
originTypestring | null実行の始まり方。"manual"(画面から開始)/ "api"(API で開始)/ "mail"(メールで開始)/ "cron"(定期実行)のいずれか
originRefstring | null始まり方ごとの参照値。API で開始した実行では、開始したときの Idempotency-Key の値
currentStepIdstring | null進んでいる工程の ID(UUID)。レーンに分かれて進んでいる間は、分岐する前の工程の ID。完了した実行では null。ほかの理由で終わった実行では、終わったときの工程の ID が残る場合があります
startedByRefstring | null実行を始めたもの。値は下の「実行を始めたもの」の表のとおり
actorLabelstring | null利用者ではない起動者の表示名(システム連携の名前、またはメールの送信元のアドレス)。それ以外は null
startedAtstring | null開始日時(ISO 8601)。開始前は null
endedAtstring | null終了日時(ISO 8601)。終了前は null。閉じた実行を再開すると null に戻ります
summarystring | null完了した実行で、出力が記録された最後の完了した工程の出力(先頭 2,000 文字)。そうした工程が無い場合と、完了していない実行では null
runtimeKindstring | null実行環境の種類("autonomous")。古い実行では null の場合があります
cancelRequestedAtstring | null中断が求められた日時(ISO 8601)。求められていなければ null
deadlineAtstring | nullワークフローの実行の締め切り(ISO 8601)。締め切りが無ければ null
configRevisionnumber | null案件設定のバージョン(Marketplace 版の実行だけ)。SaaS 版の実行では null
stepsarray工程ごとの実行の記録。記録した順
steps[].runStepIdstring工程の実行の ID("rs:" で始まる)
steps[].stepIdstring | null工程の ID(UUID)
steps[].placementIdstring | nullその工程を担当した配置の ID(UUID)。Agent を動かさない行(確認の工程など)では null
steps[].executionIdstring | nullAgent の実行の ID。Agent を動かし始めると付きます。外部の自動化の工程では null
steps[].conversationIdstring | nullAgent の実行の会話の ID。Agent を動かし始めると付きます
steps[].statusstring"pending"(実行待ち)/ "running"(実行中)/ "waiting_gate"(確認待ち)/ "done"(完了)/ "failed"(失敗)/ "skipped"(実行を省略)のいずれか
steps[].attemptnumber | null同じ回の中での再試行の回数(1 から)。閉じた実行の再開と、接続の確認の承認で起動し直したときも増えます
steps[].lanestring | null工程が属するレーンの ID。レーンに分かれていない工程は "main"
steps[].scheduledAtstring | null工程に時刻が設定されているとき、その時刻まで待つ行の予定日時(ISO 8601)。動き始めると null
steps[].startedAtstring | null開始日時(ISO 8601)
steps[].endedAtstring | null終了日時(ISO 8601)
steps[].outputSummarystring | null工程の出力の要約
steps[].outcomestring | nullAgent の実行か、外部の自動化の工程の送信の結果。"completed" / "incomplete" / "failed" / "timeout" / "stopped" / "denied" / "skipped" のいずれか。結果の無い行では null
steps[].reasonCodestring | null結果の理由コード。条件分岐で決められず人に選択してもらうときは "branch_undecided"、条件分岐で選ばれなかったレーンの工程は "branch_not_selected"
steps[].heldbooleanプロジェクトの一時停止で止めていて、再開を待っているか
steps[].visitnumber | nullこの工程に来た何回目か(差し戻しで増えます)。記録の無い行では null
steps[].reworkReasonstring | null差し戻しの理由
steps[].gateForstring | nullこの確認の行が、どの工程の実行(runStepId)のために立ったか
steps[].routedFromstring | null次の工程を決定して工程を飛ばしたとき、次の工程を決定した工程の実行(runStepId)
steps[].latestring | null結果が遅れて届き、進行に使わなかった理由
steps[].gateobject | null確認の要約。確認の工程の行と、接続の確認の待ちの行(gateKind が "connection")に付きます。それ以外の行では null
steps[].gate.decisionstring | null"proceed"(進める)/ "send_back"(差し戻す)/ "reject"(却下)のいずれか。決まっていなければ null
steps[].gate.waitSourcestring | null何を待つ確認か。"human"(人の判断)/ "external"(外部の条件)
steps[].resumeCommandIdstring | null閉じた実行の再開でこの行を起動したときの commandId。その再開で起動した行(選んだ工程と、起動し直したほかのレーン)に付きます。それ以外は null
steps[].resumeReasonstring | null閉じた実行の再開の理由の文。resumeCommandId と同じ行に付きます。それ以外は null
steps[].supersededBystring | null閉じた実行の再開で、前の回に残っていた行を閉じたとき "resume"。それ以外は null
steps[].gateKindstring | null接続の確認の待ちの行(Agent が人の確認の要る連携先を使おうとして止めたときに立つ行)なら "connection"。それ以外は null
steps[].connectionConfirmOfstring | null接続の確認の承認で起動し直した行なら、その確認依頼の ID(workItemId)。それ以外は null
steps[].handoffobject | nullこの工程の実行で次の工程に渡した値と資料。工程に次の工程に渡す値と資料の役割(outputConfig)が無ければ null
steps[].handoff.valuesobject値の名前 → 返された文(1 つ 1,000 文字まで)
steps[].handoff.filesobject役割の名前 → { filename }(その役割の資料のファイル名)
steps[].handoff.missing[]object[]届かなかった物。name(値か役割の名前)と reason("not_returned"〈Agent が返さなかった〉/ "file_not_found"〈成果物に無い〉)
steps[].handoff.truncatedstring[]1,000 文字で切った値の名前。無ければ []
plannedPlacementsarray開始したときの設定で、動く予定の工程と配置の並び
plannedPlacements[].stepIdstring | null工程の ID(UUID)
plannedPlacements[].placementIdstring | null配置の ID(UUID)。確認の工程と Agent の無い工程では null
lanesarray分岐した後の、レーンごとの状況。分岐する前と、レーンを使わない実行では空の配列
lanes[].laneIdstringレーンの ID
lanes[].namestring | nullレーンの名前
lanes[].positionnumber | nullレーンの並び(1 から)
lanes[].statestring"running"(実行中)/ "waiting_gate"(確認待ち)/ "arrived"(合流待ち)/ "closed"(終了)のいずれか
lanes[].currentStepIdstring | nullそのレーンで進んでいる工程の ID(UUID)。合流待ちのレーンでは null。終わったレーンでは、最後の工程の ID が残る場合があります
lanes[].arrivedboolean合流する地点に着いたか

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

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

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説明
400invalid_parameterprojectId または runId が UUID の形式ではない
403insufficient_scopeproject:read スコープが不足
403invalid_project_grantプロジェクト制限が未設定、または設定内容が不正
404run_not_found実行が存在しない、別のプロジェクトの実行を指定した、またはアクセス権が無い

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

実行中か確認待ちのワークフローの実行(status が "running"・"waiting_gate")を中断します。画面の「中断する」と同じです。

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

  • ワークフローの実行の status が "cancelled"(中断)になります。元に戻せず、再開もできません(再開できるのは、却下・失敗で閉じたワークフローの実行だけです)。
  • 進行中の工程は失敗の扱いになり、動いている Agent には停止を伝えます。
  • 確認工程の、まだ判断されていない確認依頼は取り下げられます。

パスパラメータ​

パラメータ型必須説明
projectIdstring必須プロジェクト ID(UUID)
runIdstring必須ワークフローの実行の ID(UUID)

リクエストボディ​

フィールド型必須説明
commandIdstring必須送り直しを見分ける値(英数字と _ . : - の 8〜128 文字)
reasonstring—中断の理由(500 文字まで)
  • 動いていないワークフローの実行(終わった後・中断した後)に送ると、何も変えずに 200 OK が返り、existing が true です。中断した後に送り直したときも同じです。
  • ほかの中断や、ワークフローの実行が終わるのと同じころに送ると、202 Accepted と 200 OK の別と existing が、実際と合わないことがあります。結果は、ワークフローの実行の取得(GET /v1/projects/{projectId}/runs/{runId})の status で確かめてください。
  • 504 Gateway Timeout は「中断されなかった」ことを意味しません。同じ commandId で送り直すか、ワークフローの実行の取得で status を確かめてください。

リクエスト例​

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

レスポンスフィールド(202 Accepted / 200 OK)​

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

フィールド型説明
runIdstringワークフローの実行の ID
statusstring送った後のワークフローの実行の状態(中断したときは "cancelled")
cancelRequestedAtstring | null中断を受けた日時(ISO 8601)。中断されていないワークフローの実行では null
existingbooleanこの要求で新しく中断しなかったとき true(202 Accepted のときはいつも false)

レスポンス例​

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

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId・runId が UUID の形式ではない、commandId が無い・形の誤り、または reason が文字列ではない・500 文字を超える
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
403insufficient_scopeproject:run スコープが不足
403invalid_project_grantプロジェクト制限が未設定、または設定内容が不正
404run_not_foundワークフローの実行が存在しない、ほかのプロジェクトのもの、またはアクセス権の無いプロジェクト
413body_too_largeボディが 16 KiB を超える
415unsupported_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.typestringエラーの分類。"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.messagestring人間が読めるエラーメッセージ
error.codestring機械的に処理可能なエラーコード(例: "missing_parameter"、"invalid_parameter"、"invalid_token")
error.paramstringエラーの原因となったパラメータ名。バリデーションエラー時のみ含まれます
error.suggested_actionstring推奨される対処方法。一部のエラーでのみ含まれます
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説明
403waf_blockedリクエストが、API の前段にあるセキュリティの検査に止められました。正当なリクエストの場合は、error.reference(無い場合は応答ヘッダーの x-request-id)を添えてお問い合わせください
403 以外の 4xx・5xxupstream_api_errorリクエストが、API の前段の仕組みで拒否されたか、そこでエラーになりました。続く場合は、error.reference(無い場合は応答ヘッダーの x-request-id)を添えてお問い合わせください
フィールド型説明
error.referencestring前段の仕組みで止められたときの参照番号。お問い合わせのときに添えてください。値が無い場合は含まれません
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