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

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

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

注記

このページは、システム連携(サービスアカウント)のトークンで呼ぶ API のリファレンスです。システム連携で利用できるのは、チャット・会話管理・ファイル管理・成果物取得・検索・登録 Agent の一覧と、プロジェクトの 9 つの API(プロジェクト)です。アプリケーション(外部ツールでのログイン)のトークンで呼ぶ API は、ユーザー API リファレンス(会話・組織) と ユーザー API リファレンス(プロジェクト) を参照してください。ライブラリ・ライブラリの Agent・スキル・プレイブック・ペルソナ・ユーザー管理・ログ・共有メモリの各 API は SaaS 版でのみ提供されます。SaaS 版の仕様は ユーザー API リファレンス(SaaS 版) と システム連携 API リファレンス(SaaS 版) を参照してください。

ベース URL​

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

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

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

認証​

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

Authorization: Bearer <access_token>

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

このページの API は、サービスアカウントのトークンで呼びます。アプリケーション(外部ツールでのログイン)のトークンで呼べる API は、ユーザー API リファレンスに載せています。外部ツールでのログイン以外で得た利用者のトークン(メイン画面にログインしたときのトークンなど)で呼ぶと、どのエンドポイントも 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")。時間をおいて送り直してください

プロジェクト​

プロジェクトは、複数のエージェントを配置して業務を進める単位です。外部システムから、プロジェクトの一覧取得・実行の開始・実行状況の確認・ワークフローの実行の成果物の取得ができます。

プロジェクトには 2 つの型があり、実行の起こし方が異なります。

型説明実行の起こし方
workflow工程を順に進める型。最初の有効な工程から実行を開始します。POST /v1/projects/{projectId}/runs
cycle複数のエージェントをそれぞれのスケジュールで動かし続ける型。外部イベントによる臨時の 1 回を上乗せできます。POST /v1/projects/{projectId}/triggers/{triggerId}/fire
操作できる範囲
サービスアカウントのトークンで操作できるのは、この環境にあるすべてのプロジェクトです。アプリケーション(外部ツールでのログイン)のトークンでも、ここにある 9 つのエンドポイントと、ほかのプロジェクトの API を呼べます。そのときに操作できる範囲は、プロジェクトへの参加状況と組織の運用の役割で決まります(ユーザー 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}実行状況を取得
POST/v1/projects/{projectId}/runs/{runId}/cancelワークフローの実行を中断
POST/v1/projects/{projectId}/executions/{executionId}/cancelサイクルの巡回の実行を止める
GET/v1/projects/{projectId}/executions/{executionId}実行の状態を取得(状態の項目だけ)
GET/v1/projects/{projectId}/artifactsワークフローの実行の成果物の一覧を取得
GET/v1/projects/{projectId}/artifacts/{artifactId}/content成果物の中身を取得(HEAD も可)

GET/v1/projects

この環境のすべてのプロジェクトの一覧を取得します。カーソルベースのページネーションに対応しています。cycle 型のプロジェクトも一覧に含まれますが、実行開始(POST /v1/projects/{projectId}/runs)の対象にはなりません。

クエリパラメータ​

パラメータ型デフォルト説明
limitinteger50取得件数(1〜100)
cursorstring—次ページ取得用カーソル(前回レスポンスの cursor 値)

上記以外のクエリパラメータは無視されます。

リクエスト例​

List projects
1curl "https://<your-domain>/api/v1/projects?limit=20" \
2-H "Authorization: Bearer <access_token>"

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

フィールド型説明
projectsarrayプロジェクトオブジェクトの配列
projects[].projectIdstringプロジェクト ID(UUID)
projects[].namestringプロジェクト名
projects[].typestring"workflow" または "cycle"
projects[].statusstringプロジェクトの状態。"active" / "paused" / "archived" / "admin_stopped"(管理者が停止)のいずれか
projects[].tagsarrayタグの配列。設定されていない場合は空の配列
hasMoreboolean次のページが存在するかどうか
cursorstring次ページ取得用カーソル。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
}

エラーレスポンス​

ステータス説明
400limit(1〜100 の範囲外)または cursor が不正(code は invalid_parameter)

POST/v1/projects/{projectId}/runs

workflow 型のプロジェクトの実行を開始します。cycle 型に対して呼び出すと 409 Conflict(unsupported_project_type)が返ります。

