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

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

マーケットプレイス版のユーザー向け API のエンドポイント仕様とエラーコードのリファレンスです。アプリケーション(外部ツールでのログイン)で得た利用者のトークンで呼びます。プロジェクトの API は ユーザー API リファレンス(プロジェクト) を、システム連携から呼ぶ API は システム連携 API リファレンス を参照してください。

ベース URL​

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

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

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

認証​

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

Authorization: Bearer <access_token>

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

  • このページの API は、アプリケーション(外部ツールでのログイン)で得た利用者のトークンで呼びます。外部ツールでのログインは、管理者がその入口を開けた環境でだけ使えます(API 利用準備ガイド)。
  • 外部ツールでのログイン以外で得た利用者のトークン(メイン画面にログインしたときのトークンなど)で呼ぶと、どのエンドポイントも 404 Not Found が返ります。
  • チャット・会話管理・ファイル管理・成果物取得・検索は、システム連携のトークンでも呼べます(システム連携 API リファレンス)。ユーザーとマスターデータの API をシステム連携のトークンで呼ぶと、404 Not Found が返ります。

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

チャット API の注意

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

ページネーション​

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

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

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

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

リクエストの扱い​

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

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

チャット​

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 記法を除去したプレーンテキスト(図は削除され、コードブロックは本文が残り、リンクは「文字 (URL)」になる)。"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 "agentId": "<your-agent-id>",
7 "stream": true,
8 "messages": [
9 {
10 "role": "user",
11 "content": "売上データを分析してください"
12 }
13 ]
14}'

レスポンスヘッダー​

ヘッダー説明
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件を超過)。ボディが壊れた JSON(code: "invalid_body")。または、指定した conversationId がアーカイブ済み(code: "conversation_archived")
415ボディの Content-Type が application/json ではない(code: "unsupported_media_type")
403指定した会話がプロジェクトの会話(code: "project_conversation"。プロジェクトの会話には送れません)
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 が不正、messageId が文字列ではない、ボディが壊れた JSON または JSON のオブジェクトではない(code: "invalid_body")、または会話がアーカイブ済み(code: "conversation_archived")
415ボディの Content-Type が application/json ではない(code: "unsupported_media_type")
404会話が見つからない、またはメッセージを止められない(code: "message_not_found")。message_not_found は、送った直後で 10 秒ほど待っても止められなかったとき(数秒後にもう一度送れば止まります)と、messageId がその会話のメッセージでないとき(送り直しても止まりません。messageId を確かめてください)の 2 つです

会話管理​

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

エンドポイント一覧​

