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

ユーザー API リファレンス(会話・ライブラリ・組織)

SaaS 版のユーザー向け API のエンドポイント仕様とエラーコードのリファレンスです。システム連携から呼ぶ API は システム連携 API リファレンス を参照してください。マーケットプレイス版は システム連携 API リファレンス(マーケットプレイス版) を参照してください。

ベース URL​

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

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

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

認証​

すべてのAPIリクエストには、Authorization ヘッダーに Bearer トークンを含める必要があります。このページは、アプリケーション(Authorization Code フロー)で取ったトークンで呼ぶときの仕様です。システム連携(Client Credentials フロー)のトークンは chat のスコープを持てないため、チャットには使えません(プロジェクトの一部は呼べます。システム連携 API リファレンス — プロジェクト)。

Authorization: Bearer <access_token>

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

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

共通の決まり​

このページの 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)
ファイルのアップロードへの、multipart/form-data 以外のボディ415 Unsupported Media Type
型の違うボディのフィールド400 Bad Request

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

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

ページネーション​

一覧取得エンドポイントはカーソルベースのページネーションをサポートしています。

パラメータ型説明
limitinteger1ページあたりの取得件数(1-100)。デフォルトは 50 件です
cursorstring次のページを取得するためのカーソル値。前回のレスポンスに含まれる cursor をそのまま指定します
orderstringソート順。"asc"(昇順)または "desc"(降順、デフォルト)。ほかの値を指定すると 400 Bad Request が返ります。対応するエンドポイントは一部です

レスポンスには hasMore フィールドが含まれます。true の場合、cursor の値を次のリクエストに渡すことで次ページを取得できます。

カーソルベースのページネーションに対応しているのは、会話一覧・メッセージ一覧・ファイル一覧・メッセージの検索・ライブラリ・Agent・スキル・プレイブック・プロジェクト一覧 の各一覧エンドポイントです。cursor は不透明な値のため、内容を解釈せず、前回レスポンスの値をそのまま次のリクエストに指定してください。

スキルのバージョンの一覧(GET /v1/skills/:skillId/versions)はページネーションに対応していません。新しいバージョンから 100 個までを返し、hasMore はいつも false です。

チャット​

OpenAI互換のChat Completions APIです。エージェントとの対話はSSE(Server-Sent Events)ストリーミングで配信されます。

チャットAPIは3つのエンドポイントで構成されます。メッセージの送信、既存会話への再接続、進行中の会話のキャンセルが可能です。

SSE ストリーミングガイド

接続フロー・レスポンスオブジェクト・Delta拡張・実行パターン・再接続・エラーハンドリングの詳細解説

ガイドを見る

エンドポイント一覧​

メソッドエンドポイント説明スコープ (SaaS)
POST/v1/chat/completionsチャットメッセージを送信し、SSEストリーミングでレスポンスを取得chat:exec
GET/v1/chat/completions/:conversationId進行中の会話のSSEストリームに再接続chat:exec
POST/v1/chat/completions/:conversationId/cancel進行中の会話をキャンセルchat:exec

※ Marketplace 版はスコープ不要(認証のみ)。

POST/v1/chat/completions

エージェントにメッセージを送信し、SSEストリーミングでレスポンスを受け取ります。レスポンスはOpenAI互換のChat Completion Chunk形式で配信されます。

リクエストヘッダー​

ヘッダー必須説明
Authorization必須Bearer <access_token>
Content-Type必須application/json

リクエストボディ​

パラメータ型必須説明
modelstring必須使用するモデルID。"AGENTIC STAR" を指定してください。
messagesarray必須メッセージオブジェクトの配列。少なくとも 1 つの user ロールメッセージが必要。複数の user メッセージを含めても最後の 1 件のみが処理されます。会話履歴はサーバー側で管理されるため、過去のやり取りを messages 配列で送る必要はありません。既存の会話を継続する場合は conversationId パラメータに前回の会話 ID を指定してください。
streamboolean必須true を指定してください。現在、ストリーミングモードのみサポートしています。
conversationIdstring—既存の会話を継続する場合に会話IDを指定します。省略すると新しい会話が作成されます。

エディション固有のパラメータ​

SaaS
agentLevelstring"default" または "high_performance"。省略時は "default"。
agentModebooleanエージェントモードの有効/無効。省略時は true。
privateModebooleanプライベートモードの有効/無効。省略時は false。
reportModestring"with"(省略時)または "without"。完了時に作業報告書を生成するかを制御します。
personaKeystringエージェントの応答人格(ペルソナ)を指定。GET /v1/personas が返す personaKey を指定します。省略時はペルソナを適用しません。一覧に無い値は 400 を返します。
playbookIdstring実行手順(プレイブック)を指定。GET /v1/playbooks が返す playbookId を指定します。省略時はプレイブックを適用しません。存在しない・無効化されている ID を指定した場合は 400 を返します。
skillIdsarrayエージェントに読み込ませるスキルの ID 配列(最大 10 件)。GET /v1/skills が返す skillId を指定します。11 件以上を指定した場合は 400 を返します。存在しない ID や利用できない ID は無視され、残りのスキルで実行されます。
outputFormatstring応答テキストの形式。"plain"(省略時)は Markdown 記法を除去したプレーンテキスト(図は削除され、コードブロックは本文が残り、リンクは「文字 (URL)」になる)。"markdown" は Markdown 記法をそのまま保持する。
interactionReplyobjectAgent の質問への答えの印。{ interactionId, optionIndex? } の形で、この会話で返事待ちの質問の interactionId(ストリーミングの delta.interaction.interactionId、または会話の履歴の tasks[].metadata.interactionId)と、選択肢から選んだ答えなら選んだ選択肢の番号(0〜9。最初が 0)を送ります。付けると、その質問への答えとして記録され、月の利用の枠の上限に達していても答えられます。conversationId と一緒に送ります。形が違う・知らない項目がある・この会話で返事待ちの質問の ID ではない・選択肢の外の番号のときは 400(invalid_parameter)。

Message オブジェクト​

パラメータ型必須説明
rolestring必須"user" を指定。"assistant" / "system" は受理されますが、現状のエージェント実行では "user" のみが対話の起点として使用されます
contentstring | array必須メッセージの内容。文字列、または content parts (text / input_file) の配列。処理対象となるテキストは UTF-8 換算で 1 MB 以下。

コンテンツパーツ(配列形式の場合)​

content を配列で指定する場合、以下のパーツタイプが利用できます。テキストとファイルを組み合わせて送信できます。

typeパラメータ説明
"text"text (string)テキストメッセージ
"input_file"fileId または filepath (string)アップロード済みファイルの fileId、または GET /v1/library が返す filepath(ライブラリファイル)のいずれか一方。1リクエストあたり合計最大20件

リクエスト例​

Create chat completion
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/chat/completions \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "model": "AGENTIC STAR",
6 "stream": true,
7 "messages": [
8 {
9 "role": "user",
10 "content": "売上データを分析してください"
11 }
12 ]
13}'

レスポンスヘッダー​

ヘッダー説明
Content-Typetext/event-stream
X-Conversation-Id会話ID。新規会話の場合はサーバーが生成したIDが返されます。
X-Message-Idアシスタントの応答メッセージID。

SSE レスポンス形式​

レスポンスは以下の順序でSSEイベントとして配信されます。各イベントは data: プレフィックス付きのJSON行です。

SSEイベントフロー
1. data: {"choices":[{"delta":{"role":"assistant"}}]}
2. data: {"choices":[{"delta":{"content":"..."}}]} × N
3. data: {"choices":[{"finishReason":"stop"}]}
4. data: [DONE]

レスポンスは SSE(Server-Sent Events)ストリーミングで配信されます。各チャンクは OpenAI 互換の ChatCompletionChunk 形式です。接続ライフサイクル、レスポンスオブジェクトの詳細、エージェント拡張フィールド、エラーハンドリングについてはストリーミングガイドを参照してください。

レスポンス例​

SSE
data: {"createdAt":"2026-03-14T10:30:00Z","model":"AGENTIC STAR","choices":[{"index":0,"delta":{"role":"assistant"},"finishReason":null}]}

data: {"createdAt":"2026-03-14T10:30:00Z","model":"AGENTIC STAR","choices":[{"index":0,"delta":{"content":"売上データ"},"finishReason":null}]}

data: {"createdAt":"2026-03-14T10:30:00Z","model":"AGENTIC STAR","choices":[{"index":0,"delta":{"content":"を分析します。"},"finishReason":null}]}

data: {"createdAt":"2026-03-14T10:30:01Z","model":"AGENTIC STAR","choices":[{"index":0,"delta":{},"finishReason":"stop"}]}

data: [DONE]

エラーレスポンス​

SSEストリーム開始前のエラーはJSON形式で返されます。ストリーム中のエラーはSSEチャンクとして配信されます。

ステータス説明
400リクエストパラメータ不正(model / messages / stream / conversationId / role / content の欠落・型不一致、または input_file が1リクエストあたり20件を超過、reportMode が "with" / "without" 以外)。ボディが壊れた JSON(code: "invalid_body")。または、指定した conversationId がアーカイブ済み(code: "conversation_archived")。interactionReply の形が違う・知らない項目がある・この会話で返事待ちの質問の ID ではない・選択肢の外の番号(code: "invalid_parameter"。param は interactionReply、または interactionReply.interactionId のように interactionReply. を頭に付けた項目の名前)、または interactionReply を conversationId なしで送った(code: "missing_parameter")
400messages に user ロールのメッセージが 1 つも無い(code: "no_user_message")
400personaKey が GET /v1/personas の一覧に無い(code: "invalid_parameter"・param: "personaKey")
400playbookId のプレイブックが存在しない(code: "playbook_not_found")、または無効化されている(code: "playbook_not_active")
415ボディの Content-Type が application/json ではない(code: "unsupported_media_type")
403chat:exec スコープが不足、または指定した会話がプロジェクトの会話(code: "project_conversation"。プロジェクトの会話には送れません)
404指定した input_file の fileId または filepath が見つからない(code: "file_not_found")
409指定した会話が現在処理中(code: "conversation_processing")
403エージェントモードの依頼(agentMode が true。省略したときも true)を、管理者が許可していない(code: "feature_not_permitted"・param: "agentMode")。agentMode を false にして送り直すか、管理者に許可を頼む
503機能の許可を確かめられない(code: "feature_permissions_unavailable")。時間をおいて送り直す

GET/v1/chat/completions/:conversationId

進行中の会話のSSEストリームに再接続します。エージェントが長時間実行タスクを処理している場合や、ネットワーク切断後の復帰に使用します。

パスパラメータ​

パラメータ型必須説明
conversationIdstring必須再接続する会話のID

リクエスト例​

Resume SSE stream
1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000 \
2-H "Authorization: Bearer <access_token>"

レスポンス(200 OK)​

SSE ストリームに再接続します。レスポンス形式は POST /v1/chat/completions と同じです。レスポンスヘッダーに X-Conversation-Id と X-Message-Id が含まれます。再接続の詳細な手順についてはストリーミングガイドを参照してください。

エラーレスポンス​

ステータスcode説明
403insufficient_scopechat:exec スコープが不足
404not_found会話が見つからない、進行中でない、または自分の会話ではない(conversationId が空の値のときも同じ)

POST/v1/chat/completions/:conversationId/cancel

進行中の会話をキャンセルします。エージェントの実行を中断する場合に使用します。

パスパラメータ​

パラメータ型必須説明
conversationIdstring必須キャンセルする会話のID

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

パラメータ型必須説明
messageIdstring—キャンセル対象のメッセージID(UUID)。省略時は会話全体のキャンセル。

リクエスト例​

Cancel chat
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000/cancel \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json"

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

フィールド型説明
conversationIdstringキャンセルされた会話のID(UUID)
cancelledbooleanキャンセル成功時は常に true

レスポンス例​

JSON
{ "conversationId": "550e8400-...", "cancelled": true }

エラーレスポンス​

ステータス説明
400conversationId が不正、messageId が文字列ではない、ボディが壊れた JSON または JSON のオブジェクトではない(code: "invalid_body")、または会話がアーカイブ済み(code: "conversation_archived")
400messageId のメッセージが、指定した会話のものではない(code: "conversation_mismatch")
400この会話の接続先がキャンセルに対応していない(code: "unsupported_endpoint")、またはこの環境でキャンセルが有効になっていない(code: "post_processing_not_enabled")
415ボディの Content-Type が application/json ではない(code: "unsupported_media_type")
403chat:exec スコープが不足
404会話が見つからない、またはメッセージを止められない(code: "message_not_found")。message_not_found は、送った直後で 10 秒ほど待っても止められなかったとき(数秒後にもう一度送れば止まります)と、messageId のメッセージが無い、または自分のものではないとき(送り直しても止まりません。messageId を確かめてください)の 2 つです
404messageId のメッセージが処理中ではない(すでに終わっている。code: "not_processing")

会話管理​

会話の一覧取得・メッセージ履歴参照・削除・タイトル更新を行います。

エンドポイント一覧​

メソッドエンドポイント説明スコープ (SaaS)
GET/v1/conversations会話一覧を取得chat:history
GET/v1/conversations/:conversationId/messagesメッセージ履歴を取得chat:history
GET/v1/conversations/:conversationId/ui-resources/:toolCallIdUI リソースの HTML を取得chat:exec / a2a:all / mcp:all
PATCH/v1/conversations/:conversationId会話のタイトルを更新chat:history
DELETE/v1/conversations/:conversationId会話を削除chat:history
POST/v1/conversations/:conversationId/restoreアーカイブ済み会話を復元chat:history
POST/v1/conversations/:conversationId/read会話を既読にするchat:history

※ Marketplace 版はスコープ不要(認証のみ)。

アーカイブ済みの会話は、管理者が保持の期間を決めていると、アーカイブしてからその日数を過ぎたときに自動で削除されます。 メッセージと、その会話だけで使っていた添付・成果物のファイルも一緒に削除されます。保持の期間を決めていなければ、削除されません。

アーカイブ会話への操作制約​

mode=archive で取得できるアーカイブ済み会話は、参照系の操作(一覧取得・メッセージ履歴取得)と復元のみ可能です。以下の操作は 400 エラー(code: "conversation_archived")になります。

操作アーカイブ済みでの動作
GET /v1/conversations?mode=archive✅ 取得可能
GET /v1/conversations/:id/messages✅ 取得可能(messages[].archived: true 付与)
PATCH /v1/conversations/:id❌ 400 Archived conversations cannot be modified
DELETE /v1/conversations/:id❌ 400 Archived conversations cannot be deleted via this endpoint
POST /v1/chat/completions(既存会話継続)❌ 400 Cannot send messages to an archived conversation
POST /v1/chat/completions/:id/cancel❌ 400 Cannot cancel an archived conversation
POST /v1/conversations/:id/restore✅ active に戻す

GET/v1/conversations

会話一覧を取得します。カーソルベースのページネーションに対応しています。

クエリパラメータ​

パラメータ型必須デフォルト説明
limitinteger—50取得件数(1〜100)
cursorstring——次ページ取得用カーソル(前回レスポンスの cursor 値)
orderstring—"desc""asc" または "desc"
titlestring——タイトルで絞り込み
modestring—"active""active"(通常会話)または "archive"(アーカイブ済み会話)。`mode` を切り替えると別データストアになるため、`cursor` は引き継げません

リクエスト例​

List conversations
1curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations?limit=10&order=desc" \
2-H "Authorization: Bearer <access_token>"

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

フィールド型説明
conversationsarray会話オブジェクトの配列
conversations[].conversationIdstring会話の一意識別子(UUID)
conversations[].titlestring会話のタイトル
conversations[].typestring?会話の種類。"chat"(チャット)・"mail"(メールから始めた会話)。プロジェクトの工程の会話は一覧に含まれません(会話 ID を指定すればメッセージを取得できます)。mode=archive では返しません
conversations[].createdAtstring作成日時(ISO 8601)
conversations[].updatedAtstring最終更新日時(ISO 8601)
conversations[].archivedboolean?アーカイブ済みかどうか。mode=archive で取得した場合は常に true。mode=active でこのフィールドが true で返るのは、archive 状態のまま active 一覧から取得された場合のみで、通常は省略されます
hasMoreboolean次のページが存在するかどうか
cursorstring次ページ取得用カーソル。hasMore が true の場合のみ含まれます

レスポンス例​