リクエストヘッダー​

ヘッダー必須説明
Idempotency-Key必須呼び出し側が採番する重複実行の防止キー。8〜128 文字で、使用できる文字は半角英数字と _ . : - です

パスパラメータ​

パラメータ型必須説明
projectIdstring必須プロジェクトの ID(UUID)

リクエストボディ​

ボディは省けます。送信する場合は JSON のオブジェクトにしてください。下のフィールドのほかは無視されます。

パラメータ型必須説明
payloadany—実行の依頼。JSON の値(オブジェクト・配列・文字列など)を、中身を変えずに受け取ります。最初の工程のエージェントが context.start_input で受け取ります(マーケットプレイスのワークフローガイドの「外から始めた run の依頼」を参照)。依頼の中にファイルの ID を入れても、ファイルは添付されません。省略・null は依頼なし。JSON の文字列にして 8,000 文字まで
configobject—入力ファイルと工程の設定。{ "placements": [{ "placementId", "stepId", "parameters", "connectionBindings", "fileBindings" }] } の形で、配置と工程の組ごとに書きます。fileBindings は入力ファイルの名前(置ける登録 Agent の一覧の inputs[].name)から、上げた下書きの artifactId への対応、parameters は登録 Agent の parameters(parametersSchema の形)、connectionBindings は接続の枠の名前から連携先の ID への対応です。placementId・stepId のほかは省けます。省略・null は設定なし

上限は 2 つあります。payload を JSON の文字列にした長さが 8,000 文字を超えると 400 Bad Request(payload_too_large)、ボディ全体が 16 KiB を超えると 413 Payload Too Large(body_too_large)が返ります。

config もボディ全体の 16 KiB に含まれます。

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

フィールド型説明
runIdstring実行の ID(UUID)。実行状況の取得に使用します
existingboolean?同じ Idempotency-Key での再送により既存の実行を返した場合に true。初回は含まれません

初回の呼び出しは 201 Created、同じ Idempotency-Key での再送は 200 OK が返ります。

リクエスト例​

Start run
1curl -X POST https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs \
2-H "Authorization: Bearer <access_token>" \
3-H "Idempotency-Key: nightly-batch-20260917" \
4-H "Content-Type: application/json" \
5-d '{
6 "payload": {
7 "ticketId": "INC-1024",
8 "summary": "ログインできない利用者がいる"
9 }
10}'

レスポンス例​

