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

システム連携 API リファレンス

マーケットプレイス版のシステム連携 API のエンドポイント仕様とエラーコードのリファレンスです。

注記

マーケットプレイス版で利用できるのは、チャット・会話管理・ファイル管理・成果物取得・検索です。ライブラリ・スキル・プレイブック・ユーザー・マスターデータ・ユーザー管理・ログ・共有メモリ・プロジェクトの各 API は SaaS 版でのみ提供されます。SaaS 版の仕様は ユーザー API リファレンス(SaaS 版) と システム連携 API リファレンス(SaaS 版) を参照してください。

ベース URL​

すべての API リクエストは以下のベース URL に対して送信します。<your-domain> は導入した環境のドメインに読み替えてください。

Marketplace
https://<your-domain>/api

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

認証​

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

Authorization: Bearer <access_token>

トークンが無効または未指定の場合、401 Unauthorized が返されます。マーケットプレイス版ではスコープによる制限はありません。

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

チャット API の注意

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

ページネーション​

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

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

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

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

チャット​

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

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

SSE ストリーミングガイド

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

ガイドを見る

エンドポイント一覧​

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

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

POST/v1/chat/completions

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

リクエストヘッダー​

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

リクエストボディ​

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

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

Marketplace
agentIdstring使用するエージェントのID(必須)。
outputFormatstring応答テキストの形式。"plain"(省略時)は Markdown 記法を除去したプレーンテキスト(図は削除され、コードブロックは本文が残る)。"markdown" は Markdown 記法をそのまま保持する。

Message オブジェクト​

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

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

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

typeパラメータ説明
"text"text (string)テキストメッセージ
"input_file"fileId (string)アップロード済みファイルの fileId。1リクエストあたり合計最大20件

リクエスト例​

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

レスポンスヘッダー​

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

SSE レスポンス形式​

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

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

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

レスポンス例​

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

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

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

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

data: [DONE]

エラーレスポンス​

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

ステータス説明
400リクエストパラメータ不正(model / messages / stream / conversationId / role / content の欠落・型不一致、または input_file が1リクエストあたり20件を超過)。または、指定した conversationId がアーカイブ済み(code: "conversation_archived")
404指定した input_file の fileId が見つからない
409指定した会話が現在処理中

GET/v1/chat/completions/:conversationId

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

パスパラメータ​

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

リクエスト例​

Resume SSE stream
1curl https://<your-domain>/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 が含まれます。再接続の詳細な手順についてはストリーミングガイドを参照してください。

エラーレスポンス​

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

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

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

パスパラメータ​

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

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

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

リクエスト例​

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

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

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

レスポンス例​

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

エラーレスポンス​

ステータス説明
400conversationId が不正、会話がアーカイブ済み(code: "conversation_archived")、messageId のメッセージが別の会話のもの(code: "conversation_mismatch")、または接続先のエージェントがキャンセルに対応していない(code: "unsupported_endpoint"・code: "post_processing_not_enabled")
404会話が見つからない(code: "conversation_not_found")、messageId のメッセージが見つからない(code: "message_not_found")、または messageId のメッセージが処理中でない(code: "not_processing")

会話管理​

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

エンドポイント一覧​

メソッドエンドポイント説明スコープ (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

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

クエリパラメータ​

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

リクエスト例​

List conversations
1curl "https://<your-domain>/api/v1/conversations?limit=10&order=desc" \
2-H "Authorization: Bearer <access_token>"

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

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

レスポンス例​

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

エラーレスポンス​

ステータス説明
400limit パラメータが不正(1〜100の範囲外)、または mode が "active" / "archive" 以外

GET/v1/conversations/:conversationId/messages

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

パスパラメータ​

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

クエリパラメータ​

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

リクエスト例​

Get messages
1curl https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/messages?order=asc \
2-H "Authorization: Bearer <access_token>"

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

フィールド型説明
messagesarrayメッセージオブジェクトの配列
messages[].conversationIdstring会話ID(UUID)
messages[].messageIdstringメッセージの一意識別子
messages[].senderstring送信者。"User" または "AI"
messages[].textstringメッセージの本文テキスト
messages[].createdAtstring作成日時(ISO 8601)
messages[].updatedAtstring最終更新日時(ISO 8601)
messages[].statusobjectメッセージの処理状態
messages[].status.processingbooleanエージェントが現在処理中かどうか
messages[].status.unfinishedbooleanエージェントの応答が中断されたかどうか
messages[].tasksarrayエージェントが実行したタスクの配列(後述)
messages[].deliverablesarrayエージェントが生成した成果物の配列。存在する場合のみ含まれます
messages[].deliverables[].filenamestring成果物のファイル名
messages[].deliverables[].filepathstring成果物のファイルパス
messages[].deliverables[].sourcestring"agent"(エージェント生成)または "user"(ユーザーアップロード)
messages[].deliverables[].isPrimaryboolean主要成果物かどうか
messages[].deliverables[].createdAtstring作成日時(ISO 8601形式)。分からないときは空文字
messages[].deliverables[].mimeTypestring?MIME タイプ(例: "application/pdf"、"text/markdown")。判定できない場合は省略
messages[].deliverables[].sizenumber?ファイルサイズ(バイト)。0 以下の場合は省略
messages[].filesarray?ユーザーが添付したファイルの配列。sender: "User" のメッセージで添付がある場合のみ含まれます
messages[].files[].fileIdstringファイルの一意識別子(UUID)
messages[].files[].mimeTypestringMIME タイプ(例: "image/png"、"application/pdf")
messages[].files[].widthnumber?画像の幅(ピクセル)。画像ファイルの場合のみ
messages[].files[].heightnumber?画像の高さ(ピクセル)。画像ファイルの場合のみ
messages[].archivedboolean?archive 経由で取得されたメッセージのみ true。GET /v1/conversations?mode=archive で取得した会話のメッセージ履歴を参照した場合に付与されます
hasMoreboolean次のページが存在するかどうか
cursorstring次ページ取得用カーソル。hasMore が true の場合のみ含まれます

Task オブジェクト​

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

ページネーション​

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

リクエスト例
1# 1ページ目
2curl "https://<your-domain>/api/v1/conversations/<conversation_id>/messages?limit=50" \
3-H "Authorization: Bearer <access_token>"
4
5# 2ページ目(1ページ目のレスポンスに含まれる cursor を指定)
6curl "https://<your-domain>/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
}

