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

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

ベース URL

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

SaaS

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

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

認証

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

Authorization: Bearer <access_token>

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

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

ページネーション

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

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

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

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

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

リクエストの扱い

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

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

チャット

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

リクエストボディ

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

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

SaaS

agentLevel	string	"default" または "high_performance"。省略時は "default"。
agentMode	boolean	エージェントモードの有効/無効。省略時は true。
privateMode	boolean	プライベートモードの有効/無効。省略時は false。
reportMode	string	"with"（省略時）または "without"。完了時に作業報告書を生成するかを制御します。
personaKey	string	エージェントの応答人格（ペルソナ）を指定。`GET /v1/personas` が返す personaKey を指定します。省略時はペルソナを適用しません。
playbookId	string	実行手順（プレイブック）を指定。`GET /v1/playbooks` が返す playbookId を指定します。省略時はプレイブックを適用しません。存在しない・無効化されている ID を指定した場合は 400 を返します。
skillIds	array	エージェントに読み込ませるスキルの ID 配列（最大 10 件）。`GET /v1/skills` が返す skillId を指定します。11 件以上を指定した場合は 400 を返します。存在しない ID や利用できない ID は無視され、残りのスキルで実行されます。
outputFormat	string	応答テキストの形式。"plain"（省略時）は Markdown 記法を除去したプレーンテキスト（図は削除され、コードブロックは本文が残る）。"markdown" は Markdown 記法をそのまま保持する。

Message オブジェクト

パラメータ	型	必須	説明
role	string	必須	"user" を指定。"assistant" / "system" は受理されますが、現状のエージェント実行では "user" のみが対話の起点として使用されます
content	string | 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-Type	text/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"）
415	ボディの Content-Type が application/json ではない（code: "unsupported_media_type"）
403	chat:exec スコープが不足
404	指定した input_file の fileId または filepath が見つからない
409	指定した会話が現在処理中

GET/v1/chat/completions/:conversationId

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

パスパラメータ

パラメータ	型	必須	説明
conversationId	string	必須	再接続する会話の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 が含まれます。再接続の詳細な手順についてはストリーミングガイドを参照してください。

エラーレスポンス

ステータス	説明
400	conversationId が不正
403	chat:exec スコープが不足
404	会話が見つからない、または進行中でない

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

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

パスパラメータ

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

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

パラメータ	型	必須	説明
messageId	string	—	キャンセル対象のメッセージ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）

フィールド	型	説明
conversationId	string	キャンセルされた会話のID（UUID）
cancelled	boolean	キャンセル成功時は常に true

レスポンス例

JSON

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

エラーレスポンス

ステータス	説明
400	conversationId が不正、messageId が文字列ではない、ボディが壊れた JSON または JSON のオブジェクトではない（code: "invalid_body"）、または会話がアーカイブ済み（code: "conversation_archived"）
415	ボディの Content-Type が application/json ではない（code: "unsupported_media_type"）
403	chat:exec スコープが不足
404	会話が見つからない

会話管理

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

エンドポイント一覧

メソッド	エンドポイント	説明	スコープ (SaaS)
GET	/v1/conversations	会話一覧を取得	chat:history
GET	/v1/conversations/:conversationId/messages	メッセージ履歴を取得	chat:history
GET	/v1/conversations/:conversationId/ui-resources/:toolCallId	UI リソースの 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

※ 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

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

クエリパラメータ

パラメータ	型	デフォルト	説明
limit	integer	50	取得件数（1〜100）
cursor	string	—	次ページ取得用カーソル（前回レスポンスの cursor 値）
order	string	"desc"	"asc" または "desc"
title	string	—	タイトルで絞り込み
mode	string	"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）

フィールド	型	説明
conversations	array	会話オブジェクトの配列
conversations[].conversationId	string	会話の一意識別子（UUID）
conversations[].title	string	会話のタイトル
conversations[].createdAt	string	作成日時（ISO 8601）
conversations[].updatedAt	string	最終更新日時（ISO 8601）
conversations[].archived	boolean?	アーカイブ済みかどうか。mode=archive で取得した場合は常に true。mode=active でこのフィールドが true で返るのは、archive 状態のまま active 一覧から取得された場合のみで、通常は省略されます
hasMore	boolean	次のページが存在するかどうか
cursor	string	次ページ取得用カーソル。hasMore が true の場合のみ含まれます

レスポンス例

JSON

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

エラーレスポンス

ステータス	説明
400	limit パラメータが不正（1〜100の範囲外）、mode が "active" / "archive" 以外、order が "asc" / "desc" 以外、または title が文字列ではない（複数回指定した場合など）
403	chat:history スコープが不足

GET/v1/conversations/:conversationId/messages

指定した会話のメッセージ履歴を取得します。カーソルベースのページネーションに対応しています。

パスパラメータ

パラメータ	型	必須	説明
conversationId	string	必須	会話のID（UUID）

クエリパラメータ

パラメータ	型	デフォルト	説明
limit	integer	50	1 ページの取得件数（1-100）
cursor	string	—	次ページ取得用カーソル（前回レスポンスの cursor 値）
order	string	"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）

フィールド	型	説明
messages	array	メッセージオブジェクトの配列
messages[].conversationId	string	会話ID（UUID）
messages[].messageId	string	メッセージの一意識別子
messages[].sender	string	送信者。"User" または "AI"
messages[].text	string	メッセージの本文テキスト
messages[].createdAt	string	作成日時（ISO 8601）
messages[].updatedAt	string	最終更新日時（ISO 8601）
messages[].status	object	メッセージの処理状態
messages[].status.processing	boolean	エージェントが現在処理中かどうか
messages[].status.unfinished	boolean	エージェントの応答が中断されたかどうか
messages[].tasks	array	エージェントが実行したタスクの配列（後述）
messages[].deliverables	array	エージェントが生成した成果物の配列。存在する場合のみ含まれます
messages[].deliverables[].filename	string	成果物のファイル名
messages[].deliverables[].filepath	string	成果物のファイルパス
messages[].deliverables[].source	string	"agent"（エージェント生成）または "user"（ユーザーアップロード）
messages[].deliverables[].isPrimary	boolean	主要成果物かどうか
messages[].deliverables[].createdAt	string	作成日時（ISO 8601形式）
messages[].deliverables[].mimeType	string?	MIME タイプ（例: "application/pdf"、"text/markdown"）。判定できない場合は省略
messages[].deliverables[].size	number?	ファイルサイズ（バイト）。0 以下の場合は省略
messages[].files	array?	ユーザーが添付したファイルの配列。sender: "User" のメッセージで添付がある場合のみ含まれます
messages[].files[].fileId	string	ファイルの一意識別子（UUID）
messages[].files[].mimeType	string	MIME タイプ（例: "image/png"、"application/pdf"）
messages[].files[].width	number?	画像の幅（ピクセル）。画像ファイルの場合のみ
messages[].files[].height	number?	画像の高さ（ピクセル）。画像ファイルの場合のみ
messages[].archived	boolean?	archive 経由で取得されたメッセージのみ true。GET /v1/conversations?mode=archive で取得した会話のメッセージ履歴を参照した場合に付与されます
hasMore	boolean	次のページが存在するかどうか
cursor	string	次ページ取得用カーソル。hasMore が true の場合のみ含まれます