JSON
{
"runId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
Idempotency-Key の扱い
  • キーはプロジェクト単位で照合されます。有効期限はありません。
  • 同じキーで再送すると、プロジェクトが停止した後・同時実行の上限に達した後・その実行が終了した後であっても、同じ実行が返ります。
  • タイムアウトなどで成否が分からなくなった場合は、同じキーでそのまま再送してください。二重に実行されることはありません。
  • 別の実行を開始したい場合は、必ず新しいキーを採番してください。

同じキーで、違う payload か config を付けて再送すると 409 Conflict(origin_conflict)が返ります。

エラーレスポンス​

ステータスcode説明
400idempotency_key_requiredIdempotency-Key ヘッダーが無い
400idempotency_key_invalidIdempotency-Key の長さまたは文字種が不正
400invalid_parameterprojectId が UUID の形式ではない
400payload_too_largepayload を JSON の文字列にした長さが 8,000 文字を超える
400invalid_bodyリクエストボディが壊れた JSON、または JSON のオブジェクトではない
413body_too_largeリクエストボディが 16 KiB を超過
415unsupported_media_typeリクエストボディがあるのに、Content-Type が application/json ではない
404project_not_foundプロジェクトが存在しない、またはアクセス権が無い
400approvers_required有効な確認工程に確認担当者が設定されていない
409unsupported_project_typecycle 型のプロジェクトを指定した
409project_inactiveプロジェクトが有効な状態ではない(一時停止中、またはアーカイブ済み)
409principal_suspendedプロジェクトを実行する人の利用を、管理者が止めている。管理者に、プロジェクトの持ち主を変更するか、利用の停止を解くよう頼む
409start_step_in_branch_lane開始の工程が条件分岐のレーンの中にある。時間トリガーの開始する工程を、条件分岐のレーンの外の工程にしてください
409definition_pendingプロジェクトの最初の定義が承認待ちの間は始められない。承認する人(ほかのオーナーか組織の管理者)が製品の画面で承認してから始めてください
409relink_required取り込みで見つからなかった参照をつなぎ直すまで、プロジェクトを始められない・再開できない。プロジェクトの取得の relink と配置の relink に、残っている参照が出ます。起動を断る参照の外し方: kind が "agent" の行は Agent を置き直す(POST /v1/projects/{projectId}/placements)、kind が "connector" の行は製品の画面で連携先を保存し直す。blocking が false の行は実行を断らない、必要に応じて再度設定する項目で、DELETE /v1/projects/{projectId}/relink で消せますが、それだけでは始められません
409admin_stoppedプロジェクト、またはプロジェクトに置いた登録 Agentを、管理者が止めている。再開は管理者に頼む(この API では再開できない)
409mixed_runtime登録した Agent と、それ以外のエージェントが同じプロジェクトに置かれている
409agent_not_certified置いた登録 Agent に、ワークフローで使うための認定が無い
409lanes_not_for_marketplaceプロジェクトの流れにレーンがある(登録 Agent のプロジェクトはレーンで進められません)
400invalid_parameter開始の入力の値が正しくない
400missing_input工程が必要とする入力ファイルが無い(前の工程が出していない、または指定していない)
400duplicate_target_path同じ置き先のパスに、2 つ以上の入力ファイルを置こうとしている
400mp_placement_not_in_snapshot工程の登録 Agent が、実行を始めたときの構成に含まれていない
400connection_version_missing接続のバージョンが保存されていない
400invalid_runtime_config配置の実行の設定が、登録 Agent の定義に合わない
400input_binding_cycle入力の受け渡しが循環している
400input_binding_forward_referenceまだ動いていない後の工程の出力を、入力に指定している
400input_binding_unknown_output入力に指定した出力が、元の登録 Agent に無い
400artifact_format_mismatch入力に指定した成果物の形式が、求める形式と違う
400artifact_digest_missing入力に指定した成果物に digest が無い
400invalid_configconfig の形が違う、知らない配置・工程を指している、設定が登録 Agent の定義に合わない、またはプロジェクトの工程に登録 Agent が置かれていない
409artifact_not_ready入力に指定した成果物が、まだ使える状態ではない(または確認した内容と違う)。システム連携のトークンでは、プロジェクトの今のオーナーが上げ、まだ実行に結び付いていない下書きだけを指定できる
409origin_conflict同じ Idempotency-Key で、違う payload か config を送った(同じ起点が、違う中身で使われている)
409connection_version_unavailable接続のバージョンを確かめられない(承認した後に、接続の対象または権限が変わった)
429too_many_active_runs同じプロジェクトで、実行中と確認待ちの実行が合わせて上限(3 件)に達している

POST/v1/projects/{projectId}/triggers/{triggerId}/fire

cycle 型のプロジェクトに設定された Webhook トリガーを発火し、対象のエージェントを臨時に 1 回だけ実行します。workflow 型に対して呼び出すと 404 Not Found が返ります。

定期実行の設定はそのまま維持されます。発火による実行は、定期実行とは別に追加されるものです。発火は 1 件ずつ別に受け付けられ、先の発火にまとまることはありません。同じエージェント配置の同じ工程への発火は、受け付けた順に 1 件ずつ処理されます。

パスパラメータ​

パラメータ型必須説明
projectIdstring必須プロジェクトの ID(UUID)
triggerIdstring必須発火するトリガーの ID(UUID)

リクエストボディ​

パラメータ型必須説明
eventIdstring必須送信側が採番する一意な ID。同じ ID の再送は重複として扱われます。1〜160 文字で、使用できる文字は半角英数字と _ . : @ + - です
payloadany—エージェントへ渡す任意の JSON。JSON の文字列にして、エージェントへの依頼に添えて渡されます。文字列にしたときに 8,000 文字を超える部分は省略されます

リクエスト例​

Fire trigger
1curl -X POST https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/triggers/d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70/fire \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "eventId": "order-20261118-0001",
6 "payload": {
7 "orderId": "A-1024"
8 }
9}'

レスポンスフィールド(202 Accepted)​

