ユーザー API リファレンス

ユーザー向け API のエンドポイント仕様とエラーコードのリファレンスです。管理者専用 API は管理 API リファレンスを参照してください。

ベース URL

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

SaaS

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

Marketplace

https://<your-domain>/api

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

エディション別の機能対応

各エンドポイントの見出しに付いているバッジ（SaaS / Marketplace）でエディションごとの対応を示しています。サマリーは以下のとおりです。

エンドポイント群	SaaS	Marketplace	主な用途
チャット	✅	✅	OpenAI 互換 SSE
会話管理	✅	✅	会話一覧 / メッセージ取得 / 削除 / 更新
ファイル管理	✅	✅	アップロード / ダウンロード / 削除
成果物取得	✅	✅	エージェントが生成したファイルの取得
検索	✅	✅	メッセージ検索
ライブラリ	✅	—	プロンプトテンプレート / 共有アセット
ユーザー	✅	—	ユーザー情報の参照
マスターデータ	✅	—	組織・職種マスター

注記

Marketplace 版でチャット API を利用する場合、agentId ヘッダーが必須で、stream: true 固定で動作します。詳細はマーケットプレイス版クイックスタートを参照してください。

認証

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

Authorization: Bearer <access_token>

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

トークンの取得方法・スコープの詳細については、認証ガイド、および利用エディションに応じて認証 API リファレンス（SaaS）または認証 API リファレンス（MP）を参照してください。

ページネーション

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

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

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

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

# 2ページ目（レスポンスの cursor 値を使用）
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations?limit=10&cursor=<cursor>" \
  -H "Authorization: Bearer <access_token>"

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

チャット SaaS Marketplace

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 記法をそのまま保持する。

Marketplace

`agentId`	`string`	使用するエージェントの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イベントフロー

data: {"choices":[{"delta":{"role":"assistant"}}]}
data: {"choices":[{"delta":{"content":"..."}}]} × N
data: {"choices":[{"finishReason":"stop"}]}
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件を超過）。または、指定した `conversationId` がアーカイブ済み（`code: "conversation_archived"`）
`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 が不正、または会話がアーカイブ済み（`code: "conversation_archived"`）
`403`	chat:exec スコープが不足
`404`	会話が見つからない

会話管理 SaaS Marketplace

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

エンドポイント一覧

メソッド	エンドポイント	説明	スコープ (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" 以外
`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 をそのまま次のリクエストに渡してください。

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

# 2ページ目（1ページ目のレスポンスに含まれる cursor を指定）
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/<conversation_id>/messages?limit=50&cursor=<cursor>" \\
  -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 が不正（前回レスポンスの値以外）
`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 文字を超える、または会話がアーカイブ済み（`code: "conversation_archived"`）
`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 Marketplace

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

エンドポイント一覧