JSON
{
"conversations": [
{
"conversationId": "550e8400-e29b-41d4-a716-446655440000",
"title": "売上データ分析",
"type": "chat",
"createdAt": "2026-03-14T10:30:00Z",
"updatedAt": "2026-03-14T10:35:00Z"
}
],
"hasMore": true,
"cursor": "eyJrIjoiMjAyNi0wMy0xNFQxMDozMDowMC4wMDBaIn0"
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterlimit パラメータが不正(1〜100の範囲外)、mode が "active" / "archive" 以外、order が "asc" / "desc" 以外、cursor が不正(前回レスポンスの値以外)、または title が文字列ではない(複数回指定した場合など)
403insufficient_scopechat:history スコープが不足
502upstream_connection_error会話の一覧を取得できなかった(時間をおいて再試行してください)

GET/v1/conversations/:conversationId/messages

指定した会話のメッセージ履歴を取得します。カーソルベースのページネーションに対応しています。取得しても会話は既読になりません(MCP・A2A で読んでも同じです)。既読にするには会話を既読にするを呼びます。

パスパラメータ​

パラメータ型必須説明
conversationIdstring必須会話のID(UUID)

クエリパラメータ​

パラメータ型必須デフォルト説明
limitinteger—501 ページの取得件数(1-100)
cursorstring——次ページ取得用カーソル(前回レスポンスの cursor 値)
orderstring—"desc""asc" または "desc"

リクエスト例​

Get messages
1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/messages?order=asc \
2-H "Authorization: Bearer <access_token>"

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

フィールド型説明
messagesarrayメッセージオブジェクトの配列
messages[].conversationIdstring会話ID(UUID)
messages[].messageIdstringメッセージの一意識別子
messages[].senderstring送信者。"User" または "AI"
messages[].textstringメッセージの本文テキスト。本文が空のときは、いちばん新しいタスクの結果(content)が入ります
messages[].createdAtstring作成日時(ISO 8601)
messages[].updatedAtstring最終更新日時(ISO 8601)
messages[].statusobjectメッセージの処理状態
messages[].status.processingbooleanエージェントが現在処理中かどうか
messages[].status.unfinishedbooleanエージェントの応答が中断されたかどうか
messages[].tasksarrayエージェントが実行したタスクの配列(後述)
messages[].deliverablesarrayエージェントが生成した成果物の配列。存在する場合のみ含まれます
messages[].deliverables[].filenamestring成果物のファイル名
messages[].deliverables[].filepathstring成果物のファイルパス
messages[].deliverables[].sourcestring"agent"(エージェント生成)または "user"(ユーザーアップロード)
messages[].deliverables[].isPrimaryboolean主要成果物かどうか
messages[].deliverables[].createdAtstring作成日時(ISO 8601形式)。分からないときは空文字
messages[].deliverables[].mimeTypestringMIME タイプ(例: "application/pdf"、"text/markdown")。判定できない場合は "application/octet-stream"
messages[].deliverables[].sizenumber?ファイルサイズ(バイト)。0 以下の場合は省略
messages[].filesarray?ユーザーが添付したファイルの配列。sender: "User" のメッセージで添付がある場合のみ含まれます
messages[].files[].fileIdstringファイルの一意識別子(UUID)
messages[].files[].mimeTypestringMIME タイプ(例: "image/png"、"application/pdf")
messages[].files[].widthnumber?画像の幅(ピクセル)。画像ファイルの場合のみ
messages[].files[].heightnumber?画像の高さ(ピクセル)。画像ファイルの場合のみ
messages[].settingsobject?利用者の発言(sender: "User")を送ったときの設定。保存されている項目だけが入り、1 つも無ければ省略されます。各項目は送信(POST /v1/chat/completions)の同じ名前の項目と同じ意味です。アーカイブ済みの発言には付きません
messages[].settings.agentLevelstring?"default" / "high_performance"
messages[].settings.agentModeboolean?エージェントモード
messages[].settings.privateModeboolean?プライベートモード
messages[].settings.reportModestring?"with" / "without"
messages[].settings.personaKeystring | null?ペルソナのキー。ペルソナを選ばずに送ったときは null
messages[].settings.playbookIdstring?Playbook の ID
messages[].settings.skillIdsstring[]?Skill の ID の配列
messages[].archivedboolean?archive 経由で取得されたメッセージのみ true。GET /v1/conversations?mode=archive で取得した会話のメッセージ履歴を参照した場合に付与されます
hasMoreboolean次のページが存在するかどうか
cursorstring次ページ取得用カーソル。hasMore が true の場合のみ含まれます

Task オブジェクト​

フィールド型説明
messageIdstringタスクが属するメッセージのID
conversationIdstringタスクが属する会話のID
callIdstring?ツール呼び出しID。Complex Path では複数のタスクが同じ callId を共有し、同一ツール呼び出しのステップ列を識別するために利用される
actionTypestringタスクの種類(例: ツール実行、コード生成)
titlestring?タスクのタイトル。存在しない場合は省略される
descriptionstring?タスクの説明。存在しない場合は省略される
statusstringタスクの状態。値は "in_progress" / "completed" / "failed" / "error" / "pending" のいずれか
contentstring?タスクの実行結果テキスト。存在しない場合は省略される
metadataobject?actionType ごとに異なる補助情報(sub_event_type、url、filepath など)。詳細は ストリーミングガイド を参照
filesarray?タスクに関連するファイル(filename / size / filepath / mimeType? の構造。MIME タイプ判定不能時は mimeType を省略)。タスクに関連ファイルがない場合は配列自体が省略される
timestampnumberタスク実行時のタイムスタンプ(Unix ミリ秒)
createdAtstring作成日時(ISO 8601)
updatedAtstring更新日時(ISO 8601)

UI リソース(tasks[].metadata.uiResource)​

エージェントが実行中に UI(グラフ・地図・カード一覧など)を生成した場合、そのメタ情報が該当タスクの metadata.uiResource に含まれます。HTML 本体は含まれません。取得するには UI リソース取得エンドポイントを使用します。

オブジェクトの構造は SSE と同一です。フィールドの詳細は ストリーミングガイド — delta.uiResource を参照してください。代替テキストは同じタスクの content に入ります(SSE では同じチャンクの delta.content)。

metadata の内容意味
uiResource のみ表示専用の UI。ユーザーの回答は不要です
uiResource + interaction_type回答を求める UI。interaction_type は "choice" または "question"。この形は origin: "first-party" に限られます
interaction_type のみ回答を求めるが UI は含まれない場合。interaction_type は "choice" | "confirmation" | "question" のいずれか。回答方法は同じタスクの content に入ります
options選択肢の配列(最大10件、各200文字以下)。interaction_type の有無とは独立に含まれることがあります
interactionIdAgent の質問の ID。付かない場合があります(画面の部品で尋ねる質問など)。この質問がまだ返事待ちなら、次の Chat API・MCP の interactionReply に使えます
draftチャットで作った下書き。uiResource と一緒に入ります。形と作り方は ストリーミングガイド — delta.draft を参照してください
判別方法が SSE と異なります

SSE では delta.uiResource(表示専用)と delta.interaction.uiResource(入力系)が構造で分かれますが、履歴・検索ではどちらも tasks[].metadata.uiResource に入ります。判別には metadata.interaction_type の有無を使ってください。

JSON
{
"status": "completed",
"content": "売上は3四半期連続で増加しています",
"metadata": {
"uiResource": {
"type": "html",
"origin": "first-party",
"altText": "売上は3四半期連続で増加しています",
"uri": "ui://widget/chart",
"server_name": "agentic-star-widgets",
"tool_name": "widget_chart",
"tool_call_id": "chart-7f3a2b1c9e4d5a6b7c8d9e0f1a2b3c4d",
"mime_type": "text/html;profile=mcp-app"
}
},
"timestamp": 1788007347240
}

size は履歴・検索では含まれません。

ページネーション​

limit を指定すると、その件数ずつ取得できます。hasMore が true の間、レスポンスの cursor をそのまま次のリクエストに渡してください。

リクエスト例
1# 1ページ目
2curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/<conversation_id>/messages?limit=50" \
3-H "Authorization: Bearer <access_token>"
4
5# 2ページ目(1ページ目のレスポンスに含まれる cursor を指定)
6curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/<conversation_id>/messages?limit=50&cursor=<cursor>" \
7-H "Authorization: Bearer <access_token>"

limit を省略した場合は 50 件が返ります。全件を取得する場合は、hasMore が false になるまで cursor で続きを取得してください。

カーソル利用時の注意

cursor は取得位置を表すため、同じカーソルを使い続ける間は order を変更しないでください。条件を変えると対象範囲が変わり、項目の重複や取りこぼしが起きます。

また、ページを取得している間にメッセージが追加・削除された場合も、ページ間で重複や取りこぼしが生じることがあります。

未知のフィールドは安全に無視

実装は将来 actionType / metadata に新規フィールドを追加する可能性があります。クライアント実装では、本表に記載されていないフィールドは安全に無視するようにしてください。詳細な metadata 構造は ストリーミングガイド — Task データモデル を参照してください。

レスポンス例​

JSON
{
"messages": [
{
"conversationId": "550e8400-...",
"messageId": "msg-abc123",
"sender": "User",
"text": "売上データを分析してください",
"createdAt": "2026-03-14T10:30:00Z",
"updatedAt": "2026-03-14T10:30:00Z",
"status": { "processing": false, "unfinished": false },
"tasks": []
}
],
"hasMore": false
}

エラーレスポンス​

ステータスcode説明
400invalid_conversation_idconversationId が全部 0 の UUID(00000000-0000-0000-0000-000000000000)。この値は受け付けません
400invalid_parameterlimit が 1-100 の整数でない、cursor が不正(前回レスポンスの値以外)、または order が "asc" / "desc" 以外
403insufficient_scopechat:history スコープが不足
404conversation_not_found会話が見つからない、または自分の会話ではない

GET/v1/conversations/:conversationId/ui-resources/:toolCallId

UI リソースの HTML を取得します。SSE の delta.uiResource、履歴・検索の tasks[].metadata.uiResource、A2A・MCP の各応答に含まれる tool_call_id を指定します。

対象は type: "html" の UI リソースのみです。type: "data" は応答にペイロードがインラインで含まれるため、このエンドポイントを呼ぶ必要はありません。

応答は JSON です

このエンドポイントは HTML を Content-Type: text/html で返しません。ブラウザで直接開いて描画させるためのものではなく、利用者のアプリケーションが HTML を取得するための口です。

必要スコープ​

chat:exec / a2a:all / mcp:all のいずれか1つが必要です。UI リソースを受け取った経路のスコープでそのまま取得できます。chat:history は対象外のため、履歴 API だけを利用しているクライアントは別途いずれかのスコープが必要です。

パスパラメータ​

パラメータ型必須説明
conversationIdstring必須会話のID(UUID)
toolCallIdstring必須UI リソースの識別子。uiResource.tool_call_id の値。形式は英数字・ハイフン・アンダースコアの1〜128文字

リクエスト例​

Get UI resource
1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/ui-resources/chart-7f3a2b1c9e4d5a6b7c8d9e0f1a2b3c4d \
2-H "Authorization: Bearer <access_token>"

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

フィールド型説明
toolCallIdstringリクエストで指定した UI リソースの識別子
typestring"html" 固定
originstring"first-party"(AGENTIC STAR が生成)または "external"(管理者が接続を許可した外部の MCP サーバーが生成)
mimeTypestringHTML の MIME タイプ。通常は "text/html;profile=mcp-app"
htmlstringHTML のソース

レスポンス例​

JSON
{
"toolCallId": "chart-7f3a2b1c9e4d5a6b7c8d9e0f1a2b3c4d",
"type": "html",
"origin": "first-party",
"mimeType": "text/html;profile=mcp-app",
"html": "<!doctype html><html>...</html>"
}

エラーレスポンス​

code でリトライの可否を判断できます。

ステータスcode説明リトライ
400invalid_conversation_idconversationId が全部 0 の UUID(00000000-0000-0000-0000-000000000000)不可
400invalid_parametertoolCallId の形式が不正不可
403insufficient_scopechat:exec / a2a:all / mcp:all のいずれも持っていない不可
404not_found該当する UI リソースが存在しない不可
404conversation_not_found会話が存在しない、または他のユーザーの会話不可
404file_too_largeHTML の実体が 512KB を超えており返却できない不可(永続的な失敗)
502upstream_api_error一時的な取得失敗可
500internal_errorその他のエラー可
描画時の注意

このエンドポイントが返すのは HTML の文字列で、描画は利用者のアプリケーション側で行います。サンドボックス化の要否や origin による違いは、ストリーミングガイド — 描画時の注意 を参照してください。

PATCH/v1/conversations/:conversationId

会話のタイトルを更新します。

パスパラメータ​

パラメータ型必須説明
conversationIdstring必須会話のID(UUID)

リクエストボディ​

パラメータ型必須説明
titlestring必須新しい会話タイトル(200文字以内)

リクエスト例​

Update conversation
1curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000 \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{ "title": "新しいタイトル" }'

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

フィールド型説明
conversationIdstring会話ID(UUID)
titlestring更新後のタイトル
typestring会話の種類。"chat"・"mail"・"project"(プロジェクトの工程の会話)
createdAtstring会話の作成日時(ISO 8601)
updatedAtstring会話の更新日時(ISO 8601)

レスポンス例​

JSON
{
"conversationId": "550e8400-...",
"title": "新しいタイトル",
"type": "chat",
"createdAt": "2026-03-14T10:30:00.000Z",
"updatedAt": "2026-03-14T12:00:00.000Z"
}

エラーレスポンス​

ステータスcode説明
400invalid_conversation_idconversationId が全部 0 の UUID(00000000-0000-0000-0000-000000000000)。この値は受け付けません
400missing_parametertitle が未指定
400invalid_titletitle が空文字・文字列ではない・200 文字を超える
400invalid_bodyボディが壊れた JSON
400conversation_archived会話がアーカイブ済み
415unsupported_media_typeボディの Content-Type が application/json ではない
403insufficient_scopechat:history スコープが不足
404conversation_not_found会話が見つからない、または自分の会話ではない

DELETE/v1/conversations/:conversationId

会話を削除します。その会話のメッセージに添付したファイルと成果物のファイルのうち、ほかの会話で使っていないものも削除されます(GET /v1/files にも出なくなります)。

パスパラメータ​

パラメータ型必須説明
conversationIdstring必須会話のID(UUID)

リクエスト例​

Delete conversation
1curl -X DELETE https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000 \
2-H "Authorization: Bearer <access_token>"

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

フィールド型説明
conversationIdstring削除された会話のID(UUID)
deletedboolean削除成功時は常に true

レスポンス例​

JSON
{ "conversationId": "550e8400-...", "deleted": true }

エラーレスポンス​

ステータスcode説明
400invalid_conversation_idconversationId が全部 0 の UUID(00000000-0000-0000-0000-000000000000)。この値は受け付けません
400conversation_archived会話がアーカイブ済み。復元には POST /v1/conversations/:id/restore を使用
403insufficient_scopechat:history スコープが不足
404conversation_not_found会話が見つからない、または自分の会話ではない
409conversation_processing会話が現在処理中のため削除できない
409project_conversationプロジェクトの会話。プロジェクトの会話は削除できません
409claw_bound_conversationClaw の予定に結び付いた会話。先にアプリで、この会話に結び付いた Claw の予定を削除してください
409legal_hold保全中の会話。管理者が保全を解除するまで削除できません
503claw_binding_unverifiedClaw の予定に結び付いているかを確かめられなかった。時間をおいて再試行してください

POST/v1/conversations/:conversationId/restore

アーカイブ済み会話を active に戻します。復元後は通常会話と同様に編集・継続・削除が可能になります。

パスパラメータ​

パラメータ型必須説明
conversationIdstring必須アーカイブ済み会話のID(UUID)

リクエスト例​

Restore archived conversation
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/restore \
2-H "Authorization: Bearer <access_token>"

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

フィールド型説明
conversationIdstring復元された会話のID(UUID)
restoredboolean復元成功時は常に true

レスポンス例​

JSON
{ "conversationId": "550e8400-...", "restored": true }

エラーレスポンス​

ステータスcode説明
400invalid_conversation_idconversationId が全部 0 の UUID(00000000-0000-0000-0000-000000000000)。この値は受け付けません
403insufficient_scopechat:history スコープが不足
404conversation_not_foundアーカイブに該当会話が存在しない、または既に active(archive 状態と区別されません)

POST/v1/conversations/:conversationId/read

会話を既読にします。会話のメッセージを API(REST・MCP・A2A)で読んでも既読にはならないので、読んだことを残すときに呼びます。既読の位置は後ろに戻りません(前のメッセージを指定しても、今より前には戻りません)。

SaaS 版では、プロジェクトの外の個人のスケジュールと Claw は、最後に読んだ後に続けて終わった回が 3 回以上あり、そのいちばん古い回が 14 日以上前になると、止まることがあります(プロジェクトの巡回は対象外です)。API で結果を読んでいて止めたくないときは、この API で既読にしてください。画面でその会話を開いても既読になります。

パスパラメータ​

パラメータ型必須説明
conversationIdstring必須会話のID(UUID)

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

本文は省けます。付けるときは Content-Type: application/json で送ります。

パラメータ型必須説明
messageIdstring—読んだ最後のメッセージのID。省くと、その時点の最新のメッセージまで既読にします(読んでいる間に届いたメッセージを既読にしないときに指定します)

リクエスト例​

Mark a conversation as read
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/read \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{"messageId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"}'

レスポンス(204 No Content)​

本文はありません。

エラーレスポンス​

ステータスcode説明
400invalid_conversation_idconversationId が全部 0 の UUID(00000000-0000-0000-0000-000000000000)。この値は受け付けません
400invalid_parametermessageId が空・文字列ではない
400invalid_body本文が JSON のオブジェクトではない
400conversation_archived会話がアーカイブ済み
415unsupported_media_type本文が application/json でない
403insufficient_scopechat:history スコープが不足
404conversation_not_found会話が存在しない・自分の会話でない
404message_not_foundmessageId がその会話に無い

ファイル管理​

ファイルのアップロード・取得・削除を行います。

エンドポイント一覧​

メソッドエンドポイント説明スコープ (SaaS)
GET/v1/filesファイル一覧を取得chat:file
POST/v1/filesファイルをアップロードchat:file
GET/v1/files/:fileId/contentファイルをダウンロードchat:file
DELETE/v1/files/:fileIdファイルを削除chat:file

※ Marketplace 版はスコープ不要(認証のみ)。

POST/v1/files

ファイルをアップロードします。

リクエストボディ(multipart/form-data)​

パラメータ型必須説明
filefile必須アップロードするファイル。サイズ上限 512 MB。
filenamestring必須ファイル名

リクエスト例​

Upload file
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/files \
2-H "Authorization: Bearer <access_token>" \
3-F "file=@report.pdf" \
4-F "filename=report.pdf"

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

フィールド型説明
fileIdstringファイルの一意識別子(UUID)
filenamestringファイル名
bytesintegerファイルサイズ(バイト)
createdAtstring作成日時(ISO 8601)
widthinteger画像の幅(ピクセル)。画像ファイルの場合のみ
heightinteger画像の高さ(ピクセル)。画像ファイルの場合のみ

レスポンス例​

JSON
{
"fileId": "550e8400-e29b-41d4-a716-446655440001",
"filename": "report.pdf",
"bytes": 1048576,
"createdAt": "2026-03-14T10:30:00.000Z"
}

エラーレスポンス​

ステータスcode説明
400missing_parameterfile または filename パラメータが未指定
400file_too_largeファイルサイズが 512 MB を超過
400invalid_parameterアップロードされた画像ファイルが破損している/不正
415unsupported_media_typeボディが multipart/form-data ではない、またはファイルの種類を受け付けていない(環境で受け付けないと決めた拡張子・MIME タイプを含む)
403insufficient_scopechat:file スコープが不足
403feature_not_permitted管理者がファイルの添付を許可していない
503feature_permissions_unavailable機能の許可を確かめられない。時間をおいて送り直す

GET/v1/files

ファイル一覧を取得します。カーソルベースのページネーションに対応しています。

クエリパラメータ​

パラメータ型必須デフォルト説明
limitinteger—501 ページの取得件数(1-100)
cursorstring——次ページ取得用カーソル(前回レスポンスの cursor 値)
orderstring—"desc""asc"(古い順)または "desc"(新しい順)。並びの基準はファイルの更新日時

リクエスト例​

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

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

フィールド型説明
filesarrayファイルオブジェクトの配列
files[].fileIdstringファイルの一意識別子(UUID)
files[].filenamestringファイル名
files[].bytesintegerファイルサイズ(バイト)
files[].createdAtstring作成日時(ISO 8601)
files[].widthinteger画像の幅(ピクセル)。画像ファイルの場合のみ
files[].heightinteger画像の高さ(ピクセル)。画像ファイルの場合のみ
hasMoreboolean次のページが存在するかどうか
cursorstring次ページ取得用カーソル。hasMore が true の場合のみ含まれます

レスポンス例​

JSON
{
"files": [
{
"fileId": "550e8400-e29b-41d4-a716-446655440001",
"filename": "report.pdf",
"bytes": 1048576,
"createdAt": "2026-03-14T10:30:00.000Z"
}
],
"hasMore": false
}

ページネーション​

limit を指定すると、その件数ずつ取得できます。hasMore が true の間、レスポンスの cursor をそのまま次のリクエストに渡してください。

リクエスト例
1# 1ページ目
2curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/files?limit=50&order=desc" \
3-H "Authorization: Bearer <access_token>"
4
5# 2ページ目(1ページ目のレスポンスに含まれる cursor を指定)
6curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/files?limit=50&order=desc&cursor=<cursor>" \
7-H "Authorization: Bearer <access_token>"

limit を省略した場合は 50 件が返ります。全件を取得する場合は、hasMore が false になるまで cursor で続きを取得してください。

カーソル利用時の注意

cursor は取得位置を表すため、同じカーソルを使い続ける間は order を変更しないでください。条件を変えると対象範囲が変わり、項目の重複や取りこぼしが起きます。

また、ページを取得している間にファイルが追加・削除された場合も、ページ間で重複や取りこぼしが生じることがあります。

エラーレスポンス​

ステータスcode説明
400invalid_parameterlimit が 1-100 の整数でない
400invalid_parametercursor が不正(前回レスポンスの値以外)
400invalid_parameterorder が "asc" / "desc" 以外
403insufficient_scopechat:file スコープが不足

GET/v1/files/:fileId/content

ファイルをダウンロードします。

パスパラメータ​

パラメータ型必須説明
fileIdstring必須ファイルID(UUID)

リクエスト例​

Download file
1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/files/550e8400-e29b-41d4-a716-446655440001/content \
2-H "Authorization: Bearer <access_token>" \
3-o downloaded_file.pdf

レスポンス(200 OK)​

ファイルのバイナリデータがストリームで返されます。

レスポンスヘッダー説明
Content-Typeファイルの MIME タイプ
Content-Lengthファイルサイズ(バイト)
Content-Dispositionattachment; filename="ファイル名"; filename*=UTF-8''<UTF-8 をパーセント符号化したファイル名>

保存するときのファイル名は、filename*(UTF-8 をパーセント符号化した名前)があればそちらを使い、無ければ filename を使います。日本語などを含む名前では、filename は代わりの名前になり、元の名前は filename* にだけ入ります。例えば 売上.pdf のときは次のようになります(filename の代わりの名前は一例です)。

Content-Disposition: attachment; filename="file_1731650000000.pdf"; filename*=UTF-8''%E5%A3%B2%E4%B8%8A.pdf

エラーレスポンス​

ステータスcode説明
400invalid_parameterfileId が不正なフォーマット
403insufficient_scopechat:file スコープが不足
404file_not_foundファイルが見つからない
503service_unavailable認証の仕組みが一時的に使えない。少し待ってから送り直してください。続くときは、サービスの管理者に問い合わせてください

DELETE/v1/files/:fileId

ファイルを削除します。会話を削除したときも、その会話だけで使っていたファイルは削除されます(会話を削除)。

パスパラメータ​

パラメータ型必須説明
fileIdstring必須ファイルID(UUID)

リクエスト例​

Delete file
1curl -X DELETE https://api.fd.agenticstar.tm.softbank.jp/api/v1/files/550e8400-e29b-41d4-a716-446655440001 \
2-H "Authorization: Bearer <access_token>"

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

フィールド型説明
fileIdstring削除されたファイルのID(UUID)
deletedboolean削除成功時は常に true

レスポンス例​

JSON
{ "fileId": "550e8400-e29b-41d4-a716-446655440001", "deleted": true }

エラーレスポンス​

ステータスcode説明
400invalid_parameterfileId が不正なフォーマット
403insufficient_scopechat:file スコープが不足
404file_not_foundファイルが見つからない

成果物取得​

エージェントが生成した成果物ファイルを取得します。

エンドポイント一覧​

メソッドエンドポイント説明スコープ (SaaS)
GET/v1/files/proxy成果物ファイルを取得chat:exec / a2a:all / mcp:all

※ Marketplace 版はスコープ不要(認証のみ)。

GET/v1/files/proxy

メッセージ履歴の deliverables[].filepath で取得したパスを指定して、成果物ファイルをダウンロードします。

chat:exec / a2a:all / mcp:all のいずれか1つがあれば取得できます。A2A の artifact や MCP のツール応答で得た成果物も、その経路のスコープのままこのエンドポイントで取得できます。 プロジェクトの実行の結果・確認依頼の材料のファイル(files[].filepath)は、このエンドポイントではなく、プロジェクトのファイルの中身の取得(GET /v1/projects/{projectId}/files/content)で取得します。

クエリパラメータ​

パラメータ型必須説明
pathstring必須成果物のファイルパス(メッセージ履歴の deliverables[].filepath で取得)
version_idstring—ファイルのバージョンの ID(ファイルライブラリのバージョンの一覧 GET /v1/library/versions の versionId)。省くと今のバージョン

リクエスト例​

filepath は メッセージ履歴の取得 の messages[].deliverables[].filepath の値です。

Get artifact file
1FILEPATH='<filepath>'
2
3curl --get "https://api.fd.agenticstar.tm.softbank.jp/api/v1/files/proxy" \
4--data-urlencode "path=$FILEPATH" \
5-H "Authorization: Bearer <access_token>" \
6-o artifact.xlsx

レスポンス(200 OK)​

成果物ファイルのバイナリデータがストリームで返されます。

レスポンスヘッダー説明
Content-Typeファイルの MIME タイプ
Content-Lengthファイルサイズ(バイト)

エラーレスポンス​

ステータスcode説明
400missing_parameterpath パラメータが未指定
400invalid_parameterpath のフォーマットが不正(UUID の形の段が無い)
403insufficient_scopechat:exec / a2a:all / mcp:all のいずれも持っていない
404not_foundファイルが見つからない(保存先の応答に別の code があるときはその code)
500unknown保存先の不明な誤り
500storage_forbidden保存先へのアクセスが拒否された。管理者に連絡してください
500rejected保存先がリクエストを断った。管理者に連絡してください
503rate_limited保存先が一時的に混んでいる。時間をおいて再試行してください
503transient保存先が一時的に使えない。時間をおいて再試行してください
503service_unavailable認証の仕組みが一時的に使えない。少し待ってから送り直してください。続くときは、サービスの管理者に問い合わせてください

ライブラリ​

ユーザーのライブラリファイル(アップロード済みファイルおよびエージェントが生成した成果物)を横断的に一覧します。取得した filepath は Chat の input_file 添付や成果物取得(GET /v1/files/proxy)でのダウンロードに使用できます。

エンドポイント一覧​

メソッドエンドポイント説明スコープ (SaaS)
GET/v1/libraryライブラリファイル一覧を取得chat:exec
GET/v1/library/versionsライブラリファイルのバージョンの一覧を取得chat:exec

GET/v1/library

ライブラリファイルの一覧を取得します。カーソルベースのページネーションに対応しています。

クエリパラメータ​

パラメータ型デフォルト説明
limitinteger50取得件数(1〜100)
cursorstring—次ページ取得用カーソル(前回レスポンスの cursor 値)
searchstring—ファイル名で絞り込み(部分一致)
sourcestring—"agent"(エージェント生成)または "user"(ユーザーアップロード)で絞り込み
orderstring"desc""asc" または "desc"

リクエスト例​

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

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

フィールド型説明
filesarrayライブラリファイルオブジェクトの配列
files[].filenamestringファイル名
files[].filepathstringファイルパス(Chat の input_file 添付や GET /v1/files/proxy でのダウンロードに使用)
files[].sourcestring"agent"(エージェント生成)または "user"(ユーザーアップロード)
files[].createdAtstring作成日時(ISO 8601)
files[].updatedAtstring最終更新日時(ISO 8601)
files[].mimeTypestring?MIME タイプ。判定できない場合は省略
files[].sizenumber?ファイルサイズ(バイト)。取得できない場合は省略
files[].conversationIdstring?関連する会話 ID。成果物が会話に紐づく場合のみ含まれます
hasMoreboolean次のページが存在するかどうか
cursorstring次ページ取得用カーソル。hasMore が true の場合のみ含まれます

レスポンス例​

JSON
{
"files": [
{
"filename": "report.xlsx",
"filepath": "/users/11111111-2222-3333-4444-555555555555/plans/550e8400-e29b-41d4-a716-446655440000/deliverables/report.xlsx",
"source": "agent",
"createdAt": "2026-03-14T10:30:00.000Z",
"updatedAt": "2026-03-14T10:30:00.000Z",
"mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
"size": 20480,
"conversationId": "550e8400-e29b-41d4-a716-446655440000"
}
],
"hasMore": false
}

エラーレスポンス​

ステータス説明
400limit(1〜100の範囲外)、cursor、source("agent" / "user" 以外)、order("asc" / "desc" 以外)、または search(文字列ではない)が不正
403chat:exec スコープが不足

GET/v1/library/versions

ライブラリファイル 1 件のバージョンの一覧を、新しい順に取得します。すべてのバージョンを返し、hasMore はいつも false です。バージョンの中身は、成果物取得(GET /v1/files/proxy)の version_id に versionId を渡して取得します。バージョンの記録が無いファイルでは、versions は空の配列で、currentVersionId は null です。

クエリパラメータ​

パラメータ型デフォルト説明
pathstring—必須。ファイルのパス(GET /v1/library の filepath)

リクエスト例​

List library file versions
1curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/library/versions?path=/users/11111111-2222-3333-4444-555555555555/plans/550e8400-e29b-41d4-a716-446655440000/deliverables/report.xlsx" \
2-H "Authorization: Bearer <access_token>"

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

フィールド型説明
filepathstringファイルのパス
currentVersionIdstring | null今のバージョンの ID。バージョンが無いときは null
versionsarrayバージョンの配列(新しい順)
versions[].versionIdstring | nullバージョンの ID
versions[].sizenumber | null大きさ(バイト)
versions[].createdAtstring | nullバージョンができた日時(ISO 8601)
versions[].isCurrentboolean今のバージョンかどうか
hasMorebooleanいつも false

レスポンス例​

JSON
{
"filepath": "/users/11111111-2222-3333-4444-555555555555/plans/550e8400-e29b-41d4-a716-446655440000/deliverables/report.xlsx",
"currentVersionId": "3b8a1c5e-7d2f-4e9a-a6c0-1f4d8b2e5a79",
"versions": [
{
"versionId": "3b8a1c5e-7d2f-4e9a-a6c0-1f4d8b2e5a79",
"size": 20480,
"createdAt": "2026-03-14T10:30:00.000Z",
"isCurrent": true
},
{
"versionId": "c4d9e2f1-0a3b-4c6d-8e7f-5a1b2c3d4e6f",
"size": 18944,
"createdAt": "2026-03-13T08:00:00.000Z",
"isCurrent": false
}
],
"hasMore": false
}

エラーレスポンス​

ステータス説明
400path が無い・空(code: "invalid_parameter")
403chat:exec スコープが不足
404ファイルが見つからない、または自分のファイルではない(code: "not_found")
502サービスの内部で一時的な誤りが起きた(code: "upstream_connection_error")。時間をおいて送り直してください

Agent・Playbook・Skill の共通の決まり​

Agent・Playbook・Skill を読む・作る・変える・消す・コピーする API に共通の決まりです。システム連携のトークンでは呼べません(呼ぶと 403 Forbidden(forbidden))。

操作スコープ対象対象外のとき
読むassets:read(スキル・プレイブックの一覧は chat:exec でも呼べます)自分のものと、公開されているものほかの利用者の非公開のもの・存在しないものは 404 Not Found(agent_not_found・playbook_not_found・skill_not_found)
作る・コピーするassets:write——
変えるassets:write自分のものだけほかの利用者のものは 404 Not Found
消すassets:delete自分のものだけ(システム管理者は、ほかの利用者が公開したプレイブック・スキルも消せます)ほかの利用者のものは 404 Not Found
  • ほかの利用者のものを直したいときは、自分のものにコピーしてから直します。
  • 変えるときは、取得の digest を baseDigest に入れて送ります。取得した後にほかの変更が入っていると 409 Conflict(stale_base)が返ります。取得し直してから送り直してください。
  • JSON のボディは 3 MiB までです。超えると 413 Payload Too Large(body_too_large)が返ります。スキルのファイルを送る API の上限は、その API の説明を参照してください。
  • Agent の API は、SSO でログインしていない利用者のトークンでは 403 Forbidden(sso_required)が返ります。

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

API送り直しを見分けるもの同じもので送り直すと
作る—もう 1 つ作られます。応答が届かなかったときは、一覧の ID と createdAt で作られたかを確かめてから送り直してください
コピーするIdempotency-Key ヘッダー(任意)1 回目のコピーが返り、もう 1 つは作られません。付けないときは、作ると同じく、送り直すともう 1 つ作られます(マーケットプレイス版の登録 Agent のコピーは除きます。Agent のコピーの説明を参照)
スキルの文書を書き換える(PATCH /v1/skills/:skillId/files)Idempotency-Key ヘッダー(任意)新しいバージョンを作らずに、1 回目にできたバージョンが返ります

スキル・プレイブックの公開の承認​

テナントの管理者が、スキル・プレイブックの公開に管理者の承認を要るとしているときは、isShared: true を送っても公開されず、公開の承認待ちになります(画面の「公開を申請」と同じです)。承認・差し戻しは、管理者が管理コンソールで行います。承認が要るかどうかは API では読めません。公開されたか承認待ちになったかは、応答の isShared と shareRequestStatus で確かめてください。

自分のスキル・プレイブックの一覧・取得と、作る・変える・コピーの応答には、次の申請の状態の項目が入ります。公開の一覧と、ほかの利用者の公開のものの取得には入りません。ただし、スキルの文書を書き換える応答の skill には sharePendingListing は入りません(スキルの取得で読めます)。

フィールド型説明
shareRequestStatusstring | null"pending"(承認待ち)/ "rejected"(差し戻し)/ null(申請していない)
shareRequestNotestring | null申請の理由
shareReviewNotestring | null管理者のコメント(差し戻したときなど)
shareRequestedAtstring | null申請した日時(ISO 8601)
sharePendingVersionIdstring | nullスキルだけ。承認を待っているバージョンの ID
sharePendingListingobject | nullスキルだけ。承認を待っているカテゴリ・タグ。承認待ちの変更として記録された項目(category・tags)が入ります(承認の前に公開中の値に戻したときも、その項目は残ります)。無いときは null
  • 申請の理由(shareRequestNote): スキルを作る・ファイルを丸ごと入れ替える・設定を変える、プレイブックを作る・変えるで送れます。前後の空白を除いて 2000 文字までです(超えると 400 Bad Request(invalid_parameter))。空の文字列・空白だけ・null は、送らないのと同じです。理由は、申請になったときにだけ残ります。承認が要らなかったとき(承認を要るとしていないテナント)は使われません。どちらになったかは、応答の shareRequestStatus・isShared で分かります。
  • 理由だけは変えられません: 承認待ちのものに、中身を変えずに今と違う理由を送ると 400 Bad Request(invalid_parameter)です。理由を変えるときは、申請を取り下げてから再申請してください。今と同じ理由なら、送り直しとして受け付けます。
  • 取り下げ: 承認待ちのものに isShared: false を送ります(スキルは設定を変える、プレイブックはプレイブックを変えるで送ります)。
  • 公開中のスキルの新しいバージョン: 公開の承認が有効なテナントで、公開中のスキルのファイルを変えると、新しいバージョンは承認待ちになり、承認されるまで前のバージョンが使われます。
  • 公開中のスキルのカテゴリ・タグ: 公開の承認が有効なテナントで、公開中のスキルのカテゴリ・タグを変える(スキルの設定を変える)と、変えた値は承認待ちになり、承認されるまでスキルの category・tags は前の値のままです。承認待ちの値は sharePendingListing で読めます。同じ更新で isShared: false を送ったときは、承認待ちにならず、すぐに変わって非公開になります。
  • 公開中のプレイブックの中身: 公開の承認が有効なテナントで、公開中のプレイブックの中身(名前・説明・カテゴリ・タグ・手順)を変えると、公開は続いたまま(isShared は true のまま)、変えた中身の申請になります(shareRequestStatus が "pending")。承認されるまで、ほかの利用者には承認した中身が見えます(公開の一覧・取得・コピー)。自分の取得と、自分の Agent・チャットは、変えた後の中身を使います。公開している中身に戻すと、申請は取り下げられます。差し戻された後は、isShared: true を送ると(中身を変えなくても)再申請します。

Agent​

プロジェクトの工程に配置して動かす Agent を、ライブラリの資産として扱います。Agent の ID(agentId)は、プロジェクトに配置したときの配置の ID とは別の値です。

エンドポイント一覧​

メソッドエンドポイント説明スコープ (SaaS)
GET/v1/agents自分の Agent の一覧を取得assets:read
GET/v1/agents/shared公開されている Agent の一覧を取得assets:read
GET/v1/agents/:agentIdAgent を取得assets:read
POST/v1/agentsAgent を作るassets:write
PATCH/v1/agents/:agentIdAgent を変えるassets:write
DELETE/v1/agents/:agentIdAgent を消すassets:delete
POST/v1/agents/:agentId/copy公開されている Agent を自分の Agent としてコピーassets:write

GET/v1/agents

自分の Agent の一覧を取得します。最終更新日時の降順(新しい順)で返ります。カーソルベースのページネーションに対応しています。公開されている Agent の一覧(GET /v1/agents/shared)も、クエリパラメータ・レスポンスは同じです。

クエリパラメータ​

パラメータ型デフォルト説明
qstring—名前・説明・ゴールの一部で絞り込み(100 文字まで)
limitinteger501 ページの取得件数(1-100)
cursorstring—次ページ取得用カーソル(前回レスポンスの cursor 値)

リクエスト例​

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

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

フィールド型説明
agentsarrayAgent オブジェクトの配列。各項目は Agent の取得の digest 以外と同じです
hasMoreboolean次のページが存在するかどうか
cursorstring次ページ取得用カーソル。hasMore が true の場合のみ含まれます

レスポンス例​

JSON
{
"agents": [
{
"agentId": "17be0242-a5d0-4db7-92e5-f97a05abae2b",
"name": "受注データの取り込み",
"description": "受注メールから受注データを作る",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"isShared": false,
"shareScope": "all",
"shareOrganizations": null,
"runtimeKind": "autonomous",
"marketplaceAgentId": null,
"spec": {
"goal": "受信した受注メールから、受注データの表を作ってください。",
"guardrail": "外部のサービスへは送信しない。",
"skills": [
{
"skillId": "cb62d540-5439-4748-99f0-961b8de91a78",
"name": "order-parser",
"versionId": null
}
],
"playbookId": "8af8d6be-2885-446d-9e36-ee9dcf1fe1ba",
"inputFiles": [
{
"type": "blob",
"filepath": "/path/to/orders-template.xlsx",
"filename": "orders-template.xlsx"
}
],
"agentLevel": "default",
"orgId": null,
"jobRole": null,
"agentConfig": null,
"exposureConsent": null
},
"projectCount": 1,
"copyCount": 0,
"createdAt": "2026-09-20T02:10:00.000Z",
"updatedAt": "2026-09-28T15:18:02.255Z",
"adminStop": null
}
],
"hasMore": false
}

エラーレスポンス​

ステータス説明
400limit(1〜100 の範囲外)、cursor、または q(文字列ではない、100 文字を超える)が不正(code は invalid_parameter)
403assets:read スコープが不足(code は insufficient_scope)、システム連携のトークンで呼び出した(code は forbidden)、または SSO でログインしていない利用者(code は sso_required)

GET/v1/agents/shared

公開されている Agent の一覧を取得します(自分が公開したものも含みます)。組織だけに公開された Agent は、その組織の利用者にだけ出ます。クエリパラメータ・レスポンス・エラーは、自分の Agent の一覧と同じです。

リクエスト例​

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

GET/v1/agents/:agentId

Agent を取得します。自分の Agent と、公開されている Agent を取得できます。

パスパラメータ​

パラメータ型必須説明
agentIdstring必須Agent の ID(UUID)

リクエスト例​

Get agent
1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b \
2-H "Authorization: Bearer <access_token>"

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

フィールド型説明
agentIdstringAgent の ID(UUID)
namestring | null名前
descriptionstring | null説明
ownerUserIdstring | null持ち主の利用者 ID
isSharedboolean | null公開しているかどうか
shareScopestring | null公開の範囲。"all"(全員)または "organizations"(shareOrganizations の組織の利用者だけ)
shareOrganizationsarray | null公開先の組織のコードの配列。shareScope が "organizations" のときに使います
runtimeKindstring | null実行環境の種類。"autonomous"、またはマーケットプレイス版の登録 Agent は "marketplace"
marketplaceAgentIdstring | nullマーケットプレイス版の登録 Agent の ID。それ以外は null
specobjectAgent の定義
spec.goalstring | nullゴール(指示)
spec.guardrailstring | nullガードレール
spec.skillsarray使うスキル
spec.skills[].skillIdstring | nullスキル ID
spec.skills[].namestring | nullスキル名
spec.skills[].versionIdstring | null固定したスキルのバージョンの ID。固定していない場合は null で、いつもその時点のバージョンを使います
spec.playbookIdstring | null使うプレイブックの ID
spec.inputFilesarray入力ファイル
spec.inputFiles[].typestring | null入力ファイルの種類。ライブラリのファイルは "blob"。定期実行から作った Agent では "git"・"upload" が入っていることがあります
spec.inputFiles[].filepathstring | nullファイルのパス。"blob" は GET /v1/library の filepath と同じ形。"git"・"upload" は保存された参照の先頭に / を付けた値で、ライブラリのパスではありません
spec.inputFiles[].filenamestring | nullファイル名
spec.agentLevelstring | null"default" または "high_performance"
spec.orgIdstring | null実行のときに使う組織のコード
spec.jobRolestring | null実行のときに使う職種のコード
spec.agentConfigobject | null今は使っていない項目です(値が入っていても使われません)
spec.exposureConsentobject | null今は使っていない項目です(値が入っていても使われません)
projectCountnumber | nullこの Agent を配置しているプロジェクトの数(消したプロジェクトの配置は数えません)
copyCountnumber | nullコピーされた回数
adminStopobject | null管理者が止めているときの、停止元・理由・時刻。止めていなければ null。一覧と取得で返ります
adminStop.sourcestring | null停止元。"aster"(AGENTIC STAR の管理者)、または連携先の "agent365"・"aws"
adminStop.reasonCodestring | null理由の種類。"admin"(管理者が止めた)・"remote_stopped"(連携先で止められた)・"remote_unreachable"(連携先に届かない)
adminStop.reasonstring | null理由の文。自分の Agent のときだけ入ります(ほかの利用者の Agent では null)
adminStop.stoppedAtstring | null止めた時刻(ISO 8601)
createdAtstring | null作成日時(ISO 8601)
updatedAtstring | null最終更新日時(ISO 8601)
digeststringAgent を変えるときに baseDigest に送る値。名前・説明・公開・公開の範囲・公開先の組織・定義から作られ、配置しているプロジェクトの数・コピー数・日時では変わりません

レスポンス例​

JSON
{
"agentId": "17be0242-a5d0-4db7-92e5-f97a05abae2b",
"name": "受注データの取り込み",
"description": "受注メールから受注データを作る",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"isShared": false,
"shareScope": "all",
"shareOrganizations": null,
"runtimeKind": "autonomous",
"marketplaceAgentId": null,
"spec": {
"goal": "受信した受注メールから、受注データの表を作ってください。",
"guardrail": "外部のサービスへは送信しない。",
"skills": [
{ "skillId": "cb62d540-5439-4748-99f0-961b8de91a78", "name": "order-parser", "versionId": null }
],
"playbookId": "8af8d6be-2885-446d-9e36-ee9dcf1fe1ba",
"inputFiles": [
{ "type": "blob", "filepath": "/path/to/orders-template.xlsx", "filename": "orders-template.xlsx" }
],
"agentLevel": "default",
"orgId": null,
"jobRole": null,
"agentConfig": null,
"exposureConsent": null
},
"projectCount": 1,
"copyCount": 0,
"createdAt": "2026-09-20T02:10:00.000Z",
"updatedAt": "2026-09-28T15:18:02.255Z",
"digest": "1aKrerEIdHNpFSBa9TkuXycB1Q6oD2NUX18-uGPiPLg"
}

エラーレスポンス​

ステータス説明
400agentId が UUID の形式ではない(code は invalid_parameter)
403assets:read スコープが不足(code は insufficient_scope)、システム連携のトークンで呼び出した(code は forbidden)、または SSO でログインしていない利用者(code は sso_required)
404Agent が存在しない、またはほかの利用者の非公開の Agent(code は agent_not_found)

POST/v1/agents

Agent を作ります。

リクエストボディ​

フィールド型必須説明
namestring必須名前(255 文字まで。空にはできません)
descriptionstring—説明(5000 文字まで)
isSharedboolean—公開するかどうか。省くと非公開
specobject必須Agent の定義
spec.goalstring必須ゴール(指示)。5000 文字まで。空白だけにはできません
spec.guardrailstring—ガードレール。5000 文字まで
spec.skillsarray—使うスキル。[{ skillId, versionId? }] の形で、自分のスキルか公開されているスキル(有効なもの)を 10 個まで。versionId を付けるとそのバージョンに固定し、省くか null にするといつもその時点のバージョンを使います。ほかの利用者のスキルの versionId は、公開されたことのあるバージョンだけです(スキルのバージョンの一覧で返る範囲)。取得の spec.skills をそのまま送れます(name は無視します)。同じスキルを重ねて指定できません
spec.playbookIdstring—使うプレイブックの ID。自分のプレイブックだけ
spec.inputFilesarray—入力ファイル。[{ type, filepath, filename? }] の形で 10 個まで。type は "blob"(自分のライブラリのファイル。filepath は GET /v1/library の filepath)です。定期実行から作った Agent では "git"・"upload" が入っていることがあり、取得した値をそのまま送れます。filepath は先頭の / を除いて空にはできません。filename は 255 文字までの文字列か null です。付いている入力ファイルは、実行のときにそのまま渡ります(プロジェクトの持ち主のファイルでなくても外れません)
spec.agentLevelstring—"default" または "high_performance"
spec.orgIdstring—実行のときに使う組織のコード(255 文字まで)
spec.jobRolestring—実行のときに使う職種のコード(255 文字まで)

description と、spec の goal 以外の項目は、null を送ると省いたのと同じ扱いです(spec.skills・spec.inputFiles は空になります)。

spec.skillIds・spec.skillVersions は受け付けません(送ると 400、invalid_parameter)。スキルは spec.skills で指定してください。

リクエスト例​

Create agent
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "name": "受注データの取り込み",
6 "description": "受注メールから受注データを作る",
7 "spec": {
8 "goal": "受信した受注メールから、受注データの表を作ってください。",
9 "guardrail": "外部のサービスへは送信しない。",
10 "skills": [
11 {
12 "skillId": "cb62d540-5439-4748-99f0-961b8de91a78"
13 }
14 ],
15 "agentLevel": "default"
16 }
17}'

