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

ユーザー 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 が返ります。
  • チャット・会話管理・ファイル管理・成果物取得・検索・登録 Agent の一覧は、システム連携のトークンでも呼べます(システム連携 API リファレンス)。ユーザーとマスターデータの API をシステム連携のトークンで呼ぶと、404 Not Found が返ります。

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

チャット API の注意

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

共通の決まり​

このページの API に共通の決まりです。

リクエストの扱い​

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

送ったもの扱い
仕様に無いクエリパラメータとボディのフィールド無視されます。ただし、このページに載っていない項目でも、サービスが受け付けている項目は、型や値が正しくないと 400 Bad Request になることがあります
仕様にあるクエリパラメータの不正な値400 Bad Request
パスパラメータの値の不正な URL エンコード(% の並び)400 Bad Request(invalid_parameter)
壊れた JSON のボディ400 Bad Request(invalid_body)
JSON のボディを受け付けるエンドポイントへの、Content-Type: application/json 以外のボディ、対応していない文字コード(charset)のボディ415 Unsupported Media Type(unsupported_media_type)
ファイルのアップロードへの、multipart/form-data 以外のボディ415 Unsupported Media Type
型の違うボディのフィールド400 Bad Request

ボディの読み取りで 400(壊れた JSON など)や 413(サイズの上限を超えたなど)になる場合は、415 よりそちらが先に返ります。

ページネーション​

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

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

レスポンスには 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(必須)。GET /v1/marketplace-agents が返す marketplaceAgentId を指定します。
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")
400messages に user ロールのメッセージが 1 つも無い(code: "no_user_message")
415ボディの Content-Type が application/json ではない(code: "unsupported_media_type")
403指定した会話がプロジェクトの会話(code: "project_conversation"。プロジェクトの会話には送れません)
404指定した input_file の fileId が見つからない(code: "file_not_found")
409指定した会話が現在処理中(code: "conversation_processing")

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

エラーレスポンス​

ステータスcode説明
404not_found会話が見つからない、進行中でない、または自分の会話ではない(conversationId が空の値のときも同じ)

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")
400messageId のメッセージが、指定した会話のものではない(code: "conversation_mismatch")
400この会話の接続先がキャンセルに対応していない(code: "unsupported_endpoint")、またはこの環境でキャンセルが有効になっていない(code: "post_processing_not_enabled")
415ボディの Content-Type が application/json ではない(code: "unsupported_media_type")
404会話が見つからない、またはメッセージを止められない(code: "message_not_found")。message_not_found は、送った直後で 10 秒ほど待っても止められなかったとき(数秒後にもう一度送れば止まります)と、messageId のメッセージが無い、または自分のものではないとき(送り直しても止まりません。messageId を確かめてください)の 2 つです
404messageId のメッセージが処理中ではない(すでに終わっている。code: "not_processing")

登録 Agent の一覧​

チャットで動かせる登録 Agent の一覧を取得します。

エンドポイント一覧​

メソッドエンドポイント説明
GET/v1/marketplace-agents登録 Agent の一覧を取得

GET/v1/marketplace-agents

チャット(POST /v1/chat/completions の agentId)で動かせる登録 Agent を、全部返します(有効なものだけ)。MCP の受け口が有効な配備でチャットの組(?toolsets=chat。指定が無いときの既定)を使うときは MCP(execute_chat の agentId)、A2A の受け口が有効な配備では A2A(/v1/a2a/agents/{agentId}/)でも、同じ Agent を動かせます。MCP の list_agents と同じ一覧です。一覧は最大 5 分前のものです。marketplaceAgentId を、チャットでは agentId に指定します。

リクエスト例​

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

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

フィールド型説明
marketplaceAgentsarray登録 Agent の配列(有効なものの全部)
marketplaceAgents[].marketplaceAgentIdstring登録 Agent の ID。チャットでは agentId に指定します
marketplaceAgents[].displayNamestring表示名
marketplaceAgents[].descriptionstring説明。説明が無い Agent は表示名
marketplaceAgents[].tagsstring[]タグ
hasMorebooleanいつも false(全部を返します)

レスポンス例​

JSON
{
"marketplaceAgents": [
{
"marketplaceAgentId": "sales-report",
"displayName": "売上レポート",
"description": "売上データを集計して報告書を作ります",
"tags": ["report"]
}
],
"hasMore": false
}

エラーレスポンス​