Task オブジェクト

フィールド	型	説明
messageId	string	タスクが属するメッセージのID
conversationId	string	タスクが属する会話のID
callId	string?	ツール呼び出しID。Complex Path では複数のタスクが同じ callId を共有し、同一ツール呼び出しのステップ列を識別するために利用される
actionType	string	タスクの種類（例: ツール実行、コード生成）
title	string?	タスクのタイトル。存在しない場合は省略される
description	string?	タスクの説明。存在しない場合は省略される
status	string	タスクの状態。値は "in_progress" / "completed" / "failed" / "error" / "pending" のいずれか
content	string?	タスクの実行結果テキスト。存在しない場合は省略される
metadata	object?	actionType ごとに異なる補助情報（sub_event_type、url、filepath など）。詳細は ストリーミングガイド を参照
files	array?	タスクに関連するファイル（filename / size / filepath / mimeType? の構造。MIME タイプ判定不能時は mimeType を省略）。タスクに関連ファイルがない場合は配列自体が省略される
timestamp	number	タスク実行時のタイムスタンプ（Unix ミリ秒）
createdAt	string	作成日時（ISO 8601）
updatedAt	string	更新日時（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 の有無とは独立に含まれることがあります

判別方法が 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
}

エラーレスポンス

ステータス	説明
400	conversationId が不正なフォーマット
400	limit が 1-100 の整数でない
400	cursor が不正（前回レスポンスの値以外）
400	order が "asc" / "desc" 以外
403	chat:history スコープが不足
404	会話が見つからない

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 だけを利用しているクライアントは別途いずれかのスコープが必要です。

パスパラメータ

パラメータ	型	必須	説明
conversationId	string	必須	会話のID（UUID）
toolCallId	string	必須	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）

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

JSON

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

エラーレスポンス

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

ステータス	code	説明	リトライ
400	invalid_conversation_id	conversationId の形式が不正（UUID ではない）	不可
400	invalid_parameter	toolCallId の形式が不正	不可
403	insufficient_scope	chat:exec / a2a:all / mcp:all のいずれも持っていない	不可
404	not_found	該当する UI リソースが存在しない	不可
404	conversation_not_found	会話が存在しない、または他のユーザーの会話	不可
404	file_too_large	HTML の実体が 512KB を超えており返却できない	不可（永続的な失敗）
502	upstream_api_error	一時的な取得失敗	可
500	internal_error	その他のエラー	可

描画時の注意

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

PATCH/v1/conversations/:conversationId

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

パスパラメータ

パラメータ	型	必須	説明
conversationId	string	必須	会話のID（UUID）

リクエストボディ

パラメータ	型	必須	説明
title	string	必須	新しい会話タイトル（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）

フィールド	型	説明
conversationId	string	会話ID（UUID）
title	string	更新後のタイトル
createdAt	string	会話の作成日時（ISO 8601）
updatedAt	string	会話の更新日時（ISO 8601）

レスポンス例

JSON

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

エラーレスポンス

ステータス	説明
400	title が未指定、空文字、もしくは 200 文字を超える、ボディが壊れた JSON（code: "invalid_body"）、または会話がアーカイブ済み（code: "conversation_archived"）
415	ボディの Content-Type が application/json ではない（code: "unsupported_media_type"）
403	chat:history スコープが不足
404	会話が見つからない

DELETE/v1/conversations/:conversationId

会話を削除します。

パスパラメータ

パラメータ	型	必須	説明
conversationId	string	必須	会話の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）

フィールド	型	説明
conversationId	string	削除された会話のID（UUID）
deleted	boolean	削除成功時は常に true

レスポンス例

JSON

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

エラーレスポンス

ステータス	説明
400	conversationId が不正、または会話がアーカイブ済み（code: "conversation_archived"、復元には POST /v1/conversations/:id/restore を使用）
403	chat:history スコープが不足
404	会話が見つからない
409	会話が現在処理中のため削除できない

POST/v1/conversations/:conversationId/restore

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

パスパラメータ

パラメータ	型	必須	説明
conversationId	string	必須	アーカイブ済み会話の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）

フィールド	型	説明
conversationId	string	復元された会話のID（UUID）
restored	boolean	復元成功時は常に true

レスポンス例

JSON

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

エラーレスポンス

ステータス	説明
400	conversationId が不正
403	chat:history スコープが不足
404	アーカイブに該当会話が存在しない、または既に active（archive 状態と区別されません）

ファイル管理

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

エンドポイント一覧

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

※ Marketplace 版はスコープ不要（認証のみ）。

POST/v1/files

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

リクエストボディ（multipart/form-data）

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

リクエスト例

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）

フィールド	型	説明
fileId	string	ファイルの一意識別子（UUID）
filename	string	ファイル名
bytes	integer	ファイルサイズ（バイト）
createdAt	string	作成日時（ISO 8601）
width	integer	画像の幅（ピクセル）。画像ファイルの場合のみ
height	integer	画像の高さ（ピクセル）。画像ファイルの場合のみ

レスポンス例

JSON

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

エラーレスポンス

ステータス	説明
400	file または filename パラメータが未指定、ファイルサイズが 512 MB を超過、またはアップロードされた画像ファイルが破損している/不正
415	ボディが multipart/form-data ではない（code: "unsupported_media_type"）
403	chat:file スコープが不足

GET/v1/files

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

クエリパラメータ

パラメータ	型	デフォルト	説明
limit	integer	50	1 ページの取得件数（1-100）
cursor	string	—	次ページ取得用カーソル（前回レスポンスの cursor 値）
order	string	"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）

フィールド	型	説明
files	array	ファイルオブジェクトの配列
files[].fileId	string	ファイルの一意識別子（UUID）
files[].filename	string	ファイル名
files[].bytes	integer	ファイルサイズ（バイト）
files[].createdAt	string	作成日時（ISO 8601）
files[].width	integer	画像の幅（ピクセル）。画像ファイルの場合のみ
files[].height	integer	画像の高さ（ピクセル）。画像ファイルの場合のみ
hasMore	boolean	次のページが存在するかどうか
cursor	string	次ページ取得用カーソル。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 を変更しないでください。条件を変えると対象範囲が変わり、項目の重複や取りこぼしが起きます。

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

エラーレスポンス

ステータス	説明
400	limit が 1-100 の整数でない
400	cursor が不正（前回レスポンスの値以外）
400	order が "asc" / "desc" 以外
403	chat:file スコープが不足

GET/v1/files/:file_id/content

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

パスパラメータ

パラメータ	型	必須	説明
file_id	string	必須	ファイル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-Disposition	attachment; filename="ファイル名"

エラーレスポンス

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

DELETE/v1/files/:file_id

ファイルを削除します。

パスパラメータ

パラメータ	型	必須	説明
file_id	string	必須	ファイル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）