レスポンス(201 Created)​

Agent の取得と同じ形(adminStop を除きます。一覧と取得で確かめてください)で、作った Agent を返します。ほかに removedSkillIds(string[])が付きます。使えなくなっていて外して保存したスキル(消された・止められた・公開がやめられた・固定したバージョンが無い、または公開されていない)の ID です。外していなければ空です。

レスポンス例​

JSON
{
"agentId": "17be0242-a5d0-4db7-92e5-f97a05abae2b",
"name": "受注データの取り込み",
"description": "受注メールから受注データを作る",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"isShared": false,
"shareScope": "all",
"shareOrganizations": null,
"runtimeKind": "autonomous",
"marketplaceAgentId": null,
"spec": {
"goal": "受信した受注メールから、受注データの表を作ってください。",
"guardrail": "外部のサービスへは送信しない。",
"skills": [
{
"skillId": "cb62d540-5439-4748-99f0-961b8de91a78",
"name": "order-parser",
"versionId": null
}
],
"playbookId": null,
"inputFiles": [],
"agentLevel": "default",
"orgId": null,
"jobRole": null,
"agentConfig": null,
"exposureConsent": null
},
"projectCount": 0,
"copyCount": 0,
"createdAt": "2026-09-20T02:10:00.000Z",
"updatedAt": "2026-09-28T15:18:02.255Z",
"digest": "GzMT6fWNUwA2FM-LYhLjEaaciV5AUkkvk5cAyupcmFs",
"removedSkillIds": []
}