ステータスcode説明
401—トークンが無い・無効(共通のエラーの節)
502upstream_connection_error登録 Agent の一覧を読めなかった
502upstream_api_error一覧の読み取り先が誤りを返した
504upstream_timeout一覧の読み取りが時間内に終わらなかった

会話管理​

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

エンドポイント一覧​

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

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

クエリパラメータ​

パラメータ型必須デフォルト説明
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[].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"
}

エラーレスポンス​

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

GET/v1/conversations/:conversationId/messages

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

パスパラメータ​

パラメータ型必須説明
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メッセージの本文テキスト。本文が空のときは、いちばん新しいタスクの結果(content)が入ります
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
}

エラーレスポンス​

ステータスcode説明
400invalid_conversation_idconversationId が全部 0 の UUID(00000000-0000-0000-0000-000000000000)。この値は受け付けません
400invalid_parameterlimit が 1-100 の整数でない、cursor が不正(前回レスポンスの値以外)、または order が "asc" / "desc" 以外
404conversation_not_found会話が見つからない、または自分の会話ではない

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

エラーレスポンス​

ステータスcode説明
400invalid_conversation_idconversationId が全部 0 の UUID(00000000-0000-0000-0000-000000000000)。この値は受け付けません
400missing_parametertitle が未指定
400invalid_titletitle が空文字・文字列ではない・200 文字を超える
400invalid_bodyボディが壊れた JSON
400conversation_archived会話がアーカイブ済み
415unsupported_media_typeボディの Content-Type が application/json ではない
404conversation_not_found会話が見つからない、または自分の会話ではない

DELETE/v1/conversations/:conversationId

会話を削除します。その会話のメッセージに添付したファイルと成果物のファイルのうち、ほかの会話で使っていないものも削除されます(GET /v1/files にも出なくなります)。

パスパラメータ​

パラメータ型必須説明
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 }

エラーレスポンス​

ステータスcode説明
400invalid_conversation_idconversationId が全部 0 の UUID(00000000-0000-0000-0000-000000000000)。この値は受け付けません
400conversation_archived会話がアーカイブ済み。復元には POST /v1/conversations/:id/restore を使用
404conversation_not_found会話が見つからない、または自分の会話ではない
409conversation_processing会話が現在処理中のため削除できない
409project_conversationプロジェクトの会話。プロジェクトの会話は削除できません
409legal_hold保全中の会話。管理者が保全を解除するまで削除できません

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 }

エラーレスポンス​

ステータスcode説明
400invalid_conversation_idconversationId が全部 0 の UUID(00000000-0000-0000-0000-000000000000)。この値は受け付けません
404conversation_not_foundアーカイブに該当会話が存在しない、または既に 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)​

本文はありません。

エラーレスポンス​

ステータスcode説明
400invalid_conversation_idconversationId が全部 0 の UUID(00000000-0000-0000-0000-000000000000)。この値は受け付けません
400invalid_parametermessageId が空・文字列ではない
400invalid_body本文が JSON のオブジェクトではない
400conversation_archived会話がアーカイブ済み
415unsupported_media_type本文が application/json でない
404conversation_not_found会話が存在しない・自分の会話でない
404message_not_foundmessageId がその会話に無い

ファイル管理​

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

エンドポイント一覧​

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

エラーレスポンス​

ステータスcode説明
400missing_parameterfile または filename パラメータが未指定
400file_too_largeファイルサイズが 512 MB を超過
400invalid_parameterアップロードされた画像ファイルが破損している/不正
415unsupported_media_typeボディが multipart/form-data ではない、またはファイルの種類を受け付けていない(環境で受け付けないと決めた拡張子・MIME タイプを含む)
403feature_not_permitted管理者がファイルの添付を許可していない
503feature_permissions_unavailable機能の許可を確かめられない。時間をおいて送り直す

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 を変更しないでください。条件を変えると対象範囲が変わり、項目の重複や取りこぼしが起きます。

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

エラーレスポンス​

ステータスcode説明
400invalid_parameterlimit が 1-100 の整数でない
400invalid_parametercursor が不正(前回レスポンスの値以外)
400invalid_parameterorder が "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="ファイル名"; 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

エラーレスポンス​

ステータスcode説明
400invalid_parameterfileId が不正なフォーマット
404file_not_foundファイルが見つからない
503service_unavailable認証の仕組みが一時的に使えない。少し待ってから送り直してください。続くときは、サービスの管理者に問い合わせてください

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 }

エラーレスポンス​

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

成果物取得​

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

エンドポイント一覧​

