システム連携 API リファレンス
マーケットプレイス版のシステム連携 API のエンドポイント仕様とエラーコードのリファレンスです。
注記
マーケットプレイス版で利用できるのは、チャット・会話管理・ファイル管理・成果物取得・検索・プロジェクトです。ライブラリ・Agent・スキル・プレイブック・確認依頼・連携先・ペルソナ・ユーザー・マスターデータ・ユーザー管理・ログ・共有メモリの各 API は SaaS 版でのみ提供されます。プロジェクトの API は、下の 4 つだけです（プロジェクトの作成・編集や、記録・指標の取得などは 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 は、サービスアカウントのトークンでだけ呼べます。利用者としてログインして得たトークンで呼ぶと 404 Not Found が返ります。
トークンの取得方法については、認証ガイド および 認証 API リファレンス を参照してください。
チャット API の注意
マーケットプレイス版でチャット API を利用する場合、agentId パラメータが必須で、stream: true 固定で動作します。詳細はAPI を呼び出すを参照してください。
ページネーション
一覧取得エンドポイントはカーソルベースのページネーションをサポートしています。
| パラメータ | 型 | 説明 |
|---|---|---|
limit | integer | 1ページあたりの取得件数（1-100）。デフォルトは 50 件です |
cursor | string | 次のページを取得するためのカーソル値。前回のレスポンスに含まれる cursor をそのまま指定します |
order | string | ソート順。"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 |
リクエストボディ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
model | string | 必須 | 使用するモデルID。"AGENTIC STAR" を指定してください。 |
messages | array | 必須 | メッセージオブジェクトの配列。少なくとも 1 つの user ロールメッセージが必要。複数の user メッセージを含めても最後の 1 件のみが処理されます。会話履歴はサーバー側で管理されるため、過去のやり取りを messages 配列で送る必要はありません。既存の会話を継続する場合は conversationId パラメータに前回の会話 ID を指定してください。 |
stream | boolean | 必須 | true を指定してください。現在、ストリーミングモードのみサポートしています。 |
conversationId | string | — | 既存の会話を継続する場合に会話IDを指定します。省略すると新しい会話が作成されます。 |
エディション固有のパラメータ
Marketplace
agentId | string | 使用するエージェントのID（必須）。 |
outputFormat | string | 応答テキストの形式。"plain"（省略時）は Markdown 記法を除去したプレーンテキスト（図は削除され、コードブロックは本文が残る）。"markdown" は Markdown 記法をそのまま保持する。 |
Message オブジェクト
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
role | string | 必須 | "user" を指定。"assistant" / "system" は受理されますが、現状のエージェント実行では "user" のみが対話の起点として使用されます |
content | string | array | 必須 | メッセージの内容。文字列、または content parts (text / input_file) の配列。処理対象となるテキストは UTF-8 換算で 1 MB 以下。 |
コンテンツパーツ（配列形式の場合）
content を配列で指定する場合、以下のパーツタイプが利用できます。テキストとファイルを組み合わせて送信できます。
| type | パラメータ | 説明 |
|---|---|---|
"text" | text (string) | テキストメッセージ |
"input_file" | fileId (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-Type | text/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":"..."}}]} × N3.
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"） |
404 | 指定した input_file の fileId が見つからない |
409 | 指定した会話が現在処理中 |
GET/v1/chat/completions/:conversationId
進行中の会話のSSEストリームに再接続します。エージェントが長時間実行タスクを処理している場合や、ネットワーク切断後の復帰に使用します。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
conversationId | string | 必須 | 再接続する会話の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 が含まれます。再接続の詳細な手順についてはストリーミングガイドを参照してください。
エラーレスポンス
| ステータス | 説明 |
|---|---|
400 | conversationId が不正 |
404 | 会話が見つからない、または進行中でない |
POST/v1/chat/completions/:conversationId/cancel
進行中の会話をキャンセルします。エージェントの実行を中断する場合に使用します。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
conversationId | string | 必須 | キャンセルする会話のID |
リクエストボディ（任意）
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
messageId | string | — | キャンセル対象のメッセージ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）
| フィールド | 型 | 説明 |
|---|---|---|
conversationId | string | キャンセルされた会話のID（UUID） |
cancelled | boolean | キャンセル成功時は常に true |
レスポンス例
JSON
{ "conversationId": "550e8400-...", "cancelled": true }
エラーレスポンス
| ステータス | 説明 |
|---|---|
400 | conversationId が不正、messageId が文字列ではない、ボディが壊れた JSON または JSON のオブジェクトではない（code: "invalid_body"）、または会話がアーカイブ済み（code: "conversation_archived"） |
415 | ボディの Content-Type が application/json ではない（code: "unsupported_media_type"） |
404 | 会話が見つからない |
会話管理
会話の一覧取得・メッセージ履歴参照・削除・タイトル更新を行います。
エンドポイント一覧
| メソッド | エンドポイント | 説明 | スコープ (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 | 50 | 取得件数（1〜100） |
cursor | string | — | 次ページ取得用カーソル（前回レスポンスの cursor 値） |
order | string | "desc" | "asc" または "desc" |
title | string | — | タイトルで絞り込み |
mode | string | "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）
| フィールド | 型 | 説明 |
|---|---|---|
conversations | array | 会話オブジェクトの配列 |
conversations[].conversationId | string | 会話の一意識別子（UUID） |
conversations[].title | string | 会話のタイトル |
conversations[].createdAt | string | 作成日時（ISO 8601） |
conversations[].updatedAt | string | 最終更新日時（ISO 8601） |
conversations[].archived | boolean? | アーカイブ済みかどうか。mode=archive で取得した場合は常に true。mode=active でこのフィールドが true で返るのは、archive 状態のまま active 一覧から取得された場合のみで、通常は省略されます |
hasMore | boolean | 次のページが存在するかどうか |
cursor | string | 次ページ取得用カーソル。hasMore が true の場合のみ含まれます |
レスポンス例
JSON
{
"conversations": [
{
"conversationId": "550e8400-e29b-41d4-a716-446655440000",
"title": "売上データ分析",
"createdAt": "2026-03-14T10:30:00Z",
"updatedAt": "2026-03-14T10:35:00Z"
}
],
"hasMore": true,
"cursor": "eyJrIjoiMjAyNi0wMy0xNFQxMDozMDowMC4wMDBaIn0"
}
エラーレスポンス
| ステータス | 説明 |
|---|---|
400 | limit パラメータが不正（1〜100の範囲外）、mode が "active" / "archive" 以外、order が "asc" / "desc" 以外、または title が文字列ではない（複数回指定した場合など） |
GET/v1/conversations/:conversationId/messages
指定した会話のメッセージ履歴を取得します。カーソルベースのページネーションに対応しています。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
conversationId | string | 必須 | 会話のID（UUID） |
クエリパラメータ
| パラメータ | 型 | デフォルト | 説明 |
|---|---|---|---|
limit | integer | 50 | 1 ページの取得件数（1-100） |
cursor | string | — | 次ページ取得用カーソル（前回レスポンスの cursor 値） |
order | string | "desc" | "asc" または "desc" |
リクエスト例
Get messages
1curl https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/messages?order=asc \2-H "Authorization: Bearer <access_token>"レスポンスフィールド（200 OK）
| フィールド | 型 | 説明 |
|---|---|---|
messages | array | メッセージオブジェクトの配列 |
messages[].conversationId | string | 会話ID（UUID） |
messages[].messageId | string | メッセージの一意識別子 |
messages[].sender | string | 送信者。"User" または "AI" |
messages[].text | string | メッセージの本文テキスト |
messages[].createdAt | string | 作成日時（ISO 8601） |
messages[].updatedAt | string | 最終更新日時（ISO 8601） |
messages[].status | object | メッセージの処理状態 |
messages[].status.processing | boolean | エージェントが現在処理中かどうか |
messages[].status.unfinished | boolean | エージェントの応答が中断されたかどうか |
messages[].tasks | array | エージェントが実行したタスクの配列（後述） |
messages[].deliverables | array | エージェントが生成した成果物の配列。存在する場合のみ含まれます |
messages[].deliverables[].filename | string | 成果物のファイル名 |
messages[].deliverables[].filepath | string | 成果物のファイルパス |
messages[].deliverables[].source | string | "agent"（エージェント生成）または "user"（ユーザーアップロード） |
messages[].deliverables[].isPrimary | boolean | 主要成果物かどうか |
messages[].deliverables[].createdAt | string | 作成日時（ISO 8601形式） |
messages[].deliverables[].mimeType | string? | MIME タイプ（例: "application/pdf"、"text/markdown"）。判定できない場合は省略 |
messages[].deliverables[].size | number? | ファイルサイズ（バイト）。0 以下の場合は省略 |
messages[].files | array? | ユーザーが添付したファイルの配列。sender: "User" のメッセージで添付がある場合のみ含まれます |
messages[].files[].fileId | string | ファイルの一意識別子（UUID） |
messages[].files[].mimeType | string | MIME タイプ（例: "image/png"、"application/pdf"） |
messages[].files[].width | number? | 画像の幅（ピクセル）。画像ファイルの場合のみ |
messages[].files[].height | number? | 画像の高さ（ピクセル）。画像ファイルの場合のみ |
messages[].archived | boolean? | archive 経由で取得されたメッセージのみ true。GET /v1/conversations?mode=archive で取得した会話のメッセージ履歴を参照した場合に付与されます |
hasMore | boolean | 次のページが存在するかどうか |
cursor | string | 次ページ取得用カーソル。hasMore が true の場合のみ含まれます |
Task オブジェクト
| フィールド | 型 | 説明 |
|---|---|---|
messageId | string | タスクが属するメッセージのID |
conversationId | string | タスクが属する会話のID |
callId | string? | ツール呼び出しID。Complex Path では複数のタスクが同じ callId を共有し、同一ツール呼び出しのステップ列を識別するために利用される |
actionType | string | タスクの種類（例: ツール実行、コード生成） |
title | string? | タスクのタイトル。存在しない場合は省略される |
description | string? | タスクの説明。存在しない場合は省略される |
status | string | タスクの状態。値は "in_progress" / "completed" / "failed" / "error" / "pending" のいずれか |
content | string? | タスクの実行結果テキスト。存在しない場合は省略される |
metadata | object? | actionType ごとに異なる補助情報（sub_event_type、url、filepath など）。詳細は ストリーミングガイド を参照 |
files | array? | タスクに関連するファイル（filename / size / filepath / mimeType? の構造。MIME タイプ判定不能時は mimeType を省略）。タスクに関連ファイルがない場合は配列自体が省略される |
timestamp | number | タスク実行時のタイムスタンプ（Unix ミリ秒） |
createdAt | string | 作成日時（ISO 8601） |
updatedAt | string | 更新日時（ISO 8601） |
ページネーション
limit を指定すると、その件数ずつ取得できます。hasMore が true の間、レスポンスの cursor をそのまま次のリクエストに渡してください。
リクエスト例
1# 1ページ目2curl "https://<your-domain>/api/v1/conversations/<conversation_id>/messages?limit=50" \3-H "Authorization: Bearer <access_token>"45# 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
}
エラーレスポンス
| ステータス | 説明 |
|---|---|
400 | conversationId が不正なフォーマット |
400 | limit が 1-100 の整数でない |
400 | cursor が不正（前回レスポンスの値以外） |
400 | order が "asc" / "desc" 以外 |
404 | 会話が見つからない |
PATCH/v1/conversations/:conversationId
会話のタイトルを更新します。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
conversationId | string | 必須 | 会話のID（UUID） |
リクエストボディ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
title | string | 必須 | 新しい会話タイトル（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）
| フィールド | 型 | 説明 |
|---|---|---|
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 文字を超える、ボディが壊れた JSON（code: "invalid_body"）、または会話がアーカイブ済み（code: "conversation_archived"） |
415 | ボディの Content-Type が application/json ではない（code: "unsupported_media_type"） |
404 | 会話が見つからない |
DELETE/v1/conversations/:conversationId
会話を削除します。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
conversationId | string | 必須 | 会話の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）
| フィールド | 型 | 説明 |
|---|---|---|
conversationId | string | 削除された会話のID（UUID） |
deleted | boolean | 削除成功時は常に true |
レスポンス例
JSON
{ "conversationId": "550e8400-...", "deleted": true }
エラーレスポンス
| ステータス | 説明 |
|---|---|
400 | conversationId が不正、または会話がアーカイブ済み（code: "conversation_archived"、復元には POST /v1/conversations/:id/restore を使用） |
404 | 会話が見つからない |
409 | 会話が現在処理中のため削除できない |
POST/v1/conversations/:conversationId/restore
アーカイブ済み会話を active に戻します。復元後は通常会話と同様に編集・継続・削除が可能になります。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
conversationId | string | 必須 | アーカイブ済み会話の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）
| フィールド | 型 | 説明 |
|---|---|---|
conversationId | string | 復元された会話のID（UUID） |
restored | boolean | 復元成功時は常に true |
レスポンス例
JSON
{ "conversationId": "550e8400-...", "restored": true }
エラーレスポンス
| ステータス | 説明 |
|---|---|
400 | conversationId が不正 |
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）
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
file | file | 必須 | アップロードするファイル。サイズ上限 512 MB。 |
filename | string | 必須 | ファイル名 |
リクエスト例
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）
| フィールド | 型 | 説明 |
|---|---|---|
fileId | string | ファイルの一意識別子（UUID） |
filename | string | ファイル名 |
bytes | integer | ファイルサイズ（バイト） |
createdAt | string | 作成日時（ISO 8601） |
width | integer | 画像の幅（ピクセル）。画像ファイルの場合のみ |
height | integer | 画像の高さ（ピクセル）。画像ファイルの場合のみ |
レスポンス例
JSON
{
"fileId": "550e8400-e29b-41d4-a716-446655440001",
"filename": "report.pdf",
"bytes": 1048576,
"createdAt": "2026-03-14T10:30:00.000Z"
}
エラーレスポンス
| ステータス | 説明 |
|---|---|
400 | file または filename パラメータが未指定、ファイルサイズが 512 MB を超過、またはアップロードされた画像ファイルが破損している/不正 |
415 | ボディが multipart/form-data ではない（code: "unsupported_media_type"） |
GET/v1/files
ファイル一覧を取得します。カーソルベースのページネーションに対応しています。
クエリパラメータ
| パラメータ | 型 | デフォルト | 説明 |
|---|---|---|---|
limit | integer | 50 | 1 ページの取得件数（1-100） |
cursor | string | — | 次ページ取得用カーソル（前回レスポンスの cursor 値） |
order | string | "desc" | "asc" または "desc" |
リクエスト例
List files
1curl https://<your-domain>/api/v1/files?order=desc \2-H "Authorization: Bearer <access_token>"レスポンスフィールド（200 OK）
| フィールド | 型 | 説明 |
|---|---|---|
files | array | ファイルオブジェクトの配列 |
files[].fileId | string | ファイルの一意識別子（UUID） |
files[].filename | string | ファイル名 |
files[].bytes | integer | ファイルサイズ（バイト） |
files[].createdAt | string | 作成日時（ISO 8601） |
files[].width | integer | 画像の幅（ピクセル）。画像ファイルの場合のみ |
files[].height | integer | 画像の高さ（ピクセル）。画像ファイルの場合のみ |
hasMore | boolean | 次のページが存在するかどうか |
cursor | string | 次ページ取得用カーソル。hasMore が true の場合のみ含まれます |
レスポンス例
JSON
{
"files": [
{
"fileId": "550e8400-e29b-41d4-a716-446655440001",
"filename": "report.pdf",
"bytes": 1048576,
"createdAt": "2026-03-14T10:30:00.000Z"
}
],
"hasMore": false
}
ページネーション
limit を指定すると、その件数ずつ取得できます。hasMore が true の間、レスポンスの cursor をそのまま次のリクエストに渡してください。
リクエスト例
1# 1ページ目2curl "https://<your-domain>/api/v1/files?limit=50&order=desc" \3-H "Authorization: Bearer <access_token>"45# 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 を変更しないでください。条件を変えると対象範囲が変わり、項目の重複や取りこぼしが起きます。
また、ページを取得している間にファイルが追加・削除された場合も、ページ間で重複や取りこぼしが生じることがあります。
エラーレスポンス
| ステータス | 説明 |
|---|---|
400 | limit が 1-100 の整数でない |
400 | cursor が不正（前回レスポンスの値以外） |
400 | order が "asc" / "desc" 以外 |
GET/v1/files/:file_id/content
ファイルをダウンロードします。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
file_id | string | 必須 | ファイル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-Disposition | attachment; filename="ファイル名" |
エラーレスポンス
| ステータス | 説明 |
|---|---|
400 | fileId が不正なフォーマット |
404 | ファイルが見つからない |
DELETE/v1/files/:file_id
ファイルを削除します。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
file_id | string | 必須 | ファイル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）
| フィールド | 型 | 説明 |
|---|---|---|
fileId | string | 削除されたファイルのID（UUID） |
deleted | boolean | 削除成功時は常に true |
レスポンス例
JSON
{ "fileId": "550e8400-e29b-41d4-a716-446655440001", "deleted": true }
エラーレスポンス
| ステータス | 説明 |
|---|---|
400 | fileId が不正なフォーマット |
404 | ファイルが見つからない |
成果物取得
エージェントが生成した成果物ファイルを取得します。
エンドポイント一覧
| メソッド | エンドポイント | 説明 | スコープ (SaaS) |
|---|---|---|---|
| GET | /v1/files/proxy | 成果物ファイルを取得 | chat:exec |
※ Marketplace 版はスコープ不要（認証のみ）。
GET/v1/files/proxy
メッセージ履歴の deliverables[].filepath で取得したパスを指定して、成果物ファイルをダウンロードします。
クエリパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
path | string | 必須 | 成果物のファイルパス（メッセージ履歴の 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 | ファイルサイズ（バイト） |
エラーレスポンス
| ステータス | 説明 |
|---|---|
400 | path パラメータが未指定またはフォーマット不正 |
404 | ファイルが見つからない |
検索
メッセージを全文検索します。
エンドポイント一覧
| メソッド | エンドポイント | 説明 | スコープ (SaaS) |
|---|---|---|---|
| GET | /v1/search/messages | メッセージを全文検索 | chat:history |
※ Marketplace 版はスコープ不要（認証のみ）。
GET/v1/search/messages
メッセージを全文検索します。
クエリパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
q | string | 必須 | 検索クエリ |
order | string | — | ソート順。"asc"（昇順）または "desc"（降順、デフォルト） |
リクエスト例
Search messages
1curl "https://<your-domain>/api/v1/search/messages?q=売上" \2-H "Authorization: Bearer <access_token>"レスポンスフィールド（200 OK）
| フィールド | 型 | 説明 |
|---|---|---|
messages | array | 検索結果のメッセージ配列（最大50件） |
messages[].conversationId | string | 会話ID（UUID） |
messages[].messageId | string | メッセージの一意識別子 |
messages[].text | string | メッセージの本文テキスト |
messages[].title | string | 会話のタイトル |
messages[].sender | string | 送信者。"User" または "AI" |
messages[].createdAt | string | 作成日時（ISO 8601） |
messages[].updatedAt | string | 最終更新日時（ISO 8601） |
messages[].matchedQueries | array | 一致した検索クエリの配列 |
messages[].status | object | メッセージの処理状態 |
messages[].status.processing | boolean | エージェントが現在処理中かどうか |
messages[].status.unfinished | boolean | エージェントの応答が中断されたかどうか |
messages[].tasks | array | エージェントが実行したタスクの配列。フィールド定義は GET /v1/conversations/:conversationId/messages の Task オブジェクトを参照 |
messages[].deliverables | array | エージェントが生成した成果物の配列。存在する場合のみ含まれます |
messages[].deliverables[].filename | string | 成果物のファイル名 |
messages[].deliverables[].filepath | string | 成果物のファイルパス |
messages[].deliverables[].source | string | "agent"（エージェント生成）または "user"（ユーザーアップロード） |
messages[].deliverables[].isPrimary | boolean | 主要成果物かどうか |
messages[].deliverables[].createdAt | string | 作成日時（ISO 8601形式） |
messages[].deliverables[].mimeType | string? | MIME タイプ（例: "application/pdf"、"text/markdown"）。判定できない場合は省略 |
messages[].deliverables[].size | number? | ファイルサイズ（バイト）。0 以下の場合は省略 |
messages[].files | array? | ユーザーが添付したファイルの配列。sender: "User" のメッセージで添付がある場合のみ含まれます。フィールド構造は履歴 API と同じ（fileId / mimeType / width? / height?）。詳細は GET /v1/conversations/:id/messages を参照 |
hasMore | boolean | 常に false（ページネーション非対応）。一致したメッセージが 50 件を超えても 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 パラメータが未指定、または 1 つの文字列として指定されていない（q を複数回指定した場合など）。または order が "asc" / "desc" 以外 |
プロジェクト
プロジェクトは、複数のエージェントを配置して業務を進める単位です。外部システムから、プロジェクトの一覧取得・実行の開始・実行状況の確認ができます。
プロジェクトには 2 つの型があり、実行の起こし方が異なります。
| 型 | 説明 | 実行の起こし方 |
|---|---|---|
workflow | 工程を順に進める型。最初の有効な工程から実行を開始します。 | POST /v1/projects/{projectId}/runs |
cycle | 複数のエージェントをそれぞれのスケジュールで動かし続ける型。外部イベントによる臨時の 1 回を上乗せできます。 | POST /v1/projects/{projectId}/triggers/{triggerId}/fire |
操作できる範囲
プロジェクトの API は、サービスアカウントのトークンでだけ呼べます。利用者としてログインして得たトークンで呼ぶと、どのエンドポイントも
404 Not Found が返ります。操作できるのは、この環境にあるすべてのプロジェクトです。エンドポイント一覧
| メソッド | エンドポイント | 説明 |
|---|---|---|
| GET | /v1/projects | プロジェクト一覧を取得 |
| POST | /v1/projects/{projectId}/runs | プロジェクトの実行を開始 |
| POST | /v1/projects/{projectId}/triggers/{triggerId}/fire | トリガーを発火して臨時に 1 回実行 |
| GET | /v1/projects/{projectId}/runs/{runId} | 実行状況を取得 |
GET/v1/projects
アクセスできるプロジェクトの一覧を取得します。カーソルベースのページネーションに対応しています。cycle 型のプロジェクトも一覧に含まれますが、実行開始（POST /v1/projects/{projectId}/runs）の対象にはなりません。
クエリパラメータ
| パラメータ | 型 | デフォルト | 説明 |
|---|---|---|---|
limit | integer | 50 | 取得件数（1〜100） |
cursor | string | — | 次ページ取得用カーソル（前回レスポンスの cursor 値） |
上記以外のクエリパラメータは無視されます。
レスポンスフィールド（200 OK）
| フィールド | 型 | 説明 |
|---|---|---|
projects | array | プロジェクトオブジェクトの配列 |
projects[].projectId | string | プロジェクト ID（UUID） |
projects[].name | string | プロジェクト名 |
projects[].type | string | "workflow" または "cycle" |
projects[].status | string | プロジェクトの状態。"active" / "paused" / "archived" のいずれか |
projects[].tags | array | タグの配列。設定されていない場合は空の配列 |
hasMore | boolean | 次のページが存在するかどうか |
cursor | string | 次ページ取得用カーソル。hasMore が true の場合のみ含まれます |
レスポンス例
JSON
{
"projects": [
{
"projectId": "550e8400-e29b-41d4-a716-446655440000",
"name": "受注処理フロー",
"type": "workflow",
"status": "active",
"tags": []
},
{
"projectId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "問い合わせ常時対応",
"type": "cycle",
"status": "active",
"tags": []
}
],
"hasMore": false
}
エラーレスポンス
| ステータス | 説明 |
|---|---|
400 | limit（1〜100 の範囲外）または cursor が不正（code は invalid_parameter） |
POST/v1/projects/{projectId}/runs
workflow 型のプロジェクトの実行を開始します。cycle 型に対して呼び出すと 409 Conflict（unsupported_project_type）が返ります。
リクエストヘッダー
| ヘッダー | 必須 | 説明 |
|---|---|---|
Idempotency-Key | 必須 | 呼び出し側が採番する重複実行の防止キー。8〜128 文字で、使用できる文字は半角英数字と _ . : - です |
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
projectId | string | 必須 | プロジェクトの ID（UUID） |
リクエストボディ
ボディは不要です。送信する場合は JSON のオブジェクトにしてください。含めたフィールドは無視されます。
レスポンスフィールド（201 Created / 200 OK）
| フィールド | 型 | 説明 |
|---|---|---|
runId | string | 実行の ID（UUID）。実行状況の取得に使用します |
existing | boolean? | 同じ Idempotency-Key での再送により既存の実行を返した場合に true。初回は含まれません |
初回の呼び出しは 201 Created、同じ Idempotency-Key での再送は 200 OK が返ります。
リクエスト例
curl
curl -X POST https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/runs \
-H "Authorization: Bearer <access_token>" \
-H "Idempotency-Key: nightly-batch-20260917" \
-H "Content-Type: application/json" \
-d '{}'
レスポンス例
JSON
{
"runId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
Idempotency-Key の扱い
- キーはプロジェクト単位で照合されます。有効期限はありません。
- 同じキーで再送すると、プロジェクトが停止した後・同時実行の上限に達した後・その実行が終了した後であっても、同じ実行が返ります。
- タイムアウトなどで成否が分からなくなった場合は、同じキーでそのまま再送してください。二重に実行されることはありません。
- 別の実行を開始したい場合は、必ず新しいキーを採番してください。
エラーレスポンス
| ステータス | code | 説明 |
|---|---|---|
400 | idempotency_key_required | Idempotency-Key ヘッダーが無い |
400 | idempotency_key_invalid | Idempotency-Key の長さまたは文字種が不正 |
400 | invalid_parameter | projectId が UUID の形式ではない |
400 | invalid_body | リクエストボディが壊れた JSON、または JSON のオブジェクトではない |
413 | body_too_large | リクエストボディが 16 KiB を超過 |
415 | unsupported_media_type | リクエストボディがあるのに、Content-Type が application/json ではない |
404 | project_not_found | プロジェクトが存在しない、またはアクセス権が無い |
400 | approvers_required | 有効な確認工程に確認担当者が設定されていない |
409 | unsupported_project_type | cycle 型のプロジェクトを指定した |
409 | project_inactive | プロジェクトが有効な状態ではない（一時停止中、またはアーカイブ済み） |
409 | mixed_runtime | 登録した Agent と、それ以外のエージェントが同じプロジェクトに置かれている |
409 | agent_not_certified | 置いた登録 Agent に、ワークフローで使うための認定が無い |
409 | lanes_not_for_marketplace | 工程の流れにレーンが設定されている（登録した Agent で動くプロジェクトでは、レーンを使えません） |
429 | too_many_active_runs | 同じプロジェクトで、実行中と確認待ちの実行が合わせて上限（3 件）に達している |
POST/v1/projects/{projectId}/triggers/{triggerId}/fire
cycle 型のプロジェクトに設定された Webhook トリガーを発火し、対象のエージェントを臨時に 1 回だけ実行します。workflow 型に対して呼び出すと 404 Not Found が返ります。
定期実行の設定はそのまま維持されます。発火による実行は、定期実行とは別に追加されるものです。発火は 1 件ずつ別に受け付けられ、先の発火にまとまることはありません。同じエージェント配置の同じ工程への発火は、受け付けた順に 1 件ずつ処理されます。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
projectId | string | 必須 | プロジェクトの ID（UUID） |
triggerId | string | 必須 | 発火するトリガーの ID（UUID） |
リクエストボディ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
eventId | string | 必須 | 送信側が採番する一意な ID。同じ ID の再送は重複として扱われます。1〜160 文字で、使用できる文字は半角英数字と _ . : @ + - です |
payload | any | — | エージェントへ渡す任意の JSON。JSON の文字列にして、エージェントへの依頼に添えて渡されます。文字列にしたときに 8,000 文字を超える部分は省略されます |
レスポンスフィールド（202 Accepted）
| フィールド | 型 | 説明 |
|---|---|---|
result | string | "accepted"（新しく受け付けた）または "duplicate"（同じ eventId で受付済み） |
jobId | string | 受付先のジョブ ID。エージェント配置と工程の組み合わせごとに決まり、同じ組み合わせへの発火では同じ値になります（発火ごとには変わりません）。実行状況の取得（GET /v1/projects/{projectId}/runs/{runId}）には使えません |
レスポンス例
JSON
{
"result": "accepted",
"jobId": "9b2e4c61-0f3a-4a9b-9c1d-2f7e5a8b3c40"
}
202 の意味
ここでの 202 Accepted は、受付を記録したことだけを表します。実行はこの後に行われ、その成否はこの応答に含まれません。実行の結果は含まないため、202 を業務上の成功として扱わないでください。
再送
冪等性はプロジェクト・トリガー・eventId の組み合わせで判定されます。同じ内容で再送すると 202 と result: "duplicate" が返ります。同じ eventId で payload が異なる場合は 409 Conflict（event_conflict）が返ります。
エラーレスポンス
| ステータス | code | 説明 |
|---|---|---|
400 | invalid_event_id | eventId が無い、または形式が不正 |
400 | invalid_parameter | projectId または triggerId が UUID の形式ではない |
400 | invalid_body | リクエストボディが壊れた JSON、または JSON のオブジェクトではない |
415 | unsupported_media_type | リクエストボディがあるのに、Content-Type が application/json ではない |
404 | trigger_not_found | プロジェクト・トリガーが存在しない、アクセス権が無い、Webhook ではないトリガーを指定した、または workflow 型のプロジェクトを指定した |
409 | trigger_disabled | トリガーが無効化されている |
409 | project_not_active | プロジェクトが実行可能な状態にない |
409 | placement_unavailable | 発火対象のエージェント配置が存在しない、または実行できる状態にない |
409 | event_conflict | 同じ eventId で payload が異なる |
413 | body_too_large | リクエストボディが 16 KiB を超過 |
429 | queue_full | 同じエージェント配置の同じ工程で実行を待っている発火が上限（20 件）に達している |
GET/v1/projects/{projectId}/runs/{runId}
実行の状況を取得します。API（POST /v1/projects/{projectId}/runs）で開始した実行のほか、画面・定期実行で始まった実行も取得できます。cycle 型のプロジェクトは実行（run）を作らないため、このエンドポイントの対象外です。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
projectId | string | 必須 | プロジェクトの ID（UUID） |
runId | string | 必須 | 実行の ID（UUID） |
レスポンスフィールド（200 OK）
| フィールド | 型 | 説明 |
|---|---|---|
runId | string | 実行の ID（UUID） |
status | string | 実行の状態。"running"（実行中）/ "waiting_gate"（確認待ち）/ "closed_done"（完了）/ "closed_rejected"（却下で終了）/ "closed_failed"（失敗で終了）/ "cancelled"（中断）のいずれか。"running" と "waiting_gate" 以外は、実行が終わったことを表します |
originType | string | null | 実行の始まり方。"manual"（画面から開始）/ "api"（API で開始）/ "cron"（定期実行）のいずれか |
originRef | string | null | 始まり方ごとの参照値。API で開始した実行では、開始したときの Idempotency-Key の値 |
currentStepId | string | null | 進んでいる工程の ID（UUID）。レーンに分かれて進んでいる間は、分岐する前の工程の ID。完了した実行では null。ほかの理由で終わった実行では、終わったときの工程の ID が残る場合があります |
startedByRef | string | null | 実行を始めたもの。値は下の「実行を始めたもの」の表のとおり |
actorLabel | string | null | 利用者ではない起動者の表示名（サービスアカウントの名前）。分からない場合と、それ以外は null |
startedAt | string | null | 開始日時（ISO 8601）。開始前は null |
endedAt | string | null | 終了日時（ISO 8601）。終了前は null |
summary | string | null | 完了した実行で、出力が記録された最後の完了した工程の出力（先頭 2,000 文字）。そうした工程が無い場合と、完了していない実行では null |
runtimeKind | string | null | 実行環境の種類。"marketplace"（登録した Agent で動く実行）または "autonomous"。古い実行では null の場合があります |
cancelRequestedAt | string | null | 中断が求められた日時（ISO 8601）。求められていなければ null |
configRevision | number | null | 案件設定の版。登録した Agent で動く実行で使い、それ以外の実行では null |
steps | array | 工程ごとの実行の記録。記録した順 |
steps[].runStepId | string | 工程の実行の ID（"rs:" で始まる） |
steps[].stepId | string | null | 工程の ID（UUID） |
steps[].placementId | string | null | その工程を担当した配置の ID（UUID）。Agent を動かさない行（確認の工程など）では null |
steps[].executionId | string | null | Agent の実行の ID。Agent を動かし始めると付きます |
steps[].conversationId | string | null | Agent の実行の会話の ID。登録した Agent で動く実行では null |
steps[].status | string | "pending"（実行待ち）/ "running"（実行中）/ "waiting_gate"（確認待ち）/ "done"（完了）/ "failed"（失敗）/ "skipped"（実行を省略）のいずれか |
steps[].attempt | number | null | 同じ回の中での再試行の回数（1 から） |
steps[].lane | string | null | 工程が属するレーンの ID。レーンに分かれていない工程は "main" |
steps[].scheduledAt | string | null | 工程に時刻が設定されているとき、その時刻まで待つ行の予定日時（ISO 8601）。動き始めると null |
steps[].startedAt | string | null | 開始日時（ISO 8601） |
steps[].endedAt | string | null | 終了日時（ISO 8601） |
steps[].outputSummary | string | null | 工程の出力の要約 |
steps[].outcome | string | null | Agent の実行の結果。"completed" / "incomplete" / "failed" / "timeout" / "stopped" / "denied" / "skipped" のいずれか。結果の無い行では null |
steps[].reasonCode | string | null | 結果の理由コード |
steps[].held | boolean | プロジェクトの一時停止で止めていて、再開を待っているか |
steps[].visit | number | null | この工程に来た何回目か（差し戻しで増えます）。記録の無い行では null |
steps[].reworkReason | string | null | 差し戻しの理由 |
steps[].gateFor | string | null | この確認の行が、どの工程の実行（runStepId）のために立ったか |
steps[].routedFrom | string | null | 行き先を決めて工程を飛ばしたとき、行き先を決めた工程の実行（runStepId） |
steps[].late | string | null | 結果が遅れて届き、進行に使わなかった理由 |
steps[].gate | object | null | 確認の工程の要約。確認の工程ではない行では null |
steps[].gate.decision | string | null | "proceed"（進める）/ "send_back"（差し戻す）/ "reject"（却下）のいずれか。決まっていなければ null |
steps[].gate.waitSource | string | null | 何を待つ確認か。"human"（人の判断）/ "external"（外部の条件） |
plannedPlacements | array | 開始したときの設定で、動く予定の工程と配置の並び |
plannedPlacements[].stepId | string | null | 工程の ID（UUID） |
plannedPlacements[].placementId | string | null | 配置の ID（UUID）。確認の工程と Agent の無い工程では null |
lanes | array | 分岐した後の、レーンごとの状況。分岐する前と、レーンを使わない実行では空の配列 |
lanes[].laneId | string | レーンの ID |
lanes[].name | string | null | レーンの名前 |
lanes[].position | number | null | レーンの並び（1 から） |
lanes[].state | string | "running"（実行中）/ "waiting_gate"（確認待ち）/ "arrived"（合流待ち）/ "closed"（終了）のいずれか |
lanes[].currentStepId | string | null | そのレーンで進んでいる工程の ID（UUID）。合流待ちのレーンでは null。終わったレーンでは、最後の工程の ID が残る場合があります |
lanes[].arrived | boolean | 合流する地点に着いたか |
実行を始めたもの
| 始めたもの | startedByRef | actorLabel |
|---|---|---|
| 利用者（画面から開始） | 利用者 ID | null |
| サービスアカウント | "client:" に続くサービスアカウントのクライアント ID | サービスアカウントの名前（分からない場合は null） |
| 定期実行 | null | null |
2026-09-25 より前にサービスアカウントが始めた実行では、startedByRef は null です。
レスポンス例
JSON
{
"runId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "running",
"originType": "api",
"originRef": "nightly-batch-20260917",
"currentStepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
"startedByRef": "client:order-batch",
"actorLabel": null,
"startedAt": "2026-09-17T01:30:00.000Z",
"endedAt": null,
"summary": null,
"runtimeKind": "marketplace",
"cancelRequestedAt": null,
"configRevision": 1,
"steps": [
{
"runStepId": "rs:1042",
"stepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
"placementId": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8",
"executionId": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
"conversationId": null,
"status": "running",
"attempt": 1,
"lane": "main",
"scheduledAt": null,
"startedAt": "2026-09-17T01:30:01.000Z",
"endedAt": null,
"outputSummary": null,
"outcome": null,
"reasonCode": null,
"held": false,
"visit": 1,
"reworkReason": null,
"gateFor": null,
"routedFrom": null,
"late": null,
"gate": null
}
],
"plannedPlacements": [
{ "stepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f", "placementId": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8" },
{ "stepId": "c2f1a8e4-6b3d-4e7a-9c15-8d2e4f6a7b90", "placementId": null }
],
"lanes": []
}
エラーレスポンス
| ステータス | code | 説明 |
|---|---|---|
400 | invalid_parameter | projectId または runId が UUID の形式ではない |
404 | run_not_found | 実行が存在しない、別のプロジェクトの実行を指定した、またはアクセス権が無い |
プロジェクト API の注意事項
| 項目 | 内容 |
|---|---|
| 404 の意味 | プロジェクトが存在しない場合とアクセス権が無い場合は、どのエンドポイントでも同じ 404 Not Found が返り、どちらであるかは応答から区別できません。code はエンドポイントごとに決まっていて、実行の開始は project_not_found、トリガーの発火は trigger_not_found、実行状況の取得は run_not_found です。 |
| 型が対象外の場合 | 発火を workflow に対して呼んだ場合、および実行状況を cycle のプロジェクトに対して呼んだ場合は 404 です。実行の開始を cycle に対して呼んだ場合だけは例外で、409 unsupported_project_type が返ります。 |
| リクエストボディ | 実行の開始とトリガーの発火でボディを送る場合は、JSON オブジェクトにしてください。Content-Type: application/json 以外は 415、壊れた JSON や JSON のオブジェクトではないボディは 400（invalid_body）、16 KiB を超えるボディは 413 が返ります。 |
| 未知のフィールド / クエリ | 仕様に無いフィールドやクエリパラメータは無視されます。仕様にあるクエリパラメータの値が不正な場合と、読めない cursor を指定した場合は 400 Bad Request が返ります。 |
| タイムアウト | 504 Gateway Timeout は「実行されなかったこと」を意味しません。実行の開始は同じ Idempotency-Key で、発火は同じ eventId と同じ本文でそのまま再送してください。 |
エラーレスポンス
HTTP ステータスコード
すべてのエンドポイントで返される可能性のある HTTP ステータスコードです。
| ステータス | 説明 |
|---|---|
400 Bad Request | リクエストパラメータが不正 |
401 Unauthorized | トークンが無効または未指定 |
403 Forbidden | リソースへのアクセス権限なし |
404 Not Found | リソースが存在しない |
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.type | string | エラーの分類。"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.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"
}
}