フィールド型説明
resultstring"accepted"(新しく受け付けた)または "duplicate"(同じ eventId で受付済み)
jobIdstring受付先のジョブ ID。エージェント配置と工程の組み合わせごとに決まり、同じ組み合わせへの発火では同じ値になります(発火ごとには変わりません)。実行状況の取得(GET /v1/projects/{projectId}/runs/{runId})には使えません
executionIdstring受け付けた巡回の実行の ID。実行の結果の取得・巡回の実行を止めるに使えます。同じ eventId の送り直しでも同じ値です(送り直しの応答には入らないことがあります。そのときは、発火で動いた実行の見分け方で探します)。動き出すまで(1 分ほどかかることがあります。同じエージェント配置の同じ工程に先の発火が待っていれば、その後)は、実行の結果の取得で 404 Not Found(execution_not_found)です

レスポンス例​

JSON
{
"result": "accepted",
"jobId": "9b2e4c61-0f3a-4a9b-9c1d-2f7e5a8b3c40",
"executionId": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f"
}
202 の意味

ここでの 202 Accepted は、受付を記録したことだけを表します。実行はこの後に行われ、その成否はこの応答に含まれません。実行の結果は含まないため、202 を業務上の成功として扱わないでください。

再送​

冪等性はプロジェクト・トリガー・eventId の組み合わせで判定されます。同じ内容で再送すると 202 と result: "duplicate" が返ります。同じ eventId で payload が異なる場合は 409 Conflict(event_conflict)が返ります。

エラーレスポンス​

ステータスcode説明
400invalid_event_ideventId が無い、または形式が不正
400invalid_parameterprojectId または triggerId が UUID の形式ではない
400invalid_bodyリクエストボディが壊れた JSON、または JSON のオブジェクトではない
415unsupported_media_typeリクエストボディがあるのに、Content-Type が application/json ではない
404trigger_not_foundプロジェクト・トリガーが存在しない、アクセス権が無い、Webhook ではないトリガーを指定した、または workflow 型のプロジェクトを指定した
409trigger_disabledトリガーが無効化されている
409project_not_activeプロジェクトが実行可能な状態にない
409principal_suspendedプロジェクトを実行する人の利用を、管理者が止めている。管理者に、プロジェクトの持ち主を変更するか、利用の停止を解くよう頼む
409admin_stoppedプロジェクト、または発火で動かす配置の Agent を、管理者が止めている。再開は管理者に頼む
409placement_unavailable発火対象のエージェント配置が存在しない、または実行できる状態にない
409event_conflict同じ eventId で payload が異なる
413body_too_largeリクエストボディが 16 KiB を超過
429queue_full同じエージェント配置の同じ工程で実行を待っている発火が上限(20 件)に達している

GET/v1/projects/{projectId}/runs/{runId}

実行の状況を取得します。API(POST /v1/projects/{projectId}/runs)で開始した実行のほか、画面・定期実行で始まった実行も取得できます。cycle 型のプロジェクトは実行(run)を作らないため、このエンドポイントの対象外です。

パスパラメータ​

パラメータ型必須説明
projectIdstring必須プロジェクトの ID(UUID)
runIdstring必須実行の ID(UUID)

リクエスト例​

Get run
1curl https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13 \
2-H "Authorization: Bearer <access_token>"

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