フィールド	型	説明
fileId	string	削除されたファイルのID（UUID）
deleted	boolean	削除成功時は常に true

レスポンス例

JSON

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

エラーレスポンス

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

成果物取得

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

エンドポイント一覧

メソッド	エンドポイント	説明	スコープ (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 のツール応答で得た成果物も、その経路のスコープのままこのエンドポイントで取得できます。

クエリパラメータ

パラメータ	型	必須	説明
path	string	必須	成果物のファイルパス（メッセージ履歴の deliverables[].filepath で取得）

リクエスト例

Get artifact file

1curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/files/proxy?path=/path/to/artifact.xlsx" \
2-H "Authorization: Bearer <access_token>" \
3-o artifact.xlsx

レスポンス（200 OK）

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

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

エラーレスポンス

ステータス	説明
400	path パラメータが未指定またはフォーマット不正
403	chat:exec / a2a:all / mcp:all のいずれも持っていない
404	ファイルが見つからない

ライブラリ

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

エンドポイント一覧

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

GET/v1/library

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

クエリパラメータ

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

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

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

レスポンス例

JSON

{
  "files": [
    {
      "filename": "report.xlsx",
      "filepath": "/path/to/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
}

エラーレスポンス

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

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

Agent・Playbook・Skill を読む・作る・変える・消す・コピーする API に共通の決まりです。

• スコープ: 読むは assets:read、作る・変える・コピーするは assets:write、消すは assets:delete です。スキル・プレイブックの一覧は chat:exec でも呼べます。
• システム連携のトークンでは呼べません。呼ぶと 403 Forbidden（forbidden）が返ります。
• 読めるもの: 自分のものと、公開されているものです。ほかの利用者の非公開のもの・存在しないものは 404 Not Found（agent_not_found・playbook_not_found・skill_not_found）です。
• 変える・消す: 自分のものだけです（システム管理者は、ほかの利用者が公開したプレイブック・スキルも消せます）。ほかの利用者のものは 404 Not Found です。ほかの利用者のものを直したいときは、自分のものにコピーしてから直します。消すときは、ほかの利用者が公開したプレイブック・スキルでも、使っている Agent があれば先に 409 Conflict が返ることがあります。プレイブックは、使っているスケジュールがあるときも同じです（各 API の説明を参照）。
• 変える: 取得の digest を baseDigest に入れて送ります。取得した後にほかの変更が入っていると 409 Conflict（stale_base）が返ります。取得し直してから送り直してください。
• 作る・コピー: 送り直すと、もう 1 つ作られます（マーケットプレイス版の登録 Agent のコピーは除きます。Agent のコピーの説明を参照）。応答が届かなかったときは、一覧の ID と createdAt で作られたかを確かめてから送り直してください。
• ボディの上限: JSON のボディは 3 MiB までです。超えると 413 Payload Too Large（body_too_large）が返ります。スキルのファイルを送る API の上限は、その API の説明を参照してください。
• Agent の API は、SSO でログインしていない利用者のトークンでは 403 Forbidden（sso_required）が返ります。

Agent

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

エンドポイント一覧

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

GET/v1/agents

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

クエリパラメータ

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

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

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

エラーレスポンス

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

GET/v1/agents/shared

公開されている Agent の一覧を取得します（自分が公開したものも含みます）。クエリパラメータ・レスポンス・エラーは、自分の Agent の一覧と同じです。

GET/v1/agents/:agentId

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

パスパラメータ

パラメータ	型	必須	説明
agentId	string	必須	Agent の ID（UUID）

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

フィールド	型	説明
agentId	string	Agent の ID（UUID）
name	string | null	名前
description	string | null	説明
ownerUserId	string | null	持ち主の利用者 ID
isShared	boolean | null	公開しているかどうか
runtimeKind	string | null	実行環境の種類。"autonomous"、またはマーケットプレイス版の登録 Agent は "marketplace"
marketplaceAgentId	string | null	マーケットプレイス版の登録 Agent の ID。それ以外は null
spec	object	Agent の定義
spec.goal	string | null	ゴール（指示）
spec.guardrail	string | null	ガードレール
spec.skills	array	使うスキル
spec.skills[].skillId	string | null	スキル ID
spec.skills[].name	string | null	スキル名
spec.skills[].versionId	string | null	固定したスキルの版の ID。固定していない場合は null で、いつもその時点の版を使います
spec.playbookId	string | null	使うプレイブックの ID
spec.inputFiles	array	入力ファイル
spec.inputFiles[].type	string | null	入力ファイルの種類。ライブラリのファイルは "blob"。定期実行から作った Agent では "git"・"upload" が入っていることがあります
spec.inputFiles[].filepath	string | null	ファイルのパス。"blob" は GET /v1/library の filepath と同じ形。"git"・"upload" は保存された参照の先頭に / を付けた値で、ライブラリのパスではありません
spec.inputFiles[].filename	string | null	ファイル名
spec.agentLevel	string | null	"default" または "high_performance"
spec.orgId	string | null	実行のときに使う組織のコード
spec.jobRole	string | null	実行のときに使う職種のコード
spec.agentConfig	object | null	今は使っていない項目です（値が入っていても使われません）
spec.exposureConsent	object | null	今は使っていない項目です（値が入っていても使われません）
projectCount	number | null	この Agent を配置しているプロジェクトの数（消したプロジェクトの配置も数えます）
copyCount	number | null	コピーされた回数
createdAt	string | null	作成日時（ISO 8601）
updatedAt	string | null	最終更新日時（ISO 8601）
digest	string	Agent を変えるときに baseDigest に送る値。名前・説明・公開・定義から作られ、配置しているプロジェクトの数・コピー数・日時では変わりません

レスポンス例

JSON

{
  "agentId": "17be0242-a5d0-4db7-92e5-f97a05abae2b",
  "name": "受注データの取り込み",
  "description": "受注メールから受注データを作る",
  "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "isShared": false,
  "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": "6f1c2a9e0b7d…"
}

エラーレスポンス

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

POST/v1/agents

Agent を作ります。

リクエストボディ

フィールド	型	必須	説明
name	string	必須	名前（255 文字まで。空にはできません）
description	string	—	説明（5000 文字まで）
isShared	boolean	—	公開するかどうか。省くと非公開
spec	object	必須	Agent の定義
spec.goal	string	必須	ゴール（指示）。5000 文字まで。空白だけにはできません
spec.guardrail	string	—	ガードレール。5000 文字まで
spec.skills	array	—	使うスキル。[{ skillId, versionId? }] の形で、自分のスキルか公開されているスキル（有効なもの）を 10 個まで。versionId を付けるとその版に固定し、省くか null にするといつもその時点の版を使います。取得の spec.skills をそのまま送れます（name は無視します）。同じスキルを重ねて指定できません
spec.playbookId	string	—	使うプレイブックの ID。自分のプレイブックだけ
spec.inputFiles	array	—	入力ファイル。[{ type, filepath, filename? }] の形で 10 個まで。type は "blob"（自分のライブラリのファイル。filepath は GET /v1/library の filepath）です。定期実行から作った Agent では "git"・"upload" が入っていることがあり、取得した値をそのまま送れます。filepath は先頭の / を除いて空にはできません。filename は 255 文字までの文字列か null です。実行のときに渡るのは、プロジェクトを作った利用者のファイルだけです
spec.agentLevel	string	—	"default" または "high_performance"
spec.orgId	string	—	実行のときに使う組織のコード（255 文字まで）
spec.jobRole	string	—	実行のときに使う職種のコード（255 文字まで）

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

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

レスポンス（201 Created）

Agent の取得と同じ形で、作った Agent を返します。

エラーレスポンス

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

PATCH/v1/agents/:agentId

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

パスパラメータ

パラメータ	型	必須	説明
agentId	string	必須	Agent の ID（UUID）

リクエストボディ

フィールド	型	必須	説明
baseDigest	string	必須	Agent の取得の digest
name	string	—	名前（255 文字まで。空にはできません）
description	string	—	説明（5000 文字まで。空の文字列・空白だけ・null にはできません）
isShared	boolean	—	公開するかどうか
spec	object	—	Agent の定義。送った項目だけを今の定義に重ねます（skills・inputFiles は配列ごと置き換わります）。項目は Agent を作るときと同じです。項目に null を送ると、その項目を外します（skills・inputFiles は空になります）。goal は外せません

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

spec を変えるときは、送っていない項目も含めて、定義が指すプレイブック・スキル・入力ファイルを確かめます。公開されている Agent をコピーした Agent は、元の利用者のプレイブック・スキル・入力ファイルを指したままなので、自分のもの（スキルは公開されているものでもかまいません）に変えないと 400 が返ります。

レスポンス（200 OK）

Agent の取得と同じ形で、変えた後の Agent（新しい digest）を返します。

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	agentId が UUID の形式ではない、baseDigest が無い・空・文字列ではない、変える項目が無い、name・description・isShared の型や長さの誤り、name が空白だけ、description を空の文字列・空白だけ・null にした、spec がオブジェクトではない、spec.playbookId が UUID の形式ではない、spec.skills の形の誤り（同じスキルを重ねた など）、または spec.skillIds・spec.skillVersions を送った
400	invalid_spec	spec.goal を null・空白だけにした、spec の文字列の項目の型や長さの誤り、spec.agentLevel が選べる値ではない、spec.inputFiles の形の誤り（type が "blob"・"git"・"upload" 以外、filepath が空、filename が 255 文字を超える など）、またはスキル・入力ファイルが 10 個を超える
400	playbook_not_found	定義のプレイブックが自分のプレイブックではない
400	skill_not_found	定義のスキルが、自分のスキルでも公開されている有効なスキルでもない
400	version_not_found	定義のスキルの versionId が、そのスキルの版ではない（版が 100 以上あるスキルでは invalid_spec が返ります）
400	file_not_found	定義の入力ファイル（type が "blob" のもの）が、自分のライブラリにない
400	runtime_not_allowed	マーケットプレイス版の登録 Agent は変えられない
400	invalid_body	ボディが壊れた JSON、または JSON のオブジェクトではない
403	insufficient_scope	assets:write スコープが不足
403	forbidden	システム連携のトークンで呼び出した
403	sso_required	SSO でログインしていない利用者
404	agent_not_found	Agent が存在しない、またはほかの利用者の Agent
409	stale_base	取得した後に Agent が変わっている
413	body_too_large	ボディが 3 MiB を超える
415	unsupported_media_type	ボディの Content-Type が application/json ではない

DELETE/v1/agents/:agentId

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

パスパラメータ

パラメータ	型	必須	説明
agentId	string	必須	Agent の ID（UUID）

クエリパラメータ

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

レスポンス（200 OK）

JSON

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

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	agentId が UUID の形式ではない、または force が "true" / "false" 以外
403	insufficient_scope	assets:delete スコープが不足
403	forbidden	システム連携のトークンで呼び出した
403	sso_required	SSO でログインしていない利用者
404	agent_not_found	Agent が存在しない、またはほかの利用者の Agent
409	agent_in_use	Agent を配置しているプロジェクトがある（消したプロジェクトの配置も含みます。force=true で消せます。配置しているプロジェクトの数は取得の projectCount で読めます）
409	agent_running	この Agent の巡回が実行中

POST/v1/agents/:agentId/copy

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

定義はそのまま写ります。定義が指すプレイブック・スキル・入力ファイルは、元の利用者のものを指したままです。自分のものに変えるには、コピーした Agent を変えてください。マーケットプレイス版の登録 Agent では、同じ登録 Agent の自分の Agent が既にあれば、新しく作らずにそれを返します。

パスパラメータ

パラメータ	型	必須	説明
agentId	string	必須	コピーする Agent の ID（UUID）

レスポンス（201 Created）

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

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	agentId が UUID の形式ではない
403	insufficient_scope	assets:write スコープが不足
403	forbidden	システム連携のトークンで呼び出した
403	sso_required	SSO でログインしていない利用者
404	agent_not_found	Agent が存在しない、またはほかの利用者の非公開の Agent
409	already_owned	自分の 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_only	boolean	true	false を指定すると無効化したスキルも含めます。"true" / "false" 以外は 400
limit	integer	50	1 ページの取得件数（1-100）
cursor	string	—	次ページ取得用カーソル（前回レスポンスの cursor 値）

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

フィールド	型	説明
skills	array	スキルオブジェクトの配列
skills[].skillId	string	スキル ID（Chat の skillIds に指定します）
skills[].ownerUserId	string | null	持ち主の利用者 ID
skills[].name	string	スキル名
skills[].description	string?	スキルの説明
skills[].category	string?	カテゴリ
skills[].tags	array	タグの配列（同じタグは 1 つにして返します）。未設定の場合は空配列
skills[].isShared	boolean	スキルを公開しているかどうか
skills[].isActive	boolean	有効かどうか
skills[].createdAt	string	作成日時（ISO 8601）
skills[].updatedAt	string	最終更新日時（ISO 8601）
hasMore	boolean	次のページが存在するかどうか
cursor	string	次ページ取得用カーソル。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,
      "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 を変更しないでください。条件を変えると対象範囲が変わり、項目の重複や取りこぼしが起きます。

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

エラーレスポンス

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

GET/v1/skills/shared

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

クエリパラメータ

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

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

公開スキルは常に有効なため、isShared / isActive フィールドは含まれません。

フィールド	型	説明
skills	array	スキルオブジェクトの配列
skills[].skillId	string	スキル ID（Chat の skillIds に指定します）
skills[].ownerUserId	string | null	持ち主の利用者 ID
skills[].name	string	スキル名
skills[].description	string?	スキルの説明
skills[].category	string?	カテゴリ
skills[].tags	array	タグの配列（同じタグは 1 つにして返します）。未設定の場合は空配列
skills[].createdAt	string	作成日時（ISO 8601）
skills[].updatedAt	string	最終更新日時（ISO 8601）
hasMore	boolean	次のページが存在するかどうか
cursor	string	次ページ取得用カーソル。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
}

エラーレスポンス

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

GET/v1/skills/:skillId

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

パスパラメータ

パラメータ	型	必須	説明
skillId	string	必須	スキル ID（UUID）

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

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

フィールド	型	説明
currentVersionId	string | null	今の版の ID。版の記録が始まる前に作られ、その後ファイルを変えていないスキルは null
digest	string	スキルの設定を変えるときに 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,
  "createdAt": "2026-08-01T03:12:45.123Z",
  "updatedAt": "2026-08-05T09:00:00.000Z",
  "currentVersionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80",
  "digest": "9d2e41c7a0b3…"
}

エラーレスポンス

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

GET/v1/skills/:skillId/versions

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

パスパラメータ

パラメータ	型	必須	説明
skillId	string	必須	スキル ID（UUID）

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

フィールド	型	説明
skillId	string	スキル ID
currentVersionId	string | null	今の版の ID
versions	array	版の配列（新しい順）
versions[].versionId	string | null	版の ID
versions[].versionNo	number	版の番号（1 から）
versions[].parentVersionId	string | null	元にした版の ID
versions[].source	string	版のでき方。"upload"（ファイルを送って作った・入れ替えた）、"edit"（文書を書き換えた）、"copy"（コピーで作った）、"baseline"（版の記録が始まる前からの内容）
versions[].contentDigest	string | null	版のファイルの中身から作った値。同じ中身の版は同じ値になります
versions[].createdAt	string	版ができた日時（ISO 8601）
versions[].isCurrent	boolean	今の版かどうか
hasMore	boolean	いつも 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": "78a4ea5aade3…",
      "createdAt": "2026-08-05T09:00:00.000Z",
      "isCurrent": true
    },
    {
      "versionId": "e2c4a6b8-1d3f-4a5c-9e7b-0f2d4c6a8e1b",
      "versionNo": 1,
      "parentVersionId": null,
      "source": "upload",
      "contentDigest": "3cd01ce0220c…",
      "createdAt": "2026-08-01T03:12:45.123Z",
      "isCurrent": false
    }
  ],
  "hasMore": false
}