エラーレスポンス​

ステータスcode説明
400invalid_parametername・spec が無い、name・description・isShared の型や長さの誤り、name が空白だけ、spec がオブジェクトではない、spec.playbookId が UUID の形式ではない、spec.skills の形の誤り(skillId・versionId が UUID の形式ではない、同じスキルを重ねた など)、または spec.skillIds・spec.skillVersions を送った
400invalid_specspec.goal が無い・空白だけ、spec の文字列の項目の型や長さの誤り、spec.agentLevel が選べる値ではない、spec.inputFiles の形の誤り(type が "blob"・"git"・"upload" 以外、filepath が空、filename が 255 文字を超える など)、またはスキル・入力ファイルが 10 個を超える
400playbook_not_foundspec.playbookId が自分のプレイブックではない
400skill_not_foundspec.skills のスキルが、自分のスキルでも公開されている有効なスキルでもない
400version_not_foundspec.skills の versionId が、そのスキルのバージョンではない、またはほかの利用者のスキルで見せていないバージョン(スキルのバージョンの一覧で返らないもの)
400file_not_foundspec.inputFiles の type が "blob" のファイルが、自分のライブラリにない
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
403insufficient_scopeassets:write スコープが不足
403forbiddenシステム連携のトークンで呼び出した
403sso_requiredSSO でログインしていない利用者
413body_too_largeボディが 3 MiB を超える
415unsupported_media_typeボディの Content-Type が application/json ではない

PATCH/v1/agents/:agentId

自分の Agent を変えます。送った項目だけを変えます。

パスパラメータ​

パラメータ型必須説明
agentIdstring必須Agent の ID(UUID)

リクエストボディ​

フィールド型必須説明
baseDigeststring必須Agent の取得の digest
namestring—名前(255 文字まで。空にはできません)
descriptionstring—説明(5000 文字まで。空の文字列・空白だけ・null にはできません)
isSharedboolean—公開するかどうか
shareScopestring—公開の範囲。"all"(全員)または "organizations"(shareOrganizations の組織の利用者だけ)
shareOrganizationsarray—公開先の組織のコード(20 件まで。1 件 255 文字まで。前後の空白を除き、同じ値は 1 つにします)。送ると全部が置き換わります。公開していて範囲が "organizations" のときと、shareScope の "organizations" と一緒に送るときは、1 件以上が要ります
specobject—Agent の定義。送った項目だけを今の定義に重ねます(skills・inputFiles は配列ごと置き換わります)。項目は Agent を作るときと同じです。項目に null を送ると、その項目を外します(skills・inputFiles は空になります)。goal は外せません

name・description・isShared・shareScope・shareOrganizations・spec のうち、少なくとも 1 つを送ってください。

spec を変えるときは、送っていない項目も含めて、定義が指すプレイブック・入力ファイルと、新しく付けたスキル(バージョンを変えたスキルを含みます)を確かめます。プレイブックは自分のもの、スキルは有効で自分のものか公開されているもの、入力ファイルは自分のライブラリにあるものでないと 400 が返ります。前から付いているスキルは、使えなくなっていても 400 にせず、外して保存し、removedSkillIds で返します。コピーした Agent は、ほかの利用者のプレイブック・スキル・入力ファイルを指していることがあります(公開されていて有効なスキルは、コピーしても元のスキルを指します。そのスキルの公開がやめられると使えなくなります)。そのときは、自分のものに変えてください。

リクエスト例​

Update agent
1curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "baseDigest": "GzMT6fWNUwA2FM-LYhLjEaaciV5AUkkvk5cAyupcmFs",
6 "description": "受注メールから受注データの表を作る"
7}'

レスポンス(200 OK)​

Agent の取得と同じ形(adminStop を除きます。一覧と取得で確かめてください)で、変えた後の Agent(新しい digest)を返します。ほかに removedSkillIds(string[])が付きます。使えなくなっていて外して保存したスキル(消された・止められた・公開がやめられた・固定したバージョンが無い、または公開されていない)の ID です。外していなければ空です。

レスポンス例​

JSON
{
"agentId": "17be0242-a5d0-4db7-92e5-f97a05abae2b",
"name": "受注データの取り込み",
"description": "受注メールから受注データの表を作る",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"isShared": false,
"shareScope": "all",
"shareOrganizations": null,
"runtimeKind": "autonomous",
"marketplaceAgentId": null,
"spec": {
"goal": "受信した受注メールから、受注データの表を作ってください。",
"guardrail": "外部のサービスへは送信しない。",
"skills": [
{
"skillId": "cb62d540-5439-4748-99f0-961b8de91a78",
"name": "order-parser",
"versionId": null
}
],
"playbookId": null,
"inputFiles": [],
"agentLevel": "default",
"orgId": null,
"jobRole": null,
"agentConfig": null,
"exposureConsent": null
},
"projectCount": 0,
"copyCount": 0,
"createdAt": "2026-09-20T02:10:00.000Z",
"updatedAt": "2026-09-28T15:18:02.255Z",
"digest": "NhoPOFZIlKaF-GPh9VCRdVUAFqIZpE3OX1wt-BKdtu0",
"removedSkillIds": []
}

エラーレスポンス​

ステータスcode説明
400invalid_parameteragentId が UUID の形式ではない、baseDigest が無い・空・文字列ではない、変える項目が無い、name・description・isShared の型や長さの誤り、name が空白だけ、description を空の文字列・空白だけ・null にした、spec がオブジェクトではない、spec.playbookId が UUID の形式ではない、spec.skills の形の誤り(同じスキルを重ねた など)、または spec.skillIds・spec.skillVersions を送った
400invalid_specspec.goal を null・空白だけにした、spec の文字列の項目の型や長さの誤り、spec.agentLevel が選べる値ではない、spec.inputFiles の形の誤り(type が "blob"・"git"・"upload" 以外、filepath が空、filename が 255 文字を超える など)、またはスキル・入力ファイルが 10 個を超える
400playbook_not_found定義のプレイブックが自分のプレイブックではない
400skill_not_found新しく付けたスキル(バージョンを変えたスキルを含みます)が、自分のスキルでも公開されている有効なスキルでもない(前から付いているスキルは、外して保存し、removedSkillIds で返します)
400version_not_found新しく付けたスキル・バージョンを変えたスキルの versionId が、そのスキルのバージョンではない、またはほかの利用者のスキルで見せていないバージョン(スキルのバージョンの一覧で返らないもの)。バージョンを変えずに残した固定が使えなくなっていれば、外して保存し、removedSkillIds で返します
400file_not_found定義の入力ファイル(type が "blob" のもの)が、自分のライブラリにない
400runtime_not_allowedマーケットプレイス版の登録 Agent は変えられない
400invalid_share_scopeshareScope が "all"・"organizations" ではない
400invalid_share_organizationsshareOrganizations が配列ではない、21 件以上、または文字列でない・空・空白だけ・256 文字以上の値がある
400share_organizations_requiredshareScope に "organizations" と空の shareOrganizations を送った、または公開している(送った値か今の値の isShared が true)のに、範囲が "organizations" で組織が 1 件も無い(送った値と今の値を合わせて見ます)
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
403insufficient_scopeassets:write スコープが不足
403forbiddenシステム連携のトークンで呼び出した
403sso_requiredSSO でログインしていない利用者
404agent_not_foundAgent が存在しない、またはほかの利用者の Agent
409stale_base取得した後に Agent が変わっている
413body_too_largeボディが 3 MiB を超える
415unsupported_media_typeボディの Content-Type が application/json ではない

DELETE/v1/agents/:agentId

自分の Agent を消します。消した Agent は、配置していたプロジェクトから外れ、その配置の巡回も止まります。

パスパラメータ​

パラメータ型必須説明
agentIdstring必須Agent の ID(UUID)

クエリパラメータ​

パラメータ型デフォルト説明
forcestring"false""true" を指定すると、配置しているプロジェクトがあっても消します。"true" / "false" 以外は 400

リクエスト例​

Delete agent
1curl -X DELETE "https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b?force=false" \
2-H "Authorization: Bearer <access_token>"

レスポンス(200 OK)​

JSON
{
"agentId": "17be0242-a5d0-4db7-92e5-f97a05abae2b",
"deleted": true
}

エラーレスポンス​

ステータスcode説明
400invalid_parameteragentId が UUID の形式ではない、または force が "true" / "false" 以外
403insufficient_scopeassets:delete スコープが不足
403forbiddenシステム連携のトークンで呼び出した
403sso_requiredSSO でログインしていない利用者
404agent_not_foundAgent が存在しない、またはほかの利用者の Agent
409agent_in_useAgent を配置しているプロジェクトがある(force=true で、配置から外して消せます)
409agent_runningこの Agent の巡回が実行中
409admin_stopped管理者がこの Agent を止めている

POST/v1/agents/:agentId/copy

公開されている Agent を、自分の Agent としてコピーします。新しく作るコピーは非公開です。ボディは不要です(送っても読みません)。

定義はそのまま写ります。定義が指すプレイブック・スキル・入力ファイルは、コピーする人が使えるように、次のように直します。

  • プレイブック: 自分のもの以外は、自分のプレイブックとして複製し、複製を指します。公開の承認が有効なテナントでは、公開されていないものは複製せずに外します。公開中のものは、承認した中身を複製します
  • スキル: 自分のものと、公開されていて有効なものは、そのまま指します(元の Agent がバージョンを指定していればそのバージョンを、指定していなければ持ち主の今のバージョンを使います)。公開されているスキルにバージョンを指定しているときは、公開されたことのあるバージョンだけをそのまま指します。それ以外は、使っているバージョンを自分のスキルとして複製し、複製を指します。公開の承認が有効なテナントでは、公開されていないか無効なスキル(公開されたことの無いバージョンを指定しているものを含む)は、複製せずに外します
  • 入力ファイル: 複製しません。自分のライブラリに無いものは外します
  • 見つからないプレイブック・スキルは外します

定義をこの形に直せないとき(自分の無効なスキルを指しているときなど)は、プレイブック・スキル・入力ファイルを全部外して写します。マーケットプレイス版の登録 Agent では、同じ登録 Agent の自分の Agent が既にあれば、新しく作らずにそれを返します。

パスパラメータ​

パラメータ型必須説明
agentIdstring必須コピーする Agent の ID(UUID)

リクエストヘッダー​

ヘッダー必須説明
Idempotency-Key—送り直しを見分けるキー(英数字と _ . : - の 8〜128 文字)。同じキーで送り直すと、新しく作らずに、1 回目のコピーを返します

リクエスト例​

Copy agent
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b/copy \
2-H "Authorization: Bearer <access_token>" \
3-H "Idempotency-Key: copy-agent-20261118-0001"

レスポンス(201 Created)​

Agent の取得と同じ形(adminStop を除きます。一覧と取得で確かめてください)に次の 3 つを足して、コピーして作った Agent を返します。マーケットプレイス版の登録 Agent では、既にある自分の Agent を返すことがあります(そのときの応答の projectCount は 0 です。配置しているプロジェクトの数は取得で確かめてください)。

フィールド型説明
duplicatedobject自分のものとして複製した数(playbooks: プレイブックの数、skills: スキルの数)
strippedInputFilesstring[]入力ファイルを外したとき(定義を直せずに全部外したときも)、コピーした Agent の名前が 1 つ入ります。外していなければ空です。外したファイルの名前ではありません
strippedResourcesstring[]公開の承認が有効なテナントで、公開されていないプレイブック、または公開されていないか無効なスキル(公開されたことの無いバージョンの固定を含む)を外したとき、コピーした Agent の名前が 1 つ入ります。外していなければ空です。外したプレイブック・スキルの名前ではありません

同じ Idempotency-Key で送り直したときは、200 OK で、1 回目のコピーを同じ形で返します。このとき duplicated は 0 件、strippedInputFiles・strippedResources は空です(送り直しでは新しく複製しないため)。1 回目のコピーが消されていると 404 Not Found(agent_not_found)が返ります。新しいキーで送ってください。

レスポンス例​

JSON
{
"agentId": "2c9d4e6f-1a3b-4c5d-8e7f-9a0b1c2d3e4f",
"name": "受注データの取り込み",
"description": "受注メールから受注データを作る",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"isShared": false,
"shareScope": "all",
"shareOrganizations": null,
"runtimeKind": "autonomous",
"marketplaceAgentId": null,
"spec": {
"goal": "受信した受注メールから、受注データの表を作ってください。",
"guardrail": "外部のサービスへは送信しない。",
"skills": [
{
"skillId": "cb62d540-5439-4748-99f0-961b8de91a78",
"name": "order-parser",
"versionId": null
}
],
"playbookId": "2f6a8c0e-4b1d-4a3c-9e5f-7d9b1a3c5e70",
"inputFiles": [
{
"type": "blob",
"filepath": "/path/to/orders-template.xlsx",
"filename": "orders-template.xlsx"
}
],
"agentLevel": "default",
"orgId": null,
"jobRole": null,
"agentConfig": null,
"exposureConsent": null
},
"projectCount": 0,
"copyCount": 0,
"createdAt": "2026-09-20T02:10:00.000Z",
"updatedAt": "2026-09-28T15:18:02.255Z",
"digest": "SBD5evHBJXCLMJy93n5V7KQJQn9o_NmbPmvgYSQFLSo",
"duplicated": {
"playbooks": 1,
"skills": 0
},
"strippedInputFiles": [],
"strippedResources": []
}

エラーレスポンス​

ステータスcode説明
400invalid_parameteragentId が UUID の形式ではない
400idempotency_key_invalidIdempotency-Key の形式が誤っている
403insufficient_scopeassets:write スコープが不足
403forbiddenシステム連携のトークンで呼び出した
403sso_requiredSSO でログインしていない利用者
404agent_not_foundAgent が存在しない、ほかの利用者の非公開の Agent、または同じ Idempotency-Key で作ったコピーが消されている(新しいキーで送ってください)
409already_owned自分の Agent をコピーしようとした
409idempotency_conflict同じ Idempotency-Key で、別の Agent のコピーを送った
409admin_stopped管理者がこの Agent を止めている

スキル​

スキルを読む・作る・変える・消す・コピーします。skillId は、Chat の skillIds パラメータに指定してエージェントにスキルを読み込ませるときや、Agent の定義(spec.skills)に使います。共通の決まりは Agent・Playbook・Skill の共通の決まり を参照してください。

スキルは、SKILL.md と付属のファイル(文書・スクリプト・設定値のファイルなど)でできています。ファイルを変えるたびに新しいバージョンができ、前のバージョンも残ります。

自分が登録したスキルは GET /v1/skills、公開されているスキル(自分が公開したものを含む)は GET /v1/skills/shared で取得します。公開スキルはコピーせずそのまま skillIds に指定できます。