フィールド型説明
runIdstring実行の ID(UUID)
statusstring実行の状態。"running"(実行中)/ "waiting_gate"(確認待ち)/ "closed_done"(完了)/ "closed_rejected"(却下で終了)/ "closed_failed"(失敗で終了)/ "cancelled"(中断)のいずれか。"running" と "waiting_gate" 以外は、実行が終わったことを表します
originTypestring | null実行の始まり方。"manual"(画面から開始)/ "api"(API で開始)/ "cron"(定期実行)のいずれか
originRefstring | null始まり方ごとの参照値。API で開始した実行では、開始したときの Idempotency-Key の値
currentStepIdstring | null進んでいる工程の ID(UUID)。完了した実行では null。ほかの理由で終わった実行では、終わったときの工程の ID が残る場合があります
startedByRefstring | null実行を始めたもの。値は下の「実行を始めたもの」の表のとおり
actorLabelstring | null利用者ではない起動者の表示名(サービスアカウントの名前)。分からない場合と、それ以外は null
startedAtstring | null開始日時(ISO 8601)。開始前は null
endedAtstring | null終了日時(ISO 8601)。終了前は null
summarystring | null完了した実行で、出力が記録された最後の完了した工程の出力(先頭 2,000 文字)。そうした工程が無い場合と、完了していない実行では null
runtimeKindstring | null実行環境の種類。"marketplace"(登録した Agent で動く実行)または "autonomous"。古い実行では null の場合があります
cancelRequestedAtstring | null中断が求められた日時(ISO 8601)。求められていなければ null
deadlineAtstring | nullワークフローの実行の締め切り(ISO 8601)。締め切りが無ければ null
configRevisionnumber | null案件設定のバージョン。登録した Agent で動く実行で使い、それ以外の実行では null
stepsarray工程ごとの実行の記録。記録した順
steps[].runStepIdstring工程の実行の ID("rs:" で始まる)
steps[].stepIdstring | null工程の ID(UUID)
steps[].placementIdstring | nullその工程を担当した配置の ID(UUID)。Agent を動かさない行(確認の工程など)では null
steps[].executionIdstring | nullAgent の実行の ID。Agent を動かし始めると付きます
steps[].conversationIdstring | nullAgent の実行の会話の ID。登録した Agent で動く実行では null
steps[].statusstring"pending"(実行待ち)/ "running"(実行中)/ "waiting_gate"(確認待ち)/ "done"(完了)/ "failed"(失敗)/ "skipped"(実行を省略)のいずれか
steps[].attemptnumber | null同じ回の中での再試行の回数(1 から)
steps[].lanestring | nullいつも "main"
steps[].scheduledAtstring | null工程に時刻が設定されているとき、その時刻まで待つ行の予定日時(ISO 8601)。動き始めると null
steps[].startedAtstring | null開始日時(ISO 8601)
steps[].endedAtstring | null終了日時(ISO 8601)
steps[].outputSummarystring | null工程の出力の要約
steps[].outcomestring | nullAgent の実行の結果。"completed" / "incomplete" / "failed" / "timeout" / "stopped" / "denied" / "skipped" のいずれか。結果の無い行では null
steps[].reasonCodestring | null結果の理由コード。条件分岐で決められず人に選択してもらうときは "branch_undecided"、条件分岐で選ばれなかったレーンの工程は "branch_not_selected"
steps[].heldbooleanプロジェクトの一時停止で止めていて、再開を待っているか
steps[].visitnumber | nullこの工程に来た何回目か(差し戻しで増えます)。記録の無い行では null
steps[].reworkReasonstring | null差し戻しの理由
steps[].gateForstring | nullこの確認の行が、どの工程の実行(runStepId)のために立ったか
steps[].routedFromstring | null次の工程を決定して工程を飛ばしたとき、次の工程を決定した工程の実行(runStepId)
steps[].latestring | null結果が遅れて届き、進行に使わなかった理由
steps[].gateobject | null確認の要約。確認の工程の行に付きます。それ以外の行では null
steps[].gate.decisionstring | null"proceed"(進める)/ "send_back"(差し戻す)/ "reject"(却下)のいずれか。決まっていなければ null
steps[].gate.waitSourcestring | null何を待つ確認か。"human"(人の判断)/ "external"(外部の条件)
steps[].resumeCommandIdstring | nullいつも null
steps[].resumeReasonstring | nullいつも null
steps[].supersededBystring | nullいつも null
steps[].gateKindstring | nullいつも null
steps[].connectionConfirmOfstring | nullいつも null
plannedPlacementsarray開始したときの設定で、動く予定の工程と配置の並び
plannedPlacements[].stepIdstring | null工程の ID(UUID)
plannedPlacements[].placementIdstring | null配置の ID(UUID)。確認の工程と Agent の無い工程では null
lanesarrayいつも空の配列
実行を始めたもの​
始めたものstartedByRefactorLabel
利用者(画面・API から開始)利用者 IDnull
サービスアカウント"client:" に続くサービスアカウントのクライアント IDサービスアカウントの名前(分からない場合は null)
定期実行nullnull

2026-09-25 より前にサービスアカウントが始めた実行では、startedByRef は null です。

レスポンス例​

