ユーザー管理、ログ閲覧、マスターデータ管理、共有メモリ検索、プロジェクト操作の API リファレンスです。エンドユーザー向けの Chat / Conversations / Files / Search / 公開マスターデータ API は ユーザー API リファレンス、MCP / A2A の接続方式は 接続方式ガイド を参照してください。
本リファレンスに掲載しているエンドポイントはすべて SaaS 版でのみ提供 されます。Marketplace 版では管理操作は管理コンソールからのみ実施可能です。
ベース URL
すべての API リクエストは以下のベース URL に対して送信します。
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 つの方式があります。エンドポイントごとにどちらかが決まっています。組織・職種の一覧はページネーション非対応で、常に全件が返されます。
ページベース
| パラメータ | 型 | 説明 |
|---|
limit | integer | 1ページあたりの取得件数。1 〜 100(デフォルト 25) |
page | integer | ページ番号。1 以上(デフォルト 1) |
レスポンスには total, limit, page, hasMore が含まれます。hasMore が true の場合、page を 1 増やすことで次ページを取得できます。
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users?limit=25&page=1" \
-H "Authorization: Bearer <access_token>"
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 操作監査・アクセスログ・ガードレールアラート)です。
カーソルベース
| パラメータ | 型 | 説明 |
|---|
limit | integer | 1ページあたりの取得件数(1-100)。デフォルトは 50 件です |
cursor | string | 次のページを取得するためのカーソル値。前回のレスポンスに含まれる cursor をそのまま指定します |
レスポンスには hasMore が含まれます。true の場合、cursor の値を次のリクエストに渡すことで次ページを取得できます。cursor は不透明な値のため、内容を解釈せず、前回レスポンスの値をそのまま指定してください。
対応しているのは、プロジェクト一覧と利用者の操作の監査の一覧です。page は使いません(指定しても無視されます)。
共有メモリ SaaS
組織・職種に基づく共有メモリ(ナレッジ)を検索します。
エンドポイント一覧
| メソッド | エンドポイント | 説明 | スコープ |
|---|
| POST | /v1/admin/memory/query | 共有メモリを検索 | sharedmemory:query |
POST/v1/admin/memory/query
共有メモリを検索します。
リクエストボディ
| パラメータ | 型 | 必須 | 説明 |
|---|
query | string | 必須 | 検索クエリ(最大500文字) |
orgId | string | — | 組織ID(最大100文字)。指定すると組織スコープのメモリも検索対象に含まれます |
jobRole | string | — | 職種(最大100文字)。指定すると職種スコープのメモリも検索対象に含まれます |
リクエスト例
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"}'
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/memory/query \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{"query": "売上レポートの作成手順", "orgId": "sales"}'import requests
response = requests.post(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/memory/query",
headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
json={"query": "売上レポートの作成手順", "orgId": "sales"},
)
response.raise_for_status() # 502 / 504 は一時的な障害。時間をおいて再試行する
data = response.json()
for memory in data.get("memories", []):
print(f"[{memory['type']}] {memory['text']}")const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/memory/query",
{
method: "POST",
headers: {
"Authorization": "Bearer " + accessToken,
"Content-Type": "application/json",
},
body: JSON.stringify({ query: "売上レポートの作成手順", orgId: "sales" }),
}
);
if (!response.ok) {
// 502 / 504 は一時的な障害。時間をおいて再試行する
throw new Error(`memory query failed: ${response.status}`);
}
const data = await response.json();
(data.memories ?? []).forEach((m) => {
console.log(`[${m.type}] ${m.text}`);
});body, _ := json.Marshal(map[string]string{
"query": "売上レポートの作成手順",
"orgId": "sales",
})
req, _ := http.NewRequest("POST",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/memory/query",
bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
レスポンスフィールド(200 OK)
| フィールド | 型 | 説明 |
|---|
memories | array | メモリオブジェクトの配列 |
memories[].text | string | メモリの内容テキスト |
memories[].type | string | "knowledge"(ナレッジ) |
memories[].scope | string | "organization"、"role"、"global" のいずれか |
memories[].createdAt | string | null | 作成日時(ISO 8601形式) |
memories[].score | number? | 関連度スコア。スコア値がない場合はフィールド自体が省略される |
レスポンスヘッダー
| ヘッダー | 説明 |
|---|
X-RateLimit-Limit | 月間リクエスト上限数 |
X-RateLimit-Remaining | 残りリクエスト数 |
X-RateLimit-Reset | 制限リセット日時(次月初、ISO 8601形式) |
レスポンス例
{
"memories": [
{
"text": "売上レポートはダッシュボードの「月次レポート」タブから作成できます",
"type": "knowledge",
"scope": "organization",
"createdAt": "2026-03-15T10:30:00.000Z",
"score": 0.85
}
]
}
エラーレスポンス
| ステータス | 説明 |
|---|
400 | query が未指定、空文字、または500文字超過。またはボディが壊れた JSON(code: "invalid_body") |
415 | ボディの Content-Type が application/json ではない(code: "unsupported_media_type") |
403 | sharedmemory:query スコープが不足 |
429 | 月間クォータ超過(error.type: rate_limit_error、error.code: monthly_quota_exceeded) |
502 | 上流サービスとの通信エラー(error.type: upstream_error) |
504 | 上流サービスの応答タイムアウト(error.type: upstream_error、error.code: upstream_timeout) |
検索が成立して該当が 0 件の場合は 200 で memories が空配列になります。上流障害時は空配列ではなく 502 / 504 を返すため、200 の空配列を障害として扱う必要はありません。
ユーザー管理 SaaS
ユーザーの一覧取得・作成・削除・ロール変更・承認・承認取り消し・利用の停止と再開・ロックの解除・所属と職種の変更を行います。
エンドポイント一覧
| メソッド | エンドポイント | 説明 | スコープ |
|---|
| GET | /v1/admin/users | ユーザー一覧を取得 | users:read / users:manage |
| GET | /v1/admin/users/:userId/passkeys | ユーザーのパスキーの一覧を取得 | users:read / users:manage |
| POST | /v1/admin/users | ユーザーを作成 | users:manage |
| DELETE | /v1/admin/users/:userId | ユーザーを削除 | users:manage |
| PUT | /v1/admin/users/:userId/role | ユーザーのロールを変更 | users:manage |
| POST | /v1/admin/users/:userId/approve | ユーザーを承認 | users:manage |
| POST | /v1/admin/users/:userId/reject | ユーザーの承認を取り消し | users:manage |
| POST | /v1/admin/users/:userId/suspend | ユーザーの利用を止める | users:manage |
| POST | /v1/admin/users/:userId/resume | 止めた利用を戻す | users:manage |
| POST | /v1/admin/users/:userId/unlock | ユーザーのロックを解く | users:manage |
| PUT | /v1/admin/users/:userId/affiliation | ユーザーの所属と職種を変える | users:manage |
GET/v1/admin/users
ユーザー一覧を取得します。ページベースのページネーションに対応しています。users:read または users:manage スコープのいずれかが必要です(users:manage は users:read の権限を含みます)。
クエリパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|
limit | integer | — | 取得件数(1〜100、デフォルト: 25) |
page | integer | — | ページ番号(1以上、デフォルト: 1) |
role | string | — | ロールフィルター。"admin"(管理者だけ)または "user"(管理者を除いた利用者だけ) |
is_approved | string | — | 承認状態フィルター。"true" または "false"。停止中の利用者は true に入ります |
search | string | — | 検索文字列(最大100文字)。メールアドレス等で検索 |
organization | string | — | 組織コードフィルター(コードの完全一致。大文字と小文字を区別。最大50文字、英数字・ハイフン・アンダースコア) |
job_type | string | — | 職種コードフィルター(コードの完全一致。大文字と小文字を区別。最大50文字、英数字・ハイフン・アンダースコア) |
order | string | — | 並び順。"asc" または "desc"(デフォルト: "desc")。登録日時で並べます。ほかの値は 400 |
リクエスト例
1curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users?limit=10&is_approved=true" \
2-H "Authorization: Bearer <access_token>"
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users?limit=10&is_approved=true" \
-H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users",
headers={"Authorization": f"Bearer {token}"},
params={"limit": 10, "is_approved": "true"},
)
data = response.json()
for user in data["users"]:
print(f"{user['email']} ({user['role']}, {user['status']})")const params = new URLSearchParams({ limit: "10", is_approved: "true" });
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users?" + params,
{
headers: { "Authorization": "Bearer " + accessToken },
}
);
const data = await response.json();
data.users.forEach((user) => {
console.log(user.email + " (" + user.role + ", " + user.status + ")");
});req, _ := http.NewRequest("GET",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users?limit=10&is_approved=true",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
レスポンスフィールド(200 OK)
| フィールド | 型 | 説明 |
|---|
users | array | ユーザーオブジェクトの配列 |
users[].userId | string | ユーザーID |
users[].email | string | メールアドレス |
users[].username | string | ユーザー名 |
users[].emailVerified | boolean | メールアドレスの検証状態 |
users[].role | string | ロール("admin" または "user") |
users[].status | string | ステータス("unverified"、"pending"、"approved"、"suspended")。"suspended" は管理コンソールで利用を停止した承認済みの利用者(ログインできない) |
users[].organization | object? | 所属組織(value: コード、label: 名称)。未設定時はフィールド自体が省略される |
users[].jobType | object? | 職種(value: コード、label: 名称)。未設定時はフィールド自体が省略される |
users[].bio | string? | 自己紹介。未設定時はフィールド自体が省略される |
users[].createdAt | string | 作成日時(ISO 8601形式) |
users[].lastLoginAt | string? | 最終ログイン日時(ISO 8601形式)。未ログイン時はフィールド自体が省略される |
users[].idpSynced | boolean | IdP(ID 基盤)から同期している利用者か。true の利用者の設定済みの所属・職種は、PUT /v1/admin/users/:userId/affiliation で変えられない(409 affiliation_managed_by_idp) |
total | integer | 総件数 |
limit | integer | 取得件数 |
page | integer | ページ番号 |
hasMore | boolean | 次ページが存在するか |
レスポンス例(200 OK)
{
"users": [
{
"userId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"email": "user1@example.com",
"username": "user1@example.com",
"emailVerified": true,
"role": "user",
"status": "approved",
"createdAt": "2026-04-19T13:02:26.198Z",
"idpSynced": false
},
{
"userId": "90b40fd8-a6b8-42b8-ab61-f3b674169b43",
"email": "user2@example.com",
"username": "user2",
"emailVerified": true,
"role": "user",
"status": "approved",
"organization": { "value": "sales", "label": "営業部" },
"jobType": { "value": "engineer", "label": "エンジニア" },
"createdAt": "2026-04-17T07:09:47.484Z",
"idpSynced": true
},
{
"userId": "463e2c25-5a80-4362-b77e-941df96fb1f2",
"email": "admin@example.com",
"username": "admin@example.com",
"emailVerified": true,
"role": "admin",
"status": "approved",
"createdAt": "2026-04-17T07:02:41.015Z",
"lastLoginAt": "2026-04-17T07:18:17.488Z",
"idpSynced": false
}
],
"total": 132,
"limit": 3,
"page": 1,
"hasMore": true
}
エラーレスポンス
| ステータス | 説明 |
|---|
400 | クエリパラメータが不正 |
403 | users:read または users:manage スコープが不足 |
GET/v1/admin/users/:userId/passkeys
ユーザーが登録したパスキーの一覧を取得します。users:read または users:manage スコープのいずれかが必要です。パスキーを消すのは管理コンソールで行います(この API では消せません)。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|
userId | string | 必須 | ユーザーID |
リクエスト例
1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/bbbe4306-6975-420b-af47-fb4c8f48b4aa/passkeys \
2-H "Authorization: Bearer <access_token>"
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/bbbe4306-6975-420b-af47-fb4c8f48b4aa/passkeys \
-H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/bbbe4306-6975-420b-af47-fb4c8f48b4aa/passkeys",
headers={"Authorization": f"Bearer {token}"},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/bbbe4306-6975-420b-af47-fb4c8f48b4aa/passkeys",
{
headers: {
"Authorization": "Bearer " + accessToken,
},
}
);
const data = await response.json();
console.log(data);req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/bbbe4306-6975-420b-af47-fb4c8f48b4aa/passkeys", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
レスポンスフィールド
| フィールド | 型 | 説明 |
|---|
passkeys | array | パスキーの配列(全件) |
passkeys[].credentialId | string | パスキーの ID |
passkeys[].label | string | null | パスキーの名前 |
passkeys[].createdAt | string | null | 登録した日時(ISO 8601) |
passkeys[].lastUsedAt | string | null | 最後に使った日時(ISO 8601)。使っていなければ null |
hasMore | boolean | いつも false(全件を返します) |
レスポンス例(200 OK)
{
"passkeys": [
{
"credentialId": "AbCdEf0123456789_-AbCdEf0123456789_-AbCdEf0",
"label": "業務用 PC",
"createdAt": "2026-10-01T02:30:00.000Z",
"lastUsedAt": "2026-11-17T23:45:10.000Z"
}
],
"hasMore": false
}
エラーレスポンス
| ステータス | 説明 |
|---|
403 | users:read または users:manage スコープが不足 |
404 | ユーザーが見つからない |
POST/v1/admin/users
ユーザーを 1 人作ります。users:manage スコープが必要です。作ったユーザーは承認済み(status は "approved")で、契約の利用者数に入ります。
password を送らなかったときは一時パスワードを作り、作ったときの応答で 1 回だけ temporaryPassword として返します。あとから読むことはできないので、本人に伝えてください。この応答には Cache-Control: no-store が付きます。
- 知らせのメール(
sendNotificationEmail)に、パスワードは入りません。
- 同じメールアドレスのユーザーを同時に作ったり、契約の利用者数の残りが 1 のときに同時に作ったりすると、500 になったり、上限を超えて作られたりすることがあります。1 人ずつ続けて作ってください。
リクエストボディ
| パラメータ | 型 | 必須 | 説明 |
|---|
email | string | 必須 | メールアドレス。前後の空白を除いて小文字にします(255 文字まで) |
displayName | string | 必須 | 表示名(255 文字まで)。前後の空白を除き、< と > は消します |
role | string | 必須 | "admin" または "user" |
organization | string | 必須 | 組織のコード(GET /v1/organizations の値) |
job | string | 必須 | 職種のコード(GET /v1/job-types の値) |
bio | string | — | 自己紹介(255 文字まで)。前後の空白を除き、< と > は消します |
password | string | — | 初めのパスワード。パスワードの決まりを満たさないと 400。送らなければ一時パスワードを作り、応答の temporaryPassword で返します |
temporary | boolean | — | 初めのサインインでパスワードを変えさせるか。省略時は、password を送らなければ true、送れば false |
sendNotificationEmail | boolean | — | 作ったことを本人にメールで知らせるか。省略時は true。メールを送れない環境では送られず、応答の emailSent が false になります |
リクエスト例
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"}'
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{"email": "new.user@example.com", "displayName": "新しい利用者", "role": "user", "organization": "ORG001", "job": "JOB01"}'import requests
response = requests.post(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users",
headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
json={
"email": "new.user@example.com",
"displayName": "新しい利用者",
"role": "user",
"organization": "ORG001",
"job": "JOB01",
},
)const response = await fetch("https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users", {
method: "POST",
headers: {
"Authorization": "Bearer " + accessToken,
"Content-Type": "application/json",
},
body: JSON.stringify({
email: "new.user@example.com",
displayName: "新しい利用者",
role: "user",
organization: "ORG001",
job: "JOB01",
}),
});body, _ := json.Marshal(map[string]string{
"email": "new.user@example.com",
"displayName": "新しい利用者",
"role": "user",
"organization": "ORG001",
"job": "JOB01",
})
req, _ := http.NewRequest("POST",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users",
bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
レスポンスフィールド(201 Created)
| フィールド | 型 | 説明 |
|---|
user | object | 作ったユーザー。ユーザー一覧の users[] と同じ項目です(status は "approved"、idpSynced は false) |
emailSent | boolean | 知らせのメールを送ったか |
temporaryPassword | string? | password を送らなかったときだけ。作った一時パスワード(この応答で 1 回だけ返ります) |
レスポンス例(201 Created)
{
"user": {
"userId": "5d1c9b2e-8f4a-4c3b-9e7d-1a2b3c4d5e6f",
"email": "new.user@example.com",
"username": "new.user@example.com",
"emailVerified": true,
"role": "user",
"status": "approved",
"organization": { "value": "ORG001", "label": "営業部" },
"jobType": { "value": "JOB01", "label": "エンジニア" },
"createdAt": "2026-11-10T09:00:00.000Z",
"idpSynced": false
},
"emailSent": true,
"temporaryPassword": "<一時パスワード>"
}
エラーレスポンス
| ステータス | 説明 |
|---|
400 | email・displayName・role・organization・job が無い、これらと bio が文字列ではない・空・空白だけ(displayName・organization・job・bio は < と > を消すと空白だけになる値も)、role が "admin"・"user" 以外、displayName・bio が 255 文字を超える、password が空・空白だけ、temporary・sendNotificationEmail が真偽値ではない、メールアドレスの形が違う、組織・職種のコードが違う、またはパスワードが決まりを満たさない(code: "invalid_parameter") |
400 | ボディが壊れた JSON、または JSON のオブジェクトではない(code: "invalid_body") |
415 | ボディの Content-Type が application/json ではない(code: "unsupported_media_type") |
401 | トークンが無効または未指定(code: "invalid_token") |
403 | users:manage スコープが不足(code: "insufficient_scope") |
409 | 同じメールアドレスのユーザーがいる(code: "user_exists"。param は email)。別のメールアドレスで作ってください |
409 | 契約の利用者数の上限に達した(code: "conflict") |
429 | 送り元の IP ごとの回数の上限(1 時間に 30 回)を超えた(code: "rate_limit_exceeded")。少し待ってから送り直してください |
500・502・504 | ユーザーが作られたかもしれない。GET /v1/admin/users?search=<email> で確かめてから送り直してください(作られていれば、送り直すと 409 user_exists)。作られていて一時パスワードを受け取れなかったときは、本人がサインインの画面の「パスワードを忘れた方はこちら」から設定します。メールを送れない環境では、管理コンソールでパスワードを設定し直します |
503 | 契約の利用者数の上限を確かめられない。少し待ってから送り直してください |
DELETE/v1/admin/users/:userId
ユーザーを削除します。削除したユーザーは、管理コンソール・チャットの画面と API から消え、元に戻せません。アーカイブした会話・会話ごとの作業のメモ・利用者ごとの設定の記録の削除を希望する場合は、管理者ガイドを参照してください。users:manage スコープが必要です。削除の前にそのユーザーに発行されていたアクセストークンは、削除の後も、有効期限(トークンを取得したときの expires_in)まで使えることがあります。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|
userId | string | 必須 | ユーザーID |
リクエスト例
1curl -X DELETE https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID \
2-H "Authorization: Bearer <access_token>"
curl -X DELETE https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID \
-H "Authorization: Bearer <access_token>"
import requests
response = requests.delete(
f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/{user_id}",
headers={"Authorization": f"Bearer {token}"},
)const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/${userId}`,
{
method: "DELETE",
headers: { "Authorization": "Bearer " + accessToken },
}
);req, _ := http.NewRequest("DELETE",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/"+userID,
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
レスポンス例(200 OK)
{ "userId": "abc123", "deleted": true }
エラーレスポンス
| ステータス | 説明 |
|---|
403 | users:manage スコープが不足 |
404 | 指定されたユーザーが見つからない(既に削除済みを含む) |
429 | 送り元の IP ごとの回数の上限(1 分に 10 回)を超えた(code: "rate_limit_exceeded")。少し待ってから送り直してください |
500 | 利用者のデータの一部を消せなかったため、削除を止めた(code: "user_delete_incomplete")。ユーザーは残っています。もう一度削除してください |
PUT/v1/admin/users/:userId/role
ユーザーのロールを変更します。ステータスが approved のユーザーと、emailVerified が true の suspended のユーザーのみ変更可能です。
user への降格時: 対象ユーザーのログイン中のセッションは自動では終わりません。すでに発行されたアクセストークンの権限は、有効期限まで変わりません
admin への昇格時: 対象ユーザーのセッションは継続され、新しい権限は、昇格の後に発行されるトークンから有効になります
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|
userId | string | 必須 | ユーザーID |
リクエストボディ
| パラメータ | 型 | 必須 | 説明 |
|---|
role | string | 必須 | 変更先のロール。"admin" または "user" |
リクエスト例
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"}'
curl -X PUT https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/role \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{"role": "admin"}'import requests
response = requests.put(
f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/{user_id}/role",
headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
json={"role": "admin"},
)const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/${userId}/role`,
{
method: "PUT",
headers: {
"Authorization": "Bearer " + accessToken,
"Content-Type": "application/json",
},
body: JSON.stringify({ role: "admin" }),
}
);body, _ := json.Marshal(map[string]string{"role": "admin"})
req, _ := http.NewRequest("PUT",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/"+userID+"/role",
bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
レスポンス例(200 OK)
{ "userId": "abc123", "changed": true }
エラーレスポンス
| ステータス | 説明 |
|---|
400 | role が未指定または不正、ボディが壊れた JSON(code: "invalid_body")、または対象ユーザーが、ステータス approved でも、emailVerified が true の suspended でもない |
415 | ボディの Content-Type が application/json ではない(code: "unsupported_media_type") |
403 | users:manage スコープが不足 |
404 | ユーザーが見つからない |
409 | 同じ利用者のほかの更新(承認・ロールの変更・プロフィールの更新など)の処理中(code: "conflict")。少し待ってから送り直してください |
429 | 送り元の IP ごとの回数の上限(1 分に 100 回)を超えた(code: "rate_limit_exceeded")。少し待ってから送り直してください |
500 | ロールの変更を終えられなかった(code: "internal_error")。ユーザーを取得し直して今のロールを確かめ、必要なら同じ変更をもう一度送ってください |
POST/v1/admin/users/:userId/approve
ユーザーを承認します。ステータスが pending のユーザーのみ承認可能です。承認を取り消した(止めた)ユーザーも pending と表示され、承認できます。承認するとログインできるようになり、データも残っていますが、取り消しで止まった物(実行中の会話・個人の定期の実行・持ち主のプロジェクトの巡回と実行)と削除した外部サービスへの接続は、自動では戻りません。
承認処理が成功すると、対象ユーザーのメールアドレス宛に承認通知メールが自動送信されます。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|
userId | string | 必須 | ユーザーID |
リクエストボディ(任意)
| パラメータ | 型 | 必須 | 説明 |
|---|
reason | string | — | 承認の理由。空でない場合は、利用者の情報に記録されます |
リクエスト例
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/approve \
2-H "Authorization: Bearer <access_token>"
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/approve \
-H "Authorization: Bearer <access_token>"
import requests
response = requests.post(
f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/{user_id}/approve",
headers={"Authorization": f"Bearer {token}"},
)const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/${userId}/approve`,
{
method: "POST",
headers: { "Authorization": "Bearer " + accessToken },
}
);req, _ := http.NewRequest("POST",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/"+userID+"/approve",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
レスポンス例(200 OK)
{ "userId": "abc123", "approved": true }
エラーレスポンス
| ステータス | 説明 |
|---|
400 | ユーザーのステータスが pending 以外(承認不可。メールを確かめていない、または承認済み〈停止中を含む〉) |
400 | reason が文字列ではない、またはボディが壊れた JSON・JSON のオブジェクトではない(code: "invalid_body") |
415 | ボディの Content-Type が application/json ではない(code: "unsupported_media_type") |
403 | users:manage スコープが不足 |
404 | ユーザーが見つからない |
429 | 送り元の IP ごとの回数の上限(1 分に 10 回)を超えた(code: "rate_limit_exceeded")。少し待ってから送り直してください |
409 | 取得した後に別の操作で承認された、契約の利用者数の上限に達した、または同じ利用者のほかの更新の処理中(code: "conflict") |
500 | 承認を反映できなかった(変更をチャットに伝えられなかった。ユーザーはまだ承認されていない)(code: "user_suspension_incomplete")。同じ要求を送り直してください(何度でも送り直せます) |
POST/v1/admin/users/:userId/reject
ユーザーの承認を取り消します。ステータスが approved のユーザーと、emailVerified が true の suspended のユーザーのみ取り消し可能です(取り消し済みのユーザーも、もう一度取り消せます。やり直しです)。取り消すと、ユーザーは無効になり、ログインできなくなります。契約のアカウント数から外れます。会話・ファイル・スケジュールなどのデータは残ります。止めるもの(実行中の会話と個人の定期の実行、持ち主のプロジェクトの巡回と開いている実行、本人の外部サービスへの接続の削除)は停止(/suspend)と同じで、再承認(approve)してもそれらは自動では戻りません。停止(/suspend)はアカウント数に数えたまま、取り消しは数から外れます。取り消し後のステータスは pending と表示されます。取り消しの前にそのユーザーに発行されていたアクセストークンは、取り消しの後も、有効期限(トークンを取得したときの expires_in)まで使えることがあります。
承認済みのユーザーを取り消したときに、1 度だけ、対象ユーザーのメールアドレス宛に通知メールが自動送信されます。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|
userId | string | 必須 | ユーザーID |
リクエスト例
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/reject \
2-H "Authorization: Bearer <access_token>"
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/reject \
-H "Authorization: Bearer <access_token>"
import requests
response = requests.post(
f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/{user_id}/reject",
headers={"Authorization": f"Bearer {token}"},
)const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/${userId}/reject`,
{
method: "POST",
headers: { "Authorization": "Bearer " + accessToken },
}
);req, _ := http.NewRequest("POST",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/"+userID+"/reject",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
レスポンス例(200 OK)
{ "userId": "abc123", "status": "pending" }
エラーレスポンス
| ステータス | 説明 |
|---|
400 | ユーザーが、ステータス approved でも、emailVerified が true の suspended でもない(取り消し不可)。取り消し済みのユーザーも、もう一度取り消せます(やり直し。メールは送りません) |
403 | users:manage スコープが不足 |
404 | ユーザーが見つからない |
429 | 送り元の IP ごとの回数の上限(1 分に 10 回)を超えた(code: "rate_limit_exceeded")。少し待ってから送り直してください |
409 | 同じ利用者のほかの更新の処理中(code: "conflict") |
500 | 承認は取り消されているが、利用の停止をチャットに伝えられなかった(code: "user_suspension_incomplete")。ユーザーは無効・承認なしのままです。同じ要求を送り直すと、停止をやり直します |
POST/v1/admin/users/:userId/suspend
ユーザーの利用を止めます。承認の状態とデータは残り、一覧の status が "suspended" になります。止めたユーザーはログインできません。ログイン中のセッションの終了も試みます(終わらせられなかったときも停止は成功として返り、同じ要求を送り直すともう一度試みます)。止めると、そのユーザーが実行中の会話と個人の定期の実行が止まり、そのユーザー本人の外部サービスへの接続が削除され(プロジェクトの接続は残ります)、そのユーザーが持ち主のプロジェクトの巡回と開いているワークフローの実行も止まります(プロジェクトの定義は残ります)。止めを解いても、止まったものは自動では元に戻りません。止めたユーザーが持ち主のプロジェクトでは、ワークフローの実行の開始と閉じた実行の再開が 409 Conflict(principal_suspended)で断られます。止められるのは承認済みのユーザーだけです。同じ操作を何度送っても結果は同じです。テナント経由で発行したトークンは、そのトークンの idp.sub のユーザー自身を止められません(409)。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|
userId | string | 必須 | ユーザーID |
ボディは要りません(送っても使いません)。
リクエスト例
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/suspend \
2-H "Authorization: Bearer <access_token>"
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/suspend \
-H "Authorization: Bearer <access_token>"
import requests
response = requests.post(
f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/{user_id}/suspend",
headers={"Authorization": f"Bearer {token}"},
)const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/${userId}/suspend`,
{
method: "POST",
headers: { "Authorization": "Bearer " + accessToken },
}
);req, _ := http.NewRequest("POST",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/"+userID+"/suspend",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
レスポンス例(200 OK)
{ "userId": "abc123", "suspended": true }
エラーレスポンス
| ステータス | 説明 |
|---|
400 | ボディが壊れた JSON(code: "invalid_body") |
401 | トークンが無効または未指定(code: "invalid_token") |
403 | users:manage スコープが不足(code: "insufficient_scope") |
404 | ユーザーが見つからない(code: "user_not_found") |
409 | 止められないユーザー(承認済みでない・削除済み・恒久的にロックされている)、トークンの idp.sub のユーザー自身を止めようとした、または同じ利用者のほかの更新の処理中(code: "conflict")。どれに当たるかは、エラーの文と案内で分かります |
429 | 送り元の IP ごとの回数の上限(1 分に 10 回)を超えた(code: "rate_limit_exceeded")。少し待ってから送り直してください |
500 | 停止を最後まで終えられなかった(ログインは止めたが、チャットへの反映が終わらなかった)(code: "user_suspension_incomplete")。同じ要求を送り直してください |
500 | そのほかの誤り(code: "internal_error")。同じ要求を送り直してください |
POST/v1/admin/users/:userId/resume
止めたユーザーの利用を戻します。同じ操作を何度送っても結果は同じです。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|
userId | string | 必須 | ユーザーID |
ボディは要りません(送っても使いません)。
リクエスト例
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/resume \
2-H "Authorization: Bearer <access_token>"
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/resume \
-H "Authorization: Bearer <access_token>"
import requests
response = requests.post(
f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/{user_id}/resume",
headers={"Authorization": f"Bearer {token}"},
)const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/${userId}/resume`,
{
method: "POST",
headers: { "Authorization": "Bearer " + accessToken },
}
);req, _ := http.NewRequest("POST",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/"+userID+"/resume",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
レスポンス例(200 OK)
{ "userId": "abc123", "suspended": false }
エラーレスポンス
| ステータス | 説明 |
|---|
400 | ボディが壊れた JSON(code: "invalid_body") |
401 | トークンが無効または未指定(code: "invalid_token") |
403 | users:manage スコープが不足(code: "insufficient_scope") |
404 | ユーザーが見つからない(code: "user_not_found") |
409 | 戻せないユーザー(承認済みでない・削除済み・恒久的にロックされている)、または同じ利用者のほかの更新の処理中(code: "conflict")。どれに当たるかは、エラーの文と案内で分かります |
429 | 送り元の IP ごとの回数の上限(1 分に 10 回)を超えた(code: "rate_limit_exceeded")。少し待ってから送り直してください |
500 | 戻すのを最後まで終えられず、まだ止まったまま(code: "user_suspension_incomplete")。同じ要求を送り直してください |
500 | そのほかの誤り。チャットの側は戻したがログインの側を戻せなかったときも、これになります(code: "internal_error")。同じ要求を送り直してください |
POST/v1/admin/users/:userId/unlock
ログインの失敗でロックされたユーザーのロックを解きます。ロックされていなかったときは何も変えず、wasLocked が false になります。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|
userId | string | 必須 | ユーザーID |
ボディは要りません(送っても使いません)。
リクエスト例
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/unlock \
2-H "Authorization: Bearer <access_token>"
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/unlock \
-H "Authorization: Bearer <access_token>"
import requests
response = requests.post(
f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/{user_id}/unlock",
headers={"Authorization": f"Bearer {token}"},
)const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/${userId}/unlock`,
{
method: "POST",
headers: { "Authorization": "Bearer " + accessToken },
}
);req, _ := http.NewRequest("POST",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/"+userID+"/unlock",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
レスポンス例(200 OK)
{ "userId": "abc123", "wasLocked": true }
エラーレスポンス
| ステータス | 説明 |
|---|
400 | ボディが壊れた JSON(code: "invalid_body") |
401 | トークンが無効または未指定(code: "invalid_token") |
403 | users:manage スコープが不足(code: "insufficient_scope") |
404 | ユーザーが見つからない(code: "user_not_found") |
409 | 同じ利用者のほかの更新の処理中(code: "conflict")。少し待ってから送り直してください |
429 | 送り元の IP ごとの回数の上限(1 分に 100 回)を超えた(code: "rate_limit_exceeded")。少し待ってから送り直してください |
500 | ロックの解除を終えられなかった(code: "internal_error")。同じ要求を送り直してください |
PUT/v1/admin/users/:userId/affiliation
ユーザーの所属(組織のコード)と職種(職種のコード)を変えます。どちらも要ります。コードは GET /v1/organizations・GET /v1/job-types で引けます。答えに変える前と後の値が入ります(前の値が未設定なら null)。所属を変えると、新しい所属以外の組織の、組織管理者と組織の運用の役割は外れます(監査役は外れません)。500 のときは、所属と職種がもう変わっていることがあります。同じ要求を送り直すと、組織の役割の整理がやり直されます。IdP から同期している利用者(GET /v1/admin/users の users[].idpSynced が true の利用者)の、設定済みの所属・職種は変えられません(409 affiliation_managed_by_idp)。利用者を同期している ID 基盤(IdP)で変えてください。未設定の方だけを埋めるときは、設定済みの方に今の値(GET /v1/admin/users の users[].organization.value・users[].jobType.value)を送ります。無効なコードは、この判定より先に 400 になります。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|
userId | string | 必須 | ユーザーID |
リクエストボディ
| パラメータ | 型 | 必須 | 説明 |
|---|
organization | string | 必須 | 組織のコード(GET /v1/organizations の値) |
job | string | 必須 | 職種のコード(GET /v1/job-types の値) |
リクエスト例
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"}'
curl -X PUT https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/affiliation \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{"organization": "ORG002", "job": "JOB01"}'import requests
response = requests.put(
f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/{user_id}/affiliation",
headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
json={"organization": "ORG002", "job": "JOB01"},
)const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/${userId}/affiliation`,
{
method: "PUT",
headers: {
"Authorization": "Bearer " + accessToken,
"Content-Type": "application/json",
},
body: JSON.stringify({ organization: "ORG002", job: "JOB01" }),
}
);body, _ := json.Marshal(map[string]string{"organization": "ORG002", "job": "JOB01"})
req, _ := http.NewRequest("PUT",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/"+userID+"/affiliation",
bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
レスポンス例(200 OK)
{
"userId": "abc123",
"previous": { "organization": "ORG001", "job": null },
"current": { "organization": "ORG002", "job": "JOB01" }
}
エラーレスポンス
| ステータス | 説明 |
|---|
400 | organization・job が無い、文字列ではない、または組織・職種のコードが違う(code: "invalid_parameter") |
400 | ボディが壊れた JSON、または JSON のオブジェクトではない(code: "invalid_body") |
415 | ボディの Content-Type が application/json ではない(code: "unsupported_media_type") |
401 | トークンが無効または未指定(code: "invalid_token") |
403 | users:manage スコープが不足(code: "insufficient_scope") |
404 | ユーザーが見つからない(code: "user_not_found") |
409 | 同じ利用者のほかの更新の処理中(code: "conflict")。少し待ってから送り直してください |
409 | この利用者の所属・職種は IdP から同期しているので変えられない(code: "affiliation_managed_by_idp")。利用者を同期している ID 基盤(IdP)で変えてください。未設定の方だけを埋めるときは、設定済みの方に今の値を送ってください |
429 | 送り元の IP ごとの回数の上限(1 分に 100 回)を超えた(code: "rate_limit_exceeded")。少し待ってから送り直してください |
500 | 所属と職種の変更を最後まで終えられなかった(code: "internal_error")。所属と職種がもう変わっていることがあります。同じ要求を送り直すと、組織の役割の整理がやり直されます |
ログ SaaS
監査ログ・操作監査ログ・利用者の操作の監査・LLMログ・LLM Gateway ログ・LLM Gateway 操作監査・アクセスログ(外部への通信を許可・遮断した記録)・ガードレールアラートの閲覧を行います。一覧は、利用者の操作の監査だけがカーソルベース、ほかはページベースのページネーションに対応し、日付範囲フィルターが利用可能です。
エンドポイント一覧
| メソッド | エンドポイント | 説明 | スコープ |
|---|
| GET | /v1/admin/audit-logs | 監査ログ一覧を取得 | logs:read |
| GET | /v1/admin/user-action-logs | 利用者の操作の監査の一覧を取得 | logs:read |
| GET | /v1/admin/action-audit-logs | 操作監査ログ一覧を取得 | logs:read |
| GET | /v1/admin/llm-logs | LLMログ一覧を取得 | logs:read |
| GET | /v1/admin/llm-gateway-logs | LLM Gateway ログ一覧を取得 | logs:read |
| GET | /v1/admin/llm-gateway-action-logs | LLM Gateway 操作監査の一覧を取得 | logs:read |
| GET | /v1/admin/access-logs | アクセスログ一覧を取得 | logs:read |
| GET | /v1/admin/guardrail-alerts | ガードレールアラート一覧を取得 | logs:read |
共通クエリパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|
limit | integer | — | 取得件数(1〜100、デフォルト: 25。利用者の操作の監査はデフォルト: 50) |
page | integer | — | ページ番号(1以上、デフォルト: 1)。利用者の操作の監査は使いません(cursor を使います) |
from | string | — | 開始日(YYYY-MM-DD形式の実在する日付、UTC基準)。形式が違う値・実在しない日付・文字列ではない値は 400 |
to | string | — | 終了日(YYYY-MM-DD形式の実在する日付、UTC基準)。指定した日の終わりまでを含みます。形式が違う値・実在しない日付・文字列ではない値は 400 |
order | string | — | 並び順。"asc" または "desc"(デフォルト: "desc")。各ログの時刻の列で並べます。ほかの値は 400。アクセスログと利用者の操作の監査は新しい順の固定で、指定しても無視されます |
GET/v1/admin/audit-logs
監査ログ一覧を取得します。既定は作成日時の降順です(order で昇順にできます)。
絞り込みのクエリパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|
resource | string | — | リソース(resource)の完全一致 |
action | string | — | 操作(action)の完全一致 |
user_id | string | — | 操作した利用者の ID(userId)の完全一致 |
リクエスト例
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>"
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/audit-logs?limit=10&from=2026-04-01&to=2026-04-15" \
-H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/audit-logs",
headers={"Authorization": f"Bearer {token}"},
params={"limit": 10, "from": "2026-04-01", "to": "2026-04-15"},
)const params = new URLSearchParams({ limit: "10", from: "2026-04-01", to: "2026-04-15" });
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/audit-logs?" + params,
{
headers: { "Authorization": "Bearer " + accessToken },
}
);req, _ := http.NewRequest("GET",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/audit-logs?limit=10&from=2026-04-01&to=2026-04-15",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
レスポンスフィールド(200 OK)
| フィールド | 型 | 説明 |
|---|
auditLogs | array | 監査ログオブジェクトの配列 |
auditLogs[].auditLogId | string | 監査ログID |
auditLogs[].resource | string | 操作対象リソース(例: users/show, config/organizations/create, config/job-types/edit) |
auditLogs[].action | string | 操作アクション(approve / reject / promote / demote / create / update / delete / reset-password など)。meta に action がある記録は、その値(管理コンソールの表示と同じ) |
auditLogs[].meta | object | null | 追加メタデータ |
auditLogs[].userId | string | 操作ユーザーID。システム連携(Client Credentials フロー)のトークンでの操作は client:<クライアント ID> |
auditLogs[].userEmail | string | null | 操作ユーザーのメールアドレス |
auditLogs[].userName | string | null | 操作ユーザーの表示名。システム連携(Client Credentials フロー)のトークンでの操作はクライアント名 |
auditLogs[].ipAddress | string | null | IPアドレス |
auditLogs[].userAgent | string | null | User-Agent |
auditLogs[].createdAt | string | 作成日時(ISO 8601形式) |
total | integer | 総件数 |
limit | integer | 取得件数 |
page | integer | ページ番号 |
hasMore | boolean | 次ページが存在するか |
レスポンス例(200 OK)
{
"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_id | string | — | 操作した利用者の ID(userId)の完全一致(128 文字まで) |
action | string | — | 操作(action)の完全一致(64 文字まで) |
空の値は絞り込みません。空白だけの値・前後に空白がある値・長すぎる値・2 つ以上の指定は 400 です。
リクエスト例
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>"
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/user-action-logs?limit=50&from=2026-11-01&to=2026-11-10&action=export" \
-H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/user-action-logs",
headers={"Authorization": f"Bearer {token}"},
params={"limit": 50, "from": "2026-11-01", "to": "2026-11-10", "action": "export"},
)const params = new URLSearchParams({ limit: "50", from: "2026-11-01", to: "2026-11-10", action: "export" });
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/user-action-logs?" + params,
{
headers: { "Authorization": "Bearer " + accessToken },
}
);req, _ := http.NewRequest("GET",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/user-action-logs?limit=50&from=2026-11-01&to=2026-11-10&action=export",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
2 ページ目は、1 ページ目のレスポンスの cursor と、同じ絞り込み(この例では action)を送ります。
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/user-action-logs?limit=50&action=export&cursor=<前回のレスポンスの cursor>" \
-H "Authorization: Bearer <access_token>"
レスポンスフィールド(200 OK)
| フィールド | 型 | 説明 |
|---|
userActionLogs | array | 利用者の操作の監査の配列 |
userActionLogs[].userActionLogId | string | 利用者の操作の監査の ID |
userActionLogs[].occurredAt | string | 操作した日時(ISO 8601形式) |
userActionLogs[].eventType | string | 種類。user_action.<resource>.<action> の形(例: user_action.conversation.export) |
userActionLogs[].userId | string | null | 操作した利用者の ID。分からない記録は null |
userActionLogs[].actorKind | string | 操作した主体(human: 利用者 / unknown: 利用者が分からない記録) |
userActionLogs[].resource | string | null | 対象(例: conversation・share・session) |
userActionLogs[].action | string | null | 操作(例: export・delete) |
userActionLogs[].decision | string | 結果(例: allow・deny・rejected・not_found・error・aborted) |
userActionLogs[].requestId | string | null | 要求 ID |
userActionLogs[].conversationId | string | null | 会話 ID |
userActionLogs[].systemVersion | string | null | 記録したときのシステムの版 |
hasMore | boolean | 次ページが存在するか |
cursor | string? | hasMore が true のときだけ。次のページを取得するためのカーソル値 |
レスポンス例(200 OK)
{
"userActionLogs": [
{
"userActionLogId": "48213",
"occurredAt": "2026-11-10T02:15:30.123Z",
"eventType": "user_action.conversation.export",
"userId": "41b9fcf1-958d-4a86-a863-804b69224a1d",
"actorKind": "human",
"resource": "conversation",
"action": "export",
"decision": "allow",
"requestId": "7f3c2a1e-9b8d-4c6f-a5e4-3d2c1b0a9f8e",
"conversationId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
"systemVersion": "3.4.0"
}
],
"hasMore": true,
"cursor": "eyJjIjoiTWpBeU5pMHhNUzB4TUZRd01qb3hOVG96TUM0eE1qTmFmRFE0TWpFeiIsImYiOiIyMDI2LTExLTAxVDAwOjAwOjAwLjAwMFoiLCJ0IjoiMjAyNi0xMS0xMVQwMDowMDowMC4wMDBaIiwiZSI6dHJ1ZX0"
}
エラーレスポンス
| ステータス | 説明 |
|---|
400 | limit が 1〜100 ではない、from・to が YYYY-MM-DD 形式の実在する日付ではない、from が to より後、user_id・action が空白だけ・前後に空白がある・長すぎる・2 つ以上、または cursor が不正(前回レスポンスの値以外)(code: "invalid_parameter") |
400 | サービス側で期間を受け付けなかった(例: to を省いて、from に今日より後の日を指定した)(code: "bad_request") |
403 | logs:read スコープが不足(code: "insufficient_scope") |
GET/v1/admin/action-audit-logs
操作監査ログの一覧を取得します。Agent のツールの呼び出し、実行ルールでの許可・拒否、承認など、利用者・Agent・システムが実行したことの記録です。既定は発生日時の降順です(order で昇順にできます)。本文は記録されません。画面の「記録内容の整合性確認用ハッシュ」・「行ハッシュ」・「メタデータ」は返しません。
絞り込みのクエリパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|
event_type | string | — | イベント種別(eventType)の完全一致(例: "tool.invoked"・"approval.resolved"・"gate.resolved"・"run.started"・"agent.copied") |
decision | string | — | 判定(decision)の完全一致(例: "allow"・"deny"・"completed"・"failed"・"copied") |
source | string | — | 記録元(source)の完全一致(例: "worker"・"cli-api"・"front"・"admin"・"login"・"agent_executor") |
actor_type | string | — | 実行者の種類(actorType)の完全一致(例: "human"・"agent"・"system") |
actor_kind | string | — | 実行者の区分(actorKind)の完全一致(例: "human"・"human_external"・"system"・"agent"・"unknown") |
actor_ref | string | — | 実行者(actorRef)の完全一致 |
conversation_id | string | — | 会話 ID(conversationId)の完全一致 |
execution_id | string | — | 実行 ID(executionId)の完全一致 |
root_execution_id | string | — | 一連の実行 ID(rootExecutionId)の完全一致 |
project_id | string | — | プロジェクト ID(projectId)の完全一致。UUID ではない値は 400 |
request_id | string | — | リクエスト ID(requestId)の完全一致 |
値は縛らず、知らない値は該当なしになります。空の値は絞り込みません。空白だけの値・前後に空白がある値・2 つ以上の指定は 400 です。
リクエスト例
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>"
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/action-audit-logs?limit=10&from=2026-11-01&to=2026-11-10&source=front" \
-H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/action-audit-logs",
headers={"Authorization": f"Bearer {token}"},
params={"limit": 10, "from": "2026-11-01", "to": "2026-11-10", "source": "front"},
)const params = new URLSearchParams({ limit: "10", from: "2026-11-01", to: "2026-11-10", source: "front" });
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/action-audit-logs?" + params,
{
headers: { "Authorization": "Bearer " + accessToken },
}
);req, _ := http.NewRequest("GET",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/action-audit-logs?limit=10&from=2026-11-01&to=2026-11-10&source=front",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
レスポンスフィールド(200 OK)
| フィールド | 型 | 説明 |
|---|
actionAuditLogs | array | 操作監査ログオブジェクトの配列 |
actionAuditLogs[].actionAuditLogId | string | 操作監査ログID |
actionAuditLogs[].occurredAt | string | null | 発生日時(ISO 8601形式) |
actionAuditLogs[].source | string | null | 記録元(例: worker・cli-api・front・admin・login・agent_executor) |
actionAuditLogs[].eventType | string | null | イベント種別 |
actionAuditLogs[].actorType | string | null | 実行者の種類(例: human・agent・system) |
actionAuditLogs[].actorKind | string | null | 実行者の区分(例: human・human_external・system・agent・unknown)。古い記録では null |
actionAuditLogs[].actorRef | string | null | 実行者 |
actionAuditLogs[].onBehalfOfRef | string | null | 代理元(誰の代わりに実行したか) |
actionAuditLogs[].resource | string | null | 対象 |
actionAuditLogs[].action | string | null | 操作 |
actionAuditLogs[].decision | string | null | 判定 |
actionAuditLogs[].reason | string | null | 理由コード |
actionAuditLogs[].policyId | string | null | 実行ルールID |
actionAuditLogs[].policyVersion | string | null | 実行ルールの版 |
actionAuditLogs[].executionId | string | null | 実行ID |
actionAuditLogs[].rootExecutionId | string | null | 一連の実行ID。古い記録では null |
actionAuditLogs[].conversationId | string | null | 会話ID |
actionAuditLogs[].projectId | string | null | プロジェクトID。古い記録では null |
actionAuditLogs[].messageId | string | null | メッセージID |
actionAuditLogs[].requestId | string | null | リクエストID |
actionAuditLogs[].systemVersion | string | null | システムバージョン |
total | integer | 総件数 |
limit | integer | 取得件数 |
page | integer | ページ番号 |
hasMore | boolean | 次ページが存在するか |
レスポンス例(200 OK)
{
"actionAuditLogs": [
{
"actionAuditLogId": "1203344",
"occurredAt": "2026-11-10T03:00:12.456Z",
"source": "front",
"eventType": "agent.copied",
"actorType": "human",
"actorKind": "human",
"actorRef": "41b9fcf1-958d-4a86-a863-804b69224a1d",
"onBehalfOfRef": null,
"resource": "agent:9c8b7a6f-5e4d-4c3b-8a2f-1e0d9c8b7a6f",
"action": null,
"decision": "copied",
"reason": null,
"policyId": null,
"policyVersion": null,
"executionId": null,
"rootExecutionId": null,
"conversationId": null,
"projectId": null,
"messageId": null,
"requestId": null,
"systemVersion": "3.4.0"
}
],
"total": 128,
"limit": 1,
"page": 1,
"hasMore": true
}
エラーレスポンス
| ステータス | 説明 |
|---|
400 | limit・page・from・to・order が不正、絞り込みの値が空白だけ・前後に空白がある・2 つ以上、または project_id が UUID ではない(code: "invalid_parameter") |
403 | logs:read スコープが不足(code: "insufficient_scope") |
GET/v1/admin/llm-logs
LLMログ一覧を取得します。既定はタイムスタンプの降順です(order で昇順にできます)。
絞り込みのクエリパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|
conversation_id | string | — | 会話 ID(conversationId)の完全一致 |
service | string | — | サービス(service)の完全一致 |
operation | string | — | 操作(operation)の完全一致 |
success | string | — | "true"(成功)または "false"(失敗)。ほかの値は 400 |
リクエスト例
1curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-logs?limit=10" \
2-H "Authorization: Bearer <access_token>"
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-logs?limit=10" \
-H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-logs",
headers={"Authorization": f"Bearer {token}"},
params={"limit": 10},
)const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-logs?limit=10",
{
headers: { "Authorization": "Bearer " + accessToken },
}
);req, _ := http.NewRequest("GET",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-logs?limit=10",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
レスポンスフィールド(200 OK)
| フィールド | 型 | 説明 |
|---|
llmLogs | array | LLMログオブジェクトの配列 |
llmLogs[].llmLogId | string | LLMログID |
llmLogs[].timestamp | string | null | タイムスタンプ |
llmLogs[].service | string | null | サービス名 |
llmLogs[].operation | string | null | オペレーション名 |
llmLogs[].durationMs | number | null | 処理時間(ミリ秒) |
llmLogs[].conversationId | string | null | 会話ID |
llmLogs[].intentType | string | null | 意図タイプ |
llmLogs[].confidenceScore | number | null | 信頼度スコア |
llmLogs[].toolsUsed | number | null | ツール呼び出し回数(ツール名の一覧でも、使ったツールの種類数でもない。同じツールを 5 回呼べば 5)。null は未計測、0 は計測した上で一度も呼ばなかった実行。両者は区別されるため、0 を null と同一視しないでください |
llmLogs[].success | boolean | null | 成功/失敗 |
llmLogs[].agentType | string | null | エージェントタイプ |
llmLogs[].agentLevel | string | null | エージェントレベル |
llmLogs[].taskComplexity | string | null | タスクの複雑度 |
llmLogs[].currentMessage | string | null | 現在のメッセージ |
llmLogs[].contextSummary | string | null | コンテキスト要約 |
llmLogs[].suggestedApproach | string | null | 提案された進め方 |
llmLogs[].conversationGoal | string | null | 会話のゴール |
llmLogs[].finalContent | string | null | 最終出力内容 |
llmLogs[].metadata | object | null | オペレーションごとに異なる付随メタデータ(キーは可変) |
llmLogs[].createdAt | string | null | 作成日時 |
total | integer | 総件数 |
limit | integer | 取得件数 |
page | integer | ページ番号 |
hasMore | boolean | 次ページが存在するか |
レスポンス例(200 OK)
{
"llmLogs": [
{
"llmLogId": "33098",
"timestamp": "2026-04-19T04:12:51.102Z",
"service": "agent-executor",
"operation": "agent.intent.completed",
"durationMs": 5574.6,
"conversationId": "3b72544d-d6b5-4577-b5f3-c39293124a57",
"intentType": "complex_task",
"confidenceScore": 0.95,
"toolsUsed": null,
"success": null,
"agentType": "intent",
"agentLevel": "default",
"taskComplexity": null,
"currentMessage": "このURLについて教えて https://example.com/path",
"contextSummary": "ユーザーがURLについての情報を求めている。",
"suggestedApproach": "execute_single_tool",
"conversationGoal": "指定されたURLの内容や目的についての情報",
"finalContent": null,
"metadata": {
"message.id": "02038f42-154b-4363-9beb-d31512934ec5",
"task.complexity": "moderate",
"detected_language": "ja",
"requires_planning": true
},
"createdAt": "2026-04-18T19:16:16.964Z"
},
{
"llmLogId": "33097",
"timestamp": "2026-04-19T04:12:48.730Z",
"service": "agent-executor",
"operation": "agent.guardrail.completed",
"durationMs": 3170.34,
"conversationId": "3b72544d-d6b5-4577-b5f3-c39293124a57",
"intentType": null,
"confidenceScore": null,
"toolsUsed": null,
"success": null,
"agentType": "intent.guardrails",
"agentLevel": null,
"taskComplexity": null,
"currentMessage": null,
"contextSummary": null,
"suggestedApproach": null,
"conversationGoal": null,
"finalContent": null,
"metadata": { "guardrail_detected": false },
"createdAt": "2026-04-18T19:16:14.619Z"
},
{
"llmLogId": "33096",
"timestamp": "2026-04-19T04:12:33.662Z",
"service": "agent-executor",
"operation": "agent.intent.completed",
"durationMs": 4213.47,
"conversationId": "4d7c798d-2e3e-4d40-86ab-cbb6c685a3fb",
"intentType": "conversation",
"confidenceScore": 1,
"toolsUsed": null,
"success": null,
"agentType": "intent",
"agentLevel": "default",
"taskComplexity": null,
"currentMessage": "こんにちは",
"contextSummary": "新規会話開始。ユーザーが挨拶",
"suggestedApproach": "conversational_response",
"conversationGoal": "AIアシスタントとの挨拶交流",
"finalContent": null,
"metadata": {
"message.id": "cea9dbcc-4723-452a-bdcd-aa5f3a0e9ca6",
"task.complexity": "simple",
"detected_language": "ja",
"requires_planning": false
},
"createdAt": "2026-04-18T19:15:59.681Z"
}
],
"total": 33098,
"limit": 3,
"page": 1,
"hasMore": true
}
GET/v1/admin/llm-gateway-logs
LLM Gateway ログ一覧を取得します。既定は作成日時の降順です(order で昇順にできます)。1 リクエスト = 1 行で、モデル・プロバイダ・トークン・コスト・レイテンシ等の利用状況を記録します。
絞り込みのクエリパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|
provider | string | — | プロバイダ(provider)の完全一致 |
model_name | string | — | モデル名の完全一致(modelName が無い行は resolvedModel で比べます) |
success | string | — | "true"(成功)または "false"(失敗)。ほかの値は 400 |
リクエスト例
1curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-gateway-logs?limit=10" \
2-H "Authorization: Bearer <access_token>"
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-gateway-logs?limit=10" \
-H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-gateway-logs",
headers={"Authorization": f"Bearer {token}"},
params={"limit": 10},
)const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-gateway-logs?limit=10",
{
headers: { "Authorization": "Bearer " + accessToken },
}
);req, _ := http.NewRequest("GET",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-gateway-logs?limit=10",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
レスポンスフィールド(200 OK)
| フィールド | 型 | 説明 |
|---|
| llmGatewayLogs | array | LLM Gateway ログオブジェクトの配列 |
| llmGatewayLogs[].llmGatewayLogId | string | LLM Gateway ログID |
| llmGatewayLogs[].createdAt | string | null | 作成日時 |
| llmGatewayLogs[].virtualKeyId | string | null | 仮想キーID(呼び出し元クライアント) |
| llmGatewayLogs[].clientSessionId | string | null | クライアントセッションID |
| llmGatewayLogs[].clientAgentId | string | null | クライアントエージェントID |
| llmGatewayLogs[].apiFlavor | string | null | API フレーバー |
| llmGatewayLogs[].modelName | string | null | モデル名(リクエスト指定) |
| llmGatewayLogs[].resolvedModel | string | null | 解決後モデル名 |
| llmGatewayLogs[].provider | string | null | プロバイダ |
| llmGatewayLogs[].deployment | string | null | デプロイメント |
| llmGatewayLogs[].tier | string | null | ティア |
| llmGatewayLogs[].stream | boolean | null | ストリーミング有無 |
| llmGatewayLogs[].success | boolean | null | 成功/失敗 |
| llmGatewayLogs[].httpStatus | number | null | HTTP ステータス |
| llmGatewayLogs[].errorType | string | null | エラータイプ |
| llmGatewayLogs[].errorCode | string | null | エラーコード |
| llmGatewayLogs[].usageStatus | string | null | 使用量ステータス |
| llmGatewayLogs[].latencyMs | number | null | レイテンシ(ミリ秒) |
| llmGatewayLogs[].inputTokens | number | null | 入力トークン数 |
| llmGatewayLogs[].outputTokens | number | null | 出力トークン数 |
| llmGatewayLogs[].totalTokens | number | null | 合計トークン数 |
| llmGatewayLogs[].cachedTokens | number | null | キャッシュトークン数 |
| llmGatewayLogs[].cacheCreationInputTokens | number | null | キャッシュ作成入力トークン数 |
| llmGatewayLogs[].reasoningTokens | number | null | 推論トークン数 |
| llmGatewayLogs[].costUsd | number | string | null | コスト(USD) |
| llmGatewayLogs[].currency | string | null | 通貨 |
| llmGatewayLogs[].metadata | object | null | 付随メタデータ(キーは可変) |
| total | integer | 総件数 |
| limit | integer | 取得件数 |
| page | integer | ページ番号 |
| hasMore | boolean | 次ページが存在するか |
GET/v1/admin/llm-gateway-action-logs
LLM Gateway 操作監査の一覧を取得します。LLM Gateway 経由で実行された操作の記録で、LLM Gateway を使っていなければ記録はありません。既定は発生日時の降順です(order で昇順にできます)。画面の「リクエストID」・「詳細ダイジェスト」・「行ハッシュ」・「メタデータ」は返しません。
絞り込みのクエリパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|
event_type | string | — | イベント種別(eventType)の完全一致(例: "auth.denied"・"guardrail.blocked"・"policy.pii_blocked"・"policy.mcp_stripped"・"limit.rpm_exceeded"・"limit.budget_exceeded") |
decision | string | — | 判定(decision)の完全一致(例: "allowed"・"denied"・"blocked"・"degraded"・"stripped"・"throttled") |
api_flavor | string | — | API フレーバー(apiFlavor)の完全一致(例: "chat"・"responses"・"messages"・"embeddings") |
virtual_key_id | string | — | 仮想キーID(virtualKeyId)の完全一致 |
値は縛らず、知らない値は該当なしになります。空の値は絞り込みません。空白だけの値・前後に空白がある値・2 つ以上の指定は 400 です。
リクエスト例
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>"
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-gateway-action-logs?limit=10&event_type=guardrail.blocked" \
-H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-gateway-action-logs",
headers={"Authorization": f"Bearer {token}"},
params={"limit": 10, "event_type": "guardrail.blocked"},
)const params = new URLSearchParams({ limit: "10", event_type: "guardrail.blocked" });
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-gateway-action-logs?" + params,
{
headers: { "Authorization": "Bearer " + accessToken },
}
);req, _ := http.NewRequest("GET",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-gateway-action-logs?limit=10&event_type=guardrail.blocked",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
レスポンスフィールド(200 OK)
| フィールド | 型 | 説明 |
|---|
llmGatewayActionLogs | array | LLM Gateway 操作監査オブジェクトの配列 |
llmGatewayActionLogs[].llmGatewayActionLogId | string | LLM Gateway 操作監査ID |
llmGatewayActionLogs[].occurredAt | string | null | 発生日時(ISO 8601形式) |
llmGatewayActionLogs[].virtualKeyId | string | null | 仮想キーID(呼び出し元クライアント) |
llmGatewayActionLogs[].externalRequestId | string | null | 外部リクエストID |
llmGatewayActionLogs[].apiFlavor | string | null | API フレーバー |
llmGatewayActionLogs[].eventType | string | null | イベント種別 |
llmGatewayActionLogs[].decision | string | null | 判定 |
llmGatewayActionLogs[].reason | string | null | 理由コード |
llmGatewayActionLogs[].modelName | string | null | モデル名(リクエスト指定) |
llmGatewayActionLogs[].resolvedModel | string | null | 解決後モデル名 |
llmGatewayActionLogs[].systemVersion | string | null | システムバージョン |
total | integer | 総件数 |
limit | integer | 取得件数 |
page | integer | ページ番号 |
hasMore | boolean | 次ページが存在するか |
レスポンス例(200 OK)
{
"llmGatewayActionLogs": [
{
"llmGatewayActionLogId": "88412",
"occurredAt": "2026-11-10T04:21:07.318Z",
"virtualKeyId": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
"externalRequestId": null,
"apiFlavor": "chat",
"eventType": "guardrail.blocked",
"decision": "blocked",
"reason": null,
"modelName": "<モデル ID>",
"resolvedModel": "<モデル ID>",
"systemVersion": "3.4.0"
}
],
"total": 3,
"limit": 10,
"page": 1,
"hasMore": false
}
エラーレスポンス
| ステータス | 説明 |
|---|
400 | limit・page・from・to・order が不正、または絞り込みの値が空白だけ・前後に空白がある・2 つ以上(code: "invalid_parameter") |
403 | logs:read スコープが不足(code: "insufficient_scope") |
GET/v1/admin/access-logs
アクセスログ一覧を取得します。アクセスログは、外部への通信を許可・遮断した記録です。タイムスタンプの降順で返されます(order は指定できません)。
絞り込みのクエリパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|
authz_result | string | — | "allowed"(許可)または "denied"(拒否)。ほかの値は 400 |
リクエスト例
1curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/access-logs?limit=10" \
2-H "Authorization: Bearer <access_token>"
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/access-logs?limit=10" \
-H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/access-logs",
headers={"Authorization": f"Bearer {token}"},
params={"limit": 10},
)const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/access-logs?limit=10",
{
headers: { "Authorization": "Bearer " + accessToken },
}
);req, _ := http.NewRequest("GET",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/access-logs?limit=10",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
レスポンスフィールド(200 OK)
| フィールド | 型 | 説明 |
|---|
accessLogs | array | アクセスログオブジェクトの配列 |
accessLogs[].timestamp | string | タイムスタンプ |
accessLogs[].sourceNamespace | string | null | ソース名前空間 |
accessLogs[].sourceIp | string | null | ソースIPアドレス |
accessLogs[].method | string | null | HTTPメソッド |
accessLogs[].host | string | null | ホスト名 |
accessLogs[].path | string | null | リクエストパス |
accessLogs[].userAgent | string | null | User-Agent |
accessLogs[].statusCode | number | null | HTTPステータスコード |
accessLogs[].durationMs | number | null | 処理時間(ミリ秒) |
accessLogs[].authzResult | string | null | 認可結果 |
accessLogs[].authzReason | string | null | 認可理由 |
total | integer | 総件数 |
limit | integer | 取得件数 |
page | integer | ページ番号 |
hasMore | boolean | 次ページが存在するか |
skippedCount | integer | このページで読めなかったログの行の数(accessLogs には入りません。total はこの行も数えます) |
レスポンス例(200 OK)
{
"accessLogs": [
{
"timestamp": "2026-04-19T05:17:36.735896",
"sourceNamespace": "autonomous-agent",
"sourceIp": "127.0.0.1",
"method": "CONNECT",
"host": "optimizationguide-pa.googleapis.com:443",
"path": "",
"userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36",
"statusCode": 200,
"durationMs": 1,
"authzResult": "allowed",
"authzReason": "allowed: All allow"
},
{
"timestamp": "2026-04-19T03:50:36.766451",
"sourceNamespace": "autonomous-agent",
"sourceIp": "127.0.0.1",
"method": "CONNECT",
"host": "update.googleapis.com:443",
"path": "",
"userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36",
"statusCode": 200,
"durationMs": 6,
"authzResult": "allowed",
"authzReason": "allowed: All allow"
},
{
"timestamp": "2026-04-19T03:45:48.481023",
"sourceNamespace": "autonomous-agent",
"sourceIp": "127.0.0.1",
"method": "CONNECT",
"host": "optimizationguide-pa.googleapis.com:443",
"path": "",
"userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36",
"statusCode": 200,
"durationMs": 0,
"authzResult": "allowed",
"authzReason": "allowed: All allow"
}
],
"total": 57806,
"limit": 3,
"page": 1,
"hasMore": true,
"skippedCount": 0
}
GET/v1/admin/guardrail-alerts
ガードレールアラート一覧を取得します。既定は検知日時の降順です(order で昇順にできます)。
絞り込みのクエリパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|
status | string | — | "open" / "investigating" / "escalated" / "closed" / "false_positive" |
source_surface | string | — | "agent_executor" / "llm_gateway" / "agent_worker" |
resolution_code | string | — | "policy_violation_confirmed" / "no_action_required" / "escalated_externally" / "detection_error" / "benign_context" / "test_or_synthetic" / "insufficient_information" |
detection_type | string | — | 検知の種類(detectionTypes の値。例: "jailbreak_attack"・"harmful_content") |
moderation_category | string | — | 有害表現のカテゴリ(moderationCategories のキー。例: "Hate"・"Violence"・"Sexual") |
shield_origin | string | — | "userPrompt" / "documents" / "both" / "unknown" |
policy_category | string | — | 攻撃方式の分類(policyCategory の値) |
status・source_surface・resolution_code・shield_origin に上の値以外を指定すると 400 です。detection_type・moderation_category・policy_category は値を縛らず、知らない値は該当なしになります。
Prompt Shield(プロンプトインジェクション・ジェイルブレイク)と Text Moderation(有害表現)で検知し、実行を停止した記録です。検知面(sourceSurface)は AI エージェント実行時(agent_executor)と LLM Gateway 経由(llm_gateway)の 2 種類があります。
リクエスト例
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>"
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/guardrail-alerts?limit=10&from=2026-08-01&to=2026-08-15" \
-H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/guardrail-alerts",
headers={"Authorization": f"Bearer {token}"},
params={"limit": 10, "from": "2026-08-01", "to": "2026-08-15"},
)const params = new URLSearchParams({ limit: "10", from: "2026-08-01", to: "2026-08-15" });
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/guardrail-alerts?" + params,
{
headers: { "Authorization": "Bearer " + accessToken },
}
);req, _ := http.NewRequest("GET",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/guardrail-alerts?limit=10&from=2026-08-01&to=2026-08-15",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
レスポンスフィールド(200 OK)
| フィールド | 型 | 説明 |
|---|
guardrailAlerts | array | ガードレールアラートオブジェクトの配列 |
guardrailAlerts[].guardrailAlertId | string | ガードレールアラートID |
guardrailAlerts[].detectedAt | string | 検知日時(ISO 8601形式) |
guardrailAlerts[].sourceSurface | string | 検知面(agent_executor: AIエージェント実行時 / llm_gateway: LLM Gateway経由 / agent_worker: 会話 Pod の中) |
guardrailAlerts[].detectionTypes | array | 検知種別(jailbreak_attack: プロンプトインジェクション / harmful_content: 有害表現) |
guardrailAlerts[].promptShieldOrigin | object | null | Prompt Shield の検知箇所。user_prompt(利用者の入力)と document_indexes(添付文書の位置)を持つ。文書の内容は含まれません |
guardrailAlerts[].moderationCategories | object | null | カテゴリ別の深刻度。Hate / Sexual / SelfHarm / Violence を 0・2・4・6 の4段階で表す |
guardrailAlerts[].moderationThreshold | integer | null | 判定に使用したしきい値 |
guardrailAlerts[].policyOutcome | string | 判定結果。現在は blocked(実行を停止)のみ |
guardrailAlerts[].policyCategory | string | null | 攻撃方式の分類(例: prompt_injection・system_prompt_extraction・credential_request)。この分類を持たない検知では null |
guardrailAlerts[].responseTemplateCode | string | null | 利用者へ返した定型応答のコード |
guardrailAlerts[].status | string | 対応状況(open: 未対応 / investigating: 調査中 / escalated: エスカレーション中 / closed: 対応済み / false_positive: 誤検知) |
guardrailAlerts[].resolutionCode | string | null | 対応結果コード |
guardrailAlerts[].resolvedAt | string | null | 対応完了日時(ISO 8601形式) |
guardrailAlerts[].resolvedBy | string | null | 対応を完了した管理者のユーザーID |
guardrailAlerts[].createdAt | string | 作成日時(ISO 8601形式) |
guardrailAlerts[].updatedAt | string | 更新日時(ISO 8601形式) |
total | integer | 総件数 |
limit | integer | 取得件数 |
page | integer | ページ番号 |
hasMore | boolean | 次ページが存在するか |
本APIは、検知された利用者を特定する情報(利用者ID・会話ID・メッセージID)を返しません。ガードレールの品質確認と安全対応の状況把握を目的としたAPIであり、利用者個人の行動追跡には使用できません。
また、SelfHarm(自傷)のみを検知した事象はアラートとして記録されません。
レスポンス例(200 OK)
{
"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
組織一覧を取得します。全件取得(ページネーションなし)です。
リクエスト例
1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations \
2-H "Authorization: Bearer <access_token>"
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations \
-H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations",
headers={"Authorization": f"Bearer {token}"},
)
data = response.json()
for org in data["organizations"]:
print(f"{org['code']}: {org['name']}")const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations",
{
headers: { "Authorization": "Bearer " + accessToken },
}
);
const data = await response.json();
data.organizations.forEach((org) => {
console.log(org.code + ": " + org.name);
});req, _ := http.NewRequest("GET",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
レスポンスフィールド(200 OK)
| フィールド | 型 | 説明 |
|---|
organizations | array | 組織オブジェクトの配列 |
organizations[].code | string | 組織コード |
organizations[].name | string | 組織名 |
organizations[].displayOrder | integer | 表示順 |
organizations[].isActive | boolean | 有効/無効 |
organizations[].createdAt | string | 作成日時 |
organizations[].updatedAt | string | 更新日時 |
hasMore | boolean | いつも false(全件を返します) |
レスポンス例(200 OK)
{
"organizations": [
{
"code": "sample_org",
"name": "組織(サンプル)",
"displayOrder": 0,
"isActive": true,
"createdAt": "2025-12-12T10:40:45.220Z",
"updatedAt": "2026-04-13T01:21:57.695Z"
},
{
"code": "sales",
"name": "営業統括部",
"displayOrder": 1,
"isActive": true,
"createdAt": "2025-12-24T19:26:37.000Z",
"updatedAt": "2025-12-24T19:26:37.000Z"
},
{
"code": "engineering",
"name": "エンジニアリング統括部",
"displayOrder": 2,
"isActive": true,
"createdAt": "2025-12-24T19:26:37.000Z",
"updatedAt": "2025-12-24T19:26:37.000Z"
},
{
"code": "other",
"name": "その他",
"displayOrder": -1,
"isActive": false,
"createdAt": "2025-12-24T19:26:38.000Z",
"updatedAt": "2026-01-17T19:08:21.630Z"
}
],
"hasMore": false
}
エラーレスポンス
| ステータス | 説明 |
|---|
403 | master:manage スコープが不足 |
POST/v1/admin/organizations
組織を作成します。
リクエストボディ
| パラメータ | 型 | 必須 | 説明 |
|---|
code | string | 必須 | 組織コード(一意)。英小文字・数字・アンダースコア(`_`)だけで、255 文字まで。前後の空白は除かれます |
name | string | 必須 | 組織名(255 文字まで) |
displayOrder | integer | — | 表示順。省略した場合は、表示順が正の項目のいちばん大きい値に 1 を足した値になります(`code` が `other` のときは -1 で、いちばん後ろに表示されます) |
isActive | boolean | — | 有効/無効(デフォルト: true) |
リクエスト例
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}'
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"code": "marketing",
"name": "マーケティング統括部",
"displayOrder": 3,
"isActive": true
}'import requests
response = requests.post(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations",
headers={"Authorization": f"Bearer {token}"},
json={'code': 'marketing', 'name': 'マーケティング統括部', 'displayOrder': 3, 'isActive': True},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations",
{
method: "POST",
headers: {
"Authorization": "Bearer " + accessToken,
"Content-Type": "application/json",
},
body: JSON.stringify({"code": "marketing", "name": "マーケティング統括部", "displayOrder": 3, "isActive": true}),
}
);
const data = await response.json();
console.log(data);payload := []byte(`{"code": "marketing", "name": "マーケティング統括部", "displayOrder": 3, "isActive": true}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
レスポンス例(201 Created)
{
"code": "marketing",
"name": "マーケティング統括部",
"displayOrder": 3,
"isActive": true,
"createdAt": "2026-04-19T02:15:32.000Z",
"updatedAt": "2026-04-19T02:15:32.000Z"
}
エラーレスポンス
| ステータス | 説明 |
|---|
400 | リクエストボディが不正(code / name 未指定、code・name が文字列ではない、isActive が真偽値ではない、displayOrder が整数ではない、code に英小文字・数字・アンダースコア以外が含まれる、code・name が 255 文字を超える、ボディが壊れた JSON・JSON のオブジェクトではない(code: "invalid_body")など) |
415 | ボディの Content-Type が application/json ではない(code: "unsupported_media_type") |
403 | master:manage スコープが不足 |
409 | 同じ code を持つ組織が既に存在する |
GET/v1/admin/organizations/:identifier
組織の詳細を取得します。UUID または組織コードで指定できます。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|
identifier | string | 必須 | 組織のUUIDまたは組織コード |
リクエスト例
1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/sales \
2-H "Authorization: Bearer <access_token>"
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/sales \
-H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/{identifier}",
headers={"Authorization": f"Bearer {token}"},
)const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/${identifier}`,
{
headers: { "Authorization": "Bearer " + accessToken },
}
);req, _ := http.NewRequest("GET",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/"+identifier,
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
レスポンス例(200 OK)
{
"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 | — | 有効/無効 |
リクエスト例
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}'
curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/sales \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"name": "営業統括部",
"isActive": true
}'import requests
response = requests.patch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/sales",
headers={"Authorization": f"Bearer {token}"},
json={'name': '営業統括部', 'isActive': True},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/sales",
{
method: "PATCH",
headers: {
"Authorization": "Bearer " + accessToken,
"Content-Type": "application/json",
},
body: JSON.stringify({"name": "営業統括部", "isActive": true}),
}
);
const data = await response.json();
console.log(data);payload := []byte(`{"name": "営業統括部", "isActive": true}`)
req, _ := http.NewRequest("PATCH", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/sales", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
レスポンス例(200 OK)
{
"code": "sales",
"name": "営業統括部",
"displayOrder": 1,
"isActive": true,
"createdAt": "2025-12-24T19:26:37.000Z",
"updatedAt": "2026-04-19T02:18:40.000Z"
}
エラーレスポンス
| ステータス | 説明 |
|---|
400 | リクエストボディが不正(name が 255 文字超過、name / isActive のどちらも未指定、name が文字列ではない・isActive が真偽値ではない、ボディが壊れた JSON・JSON のオブジェクトではない(code: "invalid_body")など)。name / isActive 以外のフィールドは無視されます |
415 | ボディの Content-Type が application/json ではない(code: "unsupported_media_type") |
403 | master:manage スコープが不足 |
404 | 指定された組織が見つからない |
DELETE/v1/admin/organizations/:identifier
組織を削除します。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|
identifier | string | 必須 | 組織のUUIDまたは組織コード |
リクエスト例
1curl -X DELETE https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/sales \
2-H "Authorization: Bearer <access_token>"
curl -X DELETE https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/sales \
-H "Authorization: Bearer <access_token>"
import requests
response = requests.delete(
f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/{identifier}",
headers={"Authorization": f"Bearer {token}"},
)const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/${identifier}`,
{
method: "DELETE",
headers: { "Authorization": "Bearer " + accessToken },
}
);req, _ := http.NewRequest("DELETE",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/"+identifier,
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
レスポンス例(200 OK)
{ "code": "sales", "deleted": true }
| フィールド | 型 | 説明 |
|---|
code | string | 削除した組織コード(パスパラメータの identifier をそのまま返す) |
deleted | boolean | 常に true |
エラーレスポンス
| ステータス | 説明 |
|---|
403 | master:manage スコープが不足 |
404 | 指定された組織が見つからない |
GET/v1/admin/job-types
職種一覧を取得します。全件取得(ページネーションなし)です。レスポンスフィールドは組織一覧と同一構造です(organizations → jobTypes、組織コード → 職種コード)。
リクエスト例
1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types \
2-H "Authorization: Bearer <access_token>"
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types \
-H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types",
headers={"Authorization": f"Bearer {token}"},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types",
{
headers: {
"Authorization": "Bearer " + accessToken,
},
}
);
const data = await response.json();
console.log(data);req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
レスポンスフィールド(200 OK)
| フィールド | 型 | 説明 |
|---|
jobTypes | array | 職種オブジェクトの配列 |
jobTypes[].code | string | 職種コード |
jobTypes[].name | string | 職種名 |
jobTypes[].displayOrder | integer | 表示順 |
jobTypes[].isActive | boolean | 有効/無効 |
jobTypes[].createdAt | string | 作成日時 |
jobTypes[].updatedAt | string | 更新日時 |
hasMore | boolean | いつも false(全件を返します) |
レスポンス例(200 OK)
{
"jobTypes": [
{
"code": "engineer",
"name": "エンジニア",
"displayOrder": 1,
"isActive": true,
"createdAt": "2025-12-24T19:26:37.000Z",
"updatedAt": "2025-12-24T19:26:37.000Z"
},
{
"code": "sales",
"name": "営業",
"displayOrder": 2,
"isActive": true,
"createdAt": "2025-12-24T19:26:37.000Z",
"updatedAt": "2025-12-24T19:26:37.000Z"
},
{
"code": "other",
"name": "その他",
"displayOrder": -1,
"isActive": false,
"createdAt": "2025-12-24T19:26:38.000Z",
"updatedAt": "2026-01-17T19:08:21.630Z"
}
],
"hasMore": false
}
エラーレスポンス
| ステータス | 説明 |
|---|
403 | master:manage スコープが不足 |
POST/v1/admin/job-types
職種を作成します。リクエストボディは組織作成と同一構造です。
リクエスト例
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}'
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"code": "manager",
"name": "管理職",
"displayOrder": 3,
"isActive": true
}'import requests
response = requests.post(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types",
headers={"Authorization": f"Bearer {token}"},
json={'code': 'manager', 'name': '管理職', 'displayOrder': 3, 'isActive': True},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types",
{
method: "POST",
headers: {
"Authorization": "Bearer " + accessToken,
"Content-Type": "application/json",
},
body: JSON.stringify({"code": "manager", "name": "管理職", "displayOrder": 3, "isActive": true}),
}
);
const data = await response.json();
console.log(data);payload := []byte(`{"code": "manager", "name": "管理職", "displayOrder": 3, "isActive": true}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
レスポンス例(201 Created)
{
"code": "manager",
"name": "管理職",
"displayOrder": 3,
"isActive": true,
"createdAt": "2026-04-19T02:20:15.000Z",
"updatedAt": "2026-04-19T02:20:15.000Z"
}
エラーレスポンス
| ステータス | 説明 |
|---|
400 | リクエストボディが不正(code / name 未指定、code・name が文字列ではない、isActive が真偽値ではない、displayOrder が整数ではない、code に英小文字・数字・アンダースコア以外が含まれる、code・name が 255 文字を超える、ボディが壊れた JSON・JSON のオブジェクトではない(code: "invalid_body")など) |
415 | ボディの Content-Type が application/json ではない(code: "unsupported_media_type") |
403 | master:manage スコープが不足 |
409 | 同じ code を持つ職種が既に存在する |
GET/v1/admin/job-types/:identifier
職種の詳細を取得します。UUID または職種コードで指定できます。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|
identifier | string | 必須 | 職種のUUIDまたは職種コード |
リクエスト例
1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/engineer \
2-H "Authorization: Bearer <access_token>"
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/engineer \
-H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/{identifier}",
headers={"Authorization": f"Bearer {token}"},
)const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/${identifier}`,
{
headers: { "Authorization": "Bearer " + accessToken },
}
);req, _ := http.NewRequest("GET",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/"+identifier,
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
レスポンス例(200 OK)
{
"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 | — | 有効/無効 |
リクエスト例
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}'
curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/engineer \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{"name": "Senior Engineer", "isActive": true}'import requests
response = requests.patch(
f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/{identifier}",
headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
json={"name": "Senior Engineer", "isActive": True},
)const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/${identifier}`,
{
method: "PATCH",
headers: {
"Authorization": "Bearer " + accessToken,
"Content-Type": "application/json",
},
body: JSON.stringify({ name: "Senior Engineer", isActive: true }),
}
);body, _ := json.Marshal(map[string]interface{}{"name": "Senior Engineer", "isActive": true})
req, _ := http.NewRequest("PATCH",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/"+identifier,
bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
レスポンス例(200 OK)
{
"code": "engineer",
"name": "シニアエンジニア",
"displayOrder": 1,
"isActive": true,
"createdAt": "2025-12-24T19:26:37.000Z",
"updatedAt": "2026-04-19T02:22:55.000Z"
}
エラーレスポンス
| ステータス | 説明 |
|---|
400 | リクエストボディが不正(name が 255 文字超過、name / isActive のどちらも未指定、name が文字列ではない・isActive が真偽値ではない、ボディが壊れた JSON・JSON のオブジェクトではない(code: "invalid_body")など)。name / isActive 以外のフィールドは無視されます |
415 | ボディの Content-Type が application/json ではない(code: "unsupported_media_type") |
403 | master:manage スコープが不足 |
404 | 指定された職種が見つからない |
DELETE/v1/admin/job-types/:identifier
職種を削除します。レスポンス構造は組織削除と同一です。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|
identifier | string | 必須 | 職種のUUIDまたは職種コード |
リクエスト例
1curl -X DELETE https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/engineer \
2-H "Authorization: Bearer <access_token>"
curl -X DELETE https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/engineer \
-H "Authorization: Bearer <access_token>"
import requests
response = requests.delete(
f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/{identifier}",
headers={"Authorization": f"Bearer {token}"},
)const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/${identifier}`,
{
method: "DELETE",
headers: { "Authorization": "Bearer " + accessToken },
}
);req, _ := http.NewRequest("DELETE",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/"+identifier,
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
レスポンス例(200 OK)
{ "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 は、ここにある 5 つのエンドポイントだけです。ほかのプロジェクトの API を呼ぶと
403 Forbidden(
forbidden)が返ります。
エンドポイント一覧
| メソッド | エンドポイント | 説明 | スコープ (SaaS) |
|---|
| GET | /v1/projects | プロジェクト一覧を取得 | project:read |
| POST | /v1/projects/{projectId}/runs | プロジェクトの実行を開始 | project:run |
| POST | /v1/projects/{projectId}/triggers/{triggerId}/fire | トリガーを発火して臨時に 1 回実行 | project:run |
| GET | /v1/projects/{projectId}/runs/{runId} | 実行状況を取得 | project:read |
| POST | /v1/projects/{projectId}/runs/{runId}/cancel | ワークフローの実行を中断 | project:run |
GET/v1/projects
プロジェクト制限の範囲のプロジェクトの一覧を取得します。カーソルベースのページネーションに対応しています。cycle 型のプロジェクトも一覧に含まれますが、実行開始(POST /v1/projects/{projectId}/runs)の対象にはなりません。
クエリパラメータ
| パラメータ | 型 | デフォルト | 説明 |
|---|
limit | integer | 50 | 取得件数(1〜100) |
cursor | string | — | 次ページ取得用カーソル(前回レスポンスの cursor 値) |
上記以外のクエリパラメータは無視されます。 my_role は利用者のトークンでのみ使えるパラメータのため、指定しても無視されます。
リクエスト例
1curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects?limit=20" \
2-H "Authorization: Bearer <access_token>"
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects?limit=20" \
-H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects",
headers={"Authorization": f"Bearer {token}"},
params={"limit": "20"},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects" + "?limit=20",
{
headers: {
"Authorization": "Bearer " + accessToken,
},
}
);
const data = await response.json();
console.log(data);req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects?limit=20", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
レスポンスフィールド(200 OK)
| フィールド | 型 | 説明 |
|---|
projects | array | プロジェクトオブジェクトの配列 |
projects[].projectId | string | プロジェクト ID(UUID) |
projects[].name | string | プロジェクト名 |
projects[].type | string | "workflow" または "cycle" |
projects[].status | string | プロジェクトの状態。"active" / "paused" / "archived" / "admin_stopped"(管理者が停止)のいずれか |
projects[].tags | array | タグの配列。設定されていない場合は空の配列 |
hasMore | boolean | 次のページが存在するかどうか |
cursor | string | 次ページ取得用カーソル。hasMore が true の場合のみ含まれます |
レスポンス例
{
"projects": [
{
"projectId": "550e8400-e29b-41d4-a716-446655440000",
"name": "受注処理フロー",
"type": "workflow",
"status": "active",
"tags": []
},
{
"projectId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "問い合わせ常時対応",
"type": "cycle",
"status": "active",
"tags": []
}
],
"hasMore": false
}
エラーレスポンス
| ステータス | 説明 |
|---|
400 | limit(1〜100 の範囲外)または cursor が不正(code は invalid_parameter) |
403 | project:read スコープが不足、またはプロジェクト制限が未設定・不正(code は insufficient_scope または invalid_project_grant) |
POST/v1/projects/{projectId}/runs
workflow 型のプロジェクトの実行を開始します。cycle 型に対して呼び出すと 409 Conflict(unsupported_project_type)が返ります。
リクエストヘッダー
| ヘッダー | 必須 | 説明 |
|---|
Idempotency-Key | 必須 | 呼び出し側が採番する重複実行の防止キー。8〜128 文字で、使用できる文字は半角英数字と _ . : - です |
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|
projectId | string | 必須 | プロジェクトの ID(UUID) |
リクエストボディ
ボディは省けます。送信する場合は JSON のオブジェクトにしてください。下のフィールドのほかは無視されます。ただし config を送ると 400 Bad Request(invalid_parameter)が返ります。
| パラメータ | 型 | 必須 | 説明 |
|---|
payload | any | — | 実行の依頼。JSON の値(オブジェクト・配列・文字列など)を、中身を変えずに受け取ります。最初の工程(分かれた後はレーンごとの最初の工程)のエージェントへの依頼に、JSON の文字列にして添えて渡されます。エージェントには、外から届いたデータで指示ではないものとして渡されます。依頼の中にファイルの ID を入れても、ファイルは添付されません。省略・null は依頼なし。JSON の文字列にして 8,000 文字まで |
上限は 2 つあります。payload を JSON の文字列にした長さが 8,000 文字を超えると 400 Bad Request(payload_too_large)、ボディ全体が 16 KiB を超えると 413 Payload Too Large(body_too_large)が返ります。
レスポンスフィールド(201 Created / 200 OK)
| フィールド | 型 | 説明 |
|---|
runId | string | 実行の ID(UUID)。実行状況の取得に使用します |
existing | boolean? | 同じ Idempotency-Key での再送により既存の実行を返した場合に true。初回は含まれません |
初回の呼び出しは 201 Created、同じ Idempotency-Key での再送は 200 OK が返ります。
リクエスト例
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}'
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs \
-H "Authorization: Bearer <access_token>" \
-H "Idempotency-Key: nightly-batch-20260917" \
-H "Content-Type: application/json" \
-d '{
"payload": {
"ticketId": "INC-1024",
"summary": "ログインできない利用者がいる"
}
}'import requests
response = requests.post(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs",
headers={"Authorization": f"Bearer {token}", "Idempotency-Key": "nightly-batch-20260917"},
json={'payload': {'ticketId': 'INC-1024', 'summary': 'ログインできない利用者がいる'}},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs",
{
method: "POST",
headers: {
"Authorization": "Bearer " + accessToken,
"Idempotency-Key": "nightly-batch-20260917",
"Content-Type": "application/json",
},
body: JSON.stringify({"payload": {"ticketId": "INC-1024", "summary": "ログインできない利用者がいる"}}),
}
);
const data = await response.json();
console.log(data);payload := []byte(`{"payload": {"ticketId": "INC-1024", "summary": "ログインできない利用者がいる"}}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Idempotency-Key", "nightly-batch-20260917")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
レスポンス例
{
"runId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
- キーはプロジェクト単位で照合されます。有効期限はありません。
- 同じキーで再送すると、プロジェクトが停止した後・同時実行の上限に達した後・その実行が終了した後であっても、同じ実行が返ります。
- タイムアウトなどで成否が分からなくなった場合は、同じキーでそのまま再送してください。二重に実行されることはありません。
- 別の実行を開始したい場合は、必ず新しいキーを採番してください。
同じキーで、違う payload を付けて再送すると 409 Conflict(origin_conflict)が返ります。
エラーレスポンス
| ステータス | code | 説明 |
|---|
400 | idempotency_key_required | Idempotency-Key ヘッダーが無い |
400 | idempotency_key_invalid | Idempotency-Key の長さまたは文字種が不正 |
400 | invalid_parameter | projectId が UUID の形式ではない、または config を送った(この API では受け付けない。param は config) |
400 | payload_too_large | payload を JSON の文字列にした長さが 8,000 文字を超える |
400 | invalid_body | リクエストボディが壊れた JSON、または JSON のオブジェクトではない |
413 | body_too_large | リクエストボディが 16 KiB を超過 |
415 | unsupported_media_type | リクエストボディがあるのに、Content-Type が application/json ではない |
403 | insufficient_scope | project:run スコープが不足 |
403 | invalid_project_grant | プロジェクト制限が未設定、または設定内容が不正 |
404 | project_not_found | プロジェクトが存在しない、またはアクセス権が無い |
400 | approvers_required | 有効な確認工程に確認担当者が設定されていない |
409 | unsupported_project_type | cycle 型のプロジェクトを指定した |
409 | project_inactive | プロジェクトが有効な状態ではない(一時停止中、またはアーカイブ済み) |
409 | principal_suspended | プロジェクトを実行する人の利用を、管理者が止めている。管理者に、プロジェクトの持ち主を変更するか、利用の停止を解くよう頼む |
409 | start_step_in_branch_lane | 開始の工程が条件分岐のレーンの中にある。時間トリガーの開始する工程を、条件分岐のレーンの外の工程にしてください |
409 | definition_pending | プロジェクトの最初の定義が承認待ちの間は始められない。承認する人(ほかのオーナーか組織の管理者)が製品の画面で承認してから始めてください |
409 | relink_required | 取り込みで見つからなかった参照をつなぎ直すまで、プロジェクトを始められない・再開できない。プロジェクトの取得の relink と配置の relink に、残っている参照が出ます。起動を断る参照の外し方: kind が "agent" の行は Agent を置き直す(POST /v1/projects/{projectId}/placements)、kind が "connector" の行は製品の画面で連携先を保存し直す、配置の relink(置いた Agent が指す、見つからなかったプレイブック・スキル)は Agent を spec つきで保存し直す(PATCH /v1/agents/{agentId}。spec を送らない更新では外れません)。blocking が false の行は実行を断らない、必要に応じて再度設定する項目で、DELETE /v1/projects/{projectId}/relink で消せますが、それだけでは始められません |
409 | branch_ai_unavailable | AI に判定させる条件分岐の工程を、この環境では実行できない。管理者に判定の設定を頼むか、製品の画面でその工程を止めてから、新しく始めてください |
409 | automation_dlp_enabled | DLP 連携が有効な間は、外部の自動化の工程を保存・実行できない。管理者に DLP 連携を切ってもらってください。それまでは、外部の自動化の工程を止めるか外せば始められます |
409 | automation_destination_missing | 外部の自動化の工程の宛先が見つからない。工程を変える API で automationConfig.destinationId を宛先の一覧(GET /v1/projects/automation-destinations)の有効な宛先にするか、その工程を止めてください。一覧に宛先が無いときは、管理者に頼んでください |
409 | automation_destination_inactive | 外部の自動化の工程の宛先が無効。管理者に宛先を有効にしてもらうか、工程を変える API で automationConfig.destinationId を宛先の一覧(GET /v1/projects/automation-destinations)の別の有効な宛先にするか、その工程を止めてください |
409 | admin_stopped | プロジェクトを、管理者が止めている。再開は管理者に頼む(この API では再開できない) |
409 | unsupported_runtime | プロジェクト内のエージェントの実行環境が混在しているなど、実行できない構成 |
409 | origin_conflict | 同じ Idempotency-Key で、違う payload を送った |
429 | too_many_active_runs | 同じプロジェクトで、実行中と確認待ちの実行が合わせて上限(3 件)に達している |
POST/v1/projects/{projectId}/triggers/{triggerId}/fire
cycle 型のプロジェクトに設定された Webhook トリガーを発火し、対象のエージェントを臨時に 1 回だけ実行します。workflow 型に対して呼び出すと 404 Not Found が返ります。
定期実行の設定はそのまま維持されます。発火による実行は、定期実行とは別に追加されるものです。ただし、先の発火がまだ動き始めていない場合、あとの発火はその実行にまとまることがあります。まとまったときは jobId に先の発火と同じ値が返るため、発火の回数と実行の回数は必ずしも一致しません。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|
projectId | string | 必須 | プロジェクトの ID(UUID) |
triggerId | string | 必須 | 発火するトリガーの ID(UUID) |
リクエストボディ
| パラメータ | 型 | 必須 | 説明 |
|---|
eventId | string | 必須 | 送信側が採番する一意な ID。同じ ID の再送は重複として扱われます。1〜160 文字で、使用できる文字は半角英数字と _ . : @ + - です |
payload | any | — | エージェントへ渡す任意の JSON。JSON の文字列にして、エージェントへの依頼に添えて渡されます。文字列にしたときに 8,000 文字を超える部分は省略されます |
リクエスト例
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}'
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/triggers/d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70/fire \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"eventId": "order-20261118-0001",
"payload": {
"orderId": "A-1024"
}
}'import requests
response = requests.post(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/triggers/d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70/fire",
headers={"Authorization": f"Bearer {token}"},
json={'eventId': 'order-20261118-0001', 'payload': {'orderId': 'A-1024'}},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/triggers/d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70/fire",
{
method: "POST",
headers: {
"Authorization": "Bearer " + accessToken,
"Content-Type": "application/json",
},
body: JSON.stringify({"eventId": "order-20261118-0001", "payload": {"orderId": "A-1024"}}),
}
);
const data = await response.json();
console.log(data);payload := []byte(`{"eventId": "order-20261118-0001", "payload": {"orderId": "A-1024"}}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/triggers/d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70/fire", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
レスポンスフィールド(202 Accepted)
| フィールド | 型 | 説明 |
|---|
result | string | "accepted"(新しく受け付けた)または "duplicate"(同じ eventId で受付済み) |
jobId | string | 受付先のジョブ ID。実行状況の取得(GET /v1/projects/{projectId}/runs/{runId})には使えません |
レスポンス例
{
"result": "accepted",
"jobId": "9b2e4c61-0f3a-4a9b-9c1d-2f7e5a8b3c40"
}
ここでの 202 Accepted は、受付を記録したことだけを表します。実行はこの後に行われ、その成否はこの応答に含まれません。実行の結果は含まないため、202 を業務上の成功として扱わないでください。
冪等性はプロジェクト・トリガー・eventId の組み合わせで判定されます。同じ内容で再送すると 202 と result: "duplicate" が返ります。同じ eventId で payload が異なる場合は 409 Conflict(event_conflict)が返ります。
エラーレスポンス
| ステータス | code | 説明 |
|---|
400 | invalid_event_id | eventId が無い、または形式が不正 |
400 | invalid_parameter | projectId または triggerId が UUID の形式ではない |
400 | invalid_body | リクエストボディが壊れた JSON、または JSON のオブジェクトではない |
415 | unsupported_media_type | リクエストボディがあるのに、Content-Type が application/json ではない |
403 | insufficient_scope | project:run スコープが不足 |
403 | invalid_project_grant | プロジェクト制限が未設定、または設定内容が不正 |
404 | trigger_not_found | プロジェクト・トリガーが存在しない、アクセス権が無い、Webhook ではないトリガーを指定した、または workflow 型のプロジェクトを指定した |
409 | trigger_disabled | トリガーが無効化されている |
409 | project_not_active | プロジェクトが実行可能な状態にない |
409 | principal_suspended | プロジェクトを実行する人の利用を、管理者が止めている。管理者に、プロジェクトの持ち主を変更するか、利用の停止を解くよう頼む |
409 | admin_stopped | プロジェクト、または発火で動かす配置の Agent を、管理者が止めている。再開は管理者に頼む |
409 | placement_unavailable | 発火対象のエージェント配置が存在しない、実行主体が未設定、または配置の工程が無効(工程を有効に戻せるのはプロジェクトのオーナー。有効に戻してから送り直す) |
409 | event_conflict | 同じ eventId で payload が異なる |
413 | body_too_large | リクエストボディが 16 KiB を超過 |
GET/v1/projects/{projectId}/runs/{runId}
実行の状況を取得します。API(POST /v1/projects/{projectId}/runs)で開始した実行のほか、画面・メール・定期実行で始まった実行も取得できます。cycle 型のプロジェクトは実行(run)を作らないため、このエンドポイントの対象外です。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|
projectId | string | 必須 | プロジェクトの ID(UUID) |
runId | string | 必須 | 実行の ID(UUID) |
リクエスト例
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>"
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13 \
-H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
headers={"Authorization": f"Bearer {token}"},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
{
headers: {
"Authorization": "Bearer " + accessToken,
},
}
);
const data = await response.json();
console.log(data);req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
レスポンスフィールド(200 OK)
| フィールド | 型 | 説明 |
|---|
runId | string | 実行の ID(UUID) |
status | string | 実行の状態。"running"(実行中)/ "waiting_gate"(確認待ち)/ "closed_done"(完了)/ "closed_rejected"(却下で終了)/ "closed_failed"(失敗で終了)/ "cancelled"(中断)のいずれか。"running" と "waiting_gate" 以外は、実行が終わったことを表します。ただし "closed_rejected" と "closed_failed" は、オーナーか運用担当(組織の運用の役割の人を含む)が再開すると、同じ実行が "running" に戻ります(endedAt も null に戻ります) |
originType | string | null | 実行の始まり方。"manual"(画面から開始)/ "api"(API で開始)/ "mail"(メールで開始)/ "cron"(定期実行)のいずれか |
originRef | string | null | 始まり方ごとの参照値。API で開始した実行では、開始したときの Idempotency-Key の値 |
currentStepId | string | null | 進んでいる工程の ID(UUID)。レーンに分かれて進んでいる間は、分岐する前の工程の ID。完了した実行では null。ほかの理由で終わった実行では、終わったときの工程の ID が残る場合があります |
startedByRef | string | null | 実行を始めたもの。値は下の「実行を始めたもの」の表のとおり |
actorLabel | string | null | 利用者ではない起動者の表示名(システム連携の名前、またはメールの送信元のアドレス)。それ以外は null |
startedAt | string | null | 開始日時(ISO 8601)。開始前は null |
endedAt | string | null | 終了日時(ISO 8601)。終了前は null。閉じた実行を再開すると null に戻ります |
summary | string | null | 完了した実行で、出力が記録された最後の完了した工程の出力(先頭 2,000 文字)。そうした工程が無い場合と、完了していない実行では null |
runtimeKind | string | null | 実行環境の種類("autonomous")。古い実行では null の場合があります |
cancelRequestedAt | string | null | 中断が求められた日時(ISO 8601)。求められていなければ null |
deadlineAt | string | null | ワークフローの実行の締め切り(ISO 8601)。締め切りが無ければ null |
configRevision | number | null | 案件設定のバージョン(Marketplace 版の実行だけ)。SaaS 版の実行では null |
steps | array | 工程ごとの実行の記録。記録した順 |
steps[].runStepId | string | 工程の実行の ID("rs:" で始まる) |
steps[].stepId | string | null | 工程の ID(UUID) |
steps[].placementId | string | null | その工程を担当した配置の ID(UUID)。Agent を動かさない行(確認の工程など)では null |
steps[].executionId | string | null | Agent の実行の ID。Agent を動かし始めると付きます。外部の自動化の工程では null |
steps[].conversationId | string | null | Agent の実行の会話の ID。Agent を動かし始めると付きます |
steps[].status | string | "pending"(実行待ち)/ "running"(実行中)/ "waiting_gate"(確認待ち)/ "done"(完了)/ "failed"(失敗)/ "skipped"(実行を省略)のいずれか |
steps[].attempt | number | null | 同じ回の中での再試行の回数(1 から)。閉じた実行の再開と、接続の確認の承認で起動し直したときも増えます |
steps[].lane | string | null | 工程が属するレーンの ID。レーンに分かれていない工程は "main" |
steps[].scheduledAt | string | null | 工程に時刻が設定されているとき、その時刻まで待つ行の予定日時(ISO 8601)。動き始めると null |
steps[].startedAt | string | null | 開始日時(ISO 8601) |
steps[].endedAt | string | null | 終了日時(ISO 8601) |
steps[].outputSummary | string | null | 工程の出力の要約 |
steps[].outcome | string | null | Agent の実行か、外部の自動化の工程の送信の結果。"completed" / "incomplete" / "failed" / "timeout" / "stopped" / "denied" / "skipped" のいずれか。結果の無い行では null |
steps[].reasonCode | string | null | 結果の理由コード。条件分岐で決められず人に選択してもらうときは "branch_undecided"、条件分岐で選ばれなかったレーンの工程は "branch_not_selected" |
steps[].held | boolean | プロジェクトの一時停止で止めていて、再開を待っているか |
steps[].visit | number | null | この工程に来た何回目か(差し戻しで増えます)。記録の無い行では null |
steps[].reworkReason | string | null | 差し戻しの理由 |
steps[].gateFor | string | null | この確認の行が、どの工程の実行(runStepId)のために立ったか |
steps[].routedFrom | string | null | 次の工程を決定して工程を飛ばしたとき、次の工程を決定した工程の実行(runStepId) |
steps[].late | string | null | 結果が遅れて届き、進行に使わなかった理由 |
steps[].gate | object | null | 確認の要約。確認の工程の行と、接続の確認の待ちの行(gateKind が "connection")に付きます。それ以外の行では null |
steps[].gate.decision | string | null | "proceed"(進める)/ "send_back"(差し戻す)/ "reject"(却下)のいずれか。決まっていなければ null |
steps[].gate.waitSource | string | null | 何を待つ確認か。"human"(人の判断)/ "external"(外部の条件) |
steps[].resumeCommandId | string | null | 閉じた実行の再開でこの行を起動したときの commandId。その再開で起動した行(選んだ工程と、起動し直したほかのレーン)に付きます。それ以外は null |
steps[].resumeReason | string | null | 閉じた実行の再開の理由の文。resumeCommandId と同じ行に付きます。それ以外は null |
steps[].supersededBy | string | null | 閉じた実行の再開で、前の回に残っていた行を閉じたとき "resume"。それ以外は null |
steps[].gateKind | string | null | 接続の確認の待ちの行(Agent が人の確認の要る連携先を使おうとして止めたときに立つ行)なら "connection"。それ以外は null |
steps[].connectionConfirmOf | string | null | 接続の確認の承認で起動し直した行なら、その確認依頼の ID(workItemId)。それ以外は null |
steps[].handoff | object | null | この工程の実行で次の工程に渡した値と資料。工程に次の工程に渡す値と資料の役割(outputConfig)が無ければ null |
steps[].handoff.values | object | 値の名前 → 返された文(1 つ 1,000 文字まで) |
steps[].handoff.files | object | 役割の名前 → { filename }(その役割の資料のファイル名) |
steps[].handoff.missing[] | object[] | 届かなかった物。name(値か役割の名前)と reason("not_returned"〈Agent が返さなかった〉/ "file_not_found"〈成果物に無い〉) |
steps[].handoff.truncated | string[] | 1,000 文字で切った値の名前。無ければ [] |
plannedPlacements | array | 開始したときの設定で、動く予定の工程と配置の並び |
plannedPlacements[].stepId | string | null | 工程の ID(UUID) |
plannedPlacements[].placementId | string | null | 配置の ID(UUID)。確認の工程と Agent の無い工程では null |
lanes | array | 分岐した後の、レーンごとの状況。分岐する前と、レーンを使わない実行では空の配列 |
lanes[].laneId | string | レーンの ID |
lanes[].name | string | null | レーンの名前 |
lanes[].position | number | null | レーンの並び(1 から) |
lanes[].state | string | "running"(実行中)/ "waiting_gate"(確認待ち)/ "arrived"(合流待ち)/ "closed"(終了)のいずれか |
lanes[].currentStepId | string | null | そのレーンで進んでいる工程の ID(UUID)。合流待ちのレーンでは null。終わったレーンでは、最後の工程の ID が残る場合があります |
lanes[].arrived | boolean | 合流する地点に着いたか |
項目は、呼び出しに使ったトークン(アプリケーションかシステム連携か)によらず同じです。
実行を始めたもの
| 始めたもの | startedByRef | actorLabel |
|---|
| 利用者(画面・API、またはメンバーのアドレスから送ったメール) | 利用者 ID | null |
| システム連携 | "client:" に続くシステム連携の Client ID。Client ID が分からない場合は "system:federation-api" | システム連携の名前(分からない場合は null) |
| メンバーではないアドレスから送ったメール | "mail:" に続く送信元のハッシュ | 送信元のアドレス |
| 定期実行 | null | null |
2026-09-25 より前にシステム連携が始めた実行では、startedByRef は null です。
レスポンス例
{
"runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"status": "running",
"originType": "api",
"originRef": "nightly-batch-20260917",
"currentStepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
"startedByRef": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"actorLabel": null,
"startedAt": "2026-09-17T01:30:00.000Z",
"endedAt": null,
"summary": null,
"runtimeKind": "autonomous",
"cancelRequestedAt": null,
"deadlineAt": null,
"configRevision": null,
"steps": [
{
"runStepId": "rs:1042",
"stepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
"placementId": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8",
"executionId": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
"conversationId": "9c8b7a6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
"status": "running",
"attempt": 1,
"lane": "main",
"scheduledAt": null,
"startedAt": "2026-09-17T01:30:01.000Z",
"endedAt": null,
"outputSummary": null,
"outcome": null,
"reasonCode": null,
"held": false,
"visit": 1,
"reworkReason": null,
"gateFor": null,
"routedFrom": null,
"late": null,
"gate": null,
"resumeCommandId": null,
"resumeReason": null,
"supersededBy": null,
"gateKind": null,
"connectionConfirmOf": null,
"handoff": null
}
],
"plannedPlacements": [
{ "stepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f", "placementId": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8" },
{ "stepId": "c2f1a8e4-6b3d-4e7a-9c15-8d2e4f6a7b90", "placementId": null }
],
"lanes": []
}
エラーレスポンス
| ステータス | code | 説明 |
|---|
400 | invalid_parameter | projectId または runId が UUID の形式ではない |
403 | insufficient_scope | project:read スコープが不足 |
403 | invalid_project_grant | プロジェクト制限が未設定、または設定内容が不正 |
404 | run_not_found | 実行が存在しない、別のプロジェクトの実行を指定した、またはアクセス権が無い |
POST/v1/projects/{projectId}/runs/{runId}/cancel
実行中か確認待ちのワークフローの実行(status が "running"・"waiting_gate")を中断します。画面の「中断する」と同じです。
中断すると、次のようになります。
- ワークフローの実行の
status が "cancelled"(中断)になります。元に戻せず、再開もできません(再開できるのは、却下・失敗で閉じたワークフローの実行だけです)。
-
進行中の工程は失敗の扱いになり、動いている Agent には停止を伝えます。
- 確認工程の、まだ判断されていない確認依頼は取り下げられます。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|
projectId | string | 必須 | プロジェクト ID(UUID) |
runId | string | 必須 | ワークフローの実行の ID(UUID) |
リクエストボディ
| フィールド | 型 | 必須 | 説明 |
|---|
commandId | string | 必須 | 送り直しを見分ける値(英数字と _ . : - の 8〜128 文字) |
reason | string | — | 中断の理由(500 文字まで) |
- 動いていないワークフローの実行(終わった後・中断した後)に送ると、何も変えずに
200 OK が返り、existing が true です。中断した後に送り直したときも同じです。
- ほかの中断や、ワークフローの実行が終わるのと同じころに送ると、
202 Accepted と 200 OK の別と existing が、実際と合わないことがあります。結果は、ワークフローの実行の取得(GET /v1/projects/{projectId}/runs/{runId})の status で確かめてください。
504 Gateway Timeout は「中断されなかった」ことを意味しません。同じ commandId で送り直すか、ワークフローの実行の取得で status を確かめてください。
リクエスト例
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}'
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/cancel \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"commandId": "cancel-20261118-0001",
"reason": "入力データの誤りに気づいたため"
}'import requests
response = requests.post(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/cancel",
headers={"Authorization": f"Bearer {token}"},
json={'commandId': 'cancel-20261118-0001', 'reason': '入力データの誤りに気づいたため'},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/cancel",
{
method: "POST",
headers: {
"Authorization": "Bearer " + accessToken,
"Content-Type": "application/json",
},
body: JSON.stringify({"commandId": "cancel-20261118-0001", "reason": "入力データの誤りに気づいたため"}),
}
);
const data = await response.json();
console.log(data);payload := []byte(`{"commandId": "cancel-20261118-0001", "reason": "入力データの誤りに気づいたため"}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/cancel", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
レスポンスフィールド(202 Accepted / 200 OK)
この要求で新しく中断したときは 202 Accepted、新しく中断しなかったときは 200 OK です。
| フィールド | 型 | 説明 |
|---|
runId | string | ワークフローの実行の ID |
status | string | 送った後のワークフローの実行の状態(中断したときは "cancelled") |
cancelRequestedAt | string | null | 中断を受けた日時(ISO 8601)。中断されていないワークフローの実行では null |
existing | boolean | この要求で新しく中断しなかったとき true(202 Accepted のときはいつも false) |
レスポンス例
{
"runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"status": "cancelled",
"cancelRequestedAt": "2026-11-18T05:12:30.000Z",
"existing": false
}
エラーレスポンス
| ステータス | code | 説明 |
|---|
400 | invalid_parameter | projectId・runId が UUID の形式ではない、commandId が無い・形の誤り、または reason が文字列ではない・500 文字を超える |
400 | invalid_body | ボディが壊れた JSON、または JSON のオブジェクトではない |
403 | insufficient_scope | project:run スコープが不足 |
403 | invalid_project_grant | プロジェクト制限が未設定、または設定内容が不正 |
404 | run_not_found | ワークフローの実行が存在しない、ほかのプロジェクトのもの、またはアクセス権の無いプロジェクト |
413 | body_too_large | ボディが 16 KiB を超える |
415 | unsupported_media_type | ボディの Content-Type が application/json ではない |
プロジェクト API の注意事項
| 項目 | 内容 |
|---|
| 404 の意味 | プロジェクトが存在しない場合とアクセス権が無い場合は、どのエンドポイントでも同じ 404 Not Found が返り、どちらであるかは応答から区別できません。code はエンドポイントごとに決まっていて、実行の開始は project_not_found、トリガーの発火は trigger_not_found、実行状況の取得とワークフローの実行の中断は run_not_found です。 |
| 型が対象外の場合 | 発火を workflow に対して呼んだ場合、および実行状況の取得とワークフローの実行の中断を cycle のプロジェクトに対して呼んだ場合は 404 です。実行の開始を cycle に対して呼んだ場合だけは例外で、409 unsupported_project_type が返ります。 |
| リクエストボディ | ボディを送る場合は、JSON オブジェクトにしてください。Content-Type: application/json 以外は 415、壊れた JSON や JSON のオブジェクトではないボディは 400(invalid_body)、16 KiB を超えるボディは 413 が返ります。 |
| 未知のフィールド / クエリ | 仕様に無いフィールドやクエリパラメータは無視されます。仕様にあるクエリパラメータの値が不正な場合と、読めない cursor を指定した場合は 400 Bad Request が返ります。 |
| タイムアウト | 504 Gateway Timeout は「実行されなかったこと」を意味しません。実行の開始は同じ Idempotency-Key で、発火は同じ eventId と同じ本文で、ワークフローの実行の中断は同じ commandId で、そのまま再送してください。 |
エラーレスポンス
HTTP ステータスコード
すべてのエンドポイントで返される可能性のある HTTP ステータスコードです。
| ステータス | 説明 |
|---|
400 Bad Request | リクエストパラメータが不正 |
401 Unauthorized | トークンが無効または未指定 |
403 Forbidden | リソースへのアクセス権限なし |
404 Not Found | リソースが存在しない |
409 Conflict | リソースが競合(例: 既存コードとの重複) |
413 Payload Too Large | リクエストボディがサイズ上限を超過 |
415 Unsupported Media Type | リクエストボディの形式(Content-Type)に対応していない |
429 Too Many Requests | レート制限を超過 |
500 Internal Server Error | サーバー内部エラー |
502 Bad Gateway | 上流サービスとの通信エラー |
503 Service Unavailable | サービス一時利用不可 |
504 Gateway Timeout | 上流サービスの応答タイムアウト |
エラーレスポンス形式
すべてのエラーレスポンスは以下の共通構造で返されます。
| フィールド | 型 | 説明 |
|---|
error.type | string | エラーの分類。"invalid_request_error"、"authentication_error"、"insufficient_scope_error"、"forbidden_error"、"not_found_error"、"conflict_error"、"payload_too_large_error"、"rate_limit_error"、"server_error"、"upstream_error" のいずれか |
error.message | string | 人間が読めるエラーメッセージ |
error.code | string | 機械的に処理可能なエラーコード(例: "missing_parameter"、"invalid_parameter"、"invalid_token") |
error.param | string | エラーの原因となったパラメータ名。バリデーションエラー時のみ含まれます |
error.suggested_action | string | 推奨される対処方法。一部のエラーでのみ含まれます |
{
"error": {
"type": "invalid_request_error",
"message": "Invalid parameter: limit",
"code": "invalid_parameter",
"param": "limit",
"suggested_action": "limit must be between 1 and 100"
}
}
前段の仕組みで止められたとき
API の前段の仕組み(セキュリティの検査など)が HTML のエラー画面を返した場合は、上の共通の形の JSON に置き換えて返します。このときの error.code は次のとおりです。
| ステータス | error.code | 説明 |
|---|
| 403 | waf_blocked | リクエストが、API の前段にあるセキュリティの検査に止められました。正当なリクエストの場合は、error.reference(無い場合は応答ヘッダーの x-request-id)を添えてお問い合わせください |
| 403 以外の 4xx・5xx | upstream_api_error | リクエストが、API の前段の仕組みで拒否されたか、そこでエラーになりました。続く場合は、error.reference(無い場合は応答ヘッダーの x-request-id)を添えてお問い合わせください |
| フィールド | 型 | 説明 |
|---|
error.reference | string | 前段の仕組みで止められたときの参照番号。お問い合わせのときに添えてください。値が無い場合は含まれません |
{
"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 |