エンドポイント一覧​

メソッドエンドポイント説明スコープ (SaaS)
GET/v1/skills自分のスキル一覧を取得chat:exec / assets:read
GET/v1/skills/shared公開されているスキル一覧を取得chat:exec / assets:read
GET/v1/skills/:skillIdスキルを取得assets:read
GET/v1/skills/:skillId/versionsスキルのバージョンの一覧を取得assets:read
GET/v1/skills/:skillId/filesスキルのファイルの一覧を取得assets:read
GET/v1/skills/:skillId/files/contentスキルの 1 ファイルを取得assets:read
GET/v1/skills/:skillId/downloadスキルのファイルを zip で取得assets:read
POST/v1/skillsスキルを作るassets:write
PUT/v1/skills/:skillId/filesスキルのファイルを丸ごと入れ替えるassets:write
PATCH/v1/skills/:skillId/filesスキルの文書を書き換えるassets:write
PATCH/v1/skills/:skillIdスキルの設定を変えるassets:write
DELETE/v1/skills/:skillIdスキルを消すassets:delete
POST/v1/skills/:skillId/copyスキルを自分のスキルとしてコピーassets:write

GET/v1/skills

自分が登録したスキルの一覧を取得します。最終更新日時の降順(新しい順)で返ります。カーソルベースのページネーションに対応しています。

クエリパラメータ​

パラメータ型デフォルト説明
active_onlybooleantruefalse を指定すると無効化したスキルも含めます。"true" / "false" 以外は 400
limitinteger501 ページの取得件数(1-100)
cursorstring—次ページ取得用カーソル(前回レスポンスの cursor 値)

リクエスト例​

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

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

フィールド型説明
skillsarrayスキルオブジェクトの配列
skills[].skillIdstringスキル ID(Chat の skillIds に指定します)
skills[].ownerUserIdstring | null持ち主の利用者 ID
skills[].namestringスキル名
skills[].descriptionstring?スキルの説明
skills[].categorystring?カテゴリ
skills[].tagsarrayタグの配列(同じタグは 1 つにして返します)。未設定の場合は空配列
skills[].isSharedbooleanスキルを公開しているかどうか
skills[].isActiveboolean有効かどうか
skills[].shareRequestStatusstring | null公開の申請の状態(「スキル・プレイブックの公開の承認」を参照)。同じく sharePendingVersionId・sharePendingListing・shareRequestNote・shareReviewNote・shareRequestedAt も入ります
skills[].createdAtstring作成日時(ISO 8601)
skills[].updatedAtstring最終更新日時(ISO 8601)
hasMoreboolean次のページが存在するかどうか
cursorstring次ページ取得用カーソル。hasMore が true の場合のみ含まれます

レスポンス例​

JSON
{
"skills": [
{
"skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"name": "release-notes",
"description": "リリースノートを生成する",
"category": "devops",
"tags": ["ci"],
"isShared": false,
"isActive": true,
"shareRequestStatus": null,
"sharePendingVersionId": null,
"shareRequestNote": null,
"shareReviewNote": null,
"shareRequestedAt": null,
"sharePendingListing": null,
"createdAt": "2026-08-01T03:12:45.123Z",
"updatedAt": "2026-08-05T09:00:00.000Z"
}
],
"hasMore": false
}

ページネーション​

hasMore が true の間、レスポンスの cursor をそのまま次のリクエストに渡してください。

curl
# 1ページ目
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills?limit=50" \
-H "Authorization: Bearer <access_token>"

# 2ページ目(1ページ目のレスポンスに含まれる cursor を指定)
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills?limit=50&cursor=<cursor>" \
-H "Authorization: Bearer <access_token>"

全件を取得する場合は、hasMore が false になるまで cursor で続きを取得してください。

カーソル利用時の注意

cursor は取得位置を表すため、同じカーソルを使い続ける間は active_only を変更しないでください。条件を変えると対象範囲が変わり、項目の重複や取りこぼしが起きます。

また、ページを取得している間にスキルが追加・削除された場合も、ページ間で重複や取りこぼしが生じることがあります。

エラーレスポンス​

ステータス説明
400limit が 1-100 の整数でない
400cursor が不正(前回レスポンスの値以外)
400active_only が "true" / "false" 以外
403chat:exec / assets:read のいずれも持っていない
403システム連携のトークンで呼び出した(code: "forbidden")

GET/v1/skills/shared

公開されているスキルの一覧を取得します(自分が公開したスキルも含まれます)。作成日時の降順(新しい順)で返ります。カーソルベースのページネーションに対応しています。

クエリパラメータ​

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

リクエスト例​

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

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

公開スキルは常に有効なため、isShared / isActive フィールドは含まれません。申請の状態の項目も含まれません。

フィールド型説明
skillsarrayスキルオブジェクトの配列
skills[].skillIdstringスキル ID(Chat の skillIds に指定します)
skills[].ownerUserIdstring | null持ち主の利用者 ID
skills[].namestringスキル名
skills[].descriptionstring?スキルの説明
skills[].categorystring?カテゴリ
skills[].tagsarrayタグの配列(同じタグは 1 つにして返します)。未設定の場合は空配列
skills[].createdAtstring作成日時(ISO 8601)
skills[].updatedAtstring最終更新日時(ISO 8601)
hasMoreboolean次のページが存在するかどうか
cursorstring次ページ取得用カーソル。hasMore が true の場合のみ含まれます

レスポンス例​

JSON
{
"skills": [
{
"skillId": "9c8b7a6d-5e4f-4a3b-8c1d-2e3f4a5b6c7d",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"name": "sql-review",
"description": "SQL をレビューする",
"category": null,
"tags": [],
"createdAt": "2026-07-20T00:00:00.000Z",
"updatedAt": "2026-08-09T00:00:00.000Z"
}
],
"hasMore": false
}

エラーレスポンス​

ステータス説明
400limit が 1-100 の整数でない
400cursor が不正(前回レスポンスの値以外)
403chat:exec / assets:read のいずれも持っていない
403システム連携のトークンで呼び出した(code: "forbidden")

GET/v1/skills/:skillId

スキルを取得します。自分のスキルと、公開されているスキルを取得できます。

パスパラメータ​

パラメータ型必須説明
skillIdstring必須スキル ID(UUID)

リクエスト例​

Get skill
1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c \
2-H "Authorization: Bearer <access_token>"

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

自分のスキルの一覧の 1 件と同じ項目に、次の 2 つを加えた形です。ほかの利用者の公開スキルでは、公開の一覧と同じく isShared・isActive と申請の状態の項目は含まれません。

フィールド型説明
currentVersionIdstring | null今のバージョンの ID。バージョンの記録が始まる前に作られ、その後ファイルを変えていないスキルは null
digeststringスキルの設定を変えるときに baseDigest に送る値。公開・有効・カテゴリ・タグから作られ、ファイルを変えても変わりません

レスポンス例​