JSON
{
"runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"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,
"deadlineAt": 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,
"resumeCommandId": null,
"resumeReason": null,
"supersededBy": null,
"gateKind": null,
"connectionConfirmOf": null
}
],
"plannedPlacements": [
{ "stepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f", "placementId": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8" },
{ "stepId": "c2f1a8e4-6b3d-4e7a-9c15-8d2e4f6a7b90", "placementId": null }
],
"lanes": []
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId または runId が UUID の形式ではない
404run_not_found実行が存在しない、別のプロジェクトの実行を指定した、またはアクセス権が無い

POST/v1/projects/{projectId}/runs/{runId}/cancel

実行中か確認待ちのワークフローの実行(status が "running"・"waiting_gate")を中断します。画面の「中断する」と同じです。

中断すると、次のようになります。

  • ワークフローの実行の status が "cancelled"(中断)になります。元に戻せません。
  • まだ起動していない工程は起動されません。動いている工程の Agent には停止を伝えます(その工程の行の status は、止まるまで変わらないことがあります)。
  • 確認工程の、まだ判断されていない確認依頼は取り下げられます。

パスパラメータ​

パラメータ型必須説明
projectIdstring必須プロジェクト ID(UUID)
runIdstring必須ワークフローの実行の ID(UUID)

リクエストボディ​

フィールド型必須説明
commandIdstring必須送り直しを見分ける値(英数字と _ . : - の 8〜128 文字)
reasonstring—中断の理由(500 文字まで)
  • 動いていないワークフローの実行(終わった後・中断した後)に送ると、何も変えずに 200 OK が返り、existing が true です。中断した後に送り直したときも同じです。
  • ほかの中断や、ワークフローの実行が終わるのと同じころに送ると、202 Accepted と 200 OK の別と existing が、実際と合わないことがあります。結果は、ワークフローの実行の取得(GET /v1/projects/{projectId}/runs/{runId})の status で確かめてください。
  • 504 Gateway Timeout は「中断されなかった」ことを意味しません。同じ commandId で送り直すか、ワークフローの実行の取得で status を確かめてください。

リクエスト例​

Cancel run
1curl -X POST https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/cancel \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "commandId": "cancel-20261118-0001",
6 "reason": "入力データの誤りに気づいたため"
7}'

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

この要求で新しく中断したときは 202 Accepted、新しく中断しなかったときは 200 OK です。

フィールド型説明
runIdstringワークフローの実行の ID
statusstring送った後のワークフローの実行の状態(中断したときは "cancelled")
cancelRequestedAtstring | null中断を受けた日時(ISO 8601)。中断されていないワークフローの実行では null
existingbooleanこの要求で新しく中断しなかったとき true(202 Accepted のときはいつも false)

レスポンス例​