エラーレスポンス

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

GET/v1/skills/:skillId/files

スキルの版のファイルの一覧を取得します。ファイルの中身は返しません（1 ファイルの取得で読みます）。

パスパラメータ

パラメータ	型	必須	説明
skillId	string	必須	スキル ID（UUID）

クエリパラメータ

パラメータ	型	デフォルト	説明
versionId	string	今の版	読む版の ID（UUID）

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

フィールド	型	説明
skillId	string	スキル ID
versionId	string | null	版の ID
isCurrent	boolean	今の版かどうか
digest	string	スキルのファイルを丸ごと入れ替える・スキルの文書を書き換えるときに baseDigest に送る値（今の版の値を送ります）
editable	boolean	文書を書き換えられるかどうか。自分のスキルで、スクリプトや実行ファイル（.exe・.bin・.so・.dylib・.dll）を含まないときに true
files	array	ファイルの配列（パスの順）
files[].path	string	スキルの中のパス（例: scripts/run.py）
files[].kind	string	ファイルの種類（拡張子で決まります）。"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[].size	number	大きさ（バイト）
files[].editable	boolean	文書を書き換えるで中身を変えられる形式かどうか（文書で、バイナリでないときに true）

レスポンス例

JSON

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

エラーレスポンス

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

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

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