メソッド	エンドポイント	説明	スコープ (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 を超過、またはアップロードされた画像ファイルが破損している/不正
`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 をそのまま次のリクエストに渡してください。

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

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

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

カーソル利用時の注意

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

エラーレスポンス

ステータス	説明
`400`	limit が 1-100 の整数でない
`400`	cursor が不正（前回レスポンスの値以外）
`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 Marketplace

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

エンドポイント一覧

メソッド	エンドポイント	説明	スコープ (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`	ファイルが見つからない

ライブラリ SaaS

ユーザーのライブラリファイル（アップロード済みファイルおよびエージェントが生成した成果物）を横断的に一覧します。取得した 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" 以外）が不正
`403`	chat:exec スコープが不足

スキル SaaS

チャット実行時に指定できるスキルの一覧を取得します。取得した skillId は Chat の skillIds パラメータに指定して、エージェントにスキルを読み込ませるために使用します。

自分が登録したスキルは GET /v1/skills、他のユーザーが公開しているスキルは GET /v1/skills/shared で取得します。公開スキルはコピーせずそのまま skillIds に指定できます。

エンドポイント一覧

メソッド	エンドポイント	説明	スコープ (SaaS)
GET	`/v1/skills`	自分のスキル一覧を取得	`chat:exec`
GET	`/v1/skills/shared`	公開されているスキル一覧を取得	`chat:exec`

GET`/v1/skills`

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

クエリパラメータ

パラメータ	型	デフォルト	説明
`active_only`	`boolean`	`true`	false を指定すると無効化したスキルも含めます
`limit`	`integer`	`50`	1 ページの取得件数（1-100）
`cursor`	`string`	`—`	次ページ取得用カーソル（前回レスポンスの cursor 値）

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

フィールド	型	説明
`skills`	`array`	スキルオブジェクトの配列
`skills[].skillId`	`string`	スキル ID（Chat の skillIds に指定します）
`skills[].name`	`string`	スキル名
`skills[].description`	`string?`	スキルの説明
`skills[].category`	`string?`	カテゴリ
`skills[].tags`	`array`	タグの配列。未設定の場合は空配列
`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",
      "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 が不正（前回レスポンスの値以外）
`403`	chat:exec スコープが不足

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[].name`	`string`	スキル名
`skills[].description`	`string?`	スキルの説明
`skills[].category`	`string?`	カテゴリ
`skills[].tags`	`array`	タグの配列。未設定の場合は空配列
`skills[].createdAt`	`string`	作成日時（ISO 8601）
`skills[].updatedAt`	`string`	最終更新日時（ISO 8601）
`hasMore`	`boolean`	次のページが存在するかどうか
`cursor`	`string`	次ページ取得用カーソル。hasMore が true の場合のみ含まれます

レスポンス例

JSON
{
  "skills": [
    {
      "skillId": "9c8b7a6d-5e4f-4a3b-8c1d-2e3f4a5b6c7d",
      "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 スコープが不足

プレイブック SaaS

自分のプレイブックの一覧を取得します。取得した playbookId は Chat の playbookId パラメータに指定して、決まった手順でエージェントを実行させるために使用します。

エンドポイント一覧

メソッド	エンドポイント	説明	スコープ (SaaS)
GET	`/v1/playbooks`	プレイブック一覧を取得	`chat:exec`

GET`/v1/playbooks`

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

クエリパラメータ

パラメータ	型	デフォルト	説明
`active_only`	`boolean`	`true`	false を指定すると無効化したプレイブックも含めます
`limit`	`integer`	`50`	1 ページの取得件数（1-100）
`cursor`	`string`	`—`	次ページ取得用カーソル（前回レスポンスの cursor 値）

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

フィールド	型	説明
`playbooks`	`array`	プレイブックオブジェクトの配列
`playbooks[].playbookId`	`string`	プレイブック ID（Chat の playbookId に指定します）
`playbooks[].name`	`string`	プレイブック名
`playbooks[].description`	`string?`	説明
`playbooks[].category`	`string?`	カテゴリ
`playbooks[].tags`	`array`	タグの配列
`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",
      "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 で続きを取得してください。

カーソル利用時の注意

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

エラーレスポンス

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

検索 SaaS Marketplace

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

エンドポイント一覧

メソッド	エンドポイント	説明	スコープ (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（ページネーション非対応）

レスポンス例

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 パラメータが未指定
`403`	chat:history スコープが不足

ユーザー SaaS

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

エンドポイント一覧

メソッド	エンドポイント	説明
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`	更新するフィールドが未指定

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`	必須パラメータの不足、またはパスワードバリデーション失敗
`401`	認証トークンが無効、または現在のパスワードが不正

マスターデータ SaaS

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

エンドポイント一覧

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

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

エラーレスポンス

HTTP ステータスコード

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

ステータス	説明
`400 Bad Request`	リクエストパラメータが不正
`401 Unauthorized`	トークンが無効または未指定
`403 Forbidden`	リソースへのアクセス権限なし
`404 Not Found`	リソースが存在しない
`409 Conflict`	リソースが現在処理中など、操作が競合
`413 Payload Too Large`	リクエストボディがサイズ上限を超過
`429 Too Many Requests`	レート制限を超過。`error.type` は `server_error`、`error.code` は `rate_limit_exceeded` が返ります。時間をおいて再試行してください
`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"、"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"
  }
}

ベース URL​

エディション別の機能対応​

認証​

ページネーション​

チャット SaaS Marketplace​

エンドポイント一覧​

POST/v1/chat/completions

リクエストヘッダー​

リクエストボディ​

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

Message オブジェクト​

コンテンツパーツ（配列形式の場合）​

リクエスト例​

レスポンスヘッダー​

SSE レスポンス形式​

レスポンス例​

エラーレスポンス​

GET/v1/chat/completions/:conversationId

パスパラメータ​

リクエスト例​

レスポンス（200 OK）​

エラーレスポンス​

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

パスパラメータ​

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

リクエスト例​

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

レスポンス例​

エラーレスポンス​

会話管理 SaaS Marketplace​

エンドポイント一覧​

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

GET/v1/conversations

クエリパラメータ​

リクエスト例​

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

レスポンス例​

エラーレスポンス​

GET/v1/conversations/:conversationId/messages

パスパラメータ​

クエリパラメータ​

リクエスト例​

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

Task オブジェクト​

UI リソース（tasks[].metadata.uiResource）​

ページネーション​

レスポンス例​

エラーレスポンス​

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

必要スコープ​

パスパラメータ​

リクエスト例​

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

エラーレスポンス​

PATCH/v1/conversations/:conversationId

パスパラメータ​

リクエストボディ​

リクエスト例​

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

レスポンス例​

エラーレスポンス​

DELETE/v1/conversations/:conversationId

パスパラメータ​

リクエスト例​

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

レスポンス例​

エラーレスポンス​

POST/v1/conversations/:conversationId/restore

パスパラメータ​

リクエスト例​

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

レスポンス例​

エラーレスポンス​

ファイル管理 SaaS Marketplace​

エンドポイント一覧​

POST/v1/files

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

リクエスト例​

レスポンスフィールド（201 Created）​

レスポンス例​

ベース URL

エディション別の機能対応

認証

ページネーション

チャット SaaS Marketplace

エンドポイント一覧

POST`/v1/chat/completions`

リクエストヘッダー

リクエストボディ

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

Message オブジェクト

コンテンツパーツ（配列形式の場合）

リクエスト例

レスポンスヘッダー

SSE レスポンス形式

レスポンス例

エラーレスポンス

GET`/v1/chat/completions/:conversationId`

パスパラメータ

リクエスト例

レスポンス（200 OK）

エラーレスポンス

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

パスパラメータ

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

リクエスト例

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

レスポンス例

エラーレスポンス

会話管理 SaaS Marketplace

エンドポイント一覧

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

GET`/v1/conversations`

クエリパラメータ

リクエスト例

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

レスポンス例

エラーレスポンス

GET`/v1/conversations/:conversationId/messages`

パスパラメータ

クエリパラメータ

リクエスト例

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

Task オブジェクト

UI リソース（`tasks[].metadata.uiResource`）

ページネーション

レスポンス例

エラーレスポンス

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

必要スコープ

パスパラメータ

リクエスト例

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

エラーレスポンス

PATCH`/v1/conversations/:conversationId`

パスパラメータ

リクエストボディ

リクエスト例

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

レスポンス例

エラーレスポンス

DELETE`/v1/conversations/:conversationId`

パスパラメータ

リクエスト例

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

レスポンス例

エラーレスポンス

POST`/v1/conversations/:conversationId/restore`

パスパラメータ

リクエスト例

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

レスポンス例

エラーレスポンス

ファイル管理 SaaS Marketplace

エンドポイント一覧

POST`/v1/files`

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

リクエスト例

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

レスポンス例