メソッドエンドポイント説明スコープ (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ファイルサイズ(バイト)

エラーレスポンス​

ステータスcode説明
400missing_parameterpath パラメータが未指定
400invalid_parameterpath のフォーマットが不正(UUID の形の段が無い)
404not_foundファイルが見つからない(保存先の応答に別の code があるときはその code)
500unknown保存先の不明な誤り
500storage_forbidden保存先へのアクセスが拒否された。管理者に連絡してください
500rejected保存先がリクエストを断った。管理者に連絡してください
503rate_limited保存先が一時的に混んでいる。時間をおいて再試行してください
503transient保存先が一時的に使えない。時間をおいて再試行してください
503service_unavailable認証の仕組みが一時的に使えない。少し待ってから送り直してください。続くときは、サービスの管理者に問い合わせてください

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

エンドポイント一覧​

メソッドエンドポイント説明スコープ (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[].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続きのページがあれば 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")。時間をおいて送り直してください

ユーザー​

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

エンドポイント一覧​

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

エラーレスポンス​

ステータスcode説明
500internal_errorユーザー情報を取得できなかった(時間をおいて再試行してください)

PATCH/v1/user

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

リクエストボディ​

パラメータ型必須説明
usernamestring—ユーザー名。2〜50 文字で、「<」「>」「"」「'」は使えません
organizationstring—組織コード。100 文字まで。未設定のときだけ設定でき、有効な組織コードだけを設定できます。設定済みの組織を変える(空にするのも)と 403 になります。変更は管理者に依頼してください。IdP から同期しているときは、ID 基盤(IdP)で変えてください
jobTypestring—職種コード。100 文字まで。未設定のときだけ設定でき、有効な職種コードだけを設定できます。設定済みの職種を変える(空にするのも)と 403 になります。変更は管理者に依頼してください。IdP から同期しているときは、ID 基盤(IdP)で変えてください
biostring—自己紹介。150 文字までで、「<」「>」「"」「'」は使えません

リクエスト例​

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

エラーレスポンス​

ステータスcode説明
400invalid_parameter更新するフィールドが未指定
400invalid_bodyボディが壊れた JSON
400invalid_parameter入力の誤り(username / organization / jobType / bio が文字列ではない、文字数・使えない文字、または初めて設定する organization / jobType が有効なコードではない)
403affiliation_locked設定済みの organization / jobType を変えようとした(空にするのも)。変更は管理者に依頼してください。IdP から同期しているときは、ID 基盤(IdP)で変えてください
409conflict同じユーザーの別の更新を処理している。少し待ってから送り直してください
415unsupported_media_typeボディの Content-Type が application/json ではない

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
}

エラーレスポンス​

ステータスcode説明
500internal_error組織の一覧を取得できなかった(時間をおいて再試行してください)

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
}

エラーレスポンス​

ステータスcode説明
500internal_errorジョブタイプの一覧を取得できなかった(時間をおいて再試行してください)

プロジェクト​

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

エラーレスポンス​

HTTP ステータスコード​

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

ステータス説明
400 Bad Requestリクエストパラメータが不正
401 Unauthorizedトークンが無効または未指定。管理者に利用を止められた利用者のトークンでも返ります(下の「利用を止められた利用者」)
403 Forbiddenリソースへのアクセス権限なし
404 Not Foundリソースが存在しない、または未定義のパス・メソッド(405 は返しません)
409 Conflictリソースが現在処理中など、操作が競合
409 Conflict組織の運用の役割(管理コンソールの「管理の役割」で付ける「運用」の役割)の人が、プロジェクトに参加せずに、その役割では使えない操作を呼んだ(error.code は forbidden_role)。待っても直りません。オーナーだけの操作は、プロジェクトのオーナーに頼んでください。ほかの操作は、オーナーにプロジェクトに加えてもらうと、参加の役割のとおりに呼べます
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.reasonstring断りの理由の種類。プロジェクト API の 409(definition_invalid)のときだけ含まれます
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"
}
}

利用を止められた利用者​

管理者に利用を止められた利用者のトークンで呼ぶと、401 Unauthorized が返ります。error.code は account_suspended です。

次の API は、利用を止められたかどうかを見ません: GET /v1/organizations・GET /v1/job-types・GET /v1/user・PATCH /v1/user・GET /v1/marketplace-agents、MCP の list_agents と、進行中のタスクが無いときの cancel_chat、登録 Agent の Agent Card(GET /api/v1/a2a/agents/{agentId}/.well-known/agent-card.json)。