前の版で中身を読めるのは文書（kind が "document" で、バイナリでないもの）だけです。前の版のほかのファイルは 400（version_not_readable）になります。前の版のすべてのファイルを読むには、スキルのコピー（POST /v1/skills/:skillId/copy）で versionId を指定してコピーし、コピーしたスキルをダウンロード（GET /v1/skills/:skillId/download）してください。

パスパラメータ

パラメータ	型	必須	説明
skillId	string	必須	スキル ID（UUID）

クエリパラメータ

パラメータ	型	デフォルト	説明
path	string	—	必須。ファイルのパス（ファイルの一覧の files[].path。例: scripts/run.py）
versionId	string	今の版	読む版の ID（UUID）

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

フィールド	型	説明
skillId	string	スキル ID
versionId	string | null	版の ID
path	string	ファイルのパス
kind	string	ファイルの種類（ファイルの一覧の files[].kind と同じ）
size	number	大きさ（バイト）
encoding	string	中身の表し方。文字のファイルは "utf-8"、バイナリ（中身に NUL を含むもの）は "base64"
content	string	ファイルの中身（全文）

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	skillId または versionId が UUID の形式ではない、または path が無い
400	file_not_found	path のファイルが、その版に無い
400	version_not_found	versionId が、そのスキルの版ではない
400	version_not_readable	前の版の、文書でないファイルまたはバイナリの文書を指定した
403	insufficient_scope	assets:read スコープが不足
403	forbidden	システム連携のトークンで呼び出した
404	skill_not_found	スキルが存在しない、またはほかの利用者の非公開のスキル

GET/v1/skills/:skillId/download

スキルの今の版のすべてのファイル（設定値のファイル・画像なども）を、zip で取得します。版は指定できません。

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

パスパラメータ

パラメータ	型	必須	説明
skillId	string	必須	スキル ID（UUID）

エラーレスポンス

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

POST/v1/skills

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

リクエストボディ（multipart/form-data）

フィールド	型	必須	説明
files	file	必須	スキルのファイル。zip 1 つ、または SKILL.md を含むファイル群を送ります。ファイル群は 1 項目に 1 ファイルで、ファイル名をスキルの中のパス（例: scripts/run.py）にします。拡張子が .md のファイル 1 つだけを送ると、SKILL.md として保存します
category	string	—	カテゴリ（前後の空白を除いて 40 文字まで）
tags	string	—	タグ。1 項目に 1 つで、項目を繰り返して送ります（前後の空白と先頭の # を除いて 1〜24 文字のものを 10 個まで）。小文字にし、先頭の # を除いて保存します。そうして同じになるタグは送れません
isShared	string	—	公開するかどうか（"true" または "false"）。省くと非公開
isActive	string	—	有効かどうか（"true" または "false"）。省くと有効。公開するスキルは有効にしてください

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

• ルートに 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 未満にしてください。
• 中身は安全の検査を通します。

レスポンス（201 Created）

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

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	files が無い、同じパスのファイルを 2 つ送った、files 以外の項目でファイルを送った、フォームの項目が多すぎる・長すぎる、または category・tags・isShared・isActive の誤り
400	file_count	ファイルが 0 個（空の zip など）、または 50 個を超える
400	file_too_large	1 ファイルが 2 MiB を超える
400	total_too_large	展開した後の合計が 5 MiB を超える
400	zip_invalid	zip を展開できない
400	bad_path	ファイルのパスが不正（.. を含む など）
400	skill_md_missing	ルートに SKILL.md が無い
400	frontmatter_missing	SKILL.md の先頭に YAML（--- で囲んだ部分）が無い
400	name_missing	SKILL.md の YAML に name が無い
400	name_too_long	SKILL.md の name が 100 文字を超える
400	shared_requires_active	無効のまま公開しようとした
400	guardrail_blocked	中身が安全の検査で止められた
403	insufficient_scope	assets:write スコープが不足
403	forbidden	システム連携のトークンで呼び出した
413	body_too_large	送ったファイルの大きさの合計が上限を超える
415	unsupported_media_type	Content-Type が multipart/form-data ではない
502	blob_write_failed	ファイルを保存できなかった（送り直してください）
503	guardrail_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）が返ります。ファイルの一覧を取得し直して、変わったかを確かめてください。