JSON
{
"skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"name": "release-notes",
"description": "リリースノートを生成する",
"category": "devops",
"tags": ["ci"],
"isShared": false,
"isActive": true,
"shareRequestStatus": null,
"sharePendingVersionId": null,
"shareRequestNote": null,
"shareReviewNote": null,
"shareRequestedAt": null,
"sharePendingListing": null,
"createdAt": "2026-08-01T03:12:45.123Z",
"updatedAt": "2026-08-05T09:00:00.000Z",
"currentVersionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80",
"digest": "8IaqLeFZ_E0H1mO92jido8Qk7Sn-rcwYYr71jvwS_Ro"
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterskillId が UUID の形式ではない
403insufficient_scopeassets:read スコープが不足
403forbiddenシステム連携のトークンで呼び出した
404skill_not_foundスキルが存在しない、またはほかの利用者の非公開のスキル

GET/v1/skills/:skillId/versions

スキルのバージョンの一覧を取得します。スキルのファイルを変えるたびに新しいバージョンができ、前のバージョンも残ります。新しいバージョンから順に、100 個まで返ります。ページネーションには対応していません(hasMore はいつも false で、100 個より古いバージョンがあっても返りません)。100 個より古いバージョンも、バージョンの ID が分かれば、ファイルの一覧を取得でき、バイナリでない文書と、200 KiB までの文書でない文字のファイルは 1 ファイルの取得で中身も読めます(すべてのファイルを読むには、そのバージョンを指定してスキルをコピーします)。

ほかの利用者の公開スキルでは、公開されていた間に公開されたバージョンだけを返します。承認待ち・差し戻しのバージョンや、公開していないうちのバージョンは返しません。管理者が公開を止めたスキルは、公開し直した後は、公開し直したときのバージョンとその後に公開されたバージョンだけを返します(止める前のバージョンは返しません)。返さないバージョンを指定すると 400 Bad Request(version_not_found)です。

パスパラメータ​

パラメータ型必須説明
skillIdstring必須スキル ID(UUID)

リクエスト例​

List skill versions
1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/versions \
2-H "Authorization: Bearer <access_token>"

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

フィールド型説明
skillIdstringスキル ID
currentVersionIdstring | null今のバージョンの ID
versionsarrayバージョンの配列(新しい順)
versions[].versionIdstring | nullバージョンの ID
versions[].versionNonumberバージョンの番号(1 から)
versions[].parentVersionIdstring | null元にしたバージョンの ID
versions[].sourcestringバージョンのでき方。"upload"(ファイルを送って作った・入れ替えた)、"edit"(文書を書き換えた)、"copy"(コピーで作った)、"baseline"(バージョンの記録が始まる前からの内容)、"listing"(公開中のスキルのカテゴリ・タグの変更を承認待ちにするために作った)
versions[].contentDigeststring | nullバージョンのファイルの中身から作った値。同じ中身のバージョンは同じ値になります
versions[].createdAtstringバージョンができた日時(ISO 8601)
versions[].isCurrentboolean今のバージョンかどうか
hasMorebooleanいつも false

バージョンの記録が始まる前に作られ、その後ファイルを変えていないスキルは、versionId・contentDigest が null、source が "baseline" の 1 件を返します。

レスポンス例​

JSON
{
"skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
"currentVersionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80",
"versions": [
{
"versionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80",
"versionNo": 2,
"parentVersionId": "e2c4a6b8-1d3f-4a5c-9e7b-0f2d4c6a8e1b",
"source": "edit",
"contentDigest": "78a4ea5aade3b1c0d9f6e7a2b4c8d1e3f5a7b9c0d2e4f6a8b0c1d3e5f7a9b2c4",
"createdAt": "2026-08-05T09:00:00.000Z",
"isCurrent": true
},
{
"versionId": "e2c4a6b8-1d3f-4a5c-9e7b-0f2d4c6a8e1b",
"versionNo": 1,
"parentVersionId": null,
"source": "upload",
"contentDigest": "3cd01ce0220c4f7a9b1d3e5f70a2c4e6b8d0f1a3c5e7b9d1f3a5c7e9b0d2f4a6",
"createdAt": "2026-08-01T03:12:45.123Z",
"isCurrent": false
}
],
"hasMore": false
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterskillId が UUID の形式ではない
403insufficient_scopeassets:read スコープが不足
403forbiddenシステム連携のトークンで呼び出した
404skill_not_foundスキルが存在しない、またはほかの利用者の非公開のスキル

GET/v1/skills/:skillId/files

スキルのバージョンのファイルの一覧を取得します。ファイルの中身は返しません(1 ファイルの取得で読みます)。

パスパラメータ​

パラメータ型必須説明
skillIdstring必須スキル ID(UUID)

クエリパラメータ​

パラメータ型デフォルト説明
version_idstring今のバージョン読むバージョンの ID(UUID)。前の名前 versionId でも受け付けます。省いたとき、持ち主が読み、公開の承認待ち・差し戻しのバージョンがあるときは、そのバージョンを読みます

リクエスト例​

List skill files
1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files \
2-H "Authorization: Bearer <access_token>"

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

フィールド型説明
skillIdstringスキル ID
versionIdstring | nullバージョンの ID
isCurrentboolean今のバージョンかどうか
digeststringスキルのファイルを丸ごと入れ替える・スキルの文書を書き換えるときに baseDigest に送る値(version_id を省いて読んだ一覧の値を送ります)
editableboolean文書を書き換えられるかどうか。自分のスキルで、スクリプトや実行ファイル(.exe・.bin・.so・.dylib・.dll)を含まないときに true
filesarrayファイルの配列(パスの順)
files[].pathstringスキルの中のパス(例: scripts/run.py)
files[].kindstringファイルの種類(拡張子で決まります)。"document"(.md・.json・.yaml・.yml)、"script"(.py・.js・.mjs・.cjs・.ts・.sh・.bash・.zsh・.rb・.pl・.php・.go・.rs・.java・.ps1・.bat・.cmd)、"other"(それ以外。設定値のファイル・画像など)
files[].sizenumber大きさ(バイト)
files[].editableboolean文書を書き換えるで中身を変えられる形式かどうか(文書で、バイナリでないときに true)
hasMorebooleanいつも false(全件を返します)

レスポンス例​

JSON
{
"skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
"versionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80",
"isCurrent": true,
"digest": "WyI1YjFkN2UyYS04YzRmLTRlOWItYTNkNi0yZjdjOWUxYjRhODAiLCI3OGE0ZWE1YWFkZTNiMWMwZDlmNmU3YTJiNGM4ZDFlM2Y1YTdiOWMwZDJlNGY2YThiMGMxZDNlNWY3YTliMmM0Il0",
"editable": true,
"files": [
{ "path": "SKILL.md", "kind": "document", "size": 1834, "editable": true },
{ "path": "templates/notes.md", "kind": "document", "size": 412, "editable": true }
],
"hasMore": false
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterskillId または version_id が UUID の形式ではない、または version_id と versionId に違う値を指定した
400version_not_foundversion_id が、そのスキルのバージョンではない
403insufficient_scopeassets:read スコープが不足
403forbiddenシステム連携のトークンで呼び出した
404skill_not_foundスキルが存在しない、またはほかの利用者の非公開のスキル

GET/v1/skills/:skillId/files/content

スキルの 1 ファイルの中身を取得します。中身はいつも全文で返ります。

前のバージョンで中身を読めるのは、文書(kind が "document" で、バイナリでないもの。大きさを問わず全文)と、200 KiB までの文字のファイルです。持ち主で、公開の承認待ち・差し戻しのバージョンがあるときは、公開中のバージョンも同じです(バージョンを省くと、承認待ち・差し戻しのバージョンのすべてのファイルを読めます)。これらのバージョンの、バイナリのファイル(文書を含む)と、200 KiB を超える文書でないファイルは 400(version_not_readable)になります。前のバージョンのすべてのファイルを読むには、スキルのコピー(POST /v1/skills/:skillId/copy)で versionId を指定してコピーし、コピーしたスキルをダウンロード(GET /v1/skills/:skillId/download)してください。

パスパラメータ​

パラメータ型必須説明
skillIdstring必須スキル ID(UUID)

クエリパラメータ​

パラメータ型デフォルト説明
pathstring—必須。ファイルのパス(ファイルの一覧の files[].path。例: scripts/run.py)
version_idstring今のバージョン読むバージョンの ID(UUID)。前の名前 versionId でも受け付けます。省いたとき、持ち主が読み、公開の承認待ち・差し戻しのバージョンがあるときは、そのバージョンを読みます

リクエスト例​

Get skill file
1curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files/content?path=SKILL.md" \
2-H "Authorization: Bearer <access_token>"

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

フィールド型説明
skillIdstringスキル ID
versionIdstring | nullバージョンの ID
pathstringファイルのパス
kindstringファイルの種類(ファイルの一覧の files[].kind と同じ)
sizenumber大きさ(バイト)
encodingstring中身の表し方。文字のファイルは "utf-8"、バイナリ(中身に NUL を含むもの)は "base64"
contentstringファイルの中身(全文)

レスポンス例​

JSON
{
"skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
"versionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80",
"path": "SKILL.md",
"kind": "document",
"size": 88,
"encoding": "utf-8",
"content": "---\nname: release-notes\ndescription: リリースノートを生成する\n---\n\n# 手順\n"
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterskillId または version_id が UUID の形式ではない、version_id と versionId に違う値を指定した、または path が無い
400file_not_foundpath のファイルが、そのバージョンに無い
400version_not_foundversion_id が、そのスキルのバージョンではない
400version_not_readable前のバージョン(持ち主で、公開の承認待ち・差し戻しのバージョンがあるときは公開中のバージョンも)の、バイナリのファイル(文書を含む)または 200 KiB を超える文書でないファイルを指定した
403insufficient_scopeassets:read スコープが不足
403forbiddenシステム連携のトークンで呼び出した
404skill_not_foundスキルが存在しない、またはほかの利用者の非公開のスキル

GET/v1/skills/:skillId/download

スキルの今のバージョン(持ち主がダウンロードし、公開の承認待ち・差し戻しのバージョンがあるときはそのバージョン)のすべてのファイル(設定値のファイル・画像なども)を、zip で取得します。バージョンは指定できません。

  • レスポンスの Content-Type は application/zip です。ファイル名(Content-Disposition)は、スキルの名前をもとにしたもの(拡張子は .zip)です。
  • zip の中にトップフォルダはありません。そのままスキルを作る(POST /v1/skills)・ファイルを丸ごと入れ替える(PUT /v1/skills/:skillId/files)に送れます。

パスパラメータ​

パラメータ型必須説明
skillIdstring必須スキル ID(UUID)

エラーレスポンス​

ステータスcode説明
400invalid_parameterskillId が UUID の形式ではない
403insufficient_scopeassets:read スコープが不足
403forbiddenシステム連携のトークンで呼び出した
404skill_not_foundスキルが存在しない、またはほかの利用者の非公開のスキル

リクエスト例​

Download skill
1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/download \
2-H "Authorization: Bearer <access_token>"

POST/v1/skills

スキルを作ります。リクエストは multipart/form-data で送ります。名前と説明は、SKILL.md の先頭の YAML(--- で囲んだ部分)の name・description から読みます。

リクエストボディ(multipart/form-data)​

フィールド型必須説明
filesfile必須スキルのファイル。zip 1 つ、または SKILL.md を含むファイル群を送ります。ファイル群は 1 項目に 1 ファイルで、ファイル名をスキルの中のパス(例: scripts/run.py)にします。拡張子が .md のファイル 1 つだけを送ると、SKILL.md として保存します
categorystring—カテゴリ(前後の空白を除いて 40 文字まで)
tagsstring—タグ。1 項目に 1 つで、項目を繰り返して送ります(前後の空白と先頭の # を除いて 1〜24 文字のものを 10 個まで)。小文字にし、先頭の # を除いて保存します。そうして同じになるタグは送れません
isSharedstring—公開するかどうか("true" または "false")。省くと非公開
isActivestring—有効かどうか("true" または "false")。省くと有効。公開するスキルは有効にしてください
shareRequestNotestring—公開の申請の理由(前後の空白を除いて 2000 文字まで。「スキル・プレイブックの公開の承認」を参照)

スキルのファイルの決まり:

  • ルートに SKILL.md が要ります。SKILL.md の先頭の YAML に name(100 文字まで)が要ります。description は省けます(1024 文字を超える分は、一覧などに出る説明では切って保存します。SKILL.md はそのまま残ります)。
  • zip の中が 1 つのフォルダにまとまっているときは、そのフォルダを外して保存します。OS が作るファイル(__MACOSX/・._ で始まるもの・.DS_Store・Thumbs.db・desktop.ini)は保存しません。
  • ファイルは 1〜50 個、1 ファイル 2 MiB まで、展開した後の合計 5 MiB までです。
  • 送るファイルの大きさの合計(ファイル群をまとめた後の大きさを含みます)は 6 MiB 未満にしてください。
  • 中身は安全の検査を通します。

リクエスト例​

Create skill
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills \
2-H "Authorization: Bearer <access_token>" \
3-F "files=@SKILL.md" \
4-F "category=devops" \
5-F "tags=ci"

レスポンス(201 Created)​

自分のスキルの取得と同じ形で、作ったスキルを返します。

レスポンス例​

JSON
{
"skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"name": "release-notes",
"description": "リリースノートを生成する",
"category": "devops",
"tags": [
"ci"
],
"isShared": false,
"isActive": true,
"shareRequestStatus": null,
"sharePendingVersionId": null,
"shareRequestNote": null,
"shareReviewNote": null,
"shareRequestedAt": null,
"sharePendingListing": null,
"createdAt": "2026-08-01T03:12:45.123Z",
"updatedAt": "2026-08-05T09:00:00.000Z",
"currentVersionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80",
"digest": "8IaqLeFZ_E0H1mO92jido8Qk7Sn-rcwYYr71jvwS_Ro"
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterfiles が無い、同じパスのファイルを 2 つ送った、files 以外の項目でファイルを送った、フォームの項目が多すぎる・長すぎる、または category・tags・isShared・isActive の誤り
400file_countファイルが 0 個(空の zip など)、または 50 個を超える
400file_too_large1 ファイルが 2 MiB を超える
400total_too_large展開した後の合計が 5 MiB を超える
400zip_invalidzip を展開できない
400bad_pathファイルのパスが不正(.. を含む など)
400skill_md_missingルートに SKILL.md が無い
400frontmatter_missingSKILL.md の先頭に YAML(--- で囲んだ部分)が無い
400name_missingSKILL.md の YAML に name が無い
400name_too_longSKILL.md の name が 100 文字を超える
400shared_requires_active無効のまま公開しようとした
400guardrail_blocked中身が安全の検査で止められた
403insufficient_scopeassets:write スコープが不足
403forbiddenシステム連携のトークンで呼び出した
413body_too_large送ったファイルの大きさの合計が上限を超える
415unsupported_media_typeContent-Type が multipart/form-data ではない
502blob_write_failedファイルを保存できなかった(送り直してください)
503guardrail_unavailable安全の検査を使えない(時間をおいて送り直してください)
curl
curl -X POST "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills" \
-H "Authorization: Bearer <access_token>" \
-F "files=@SKILL.md;filename=SKILL.md" \
-F "files=@scripts/run.py;filename=scripts/run.py" \
-F "category=devops" \
-F "tags=ci" \
-F "tags=release"

PUT/v1/skills/:skillId/files

自分のスキルのファイルを、送ったファイルで丸ごと入れ替えます。新しいバージョンができ、前のバージョンは残ります。送らなかったファイルは新しいバージョンに入りません。リクエストは multipart/form-data で送ります。

  • 名前と説明は、新しい SKILL.md から読み直します。
  • バージョンを固定せずにこのスキルを使っている Agent とスケジュールは、新しいバージョンを使うようになります(バージョンを固定したものは変わりません)。公開の承認が有効なテナントで公開中のスキルは、新しいバージョンが承認されるまで前のバージョンのままです。
  • 送り直すと、1 回目でバージョンが変わっているため 409 Conflict(stale_base)が返ります。ファイルの一覧を取得し直して、変わったかを確かめてください。

パスパラメータ​

パラメータ型必須説明
skillIdstring必須スキル ID(UUID)

リクエストボディ(multipart/form-data)​

フィールド型必須説明
baseDigeststring必須ファイルの一覧(version_id を省いて読んだもの)の digest
filesfile必須スキルのファイル。送り方と決まりはスキルを作るときと同じです
shareRequestNotestring—公開の申請の理由(前後の空白を除いて 2000 文字まで。「スキル・プレイブックの公開の承認」を参照)

カテゴリ・タグ・公開・有効は受け付けません(送っても読みません)。スキルの設定を変える(PATCH /v1/skills/:skillId)で変えてください。

公開の承認が有効なテナントで、承認待ちのスキルの中身を変えると、承認待ちのまま、変えた後の内容で承認を待ちます。管理者が公開の承認をやめた後に、承認待ちのスキルの中身を変えると、その変更で公開されます。画面で変えた場合と同じです(公開の承認)。

baseDigest の確認は、変えてよい利用者かの確認より先に行います。このため、ほかの利用者の公開スキルでは、baseDigest が合わなければ 409 Conflict、合えば 404 Not Found が返ります。

リクエスト例​

Replace skill files
1curl -X PUT https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files \
2-H "Authorization: Bearer <access_token>" \
3-F "files=@SKILL.md" \
4-F "baseDigest=WyI1YjFkN2UyYS04YzRmLTRlOWItYTNkNi0yZjdjOWUxYjRhODAiLCI3OGE0ZWE1YWFkZTNiMWMwZDlmNmU3YTJiNGM4ZDFlM2Y1YTdiOWMwZDJlNGY2YThiMGMxZDNlNWY3YTliMmM0Il0"

レスポンス(200 OK)​

自分のスキルの取得と同じ形で、入れ替えた後のスキル(新しい currentVersionId)を返します。公開の承認が有効なテナントで公開中のスキルは、currentVersionId は変わらず、新しいバージョンの ID が sharePendingVersionId に入ります。新しいバージョンのファイルの一覧の digest は、ファイルの一覧で取得してください。

レスポンス例​

JSON
{
"skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"name": "release-notes",
"description": "リリースノートを生成する",
"category": "devops",
"tags": [
"ci"
],
"isShared": false,
"isActive": true,
"shareRequestStatus": null,
"sharePendingVersionId": null,
"shareRequestNote": null,
"shareReviewNote": null,
"shareRequestedAt": null,
"sharePendingListing": null,
"createdAt": "2026-08-01T03:12:45.123Z",
"updatedAt": "2026-08-06T10:00:00.000Z",
"currentVersionId": "8c2e4a6b-1d3f-4a5c-9e7b-0f2d4c6a8e1b",
"digest": "8IaqLeFZ_E0H1mO92jido8Qk7Sn-rcwYYr71jvwS_Ro"
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterskillId が UUID の形式ではない、baseDigest が無い・空・文字列ではない、files が無い、同じパスのファイルを 2 つ送った、または files 以外の項目でファイルを送った
400file_countファイルが 0 個(空の zip など)、または 50 個を超える
400file_too_large1 ファイルが 2 MiB を超える
400total_too_large展開した後の合計が 5 MiB を超える
400zip_invalidzip を展開できない
400bad_pathファイルのパスが不正(.. を含む など)
400skill_md_missingルートに SKILL.md が無い
400frontmatter_missingSKILL.md の先頭に YAML(--- で囲んだ部分)が無い
400name_missingSKILL.md の YAML に name が無い
400name_too_longSKILL.md の name が 100 文字を超える
400guardrail_blocked中身が安全の検査で止められた
403insufficient_scopeassets:write スコープが不足
403forbiddenシステム連携のトークンで呼び出した
404skill_not_foundスキルが存在しない、またはほかの利用者のスキル
409stale_baseファイルの一覧を取得した後に、スキルのファイルが変わっている
413body_too_large送ったファイルの大きさの合計が上限を超える
415unsupported_media_typeContent-Type が multipart/form-data ではない
502blob_write_failedファイルを保存できなかった
503guardrail_unavailable安全の検査を使えない(時間をおいて送り直してください)

PATCH/v1/skills/:skillId/files

自分のスキルの文書(.md・.json・.yaml・.yml)を書き換えます。送った文書だけを変えた新しいバージョンができ、送らなかったファイルは今のバージョン(公開の承認待ち・差し戻しのバージョンがあるときはそのバージョン)から引き継ぎます。前のバージョンは残ります。

  • 文書を足す・書き換える・消すことができます。文書でないファイルは変えられません。スクリプトや実行ファイルを含むスキルは書き換えられません(ファイルを丸ごと入れ替える PUT /v1/skills/:skillId/files で直してください)。
  • SKILL.md は消せません。SKILL.md を書き換えると、名前と説明も読み直します。
  • JSON・YAML の文書は構文を確かめます。書き換えた後のスキルも、ファイル 50 個・1 ファイル 2 MiB・合計 5 MiB までです。書き換えた文書は安全の検査を通します。
  • バージョンを固定せずにこのスキルを使っている Agent とスケジュールは、新しいバージョンを使うようになります(バージョンを固定したものは変わりません)。公開の承認が有効なテナントで公開中のスキルは、新しいバージョンが承認されるまで前のバージョンのままです。
  • 公開の申請の理由(shareRequestNote)は送れません(送ると 400 Bad Request(invalid_parameter))。理由を付けるときは、ファイルを丸ごと入れ替える(PUT /v1/skills/:skillId/files)で送ってください。公開の承認が有効なテナントで、公開中のスキルの承認待ちのバージョンをこの API で直しても、申請の理由はそのまま残ります。

パスパラメータ​

パラメータ型必須説明
skillIdstring必須スキル ID(UUID)

リクエストヘッダー​

ヘッダー必須説明
Idempotency-Key—送り直しを見分けるキー(英数字と _ . : - の 8〜128 文字)。同じキーで送り直すと、新しいバージョンを作らずに、1 回目にできたバージョンを返します

リクエストボディ​

フィールド型必須説明
baseDigeststring必須ファイルの一覧(version_id を省いて読んだもの)の digest
changesarray必須変える文書(1〜50 件。同じパスは 1 回だけ)
changes[].pathstring必須文書のパス(例: SKILL.md、templates/notes.md)。無いパスを指定すると文書を足します
changes[].contentstring—文書の新しい中身(全文)。消すときは省きます
changes[].deletedboolean—true で文書を消します(true または false。ほかの値は送れません)
JSON
{
"baseDigest": "WyI1YjFkN2UyYS04YzRmLTRlOWItYTNkNi0yZjdjOWUxYjRhODAiLCI3OGE0ZWE1YWFkZTNiMWMwZDlmNmU3YTJiNGM4ZDFlM2Y1YTdiOWMwZDJlNGY2YThiMGMxZDNlNWY3YTliMmM0Il0",
"changes": [
{ "path": "SKILL.md", "content": "---\nname: release-notes\ndescription: リリースノートを生成する\n---\n\n# 手順\n..." },
{ "path": "templates/old.md", "deleted": true }
]
}

リクエスト例​

Edit skill files
1curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files \
2-H "Authorization: Bearer <access_token>" \
3-H "Idempotency-Key: edit-skill-20261118-0001" \
4-H "Content-Type: application/json" \
5-d '{
6 "baseDigest": "WyI1YjFkN2UyYS04YzRmLTRlOWItYTNkNi0yZjdjOWUxYjRhODAiLCI3OGE0ZWE1YWFkZTNiMWMwZDlmNmU3YTJiNGM4ZDFlM2Y1YTdiOWMwZDJlNGY2YThiMGMxZDNlNWY3YTliMmM0Il0",
7 "changes": [
8 {
9 "path": "SKILL.md",
10 "content": "---\nname: release-notes\ndescription: リリースノートを生成する\n---\n\n# 手順\n"
11 },
12 {
13 "path": "templates/old.md",
14 "deleted": true
15 }
16 ]
17}'

レスポンス(201 Created)​

フィールド型説明
skillobject書き換えた後のスキル(自分のスキルの取得と同じ形。ただし sharePendingListing は入りません。スキルの取得で読めます)
versionobjectできたバージョン(バージョンの一覧の versions[] の 1 件と同じ形)

同じ Idempotency-Key で送り直したときは、200 OK で、1 回目にできたバージョン(version)と今のスキル(skill)を返します。同じキーで中身の違う書き換えを送ると 409 Conflict(command_conflict)が返ります。1 回目の処理が終わる前に送り直すと 409 Conflict(stale_base)が返ることがあります。終わってから同じキーで送り直してください。

レスポンス例​

JSON
{
"skill": {
"skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"name": "release-notes",
"description": "リリースノートを生成する",
"category": "devops",
"tags": [
"ci"
],
"isShared": false,
"isActive": true,
"shareRequestStatus": null,
"sharePendingVersionId": null,
"shareRequestNote": null,
"shareReviewNote": null,
"shareRequestedAt": null,
"createdAt": "2026-08-01T03:12:45.123Z",
"updatedAt": "2026-08-05T09:00:00.000Z",
"currentVersionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80",
"digest": "8IaqLeFZ_E0H1mO92jido8Qk7Sn-rcwYYr71jvwS_Ro"
},
"version": {
"versionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80",
"versionNo": 2,
"parentVersionId": "e2c4a6b8-1d3f-4a5c-9e7b-0f2d4c6a8e1b",
"source": "edit",
"contentDigest": "78a4ea5aade3b1c0d9f6e7a2b4c8d1e3f5a7b9c0d2e4f6a8b0c1d3e5f7a9b2c4",
"createdAt": "2026-08-05T09:00:00.000Z",
"isCurrent": true
}
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterskillId が UUID の形式ではない、baseDigest が無い・空・文字列ではない、changes[].deleted が true・false ではない、または shareRequestNote を送った
400idempotency_key_invalidIdempotency-Key の形式が誤っている
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
400no_changeschanges が無い、空、または 50 件を超える
400bad_changechanges の 1 件の形の誤り(path が無い、content が文字列でない など)、または同じパスを 2 回指定した
400bad_pathpath が不正(.. を含む など)
400not_editable文書でないファイルを指定した
400code_skill_not_editableスクリプトや実行ファイルを含むスキル
400skill_md_requiredSKILL.md を消そうとした
400file_too_large1 ファイルが 2 MiB を超える
400invalid_syntaxJSON・YAML の文書の構文の誤り
400skill_too_large書き換えた後のスキルが 50 ファイルまたは合計 5 MiB を超える
400frontmatter_missingSKILL.md の先頭に YAML(--- で囲んだ部分)が無い
400name_missingSKILL.md の YAML に name が無い
400name_too_longSKILL.md の name が 100 文字を超える
400guardrail_blocked中身が安全の検査で止められた
403insufficient_scopeassets:write スコープが不足
403forbiddenシステム連携のトークンで呼び出した
404skill_not_foundスキルが存在しない、またはほかの利用者のスキル
409stale_baseファイルの一覧を取得した後に、スキルのファイルが変わっている(読めない baseDigest も含みます)
409command_conflict同じ Idempotency-Key で、中身の違う書き換えを送った
413body_too_largeボディが 3 MiB を超える
415unsupported_media_typeボディの Content-Type が application/json ではない
502blob_write_failedファイルを保存できなかった
503guardrail_unavailable安全の検査を使えない(時間をおいて送り直してください)

PATCH/v1/skills/:skillId

自分のスキルの設定(公開・有効・カテゴリ・タグ)を変えます。送った項目だけを変えます。名前と説明は SKILL.md から読むので、ここでは変えられません。

パスパラメータ​

パラメータ型必須説明
skillIdstring必須スキル ID(UUID)

リクエストボディ​

フィールド型必須説明
baseDigeststring必須スキルの取得の digest
isSharedboolean—公開するかどうか。公開の承認が有効なテナントでは、true で承認待ちになり、承認待ちのものに false を送ると申請を取り下げます
isActiveboolean—有効かどうか
categorystring | null—カテゴリ(前後の空白を除いて 40 文字まで)。null か空の文字列で空にします。公開の承認が有効なテナントで公開中のスキルは、同じ更新で isShared: false を送らない限り、承認待ちになります(「スキル・プレイブックの公開の承認」を参照)
tagsarray—タグ(前後の空白と先頭の # を除いて 1〜24 文字の文字列を 10 個まで)。空にするときは []。小文字にし、先頭の # を除いて保存します。そうして同じになるタグは送れません。公開の承認が有効なテナントで公開中のスキルは、同じ更新で isShared: false を送らない限り、承認待ちになります(「スキル・プレイブックの公開の承認」を参照)
shareRequestNotestring | null—公開の申請の理由(前後の空白を除いて 2000 文字まで。「スキル・プレイブックの公開の承認」を参照)

baseDigest のほかに、少なくとも 1 つの項目(shareRequestNote を除きます)を送ってください。公開の申請の理由(shareRequestNote。公開の承認)も送れます。変えた後に「公開していて無効」になる変更は 400(shared_requires_active)です。

baseDigest の確認は、変えてよい利用者かの確認より先に行います。このため、ほかの利用者の公開スキルでは、baseDigest が合わなければ 409 Conflict、合えば 404 Not Found が返ります。

リクエスト例​

Update skill
1curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "baseDigest": "8IaqLeFZ_E0H1mO92jido8Qk7Sn-rcwYYr71jvwS_Ro",
6 "category": "release"
7}'

レスポンス(200 OK)​

自分のスキルの取得と同じ形で、変えた後のスキル(そのときの digest)を返します。公開の承認が有効なテナントで公開中のスキルのカテゴリ・タグを変えたとき(同じ更新で isShared: false を送らないとき)は、category・tags は前の値のままで、変えた値は sharePendingListing に入ります(shareRequestStatus は "pending")。カテゴリ・タグの変更だけでは digest は変わりません。

レスポンス例​

JSON
{
"skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"name": "release-notes",
"description": "リリースノートを生成する",
"category": "release",
"tags": [
"ci"
],
"isShared": false,
"isActive": true,
"shareRequestStatus": null,
"sharePendingVersionId": null,
"shareRequestNote": null,
"shareReviewNote": null,
"shareRequestedAt": null,
"sharePendingListing": null,
"createdAt": "2026-08-01T03:12:45.123Z",
"updatedAt": "2026-08-05T09:00:00.000Z",
"currentVersionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80",
"digest": "ZEs4wUG1R0Xfjmy6jVkkMLsikpWmXBZKAziwGO0gj9k"
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterskillId が UUID の形式ではない、baseDigest が無い・空・文字列ではない、変える項目が無い、または項目の型や長さ・数の誤り
400shared_requires_active変えた後に、公開していて無効になる
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
403insufficient_scopeassets:write スコープが不足
403forbiddenシステム連携のトークンで呼び出した
404skill_not_foundスキルが存在しない、またはほかの利用者のスキル
409stale_base取得した後にスキルの設定が変わっている
413body_too_largeボディが 3 MiB を超える
415unsupported_media_typeボディの Content-Type が application/json ではない

DELETE/v1/skills/:skillId

自分のスキルを、すべてのバージョンのファイルとともに消します。システム管理者は、ほかの利用者が公開したスキルも消せます。

パスパラメータ​

パラメータ型必須説明
skillIdstring必須スキル ID(UUID)

クエリパラメータ​

パラメータ型デフォルト説明
forcestring"false""true" を指定すると、このスキルを使っているスケジュールや Agent があっても消します。"true" / "false" 以外は 400
  • 使っているとき: このスキルを使うスケジュールか、このスキルを定義に持つ Agent があると、409 Conflict(skill_referenced。使っているスケジュールと Agent の数は error.message)が返ります。スケジュールは、すべての利用者のものを、有効・無効を問わず数えます。Agent は持ち主を問わず数えます。プロジェクトのジョブ(プロジェクトに置いた Agent の巡回と、まだ動き始めていないプロジェクトの実行)は、スケジュールとしては数えません。
  • force=true のとき: 使っているスケジュールからこのスキルを外し(ほかの利用者のスケジュールからも外します。スケジュールそのものは残ります)、このスキルを定義に持つ全員の Agent から外してから、スキルを消します。外した Agent の巡回は、外した後の定義で動き続けます。

リクエスト例​

Delete skill
1curl -X DELETE "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c?force=false" \
2-H "Authorization: Bearer <access_token>"

レスポンス(200 OK)​

JSON
{
"skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
"deleted": true
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterskillId が UUID の形式ではない、または force が "true" / "false" 以外
403insufficient_scopeassets:delete スコープが不足
403forbiddenシステム連携のトークンで呼び出した
404skill_not_foundスキルが存在しない、またはほかの利用者のスキルで消せない
409skill_referencedスケジュールか Agent が使っている(force=true で消せます)

POST/v1/skills/:skillId/copy

自分のスキルか公開されているスキルを、自分の新しいスキルとしてコピーします。指定したバージョン(省くと今のバージョン。持ち主がコピーし、公開の承認待ち・差し戻しのバージョンがあるときはそのバージョン)のすべてのファイルを写し、非公開・有効で作ります。名前・説明・カテゴリ・タグは、コピー元の今のものを写します。コピーしたスキルのバージョンは 1 から始まります。

ボディは省けます。バージョンを指定するときは JSON で送ります。

パスパラメータ​

パラメータ型必須説明
skillIdstring必須コピーするスキルの ID(UUID)

リクエストヘッダー​

ヘッダー必須説明
Idempotency-Key—送り直しを見分けるキー(英数字と _ . : - の 8〜128 文字)。同じキーで送り直すと、新しく作らずに、1 回目のコピーを返します

リクエストボディ​

フィールド型必須説明
versionIdstring—写すバージョンの ID(UUID)。省くと今のバージョン(持ち主がコピーし、公開の承認待ち・差し戻しのバージョンがあるときはそのバージョン)

リクエスト例​

Copy skill
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/copy \
2-H "Authorization: Bearer <access_token>" \
3-H "Idempotency-Key: copy-skill-20261118-0001" \
4-H "Content-Type: application/json" \
5-d '{
6 "versionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80"
7}'

レスポンス(201 Created)​

自分のスキルの取得と同じ形で、コピーして作ったスキルを返します。

同じ Idempotency-Key で送り直したときは、200 OK で、1 回目のコピー(今の内容)を同じ形で返します。送り直しで versionId を省くと、1 回目にどのバージョンを写したかによらず 1 回目のコピーが返ります。1 回目のコピーが消されていると 404 Not Found(skill_not_found)が返ります。新しいキーで送ってください。

レスポンス例​

JSON
{
"skillId": "9e1f3a5b-7c2d-4e6f-8a0b-1c3d5e7f9a2b",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"name": "release-notes",
"description": "リリースノートを生成する",
"category": "devops",
"tags": [
"ci"
],
"isShared": false,
"isActive": true,
"shareRequestStatus": null,
"sharePendingVersionId": null,
"shareRequestNote": null,
"shareReviewNote": null,
"shareRequestedAt": null,
"sharePendingListing": null,
"createdAt": "2026-11-18T05:00:00.000Z",
"updatedAt": "2026-11-18T05:00:00.000Z",
"currentVersionId": "d7e9f1a3-5b2c-4d6e-8f0a-2c4e6a8b0d1f",
"digest": "8IaqLeFZ_E0H1mO92jido8Qk7Sn-rcwYYr71jvwS_Ro"
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterskillId または versionId が UUID の形式ではない
400idempotency_key_invalidIdempotency-Key の形式が誤っている
400version_not_foundversionId が、そのスキルのバージョンではない
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
403insufficient_scopeassets:write スコープが不足
403forbiddenシステム連携のトークンで呼び出した
404skill_not_foundスキルが存在しない、ほかの利用者の非公開のスキル、または同じ Idempotency-Key で作ったコピーが消されている(新しいキーで送ってください)
409idempotency_conflict同じ Idempotency-Key で、別のスキルのコピー、または 1 回目と違う versionId のコピーを送った
413body_too_largeボディが 3 MiB を超える
415unsupported_media_typeボディの Content-Type が application/json ではない
502blob_write_failedファイルを保存できなかった

プレイブック​

プレイブックを読む・作る・変える・消す・コピーします。playbookId は、Chat の playbookId パラメータに指定して決まった手順でエージェントを実行させるときや、Agent の定義(spec.playbookId)に使います。共通の決まりは Agent・Playbook・Skill の共通の決まり を参照してください。

エンドポイント一覧​

メソッドエンドポイント説明スコープ (SaaS)
GET/v1/playbooks自分のプレイブック一覧を取得chat:exec / assets:read
GET/v1/playbooks/shared公開されているプレイブック一覧を取得chat:exec / assets:read
GET/v1/playbooks/:playbookIdプレイブックを取得assets:read
POST/v1/playbooksプレイブックを作るassets:write
PATCH/v1/playbooks/:playbookIdプレイブックを変えるassets:write
DELETE/v1/playbooks/:playbookIdプレイブックを消すassets:delete
POST/v1/playbooks/:playbookId/copy公開されているプレイブックを自分のプレイブックとしてコピーassets:write

GET/v1/playbooks

プレイブックの一覧を取得します。利用回数の多い順(同数の場合は作成日時の新しい順)で返ります。カーソルベースのページネーションに対応しています。

クエリパラメータ​

パラメータ型デフォルト説明
active_onlybooleantruefalse を指定すると無効化したプレイブックも含めます。"true" / "false" 以外は 400
limitinteger501 ページの取得件数(1-100)
cursorstring—次ページ取得用カーソル(前回レスポンスの cursor 値)

リクエスト例​

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

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

フィールド型説明
playbooksarrayプレイブックオブジェクトの配列
playbooks[].playbookIdstringプレイブック ID(Chat の playbookId に指定します)
playbooks[].ownerUserIdstring持ち主の利用者 ID
playbooks[].namestringプレイブック名
playbooks[].descriptionstring?説明
playbooks[].categorystring?カテゴリ
playbooks[].tagsarrayタグの配列(前後の空白を除き、空のタグを外し、同じタグは 1 つにして返します)
playbooks[].stepsarray手順の配列
playbooks[].steps[].titlestring手順のタイトル
playbooks[].steps[].descriptionstring?手順の説明
playbooks[].steps[].guidancearray?補足指示の配列
playbooks[].steps[].successstring?完了条件
playbooks[].sourceConversationIdstring?作成元の会話 ID
playbooks[].isSharedboolean公開しているかどうか
playbooks[].isActiveboolean有効かどうか
playbooks[].shareRequestStatusstring | null公開の申請の状態(「スキル・プレイブックの公開の承認」を参照)。同じく shareRequestNote・shareReviewNote・shareRequestedAt も入ります
playbooks[].usageCountnumber利用回数
playbooks[].copyCountnumberコピーされた回数
playbooks[].createdAtstring作成日時(ISO 8601)
playbooks[].updatedAtstring最終更新日時(ISO 8601)
hasMoreboolean次のページが存在するかどうか
cursorstring次ページ取得用カーソル。hasMore が true の場合のみ含まれます

レスポンス例​

JSON
{
"playbooks": [
{
"playbookId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"name": "週次レポート作成",
"description": "売上データから週次レポートを生成する",
"category": "レポート",
"tags": ["sales", "weekly"],
"steps": [
{
"title": "データ取得",
"description": "対象期間の売上データを取得する",
"guidance": ["前週の月曜から日曜まで"],
"success": "データが1件以上取得できている"
}
],
"sourceConversationId": "550e8400-e29b-41d4-a716-446655440000",
"isShared": false,
"isActive": true,
"shareRequestStatus": null,
"shareRequestNote": null,
"shareReviewNote": null,
"shareRequestedAt": null,
"usageCount": 12,
"copyCount": 0,
"createdAt": "2026-08-01T03:12:45.123Z",
"updatedAt": "2026-08-05T09:00:00.000Z"
}
],
"hasMore": false
}

ページネーション​

hasMore が true の間、レスポンスの cursor をそのまま次のリクエストに渡してください。

curl
# 1ページ目
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks?limit=50" \
-H "Authorization: Bearer <access_token>"

# 2ページ目(1ページ目のレスポンスに含まれる cursor を指定)
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks?limit=50&cursor=<cursor>" \
-H "Authorization: Bearer <access_token>"

全件を取得する場合は、hasMore が false になるまで cursor で続きを取得してください。

カーソル利用時の注意

cursor は取得位置を表すため、同じカーソルを使い続ける間は active_only を変更しないでください。条件を変えると対象範囲が変わり、項目の重複や取りこぼしが起きます。

また、ページを取得している間にプレイブックが追加・削除された場合も、ページ間で重複や取りこぼしが生じることがあります。

エラーレスポンス​

ステータス説明
400limit が 1-100 の整数でない
400cursor が不正(前回レスポンスの値以外)
400active_only が "true" / "false" 以外
403chat:exec / assets:read のいずれも持っていない
403システム連携のトークンで呼び出した(code: "forbidden")

GET/v1/playbooks/shared

公開されているプレイブックの一覧を取得します。自分が公開したものと、公開した人が無効にしたものも含みます。コピーされた回数の多い順(同数の場合は作成日時の新しい順)で返ります。カーソルベースのページネーションに対応しています。

クエリパラメータ​

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

リクエスト例​

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

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

自分のプレイブックの一覧と同じ形です。ただし、各項目に isShared・isActive と申請の状態の項目は含まれません。

レスポンス例​

JSON
{
"playbooks": [
{
"playbookId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"sourceConversationId": "550e8400-e29b-41d4-a716-446655440000",
"name": "週次レポート作成",
"description": "売上データから週次レポートを生成する",
"category": "レポート",
"tags": [
"sales",
"weekly"
],
"steps": [
{
"title": "データ取得",
"description": "対象期間の売上データを取得する",
"guidance": [
"前週の月曜から日曜まで"
],
"success": "データが1件以上取得できている"
}
],
"usageCount": 12,
"copyCount": 0,
"createdAt": "2026-08-01T03:12:45.123Z",
"updatedAt": "2026-08-05T09:00:00.000Z"
}
],
"hasMore": false
}

エラーレスポンス​

ステータス説明
400limit が 1-100 の整数でない
400cursor が不正(前回レスポンスの値以外)
403chat:exec / assets:read のいずれも持っていない
403システム連携のトークンで呼び出した(code: "forbidden")

GET/v1/playbooks/:playbookId

プレイブックを取得します。自分のプレイブックと、公開されているプレイブックを取得できます。

パスパラメータ​

パラメータ型必須説明
playbookIdstring必須プレイブックの ID(UUID)

リクエスト例​

Get playbook
1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7 \
2-H "Authorization: Bearer <access_token>"

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

プレイブックの一覧の 1 件と同じ項目に、digest を加えた形です。ほかの利用者の公開プレイブックでは、公開の一覧と同じく isShared・isActive と申請の状態の項目は含まれません。

フィールド型説明
digeststringプレイブックを変えるときに baseDigest に送る値。名前・説明・カテゴリ・タグ・手順・公開・有効から作られ、利用回数・コピーされた回数・日時では変わりません

updatedAt は、内容を変えたときのほか、プレイブックが使われるたびにも更新されます。

レスポンス例​

JSON
{
"playbookId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"sourceConversationId": "550e8400-e29b-41d4-a716-446655440000",
"name": "週次レポート作成",
"description": "売上データから週次レポートを生成する",
"category": "レポート",
"tags": [
"sales",
"weekly"
],
"steps": [
{
"title": "データ取得",
"description": "対象期間の売上データを取得する",
"guidance": [
"前週の月曜から日曜まで"
],
"success": "データが1件以上取得できている"
}
],
"isShared": false,
"isActive": true,
"shareRequestStatus": null,
"shareRequestNote": null,
"shareReviewNote": null,
"shareRequestedAt": null,
"usageCount": 12,
"copyCount": 0,
"createdAt": "2026-08-01T03:12:45.123Z",
"updatedAt": "2026-08-05T09:00:00.000Z",
"digest": "zP8MqAgVGbQF5em-ojsdO_8YZiLbt2J1XWTMsXjbO-E"
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterplaybookId が UUID の形式ではない
403insufficient_scopeassets:read スコープが不足
403forbiddenシステム連携のトークンで呼び出した
404playbook_not_foundプレイブックが存在しない、またはほかの利用者の非公開のプレイブック

POST/v1/playbooks

プレイブックを作ります。

リクエストボディ​

フィールド型必須説明
namestring必須名前(100 文字まで。空白だけにはできません)
descriptionstring | null—説明(500 文字まで)
categorystring | null—カテゴリ(50 文字まで)
tagsarray—タグ(1 つ 30 文字までの文字列を 10 個まで。空・空白だけのタグと、前後の空白を除いて同じになるタグは送れません。大文字小文字は区別します)
stepsarray必須手順(1〜20 個)
steps[].titlestring必須手順のタイトル(100 文字まで。空白だけにはできません)
steps[].descriptionstring—手順の説明(1000 文字まで)
steps[].guidancearray—補足指示(1 つ 500 文字までの文字列を 10 個まで。空・空白だけの文字列は送れません)
steps[].successstring—完了条件(500 文字まで)
isSharedboolean—公開するかどうか。省くと非公開
isActiveboolean—有効かどうか。省くと有効
shareRequestNotestring | null—公開の申請の理由(前後の空白を除いて 2000 文字まで。「スキル・プレイブックの公開の承認」を参照)
  • 手順の項目は title・description・guidance・success の 4 つです(ほかの項目は保存しません)。手順の文字列の項目に null は送れません。
  • 名前・説明・カテゴリは、前後の空白を除いて保存します。説明・カテゴリは、null・空の文字列・空白だけのときは null で保存します。

リクエスト例​

Create playbook
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "name": "週次レポート作成",
6 "description": "売上データから週次レポートを生成する",
7 "category": "レポート",
8 "tags": [
9 "sales",
10 "weekly"
11 ],
12 "steps": [
13 {
14 "title": "データ取得",
15 "description": "対象期間の売上データを取得する",
16 "guidance": [
17 "前週の月曜から日曜まで"
18 ],
19 "success": "データが1件以上取得できている"
20 }
21 ]
22}'

レスポンス(201 Created)​

自分のプレイブックの取得と同じ形で、作ったプレイブックを返します。

レスポンス例​

JSON
{
"playbookId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"sourceConversationId": null,
"name": "週次レポート作成",
"description": "売上データから週次レポートを生成する",
"category": "レポート",
"tags": [
"sales",
"weekly"
],
"steps": [
{
"title": "データ取得",
"description": "対象期間の売上データを取得する",
"guidance": [
"前週の月曜から日曜まで"
],
"success": "データが1件以上取得できている"
}
],
"isShared": false,
"isActive": true,
"shareRequestStatus": null,
"shareRequestNote": null,
"shareReviewNote": null,
"shareRequestedAt": null,
"usageCount": 0,
"copyCount": 0,
"createdAt": "2026-08-01T03:12:45.123Z",
"updatedAt": "2026-08-05T09:00:00.000Z",
"digest": "zP8MqAgVGbQF5em-ojsdO_8YZiLbt2J1XWTMsXjbO-E"
}

エラーレスポンス​

ステータスcode説明
400invalid_parametername・steps が無い、または項目の型や長さ・数の誤り(error.param に誤った項目。手順の中は steps[2].title のように示します)
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
403insufficient_scopeassets:write スコープが不足
403forbiddenシステム連携のトークンで呼び出した
413body_too_largeボディが 3 MiB を超える
415unsupported_media_typeボディの Content-Type が application/json ではない

PATCH/v1/playbooks/:playbookId

自分のプレイブックを変えます。送った項目だけを変えます。手順(steps)は、送ると全部が置き換わります(書き換え・削除・並べ替えは、この配列で表します)。

名前・説明・カテゴリ・タグ・手順のどれかを変えると、変える前の中身がバージョンとして残り、画面の「バージョンの履歴」から戻せます。公開・有効の切り替えだけでは残りません。

パスパラメータ​

パラメータ型必須説明
playbookIdstring必須プレイブックの ID(UUID)

リクエストボディ​

フィールド型必須説明
baseDigeststring必須プレイブックの取得の digest
namestring—名前(100 文字まで。空白だけや null にはできません)
descriptionstring | null—説明(500 文字まで)。null か空の文字列で空にします
categorystring | null—カテゴリ(50 文字まで)。null か空の文字列で空にします
tagsarray—タグ(1 つ 30 文字までの文字列を 10 個まで。送れないタグは作るときと同じです)。空にするときは []
stepsarray—手順の全部(1〜20 個)。項目はプレイブックを作るときと同じです
isSharedboolean—公開するかどうか。公開の承認が有効なテナントでは、true で承認待ちになり、承認待ちのものに false を送ると申請を取り下げます
isActiveboolean—有効かどうか
shareRequestNotestring | null—公開の申請の理由(前後の空白を除いて 2000 文字まで。「スキル・プレイブックの公開の承認」を参照)

baseDigest のほかに、少なくとも 1 つの項目(shareRequestNote を除きます)を送ってください。name・tags・steps・isShared・isActive に null は送れません。保存のしかた(前後の空白)と、送れないタグ・補足指示は、プレイブックを作るときと同じです。

1 回目で内容が変わっていれば、送り直すと digest が変わっているため 409 Conflict(stale_base)が返ります。取得し直して、変わったかを確かめてください。

公開の承認が有効なテナントで、承認待ちのプレイブックの中身(名前・説明・カテゴリ・タグ・手順)を変えると、承認待ちのまま、変えた後の内容で承認を待ちます。管理者が公開の承認をやめた後に、承認待ちのプレイブックの中身を変えると、その変更で公開されます。画面で変えた場合と同じです(公開の承認)。

公開の承認が有効なテナントで、公開中のプレイブックの中身を変えると、公開を続けたまま申請になります(応答の isShared は true、shareRequestStatus は "pending")。承認されるまで、ほかの利用者には承認した中身が見えます(公開の承認)。

リクエスト例​

Update playbook
1curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7 \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "baseDigest": "zP8MqAgVGbQF5em-ojsdO_8YZiLbt2J1XWTMsXjbO-E",
6 "description": "売上データから週次レポートを作る"
7}'

レスポンス(200 OK)​

自分のプレイブックの取得と同じ形で、変えた後のプレイブック(そのときの digest)を返します。

レスポンス例​

JSON
{
"playbookId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"sourceConversationId": "550e8400-e29b-41d4-a716-446655440000",
"name": "週次レポート作成",
"description": "売上データから週次レポートを作る",
"category": "レポート",
"tags": [
"sales",
"weekly"
],
"steps": [
{
"title": "データ取得",
"description": "対象期間の売上データを取得する",
"guidance": [
"前週の月曜から日曜まで"
],
"success": "データが1件以上取得できている"
}
],
"isShared": false,
"isActive": true,
"shareRequestStatus": null,
"shareRequestNote": null,
"shareReviewNote": null,
"shareRequestedAt": null,
"usageCount": 12,
"copyCount": 0,
"createdAt": "2026-08-01T03:12:45.123Z",
"updatedAt": "2026-08-05T09:00:00.000Z",
"digest": "DYEcDfkGIG6oOpm-WEd7l1UhFjZzruLKxM9yEYu9BTA"
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterplaybookId が UUID の形式ではない、baseDigest が無い・空・文字列ではない、変える項目が無い、項目の型や長さ・数の誤り、または送れない項目に null を送った
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
403insufficient_scopeassets:write スコープが不足
403forbiddenシステム連携のトークンで呼び出した
404playbook_not_foundプレイブックが存在しない、またはほかの利用者のプレイブック
409stale_base取得した後にプレイブックが変わっている
413body_too_largeボディが 3 MiB を超える
415unsupported_media_typeボディの Content-Type が application/json ではない

DELETE/v1/playbooks/:playbookId

自分のプレイブックを消します。システム管理者は、ほかの利用者が公開したプレイブックも消せます。

パスパラメータ​

パラメータ型必須説明
playbookIdstring必須プレイブックの ID(UUID)

クエリパラメータ​

パラメータ型デフォルト説明
forcestring"false""true" を指定すると、このプレイブックを使っているスケジュールや Agent があっても消します。"true" / "false" 以外は 400
  • 使っているとき: このプレイブックを使う有効なスケジュールか、このプレイブックを定義に持つ Agent があると、409 Conflict(has_active_references。使っている有効なスケジュールと Agent の数は error.message)が返ります。Agent は持ち主を問わず数えます。プロジェクトのジョブ(プロジェクトに置いた Agent の巡回と、まだ動き始めていないプロジェクトの実行)は、スケジュールとしては数えません。
  • force=true のとき: このプレイブックを定義に持つ全員の Agent から外して、プレイブックを消します。外した Agent の巡回は、外した後の定義で動き続けます。有効なスケジュールが使っているときは、このプレイブックを使うスケジュールを、無効なものも含めて消します。
    • 数えて消すスケジュールは、自分のスケジュールだけです(システム管理者が自分のプレイブックを消すときも同じです)。ほかの利用者のスケジュールは数えず、消しません(消えたプレイブックを指したままになります)。システム管理者が、ほかの利用者が公開したプレイブックを消すときは、すべての利用者のスケジュールを数えて消します。
    • 使っているのが無効なスケジュールだけのときは、Agent も使っていなければ 409 Conflict になりません。どちらのときも、force=true を付けても無効なスケジュールは消えず、消えたプレイブックを指したままになります。
    • 消えたスケジュールは、この後は動きません(すでに動き始めた実行は止まりません)。

リクエスト例​

Delete playbook
1curl -X DELETE "https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7?force=false" \
2-H "Authorization: Bearer <access_token>"

レスポンス(200 OK)​

JSON
{
"playbookId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"deleted": true
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterplaybookId が UUID の形式ではない、または force が "true" / "false" 以外
403insufficient_scopeassets:delete スコープが不足
403forbiddenシステム連携のトークンで呼び出した
404playbook_not_foundプレイブックが存在しない、またはほかの利用者のプレイブックで消せない
409has_active_references有効なスケジュールか Agent が使っている(force=true で消せます)
409admin_stoppedforce=true で消すとき、このプレイブックを有効なスケジュールが使っていて、使っているスケジュールに管理者が止めたものがある

POST/v1/playbooks/:playbookId/copy

公開されているプレイブックを、自分のプレイブックとしてコピーします。名前・説明・カテゴリ・タグ・手順を写し、非公開・有効で作ります。コピー元のコピーされた回数(copyCount)が 1 増えます。ボディは不要です(送っても読みません)。

パスパラメータ​

パラメータ型必須説明
playbookIdstring必須コピーするプレイブックの ID(UUID)

リクエストヘッダー​

ヘッダー必須説明
Idempotency-Key—送り直しを見分けるキー(英数字と _ . : - の 8〜128 文字)。同じキーで送り直すと、新しく作らずに、1 回目のコピーを返します

リクエスト例​

Copy playbook
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7/copy \
2-H "Authorization: Bearer <access_token>" \
3-H "Idempotency-Key: copy-playbook-20261118-0001"

レスポンス(201 Created)​

自分のプレイブックの取得と同じ形で、コピーして作ったプレイブックを返します。

同じ Idempotency-Key で送り直したときは、200 OK で、1 回目のコピー(今の内容)を同じ形で返します。1 回目のコピーが消されていると 404 Not Found(playbook_not_found)が返ります。新しいキーで送ってください。

レスポンス例​

JSON
{
"playbookId": "1d3f5a7b-9c2e-4a6c-8e0f-2b4d6f8a0c1e",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"sourceConversationId": null,
"name": "週次レポート作成",
"description": "売上データから週次レポートを生成する",
"category": "レポート",
"tags": [
"sales",
"weekly"
],
"steps": [
{
"title": "データ取得",
"description": "対象期間の売上データを取得する",
"guidance": [
"前週の月曜から日曜まで"
],
"success": "データが1件以上取得できている"
}
],
"isShared": false,
"isActive": true,
"shareRequestStatus": null,
"shareRequestNote": null,
"shareReviewNote": null,
"shareRequestedAt": null,
"usageCount": 0,
"copyCount": 0,
"createdAt": "2026-11-18T05:00:00.000Z",
"updatedAt": "2026-11-18T05:00:00.000Z",
"digest": "zP8MqAgVGbQF5em-ojsdO_8YZiLbt2J1XWTMsXjbO-E"
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterplaybookId が UUID の形式ではない
400idempotency_key_invalidIdempotency-Key の形式が誤っている
403insufficient_scopeassets:write スコープが不足
403forbiddenシステム連携のトークンで呼び出した
404playbook_not_foundプレイブックが存在しない、公開されていない(自分のプレイブックでも、公開していなければ 404)、または同じ Idempotency-Key で作ったコピーが消されている(新しいキーで送ってください)
409idempotency_conflict同じ Idempotency-Key で、別のプレイブックのコピーを送った

メッセージを全文検索します。

エンドポイント一覧​

メソッドエンドポイント説明スコープ (SaaS)
GET/v1/search/messagesメッセージを全文検索chat:history

※ Marketplace 版はスコープ不要(認証のみ)。

GET/v1/search/messages

メッセージを全文検索します。プロジェクトの工程の会話のメッセージと、アーカイブ済みの会話のメッセージは、検索の対象になりません。検索結果は作成日時の新しい順(order=asc で古い順)に、カーソルベースのページネーションで返します。

クエリパラメータ​

パラメータ型必須説明
qstring必須検索クエリ
orderstring—ソート順。"asc"(昇順)または "desc"(降順、デフォルト)
limitinteger—1 ページの件数(1〜100)。デフォルトは 50 件です
cursorstring—次のページを取得するためのカーソル値。前回のレスポンスに含まれる cursor をそのまま指定します。q と order は前回と同じにしてください

リクエスト例​

Search messages
1curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/search/messages?q=売上" \
2-H "Authorization: Bearer <access_token>"

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

フィールド型説明
messagesarray検索結果のメッセージ配列(1 ページ分。limit 件まで)
messages[].conversationIdstring会話ID(UUID)
messages[].messageIdstringメッセージの一意識別子
messages[].textstringメッセージの本文テキスト
messages[].titlestring会話のタイトル
messages[].senderstring送信者。"User" または "AI"
messages[].createdAtstring作成日時(ISO 8601)
messages[].updatedAtstring最終更新日時(ISO 8601)
messages[].matchedQueriesarray一致した検索クエリの配列
messages[].statusobjectメッセージの処理状態
messages[].status.processingbooleanエージェントが現在処理中かどうか
messages[].status.unfinishedbooleanエージェントの応答が中断されたかどうか
messages[].tasksarrayエージェントが実行したタスクの配列。フィールド定義は GET /v1/conversations/:conversationId/messages の Task オブジェクトを参照
messages[].deliverablesarrayエージェントが生成した成果物の配列。存在する場合のみ含まれます
messages[].deliverables[].filenamestring成果物のファイル名
messages[].deliverables[].filepathstring成果物のファイルパス
messages[].deliverables[].sourcestring"agent"(エージェント生成)または "user"(ユーザーアップロード)
messages[].deliverables[].isPrimaryboolean主要成果物かどうか
messages[].deliverables[].createdAtstring作成日時(ISO 8601形式)。分からないときは空文字
messages[].deliverables[].mimeTypestringMIME タイプ(例: "application/pdf"、"text/markdown")。判定できない場合は "application/octet-stream"
messages[].deliverables[].sizenumber?ファイルサイズ(バイト)。0 以下の場合は省略
messages[].filesarray?ユーザーが添付したファイルの配列。sender: "User" のメッセージで添付がある場合のみ含まれます。フィールド構造は履歴 API と同じ(fileId / mimeType / width? / height?)。詳細は GET /v1/conversations/:id/messages を参照
hasMoreboolean続きのページがあれば true。true のときは cursor が返ります
cursorstring次のページを取得するためのカーソル値。hasMore が true のときだけ含まれます
limitReachedboolean一致したメッセージが多く、一致の度合いの高い上位の結果(本文の一致と、エージェントの作業の経過の一致のそれぞれ 1,000 件まで)だけを対象にしているときだけ true。そうでないときは含まれません。もれなく探すときは検索クエリを絞ってください

レスポンス例​

JSON
{
"messages": [
{
"conversationId": "550e8400-...",
"messageId": "msg-abc123",
"text": "売上データを分析した結果...",
"title": "売上データ分析",
"sender": "AI",
"createdAt": "2026-03-14T10:30:00Z",
"updatedAt": "2026-03-14T10:35:00Z",
"matchedQueries": ["売上"],
"tasks": []
}
],
"hasMore": false
}

エラーレスポンス​

ステータス説明
400q パラメータが未指定、または 1 つの文字列として指定されていない(q を複数回指定した場合など)。order が "asc" / "desc" 以外、limit が 1〜100 の整数ではない、または cursor が読めない
403chat:history スコープが不足
501検索の設定が無い環境(code: "search_not_configured")
503検索が一時的に使えない(code: "service_unavailable")。時間をおいて送り直してください

ユーザー​

ユーザー情報の取得・更新・パスワード変更を行います。

エンドポイント一覧​

メソッドエンドポイント説明
GET/v1/userユーザー情報を取得
PATCH/v1/userユーザー情報を更新
POST/v1/user/passwordパスワードを変更

GET/v1/user

ユーザー情報を取得します。

リクエスト例​

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

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

フィールド型説明
userIdstringユーザーの一意識別子
emailstringメールアドレス
usernamestringユーザー名
emailVerifiedbooleanメールアドレスの確認状態
createdAtstringアカウント作成日時(ISO 8601)
isApprovedbooleanアカウントの承認状態
rolestringユーザーのロール
organizationobject所属組織(設定されている場合のみ)
organization.valuestring組織コード
organization.labelstring組織名
jobTypeobject職種(設定されている場合のみ)
jobType.valuestring職種コード
jobType.labelstring職種名
biostring自己紹介(設定されている場合のみ)
lastLoginAtstring最終ログイン日時(ISO 8601、存在する場合のみ)

レスポンス例​

JSON
{
"userId": "user-abc123",
"email": "tanaka@example.com",
"username": "田中太郎",
"emailVerified": true,
"createdAt": "2026-03-10T09:00:00.000Z",
"isApproved": true,
"role": "user",
"organization": { "value": "eng", "label": "エンジニアリング部門" },
"jobType": { "value": "dev", "label": "開発者" },
"bio": "AIエンジニア",
"lastLoginAt": "2026-03-14T10:00:00.000Z"
}

エラーレスポンス​

ステータスcode説明
500internal_errorユーザー情報を取得できなかった(時間をおいて再試行してください)

PATCH/v1/user

ユーザー情報を更新します。

リクエストボディ​

パラメータ型必須説明
usernamestring—ユーザー名。2〜50 文字で、「<」「>」「"」「'」は使えません
organizationstring—組織コード。100 文字まで。未設定のときだけ設定でき、有効な組織コードだけを設定できます。設定済みの組織を変える(空にするのも)と 403 になります。変更は管理者に依頼してください。IdP から同期しているときは、ID 基盤(IdP)で変えてください
jobTypestring—職種コード。100 文字まで。未設定のときだけ設定でき、有効な職種コードだけを設定できます。設定済みの職種を変える(空にするのも)と 403 になります。変更は管理者に依頼してください。IdP から同期しているときは、ID 基盤(IdP)で変えてください
biostring—自己紹介。150 文字までで、「<」「>」「"」「'」は使えません

リクエスト例​

Update user
1curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/user \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{ "username": "田中太郎", "bio": "エンジニアリング部門" }'

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

GET /v1/user と同じユーザーオブジェクトが返されます(更新後の値を含む)。

レスポンス例​

JSON
{
"userId": "user-abc123",
"email": "tanaka@example.com",
"username": "田中太郎",
"emailVerified": true,
"createdAt": "2026-03-10T09:00:00.000Z",
"isApproved": true,
"role": "user",
"organization": { "value": "eng", "label": "エンジニアリング部門" },
"jobType": { "value": "dev", "label": "開発者" },
"bio": "エンジニアリング部門",
"lastLoginAt": "2026-03-14T10:00:00.000Z"
}

エラーレスポンス​

ステータスcode説明
400invalid_parameter更新するフィールドが未指定
400invalid_bodyボディが壊れた JSON
400invalid_parameter入力の誤り(username / organization / jobType / bio が文字列ではない、文字数・使えない文字、または初めて設定する organization / jobType が有効なコードではない)
403affiliation_locked設定済みの organization / jobType を変えようとした(空にするのも)。変更は管理者に依頼してください。IdP から同期しているときは、ID 基盤(IdP)で変えてください
409conflict同じユーザーの別の更新を処理している。少し待ってから送り直してください
415unsupported_media_typeボディの Content-Type が application/json ではない

POST/v1/user/password

パスワードを変更します。

リクエストボディ​

パラメータ型必須説明
currentPasswordstring必須現在のパスワード
newPasswordstring必須新しいパスワード
confirmPasswordstring必須新しいパスワード(確認用)

リクエスト例​

Change password
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/user/password \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "currentPassword": "OldPass123!",
6 "newPassword": "NewPass456!",
7 "confirmPassword": "NewPass456!"
8}'

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

フィールド型説明
userIdstringユーザーの一意識別子
changedbooleanパスワード変更成功時は常に true

レスポンス例​

JSON
{ "userId": "user-abc123", "changed": true }

パスワードを変えたら、変える前に取ったトークンは使い続けず、もう一度ログインしてトークンを取り直してください。変える前のアクセストークンは、期限まで API に通ります。

パスワードを変えると、本人のチャットの画面のログインも、すべての端末で、次に操作したときに切れます。

エラーレスポンス​

ステータス説明
400必須パラメータの不足、currentPassword / newPassword / confirmPassword が文字列ではない、ボディが壊れた JSON(code: "invalid_body")、パスワードバリデーション失敗、または現在のパスワードが不正
415ボディの Content-Type が application/json ではない(code: "unsupported_media_type")
401認証トークンが無効
403SSO でログインする利用者(code: "federation_only_user")。SSO の利用者は、この API でパスワードを変えられません

マスターデータ​

組織・ジョブタイプ等のマスターデータを取得します。

エンドポイント一覧​

メソッドエンドポイント説明
GET/v1/organizations組織一覧を取得
GET/v1/job-typesジョブタイプ一覧を取得
GET/v1/personasペルソナ一覧を取得

GET/v1/organizations

組織一覧を取得します。無効化された組織は含まれません。

リクエスト例​

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

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

フィールド型説明
organizationsarray組織オブジェクトの配列
organizations[].valuestring組織コード
organizations[].labelstring組織名
hasMoreboolean常に false(ページネーション非対応)

レスポンス例​

JSON
{
"organizations": [
{ "value": "eng", "label": "エンジニアリング部門" },
{ "value": "sales", "label": "営業部門" }
],
"hasMore": false
}

エラーレスポンス​

ステータスcode説明
500internal_error組織の一覧を取得できなかった(時間をおいて再試行してください)

GET/v1/job-types

ジョブタイプ一覧を取得します。無効化されたジョブタイプは含まれません。

リクエスト例​

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

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

フィールド型説明
jobTypesarrayジョブタイプオブジェクトの配列
jobTypes[].valuestring職種コード
jobTypes[].labelstring職種名
hasMoreboolean常に false(ページネーション非対応)

レスポンス例​

JSON
{
"jobTypes": [
{ "value": "dev", "label": "開発者" },
{ "value": "pm", "label": "プロジェクトマネージャー" }
],
"hasMore": false
}

エラーレスポンス​

ステータスcode説明
500internal_errorジョブタイプの一覧を取得できなかった(時間をおいて再試行してください)

GET/v1/personas

ペルソナ(エージェントの応答人格)一覧を取得します。取得した personaKey を Chat / MCP / A2A の persona 指定に使用します。

クエリパラメータ​

パラメータ型必須デフォルト説明
localestring—プラットフォーム既定言語name / description の表示言語(例: "ja"、"en")。知らない値や文字列ではない値を指定しても 400 にはならず、プラットフォーム既定言語で返します

リクエスト例​

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

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

フィールド型説明
localestring解決されたロケール。指定した言語の内容が無いペルソナは、英語、日本語、ほかの言語の順で、別の言語の内容で返ります
personasarrayペルソナオブジェクトの配列
personas[].personaKeystringペルソナの識別子(Chat / MCP / A2A の personaKey に指定)
personas[].namestringペルソナの表示名
personas[].descriptionstringペルソナの説明
hasMoreboolean常に false(ページネーション非対応)

レスポンス例​

JSON
{
"locale": "ja",
"personas": [
{ "personaKey": "concise", "name": "簡潔", "description": "要点に絞って簡潔に回答します" }
],
"hasMore": false
}

エラーレスポンス​

ステータスcode説明
500internal_errorペルソナの一覧を取得できなかった(時間をおいて再試行してください)

プロジェクト​

プロジェクトの API は、ユーザー API リファレンス(プロジェクト)に載せています。システム連携(Client Credentials フロー)のトークンで呼ぶときは、システム連携 API リファレンス — プロジェクトを参照してください。

プロジェクト一覧の取得​

GET /v1/projects は、ユーザー API リファレンス(プロジェクト)のプロジェクトに載せています。

ワークフローの実行の開始​

POST /v1/projects/{projectId}/runs は、ユーザー API リファレンス(プロジェクト)のワークフローの実行(run)に載せています。

トリガーの発火​

POST /v1/projects/{projectId}/triggers/{triggerId}/fire は、ユーザー API リファレンス(プロジェクト)のトリガーに載せています。

ワークフローの実行の取得​

GET /v1/projects/{projectId}/runs/{runId} は、ユーザー API リファレンス(プロジェクト)のワークフローの実行(run)に載せています。

エラーレスポンス​

HTTP ステータスコード​

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

ステータス説明
400 Bad Requestリクエストパラメータが不正
401 Unauthorizedトークンが無効または未指定。管理者に利用を止められた利用者のトークンでも返ります(下の「利用を止められた利用者」)
403 Forbiddenリソースへのアクセス権限なし。管理者が公開 API の接続元を制限していて、接続元の IP アドレスが許可の一覧に無いときも返ります(error.code は ip_not_allowed)
404 Not Foundリソースが存在しない、または未定義のパス・メソッド(405 は返しません)
409 Conflictリソースが現在処理中など、操作が競合
409 Conflict組織の運用の役割(管理コンソールの「管理の役割」で付ける「運用」の役割)の人が、プロジェクトに参加せずに、その役割では使えない操作を呼んだ(error.code は forbidden_role)。待っても直りません。オーナーだけの操作は、プロジェクトのオーナーに頼んでください。ほかの操作は、オーナーにプロジェクトに加えてもらうと、参加の役割のとおりに呼べます
413 Payload Too Largeリクエストボディがサイズ上限を超過
415 Unsupported Media Typeリクエストボディの形式(Content-Type)に対応していない
429 Too Many Requestsレート制限または同時実行の上限を超過。error.type は rate_limit_error で、error.code はエンドポイントにより異なります(例: 月間上限は monthly_quota_exceeded、プロジェクトの同時実行は too_many_active_runs)。時間をおいて再試行してください
500 Internal Server Errorサーバー内部エラー
502 Bad Gateway上流サービス(認証基盤・チャット基盤等)との通信エラー
503 Service Unavailableサービス一時利用不可
504 Gateway Timeout上流サービスの応答タイムアウト

エラーレスポンス形式​

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

フィールド型説明
error.typestringエラーの分類。"invalid_request_error"、"authentication_error"、"insufficient_scope_error"、"forbidden_error"、"not_found_error"、"conflict_error"、"payload_too_large_error"、"rate_limit_error"、"server_error"、"upstream_error" のいずれか
error.messagestring人間が読めるエラーメッセージ
error.codestring機械的に処理可能なエラーコード(例: "missing_parameter"、"invalid_parameter"、"invalid_token")
error.paramstringエラーの原因となったパラメータ名。バリデーションエラー時のみ含まれます
error.reasonstring断りの理由の種類。プロジェクト API の 409(definition_invalid)のときだけ含まれます
error.suggested_actionstring推奨される対処方法。一部のエラーでのみ含まれます
JSON
{
"error": {
"type": "invalid_request_error",
"message": "Invalid parameter: limit",
"code": "invalid_parameter",
"param": "limit",
"suggested_action": "limit must be between 1 and 100"
}
}

利用を止められた利用者​

管理者に利用を止められた利用者のトークンで呼ぶと、401 Unauthorized が返ります。error.code は account_suspended です。

次の API は、利用を止められたかどうかを見ません: GET /v1/organizations・GET /v1/job-types・GET /v1/personas・GET /v1/user・PATCH /v1/user、MCP の list_personas と、進行中のタスクが無いときの cancel_chat。止められた後も、アクセストークンの有効期限までは呼べます。止められた利用者は、アクセストークンを更新できません。

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

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

ステータスerror.code説明
403waf_blockedリクエストが、API の前段にあるセキュリティの検査に止められました。正当なリクエストの場合は、error.reference(無い場合は応答ヘッダーの x-request-id)を添えてお問い合わせください
403 以外の 4xx・5xxupstream_api_errorリクエストが、API の前段の仕組みで拒否されたか、そこでエラーになりました。続く場合は、error.reference(無い場合は応答ヘッダーの x-request-id)を添えてお問い合わせください
フィールド型説明
error.referencestring前段の仕組みで止められたときの参照番号。お問い合わせのときに添えてください。値が無い場合は含まれません
JSON
{
"error": {
"type": "forbidden_error",
"message": "The request was blocked by a web application firewall before it reached the API.",
"code": "waf_blocked",
"suggested_action": "The request matched a firewall rule in front of the API. If the request is legitimate, contact support with the reference.",
"reference": "20261018T012345Z-0123456789abcdef"
}
}