メソッドエンドポイント説明スコープ (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
POST/v1/conversations/:conversationId/read会話を既読にするchat:history

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

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

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

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

GET/v1/conversations

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

クエリパラメータ​

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

レスポンス例​

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

エラーレスポンス​

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

GET/v1/conversations/:conversationId/messages

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

パスパラメータ​

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

クエリパラメータ​

パラメータ型デフォルト説明
limitinteger501 ページの取得件数(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[].mimeTypestringMIME タイプ(例: "application/pdf"、"text/markdown")。判定できない場合は "application/octet-stream"
messages[].deliverables[].sizenumber?ファイルサイズ(バイト)。0 以下の場合は省略
messages[].filesarray?ユーザーが添付したファイルの配列。sender: "User" のメッセージで添付がある場合のみ含まれます
messages[].files[].fileIdstringファイルの一意識別子(UUID)
messages[].files[].mimeTypestringMIME タイプ(例: "image/png"、"application/pdf")
messages[].files[].widthnumber?画像の幅(ピクセル)。画像ファイルの場合のみ
messages[].files[].heightnumber?画像の高さ(ピクセル)。画像ファイルの場合のみ
messages[].archivedboolean?archive 経由で取得されたメッセージのみ true。GET /v1/conversations?mode=archive で取得した会話のメッセージ履歴を参照した場合に付与されます
hasMoreboolean次のページが存在するかどうか
cursorstring次ページ取得用カーソル。hasMore が true の場合のみ含まれます

Task オブジェクト​

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

ページネーション​

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 が不正(前回レスポンスの値以外)
400order が "asc" / "desc" 以外
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更新後のタイトル
typestring会話の種類。"chat"・"mail"・"project"(プロジェクトの工程の会話)
createdAtstring会話の作成日時(ISO 8601)
updatedAtstring会話の更新日時(ISO 8601)

レスポンス例​

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

エラーレスポンス​

ステータス説明
400title が未指定、空文字、もしくは 200 文字を超える、ボディが壊れた JSON(code: "invalid_body")、または会話がアーカイブ済み(code: "conversation_archived")
415ボディの Content-Type が application/json ではない(code: "unsupported_media_type")
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会話が現在処理中のため削除できない、またはプロジェクトの会話(code: "project_conversation"。プロジェクトの会話は削除できません)

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 状態と区別されません)

POST/v1/conversations/:conversationId/read

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

パスパラメータ​

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

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

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

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

リクエスト例​

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

レスポンス(204 No Content)​

本文はありません。

エラーレスポンス​

ステータス説明
400conversationId・messageId・本文が不正(invalid_parameter など)、または会話がアーカイブ済み(conversation_archived)
404会話が存在しない・自分の会話でない(conversation_not_found)、または messageId がその会話に無い(message_not_found)
415本文が application/json でない

ファイル管理​

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

エンドポイント一覧​

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

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

POST/v1/files

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

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

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

リクエスト例​

Upload file
1curl -X POST https://<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 を超過、またはアップロードされた画像ファイルが破損している/不正
415ボディが multipart/form-data ではない(code: "unsupported_media_type")

GET/v1/files

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

クエリパラメータ​

パラメータ型デフォルト説明
limitinteger501 ページの取得件数(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 が不正(前回レスポンスの値以外)
400order が "asc" / "desc" 以外

GET/v1/files/:fileId/content

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

パスパラメータ​

パラメータ型必須説明
fileIdstring必須ファイル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="ファイル名"

エラーレスポンス​

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

DELETE/v1/files/:fileId

ファイルを削除します。

パスパラメータ​

パラメータ型必須説明
fileIdstring必須ファイル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 で取得)

リクエスト例​

Get artifact file
1curl "https://<your-domain>/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ファイルサイズ(バイト)

エラーレスポンス​

ステータス説明
400path パラメータが未指定またはフォーマット不正
404ファイルが見つからない(code: "not_found" など)
500保存先の不明な誤り(code: "unknown")
502保存先へのアクセスが拒否された(code: "storage_forbidden")、または保存先がリクエストを断った(code: "rejected")。管理者に連絡してください
503保存先が一時的に混んでいる(code: "rate_limited")、または一時的に使えない(code: "transient")。時間をおいて再試行してください

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

エンドポイント一覧​

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

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

GET/v1/search/messages

メッセージを全文検索します。プロジェクトの工程の会話のメッセージは、検索の対象になりません。

クエリパラメータ​

パラメータ型必須説明
qstring必須検索クエリ
orderstring—ソート順。"asc"(昇順)または "desc"(降順、デフォルト)

リクエスト例​

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

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

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

レスポンス例​

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" 以外

ユーザー​

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

エンドポイント一覧​

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

GET/v1/user

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

リクエスト例​

Get user
1curl https://<your-domain>/api/v1/user \
2-H "Authorization: Bearer <access_token>"

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

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

レスポンス例​

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

PATCH/v1/user

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

リクエストボディ​

パラメータ型必須説明
usernamestring—ユーザー名
organizationstring—組織コード。未設定のときだけ設定できます。設定済みの組織を変える(空にするのも)と 403 になります。変更は管理者に依頼してください
jobTypestring—職種コード。未設定のときだけ設定できます。設定済みの職種を変える(空にするのも)と 403 になります。変更は管理者に依頼してください
biostring—自己紹介

リクエスト例​

Update user
1curl -X PATCH https://<your-domain>/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更新するフィールドが未指定
400username / organization / jobType / bio が文字列ではない、またはボディが壊れた JSON(code: "invalid_body")
403設定済みの organization / jobType を変えようとした(空にするのも)(code: "affiliation_locked")。変更は管理者に依頼してください
409同じユーザーの別の更新を処理している(code: "conflict")。少し待ってから送り直してください
415ボディの Content-Type が application/json ではない(code: "unsupported_media_type")

POST/v1/user/password

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

リクエストボディ​

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

リクエスト例​

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

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

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

レスポンス例​

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

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

エラーレスポンス​

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

マスターデータ​

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

エンドポイント一覧​

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

GET/v1/organizations

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

リクエスト例​

List organizations
1curl https://<your-domain>/api/v1/organizations \
2-H "Authorization: Bearer <access_token>"

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

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

レスポンス例​

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

GET/v1/job-types

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

リクエスト例​

List job types
1curl https://<your-domain>/api/v1/job-types \
2-H "Authorization: Bearer <access_token>"

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

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

レスポンス例​

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

プロジェクト​

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

エラーレスポンス​

HTTP ステータスコード​

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

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

エラーレスポンス形式​

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

フィールド型説明
error.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"
}
}