パスパラメータ

パラメータ	型	必須	説明
skillId	string	必須	スキル ID（UUID）

リクエストボディ（multipart/form-data）

フィールド	型	必須	説明
baseDigest	string	必須	ファイルの一覧（今の版）の digest
files	file	必須	スキルのファイル。送り方と決まりはスキルを作るときと同じです

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

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

レスポンス（200 OK）

自分のスキルの取得と同じ形で、入れ替えた後のスキル（新しい currentVersionId）を返します。新しい版のファイルの一覧の digest は、ファイルの一覧で取得してください。

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	skillId が UUID の形式ではない、baseDigest が無い・空・文字列ではない、files が無い、同じパスのファイルを 2 つ送った、または files 以外の項目でファイルを送った
400	file_count	ファイルが 0 個（空の zip など）、または 50 個を超える
400	file_too_large	1 ファイルが 2 MiB を超える
400	total_too_large	展開した後の合計が 5 MiB を超える
400	zip_invalid	zip を展開できない
400	bad_path	ファイルのパスが不正（.. を含む など）
400	skill_md_missing	ルートに SKILL.md が無い
400	frontmatter_missing	SKILL.md の先頭に YAML（--- で囲んだ部分）が無い
400	name_missing	SKILL.md の YAML に name が無い
400	name_too_long	SKILL.md の name が 100 文字を超える
400	guardrail_blocked	中身が安全の検査で止められた
403	insufficient_scope	assets:write スコープが不足
403	forbidden	システム連携のトークンで呼び出した
404	skill_not_found	スキルが存在しない、またはほかの利用者のスキル
409	stale_base	ファイルの一覧を取得した後に、スキルのファイルが変わっている
413	body_too_large	送ったファイルの大きさの合計が上限を超える
415	unsupported_media_type	Content-Type が multipart/form-data ではない
502	blob_write_failed	ファイルを保存できなかった
503	guardrail_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 とスケジュールは、新しい版を使うようになります（版を固定したものは変わりません）。

パスパラメータ

パラメータ	型	必須	説明
skillId	string	必須	スキル ID（UUID）

リクエストヘッダー

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

リクエストボディ

フィールド	型	必須	説明
baseDigest	string	必須	ファイルの一覧（今の版）の digest
changes	array	必須	変える文書（1〜50 件。同じパスは 1 回だけ）
changes[].path	string	必須	文書のパス（例: SKILL.md、templates/notes.md）。無いパスを指定すると文書を足します
changes[].content	string	—	文書の新しい中身（全文）。消すときは省きます
changes[].deleted	boolean	—	true で文書を消します（true または false。ほかの値は送れません）

JSON

{
  "baseDigest": "WyI1YjFkN2UyYS04YzRm…",
  "changes": [
    { "path": "SKILL.md", "content": "---\nname: release-notes\ndescription: リリースノートを生成する\n---\n\n# 手順\n..." },
    { "path": "templates/old.md", "deleted": true }
  ]
}

レスポンス（201 Created）

フィールド	型	説明
skill	object	書き換えた後のスキル（自分のスキルの取得と同じ形）
version	object	できた版（版の一覧の versions[] の 1 件と同じ形）

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

エラーレスポンス

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

PATCH/v1/skills/:skillId

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

パスパラメータ

パラメータ	型	必須	説明
skillId	string	必須	スキル ID（UUID）

リクエストボディ

フィールド	型	必須	説明
baseDigest	string	必須	スキルの取得の digest
isShared	boolean	—	公開するかどうか
isActive	boolean	—	有効かどうか
category	string | null	—	カテゴリ（前後の空白を除いて 40 文字まで）。null か空の文字列で空にします
tags	array	—	タグ（前後の空白と先頭の # を除いて 1〜24 文字の文字列を 10 個まで）。空にするときは []。小文字にし、先頭の # を除いて保存します。そうして同じになるタグは送れません

baseDigest のほかに、少なくとも 1 つの項目を送ってください。変えた後に「公開していて無効」になる変更は 400（shared_requires_active）です。

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

レスポンス（200 OK）

自分のスキルの取得と同じ形で、変えた後のスキル（そのときの digest）を返します。

エラーレスポンス

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

DELETE/v1/skills/:skillId

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

パスパラメータ

パラメータ	型	必須	説明
skillId	string	必須	スキル ID（UUID）

クエリパラメータ

パラメータ	型	デフォルト	説明
cascade	string	"false"	"true" を指定すると、このスキルを使っているスケジュールからスキルを外してから、スキルを消します。"true" / "false" 以外は 400
force	string	"false"	"true" を指定すると、このスキルを使っている Agent があっても消します。"true" / "false" 以外は 400

• Agent が使っているとき: このスキルを定義に持つ Agent があると、409 Conflict（skill_in_use。使っている Agent の数は error.message）が返ります。持ち主を問わず数えます。force=true で消せます。消した後も、Agent は消えたスキルを指したままです。この確認は、消してよい利用者かの確認より先に行うため、ほかの利用者の公開スキルでも 409 Conflict が返ることがあります。
• スケジュールが使っているとき: このスキルを使うスケジュールがあると、409 Conflict（skill_referenced。使っているスケジュールの数は error.message）が返ります。すべての利用者のスケジュールを、有効・無効を問わず数えます。プロジェクトに置いた Agent の巡回なども、スケジュールとして数えます。cascade=true で、それらのスケジュールからこのスキルを外してから消します。スケジュールそのものは残ります。
• Agent とスケジュールの両方が使っているときは、cascade=true と force=true の両方が要ります。

レスポンス（200 OK）

JSON

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

エラーレスポンス

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

POST/v1/skills/:skillId/copy

自分のスキルか公開されているスキルを、自分の新しいスキルとしてコピーします。指定した版（省くと今の版）のすべてのファイルを写し、非公開・有効で作ります。名前・説明・カテゴリ・タグは、コピー元の今のものを写します。コピーしたスキルの版は 1 から始まります。

ボディは省けます。版を指定するときは JSON で送ります。

パスパラメータ

パラメータ	型	必須	説明
skillId	string	必須	コピーするスキルの ID（UUID）

リクエストボディ

フィールド	型	必須	説明
versionId	string	—	写す版の ID（UUID）。省くと今の版