JSON
{
"runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"status": "cancelled",
"cancelRequestedAt": "2026-11-18T05:12:30.000Z",
"existing": false
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId・runId が UUID の形式ではない、commandId が無い・形の誤り、または reason が文字列ではない・500 文字を超える
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
404run_not_foundワークフローの実行が存在しない、ほかのプロジェクトのもの、またはアクセス権の無いプロジェクト
413body_too_largeボディが 16 KiB を超える
415unsupported_media_typeボディの Content-Type が application/json ではない

POST/v1/projects/{projectId}/executions/{executionId}/cancel

cycle のプロジェクトで、巡回の実行を止めます。画面の「停止する」と同じです。ボディは要りません(送っても使いません)。

  • 止められるのは、cycle のプロジェクトの巡回の実行だけです。workflow の工程の実行(rs:<数値>)を指定すると 400 Bad Request(invalid_parameter)です。ワークフローの実行は、ワークフローの実行の中断で止めてください。
  • 受け付けてから実行が止まるまで、1 分ほどかかることがあります。止まったかは、実行の結果の取得(GET /v1/projects/{projectId}/executions/{executionId})で確かめてください。システム連携(サービスアカウント)のトークンでも呼べます(状態の項目だけを返します)。止める要求を受けたときに、まだ動き出していなかった実行は、実行の結果の取得で 404 Not Found(execution_not_found)のままです。
  • 前に止める要求を受けていた実行と、終わっていた実行は、何も変えずに 200 OK が返り、existing が true です。

パスパラメータ​

パラメータ型必須説明
projectIdstring必須プロジェクト ID(UUID)
executionIdstring必須巡回の実行の ID(UUID)

リクエスト例​

Cancel execution
1curl -X POST https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/a1b2c3d4-e5f6-4789-8abc-def012345678/cancel \
2-H "Authorization: Bearer <access_token>"

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

新しく止める要求を受けたときは 202 Accepted、そうでないときは 200 OK です。

フィールド型説明
executionIdstring実行の ID
statestring受け付けたときの状態。止まったかどうかは表しません(確かめ方は、この節の初めの箇条にあります)。値の例: "dispatched"(動いている実行に止める要求を伝えた)、"cancelled"(まだ動き出していなかった実行を取り消した)、"terminal"(すでに終わっていた実行)。ほかにも、受け付けた時点の実行や送信の状態の値がそのまま入ります。値の一覧を決めて使わないでください
existingboolean前に止める要求を受けていた、または実行が終わっていたとき true(202 Accepted のときはいつも false)

レスポンス例​

JSON
{
"executionId": "a1b2c3d4-e5f6-4789-8abc-def012345678",
"state": "dispatched",
"existing": false
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId が UUID の形式ではない、executionId が rs:<数値> でも UUID でもない、または executionId が workflow の工程の実行
400invalid_bodyボディが壊れた JSON、または JSON のオブジェクトではない
404execution_not_found実行が存在しない、ほかのプロジェクトの実行、cycle ではないプロジェクト、またはアクセス権の無いプロジェクト
413body_too_largeボディが 16 KiB を超える
415unsupported_media_typeボディがあるのに、Content-Type が application/json ではない

GET/v1/projects/{projectId}/executions/{executionId}

実行の状態(動いているか・終わったか・どう終わったか)を取得します。サービスアカウントのトークンでは、下の状態の項目だけを返します。アプリケーション(外部ツールでのログイン)のトークンで呼ぶと、ユーザー API リファレンス(プロジェクト)の実行の結果の取得と同じ項目を返します。

  • サイクルの巡回の実行は、トリガーの発火の応答の executionId で読めます。動き出すまで(1 分ほどかかることがあります)は 404 Not Found(execution_not_found)です。巡回の実行を止めた後に、止まったかを確かめるときにも使います。
  • workflow の工程の実行は、ワークフローの実行の取得の steps[].executionId(UUID)で読めます。応答の executionId は rs:<数値> で、この形の ID でも読めます。

パスパラメータ​

パラメータ型必須説明
projectIdstring必須プロジェクト ID(UUID)
executionIdstring必須実行の ID(rs:<数値> または UUID)

リクエスト例​

Get execution status
1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/a1b2c3d4-e5f6-4789-8abc-def012345678 \
2-H "Authorization: Bearer <access_token>"

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

サービスアカウントのトークンで呼んだときの項目です。

フィールド型説明
executionIdstring実行の ID。workflow は rs:<数値>、cycle は UUID
kindstring | null"run_step"(workflow の工程)または "sweep"(cycle の巡回)
runIdstring | nullワークフローの実行の ID。cycle は null
stepIdstring | null工程の ID
placementIdstring | null配置の ID
attemptnumber | null試行の回数(基盤の失敗でやり直すと増えます。cycle は起動し直すと新しい実行になり、増えません)
outcomestring | null結果(ユーザー API リファレンス(プロジェクト)の「結果の値」)
reasonCodestring | null結果の理由。cycle は実行の終わり方の理由(例: "guardrail_blocked")、workflow は工程の報告の理由
resultStatestring | null"terminal"(結果あり)/ "running"(実行中)/ "missing"(記録不足)/ "unmeasured"(完遂を測っていない)/ "not_applicable"(確認工程など、Agent の実行ではない行)
terminalboolean終わっているかどうか
startedAtstring | null開始日時(ISO 8601)
endedAtstring | null終了日時(ISO 8601)

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId が UUID の形式ではない、または executionId が rs:<数値> でも UUID でもない
404execution_not_found実行が存在しない、ほかのプロジェクトの実行、まだ動き出していない巡回の実行、またはアクセス権の無いプロジェクト

レスポンス例​

JSON
{
"executionId": "a1b2c3d4-e5f6-4789-8abc-def012345678",
"kind": "sweep",
"runId": null,
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"attempt": 1,
"outcome": "completed",
"reasonCode": null,
"resultState": "terminal",
"terminal": true,
"startedAt": "2026-11-18T01:30:05.000Z",
"endedAt": "2026-11-18T01:34:40.000Z"
}

GET/v1/projects/{projectId}/artifacts

ワークフローの実行の成果物(開始で結んだ入力ファイルと、工程が作った出力)の一覧を、作られた順に全件取得します。中身は、成果物の中身の取得(GET /v1/projects/{projectId}/artifacts/{artifactId}/content)で読みます。サービスアカウントのトークンでは、この環境にあるすべてのプロジェクトの成果物を読めます。run_id が必要です。

パスパラメータ​

パラメータ型必須説明
projectIdstring必須プロジェクト ID(UUID)

クエリパラメータ​

パラメータ型デフォルト説明
run_idstring—必須。ワークフローの実行の ID(UUID)

リクエスト例​

List run artifacts
1curl "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/artifacts?run_id=7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13" \
2-H "Authorization: Bearer <access_token>"

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

フィールド型説明
artifactsarray成果物の配列
artifacts[].artifactIdstring | null成果物の ID(UUID)
artifacts[].runIdstring | nullワークフローの実行の ID
artifacts[].namestring | null成果物の名前
artifacts[].mimeTypestring | null成果物の MIME タイプ
artifacts[].sizenumber | null大きさ(バイト)
artifacts[].statusstring | null"ready"(読める)または "uploading"(書き終わっていない)
artifacts[].createdAtstring | null作られた日時(ISO 8601)
hasMorebooleanいつも false(全件を返します)

レスポンス例​

JSON
{
"artifacts": [
{
"artifactId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"name": "report.md",
"mimeType": "text/markdown",
"size": 2048,
"status": "ready",
"createdAt": "2026-11-18T05:30:00.000Z"
}
],
"hasMore": false
}

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId が UUID の形式ではない、または run_id が無い・UUID の形式ではない
404project_not_foundプロジェクトが存在しない
404run_not_foundワークフローの実行が存在しない、またはほかのプロジェクトのもの

GET/v1/projects/{projectId}/artifacts/{artifactId}/content

成果物の中身を取得します。HEAD でも呼べます。本文を除いて同じヘッダーが返るので、先に大きさを確かめられます。GET で読むと、記録 (証跡) に閲覧(forensic.viewed)が残ります(HEAD では残りません)。サービスアカウントのトークンで読んだときは、システム連携として残ります。

パスパラメータ​

パラメータ型必須説明
projectIdstring必須プロジェクト ID(UUID)
artifactIdstring必須成果物の ID(UUID)。成果物の一覧の artifactId

リクエスト例​

Get run artifact content
1curl https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/artifacts/1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d/content \
2-H "Authorization: Bearer <access_token>"

レスポンス(200 OK)​

成果物の中身が、そのまま返ります。

レスポンスヘッダー説明
Content-Type成果物の MIME タイプ
Content-Length大きさ(バイト)
X-Content-Type-Options"nosniff"
Content-Disposition"attachment"(ダウンロードとして返します)

エラーレスポンス​

ステータスcode説明
400invalid_parameterprojectId・artifactId が UUID の形式ではない
404artifact_not_foundプロジェクトまたは成果物が存在しない、成果物がほかのプロジェクトのもの、またはワークフローの実行の成果物ではない
409artifact_not_ready成果物がまだ書き終わっていない

プロジェクト API の注意事項​

項目内容
404 の意味プロジェクトが存在しない場合とアクセス権が無い場合は、どのエンドポイントでも同じ 404 Not Found が返り、どちらであるかは応答から区別できません。code はエンドポイントごとに決まっていて、実行の開始は project_not_found、トリガーの発火は trigger_not_found、実行状況の取得とワークフローの実行の中断は run_not_found です。成果物の一覧は project_not_found(実行が無いときは run_not_found)、成果物の中身の取得は artifact_not_found です。サイクルの巡回の実行の停止と実行の状態の取得は execution_not_found です。
型が対象外の場合発火を workflow に対して呼んだ場合、および実行状況の取得とワークフローの実行の中断を cycle のプロジェクトに対して呼んだ場合は 404 です。サイクルの巡回の実行の停止を workflow のプロジェクトに対して呼んだ場合も 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 と同じ本文で、ワークフローの実行の中断は同じ commandId で、そのまま再送してください。サイクルの巡回の実行の停止も、そのまま再送できます。

エラーレスポンス​

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)。