エラーレスポンス​

ステータス説明
400conversationId が不正なフォーマット
400limit が 1-100 の整数でない
400cursor が不正(前回レスポンスの値以外)
404会話が見つからない

PATCH/v1/conversations/:conversationId

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

パスパラメータ​

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

リクエストボディ​

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

リクエスト例​

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

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

フィールド型説明
conversationIdstring会話ID(UUID)
titlestring更新後のタイトル
createdAtstring会話の作成日時(ISO 8601)
updatedAtstring会話の更新日時(ISO 8601)

レスポンス例​

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

エラーレスポンス​

ステータス説明
400title が未指定、空文字、もしくは 200 文字を超える、または会話がアーカイブ済み(code: "conversation_archived")
404会話が見つからない

DELETE/v1/conversations/:conversationId

会話を削除します。

パスパラメータ​

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

リクエスト例​

Delete conversation
1curl -X DELETE https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000 \
2-H "Authorization: Bearer <access_token>"

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

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

レスポンス例​

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

エラーレスポンス​

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

POST/v1/conversations/:conversationId/restore

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

パスパラメータ​

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

リクエスト例​

Restore archived conversation
1curl -X POST https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/restore \
2-H "Authorization: Bearer <access_token>"

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

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

レスポンス例​

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

エラーレスポンス​

ステータス説明
400conversationId が不正
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)​

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

リクエスト例​

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

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

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

レスポンス例​

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

エラーレスポンス​

ステータス説明
400file または filename パラメータが未指定、ファイルサイズが 512 MB を超過、またはアップロードされた画像ファイルが破損している/不正

GET/v1/files

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

クエリパラメータ​

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

リクエスト例​

List files
1curl https://<your-domain>/api/v1/files?order=desc \
2-H "Authorization: Bearer <access_token>"

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

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

レスポンス例​

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

ページネーション​

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

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

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

カーソル利用時の注意

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

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

エラーレスポンス​

ステータス説明
400limit が 1-100 の整数でない
400cursor が不正(前回レスポンスの値以外)

GET/v1/files/:file_id/content

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

パスパラメータ​

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

リクエスト例​

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

レスポンス(200 OK)​

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

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

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

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

エラーレスポンス​

ステータス説明
400fileId が不正なフォーマット
404ファイルが見つからない

DELETE/v1/files/:file_id

ファイルを削除します。

パスパラメータ​

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

リクエスト例​

Delete file
1curl -X DELETE https://<your-domain>/api/v1/files/550e8400-e29b-41d4-a716-446655440001 \
2-H "Authorization: Bearer <access_token>"

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

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

レスポンス例​

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

エラーレスポンス​

ステータス説明
400fileId が不正なフォーマット
404ファイルが見つからない

成果物取得​

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

エンドポイント一覧​

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

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

GET/v1/files/proxy

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

マーケットプレイス版ではスコープによる制限はありません。認証済みのトークンがあれば取得できます。

クエリパラメータ​

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

リクエスト例​

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

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

レスポンス(200 OK)​

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

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

エラーレスポンス​

ステータス説明
400path パラメータが未指定またはフォーマット不正
404ファイルが見つからない

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

エンドポイント一覧​

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

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

GET/v1/search/messages

メッセージを全文検索します。検索結果は作成日時の新しい順(order=asc で古い順)に、カーソルベースのページネーションで返します。

クエリパラメータ​

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

リクエスト例​

Search messages
1curl "https://<your-domain>/api/v1/search/messages?q=売上" \
2-H "Authorization: Bearer <access_token>"

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

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

レスポンス例​

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

エラーレスポンス​

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

エラーレスポンス​

HTTP ステータスコード​

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

ステータス説明
400 Bad Requestリクエストパラメータが不正
401 Unauthorizedトークンが無効または未指定
403 Forbiddenリソースへのアクセス権限なし
404 Not Foundリソースが存在しない
409 Conflictリソースが現在処理中など、操作が競合
413 Payload Too Largeリクエストボディがサイズ上限を超過
429 Too Many Requestsレート制限または上限を超過。error.type は rate_limit_error で、error.code はエンドポイントにより異なります(例: 月間上限は monthly_quota_exceeded)。時間をおいて再試行してください
500 Internal Server Errorサーバー内部エラー
502 Bad Gateway上流サービス(認証基盤・チャット基盤等)との通信エラー
503 Service Unavailableサービス一時利用不可
504 Gateway Timeout上流サービスの応答タイムアウト

エラーレスポンス形式​

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

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