レスポンス（201 Created）

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

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	skillId または versionId が UUID の形式ではない
400	version_not_found	versionId が、そのスキルの版ではない
400	invalid_body	ボディが壊れた JSON、または JSON のオブジェクトではない
403	insufficient_scope	assets:write スコープが不足
403	forbidden	システム連携のトークンで呼び出した
404	skill_not_found	スキルが存在しない、またはほかの利用者の非公開のスキル
413	body_too_large	ボディが 3 MiB を超える
415	unsupported_media_type	ボディの Content-Type が application/json ではない
502	blob_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_only	boolean	true	false を指定すると無効化したプレイブックも含めます。"true" / "false" 以外は 400
limit	integer	50	1 ページの取得件数（1-100）
cursor	string	—	次ページ取得用カーソル（前回レスポンスの cursor 値）

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

フィールド	型	説明
playbooks	array	プレイブックオブジェクトの配列
playbooks[].playbookId	string	プレイブック ID（Chat の playbookId に指定します）
playbooks[].ownerUserId	string	持ち主の利用者 ID
playbooks[].name	string	プレイブック名
playbooks[].description	string?	説明
playbooks[].category	string?	カテゴリ
playbooks[].tags	array	タグの配列（前後の空白を除き、空のタグを外し、同じタグは 1 つにして返します）
playbooks[].steps	array	手順の配列
playbooks[].steps[].title	string	手順のタイトル
playbooks[].steps[].description	string?	手順の説明
playbooks[].steps[].guidance	array?	補足指示の配列
playbooks[].steps[].success	string?	完了条件
playbooks[].sourceConversationId	string?	作成元の会話 ID
playbooks[].isShared	boolean	公開しているかどうか
playbooks[].isActive	boolean	有効かどうか
playbooks[].usageCount	number	利用回数
playbooks[].copyCount	number	コピーされた回数
playbooks[].createdAt	string	作成日時（ISO 8601）
playbooks[].updatedAt	string	最終更新日時（ISO 8601）
hasMore	boolean	次のページが存在するかどうか
cursor	string	次ページ取得用カーソル。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,
      "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 を変更しないでください。条件を変えると対象範囲が変わり、項目の重複や取りこぼしが起きます。

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

エラーレスポンス

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

GET/v1/playbooks/shared

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

クエリパラメータ

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

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

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

エラーレスポンス

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

GET/v1/playbooks/:playbookId

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

パスパラメータ

パラメータ	型	必須	説明
playbookId	string	必須	プレイブックの ID（UUID）

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

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

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

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

エラーレスポンス

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

POST/v1/playbooks

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

リクエストボディ

フィールド	型	必須	説明
name	string	必須	名前（100 文字まで。空白だけにはできません）
description	string | null	—	説明（500 文字まで）
category	string | null	—	カテゴリ（50 文字まで）
tags	array	—	タグ（1 つ 30 文字までの文字列を 10 個まで。空・空白だけのタグと、前後の空白を除いて同じになるタグは送れません。大文字小文字は区別します）
steps	array	必須	手順（1〜20 個）
steps[].title	string	必須	手順のタイトル（100 文字まで。空白だけにはできません）
steps[].description	string	—	手順の説明（1000 文字まで）
steps[].guidance	array	—	補足指示（1 つ 500 文字までの文字列を 10 個まで。空・空白だけの文字列は送れません）
steps[].success	string	—	完了条件（500 文字まで）
isShared	boolean	—	公開するかどうか。省くと非公開
isActive	boolean	—	有効かどうか。省くと有効

• 手順の項目は title・description・guidance・success の 4 つです（ほかの項目は保存しません）。手順の文字列の項目に null は送れません。
• 名前・説明・カテゴリは、前後の空白を除いて保存します。説明・カテゴリは、null・空の文字列・空白だけのときは null で保存します。

レスポンス（201 Created）

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

エラーレスポンス

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

PATCH/v1/playbooks/:playbookId

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

パスパラメータ

パラメータ	型	必須	説明
playbookId	string	必須	プレイブックの ID（UUID）

リクエストボディ

フィールド	型	必須	説明
baseDigest	string	必須	プレイブックの取得の digest
name	string	—	名前（100 文字まで。空白だけや null にはできません）
description	string | null	—	説明（500 文字まで）。null か空の文字列で空にします
category	string | null	—	カテゴリ（50 文字まで）。null か空の文字列で空にします
tags	array	—	タグ（1 つ 30 文字までの文字列を 10 個まで。送れないタグは作るときと同じです）。空にするときは []
steps	array	—	手順の全部（1〜20 個）。項目はプレイブックを作るときと同じです
isShared	boolean	—	公開するかどうか
isActive	boolean	—	有効かどうか

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

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

レスポンス（200 OK）

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

エラーレスポンス

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

DELETE/v1/playbooks/:playbookId

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

パスパラメータ

パラメータ	型	必須	説明
playbookId	string	必須	プレイブックの ID（UUID）

クエリパラメータ

パラメータ	型	デフォルト	説明
cascade	string	"false"	"true" を指定すると、このプレイブックを使っているスケジュールを消してから、プレイブックを消します。"true" / "false" 以外は 400
force	string	"false"	"true" を指定すると、このプレイブックを使っている Agent があっても消します。"true" / "false" 以外は 400

• スケジュールが使っているとき: このプレイブックを使う有効なスケジュールがあると、409 Conflict（has_active_references。使っているスケジュールの数は error.message）が返ります。プロジェクトに置いた Agent の巡回と、まだ動き始めていないプロジェクトの実行も、スケジュールとして数えます（動き始めた実行は数えません）。cascade=true を付けると、このプレイブックを使うスケジュールを、無効なものも含めて消してから、プレイブックを消します。
  • 数えて消すのは、ふつうの利用者では自分のスケジュールだけです。ほかの利用者のスケジュールは数えず、消しません（消えたプレイブックを指したままになります）。システム管理者は、すべての利用者のスケジュールを数えて消します。
  • 使っているのが無効なスケジュールだけのときは 409 Conflict にならず、cascade=true を付けてもそのスケジュールは消えません。消えなかったスケジュールは、消えたプレイブックを指したままになります。
  • cascade=true で消えたスケジュールは、この後は動きません（すでに動き始めた実行は止まりません）。巡回は、設定が有効のままでも止まったままになります。
• Agent が使っているとき: このプレイブックを定義に持つ Agent があると、409 Conflict（playbook_in_use。使っている Agent の数は error.message）が返ります。持ち主を問わず数えます。force=true で消せます。消した後も、Agent は消えたプレイブックを指したままです。
• スケジュールと Agent の両方が使っているときは、cascade=true と force=true の両方が要ります。
• スケジュール・Agent の確認は、消してよい利用者かの確認より先に行います。このため、ほかの利用者の公開プレイブックでも 409 Conflict が返ることがあります。消せないプレイブックでは、cascade=true・force=true を付けると 404 Not Found が返り、何も消えません。

レスポンス（200 OK）

JSON

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

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	playbookId が UUID の形式ではない、または cascade・force が "true" / "false" 以外
403	insufficient_scope	assets:delete スコープが不足
403	forbidden	システム連携のトークンで呼び出した
404	playbook_not_found	プレイブックが存在しない、またはほかの利用者のプレイブックで消せない
409	has_active_references	有効なスケジュールが使っている（cascade=true で消せます）
409	playbook_in_use	Agent が使っている（force=true で消せます）

