ユーザー API リファレンス

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

ベース URL

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

SaaS

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

Marketplace

https://<your-domain>/api

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

認証

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

Authorization: Bearer <access_token>

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

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

ページネーション

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

パラメータ	型	説明
`limit`	`integer`	1ページあたりの取得件数。エンドポイントごとにデフォルト値と上限が異なります
`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=2026-03-14T10:30:00.000Z" \
  -H "Authorization: Bearer <access_token>"

現在、カーソルベースのページネーションに対応しているのは GET /v1/conversations です。他のエンドポイントでは hasMore は常に false です。

チャット 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 ロールのメッセージが必要です。
`stream`	`boolean`	必須	true を指定してください。現在、ストリーミングモードのみサポートしています。
`conversationId`	`string`	—	既存の会話を継続する場合に会話IDを指定します。省略すると新しい会話が作成されます。

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

SaaS

`agentLevel`	`string`	"default" または "high_performance"。省略時は "default"。
`agentMode`	`boolean`	エージェントモードの有効/無効。省略時は true。
`privateMode`	`boolean`	プライベートモードの有効/無効。省略時は false。

Marketplace

agentId string 使用するエージェントのID（必須）。

Message オブジェクト

パラメータ	型	必須	説明
`role`	`string`	必須	"user" を指定。"assistant" / "system" は受理されますが、現状のエージェント実行では "user" のみが対話の起点として使用されます
`content`	`string \| array`	必須	メッセージの内容。文字列、またはコンテンツパーツの配列。

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

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

type	パラメータ	説明
`"text"`	`text (string)`	テキストメッセージ
`"input_file"`	`fileId (string)`	アップロード済みファイルのID（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 スコープが不足
`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`
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`	`25`	取得件数（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": "2026-03-14T10:30:00.000Z"
}

エラーレスポンス

ステータス	説明
`400`	limit パラメータが不正（1〜100の範囲外）、または mode が "active" / "archive" 以外
`403`	chat:history スコープが不足

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

指定した会話のメッセージ履歴を取得します。

パスパラメータ

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

クエリパラメータ

パラメータ	型	デフォルト	説明
`limit`	`integer`	`—`	取得件数の上限
`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`	常に false（ページネーション非対応）

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 など）。詳細は [ストリーミングガイド](/docs/api/guide/streaming-guide) を参照
`files`	`array?`	タスクに関連するファイル（`filename` / `size` / `filepath` / `mimeType?` の構造。MIME タイプ判定不能時は `mimeType` を省略）。タスクに関連ファイルがない場合は配列自体が省略される
`timestamp`	`number`	タスク実行時のタイムスタンプ（Unix ミリ秒）
`createdAt`	`string`	作成日時（ISO 8601）
`updatedAt`	`string`	更新日時（ISO 8601）

レスポンス例

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 が不正なフォーマット
`403`	chat:history スコープが不足
`404`	会話が見つからない

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`	必須	アップロードするファイル
`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 パラメータが未指定、またはファイルサイズが上限を超過
`403`	chat:file スコープが不足

GET`/v1/files`

ファイル一覧を取得します。

クエリパラメータ

パラメータ	型	デフォルト	説明
`limit`	`integer`	`—`	取得件数の上限。省略時は全件取得
`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`	常に false（ページネーション非対応）

レスポンス例

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

エラーレスポンス

ステータス	説明
`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`

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

GET`/v1/files/proxy`

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

クエリパラメータ

パラメータ	型	必須	説明
`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 スコープが不足、またはアクセス権限なし
`404`	ファイルが見つからない

検索 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](#get-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](#get-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/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
}

エラーレスポンス

HTTP ステータスコード

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

ステータス	説明
`400 Bad Request`	リクエストパラメータが不正
`401 Unauthorized`	トークンが無効または未指定
`403 Forbidden`	リソースへのアクセス権限なし
`404 Not Found`	リソースが存在しない
`409 Conflict`	リソースが現在処理中など、操作が競合
`413 Payload Too Large`	リクエストボディがサイズ上限を超過
`429 Too Many Requests`	レート制限を超過
`500 Internal Server Error`	サーバー内部エラー

エラーレスポンス形式

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

フィールド	型	説明
`error.type`	`string`	エラーの分類。"invalid_request_error"、"authentication_error"、"insufficient_scope_error"、"forbidden_error"、"not_found_error"、"conflict_error"、"payload_too_large_error"、"server_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 オブジェクト​

レスポンス例​

エラーレスポンス​

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

レスポンス例​

エラーレスポンス​

GET/v1/files

クエリパラメータ​

リクエスト例​

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

レスポンス例​

エラーレスポンス​

GET/v1/files/:file_id/content

パスパラメータ​

ベース 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 オブジェクト

レスポンス例

エラーレスポンス

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）

レスポンス例

エラーレスポンス

GET`/v1/files`

クエリパラメータ

リクエスト例

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

レスポンス例

エラーレスポンス

GET`/v1/files/:file_id/content`

パスパラメータ