POST/v1/playbooks/:playbookId/copy

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

パスパラメータ

パラメータ	型	必須	説明
playbookId	string	必須	コピーするプレイブックの ID（UUID）

レスポンス（201 Created）

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

エラーレスポンス

ステータス	code	説明
400	invalid_parameter	playbookId が UUID の形式ではない
403	insufficient_scope	assets:write スコープが不足
403	forbidden	システム連携のトークンで呼び出した
404	playbook_not_found	プレイブックが存在しない、または公開されていない（自分のプレイブックでも、公開していなければ 404）

検索

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

エンドポイント一覧

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

※ Marketplace 版はスコープ不要（認証のみ）。

GET/v1/search/messages

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

クエリパラメータ

パラメータ	型	必須	説明
q	string	必須	検索クエリ
order	string	—	ソート順。"asc"（昇順）または "desc"（降順、デフォルト）

リクエスト例

Search messages

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

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

フィールド	型	説明
messages	array	検索結果のメッセージ配列（最大50件）
messages[].conversationId	string	会話ID（UUID）
messages[].messageId	string	メッセージの一意識別子
messages[].text	string	メッセージの本文テキスト
messages[].title	string	会話のタイトル
messages[].sender	string	送信者。"User" または "AI"
messages[].createdAt	string	作成日時（ISO 8601）
messages[].updatedAt	string	最終更新日時（ISO 8601）
messages[].matchedQueries	array	一致した検索クエリの配列
messages[].status	object	メッセージの処理状態
messages[].status.processing	boolean	エージェントが現在処理中かどうか
messages[].status.unfinished	boolean	エージェントの応答が中断されたかどうか
messages[].tasks	array	エージェントが実行したタスクの配列。フィールド定義は GET /v1/conversations/:conversationId/messages の Task オブジェクトを参照
messages[].deliverables	array	エージェントが生成した成果物の配列。存在する場合のみ含まれます
messages[].deliverables[].filename	string	成果物のファイル名
messages[].deliverables[].filepath	string	成果物のファイルパス
messages[].deliverables[].source	string	"agent"（エージェント生成）または "user"（ユーザーアップロード）
messages[].deliverables[].isPrimary	boolean	主要成果物かどうか
messages[].deliverables[].createdAt	string	作成日時（ISO 8601形式）
messages[].deliverables[].mimeType	string?	MIME タイプ（例: "application/pdf"、"text/markdown"）。判定できない場合は省略
messages[].deliverables[].size	number?	ファイルサイズ（バイト）。0 以下の場合は省略
messages[].files	array?	ユーザーが添付したファイルの配列。sender: "User" のメッセージで添付がある場合のみ含まれます。フィールド構造は履歴 API と同じ（fileId / mimeType / width? / height?）。詳細は GET /v1/conversations/:id/messages を参照
hasMore	boolean	常に false（ページネーション非対応）。一致したメッセージが 50 件を超えても false のため、全部そろっている保証はありません

レスポンス例

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
}

エラーレスポンス

ステータス	説明
400	q パラメータが未指定、または 1 つの文字列として指定されていない（q を複数回指定した場合など）。または order が "asc" / "desc" 以外
403	chat:history スコープが不足

ユーザー

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

エンドポイント一覧

メソッド	エンドポイント	説明
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）

フィールド	型	説明
userId	string	ユーザーの一意識別子
email	string	メールアドレス
username	string	ユーザー名
emailVerified	boolean	メールアドレスの確認状態
createdAt	string	アカウント作成日時（ISO 8601）
isApproved	boolean	アカウントの承認状態
role	string	ユーザーのロール
organization	object	所属組織（設定されている場合のみ）
organization.value	string	組織コード
organization.label	string	組織名
jobType	object	職種（設定されている場合のみ）
jobType.value	string	職種コード
jobType.label	string	職種名
bio	string	自己紹介（設定されている場合のみ）
lastLoginAt	string	最終ログイン日時（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"
}

PATCH/v1/user

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

リクエストボディ

パラメータ	型	必須	説明
username	string	—	ユーザー名
organization	string	—	組織コード
jobType	string	—	職種コード
bio	string	—	自己紹介

リクエスト例

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

エラーレスポンス

ステータス	説明
400	更新するフィールドが未指定
400	username / organization / jobType / bio が文字列ではない、またはボディが壊れた JSON（code: "invalid_body"）
415	ボディの Content-Type が application/json ではない（code: "unsupported_media_type"）

POST/v1/user/password

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

リクエストボディ

パラメータ	型	必須	説明
currentPassword	string	必須	現在のパスワード
newPassword	string	必須	新しいパスワード
confirmPassword	string	必須	新しいパスワード（確認用）

リクエスト例

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）

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

レスポンス例

JSON

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

エラーレスポンス

ステータス	説明
400	必須パラメータの不足、currentPassword / newPassword / confirmPassword が文字列ではない、ボディが壊れた JSON（code: "invalid_body"）、またはパスワードバリデーション失敗
415	ボディの Content-Type が application/json ではない（code: "unsupported_media_type"）
401	認証トークンが無効、または現在のパスワードが不正

マスターデータ

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

エンドポイント一覧

メソッド	エンドポイント	説明
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）

フィールド	型	説明
organizations	array	組織オブジェクトの配列
organizations[].value	string	組織コード
organizations[].label	string	組織名
hasMore	boolean	常に false（ページネーション非対応）

レスポンス例

JSON

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

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）

フィールド	型	説明
jobTypes	array	ジョブタイプオブジェクトの配列
jobTypes[].value	string	職種コード
jobTypes[].label	string	職種名
hasMore	boolean	常に false（ページネーション非対応）

レスポンス例

JSON

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

GET/v1/personas

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

クエリパラメータ

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

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

フィールド	型	説明
locale	string	解決されたロケール
personas	array	ペルソナオブジェクトの配列
personas[].personaKey	string	ペルソナの識別子（Chat / MCP / A2A の personaKey に指定）
personas[].name	string	ペルソナの表示名
personas[].description	string	ペルソナの説明
hasMore	boolean	常に false（ページネーション非対応）

レスポンス例

JSON

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

プロジェクト

プロジェクトの 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	リソースへのアクセス権限なし
404 Not Found	リソースが存在しない
409 Conflict	リソースが現在処理中など、操作が競合
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.type	string	エラーの分類。"invalid_request_error"、"authentication_error"、"insufficient_scope_error"、"forbidden_error"、"not_found_error"、"conflict_error"、"payload_too_large_error"、"rate_limit_error"、"server_error"、"upstream_error" のいずれか
error.message	string	人間が読めるエラーメッセージ
error.code	string	機械的に処理可能なエラーコード（例: "missing_parameter"、"invalid_parameter"、"invalid_token"）
error.param	string	エラーの原因となったパラメータ名。バリデーションエラー時のみ含まれます
error.suggested_action	string	推奨される対処方法。一部のエラーでのみ含まれます

JSON

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