Skip to main content

System Integration API Reference

Endpoint specification and error codes for the System Integration API of the Marketplace edition.

note

This page is the reference for the APIs called with a system integration (service account) token. A system integration can use Chat, Conversation Management, File Management, Artifact Retrieval, Search, Registered Agents and nine project APIs (Projects). For the APIs called with an application (sign-in from an external tool) token, see the User API Reference (Conversations, Organizations) and the User API Reference (Projects). The Library, Library Agent, Skills, Playbooks, Persona, User Management, Logs and Shared Memory APIs are available in the SaaS edition only. See the User API Reference (SaaS) and the System Integration API Reference (SaaS) for those.

Base URL​

Send all API requests to the following base URL. Replace <your-domain> with the domain of your deployment.

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

Endpoint paths in this document are relative to the base URL.

Authentication​

Every API request must include a Bearer token in the Authorization header.

Authorization: Bearer <access_token>

If the token is missing or invalid, 401 Unauthorized is returned. The Marketplace edition applies no scope restrictions.

Call the APIs on this page with a service account token. The APIs that can be called with an application (sign-in from an external tool) token are in the User API References. Calling them with a user token obtained in any other way (such as the token used when signing in to the Main Screen) returns 404 Not Found for every endpoint.

For how to obtain a token, see the Authentication Guide and the Authentication API Reference.

Chat API

In the Marketplace edition the Chat API requires the agentId parameter and always runs with stream: true. See the Call the API for details.

Common Rules​

These rules apply to the APIs on this page.

How requests are handled​

The APIs on this page handle requests as follows. See each endpoint's description and error responses for endpoint-specific handling.

What you sentHow it is handled
Query parameters and body fields not in the specificationIgnored. However, even items not listed on this page may return 400 Bad Request if their type or value is wrong, when the service accepts them
An invalid value for a query parameter in the specification400 Bad Request
An invalid URL encoding in a path parameter value (a % sequence)400 Bad Request (invalid_parameter)
A malformed JSON body400 Bad Request (invalid_body)
A body other than Content-Type: application/json, or a body with an unsupported character set (charset), sent to an endpoint that accepts a JSON body415 Unsupported Media Type (unsupported_media_type)
A body other than multipart/form-data sent to a file upload415 Unsupported Media Type
A body field of the wrong type400 Bad Request

If reading the body results in 400 (malformed JSON and so on) or 413 (the size limit was exceeded and so on), that is returned before 415.

Pagination​

List endpoints support cursor-based pagination.

ParameterTypeDescription
limitintegerNumber of items per page (1-100). Defaults to 50.
cursorstringCursor value for the next page. Pass the cursor from the previous response as is.
orderstringSort order: "asc" or "desc" (default). Any other value returns 400 Bad Request. Supported on some endpoints only.

Responses include a hasMore field. While it is true, pass the cursor value in the next request to retrieve the following page.

Cursor-based pagination is available on the list endpoints of Conversations, Messages, Files, Message search and Projects. Treat cursor as opaque: do not interpret it, just pass the previous value back.

Chat​

OpenAI-compatible Chat Completions API. Conversations with the agent are delivered via SSE (Server-Sent Events) streaming.

The Chat API consists of three endpoints. You can send messages, reconnect to existing conversations, and cancel conversations in progress.

SSE Streaming Guide

Detailed explanation of connection flow, response objects, Delta extensions, execution patterns, reconnection, and error handling

View guide

Endpoint List​

メソッドエンドポイント説明Scope (SaaS)
POST/v1/chat/completionsSend a chat message and receive a response via SSE streamingchat:exec
GET/v1/chat/completions/:conversationIdReconnect to the SSE stream of a conversation in progresschat:exec
POST/v1/chat/completions/:conversationId/cancelCancel a conversation in progresschat:exec

Note: The Marketplace edition does not require scopes (authentication only).

POST/v1/chat/completions

Send a message to the agent and receive a response via SSE streaming. Responses are delivered in OpenAI-compatible Chat Completion Chunk format.

Request Headers​

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

Request Body​

パラメータ型必須説明
modelstring必須The model ID to use. Specify "AGENTIC STAR".
messagesarray必須Array of message objects. At least one user-role message is required. Even if multiple user messages are included, only the last one is processed. Conversation history is managed on the server side, so you do not need to send past exchanges in the messages array. To continue an existing conversation, specify the previous conversation ID in the conversationId parameter.
streamboolean必須Specify true. Currently, only streaming mode is supported.
conversationIdstring—Specify a conversation ID to continue an existing conversation. If omitted, a new conversation is created.

Edition-Specific Parameters​

Marketplace
agentIdstringThe ID of the agent to use (required). Use a marketplaceAgentId returned by GET /v1/marketplace-agents.
outputFormatstringResponse text format. "plain" (default) returns plain text with Markdown removed (diagrams dropped, code block bodies kept, and links become "text (URL)"). "markdown" preserves Markdown as-is.

Message Object​

パラメータ型必須説明
rolestring必須Use "user". "assistant" / "system" are accepted but only "user" is effectively used as the starting point of the agent turn in the current implementation
contentstring | array必須The message content. A string, or an array of content parts (text / input_file). The text to be processed must be 1 MB or less in UTF-8.

Content Parts (Array Format)​

When specifying content as an array, the following part types are available. You can combine text and files in a single message.

typeParameterDescription
"text"text (string)Text message
"input_file"fileId (string)The fileId of an uploaded file. Up to 20 files total per request

Request Example​

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": "Please analyze the sales data"
12 }
13 ]
14}'

Response Headers​

HeaderDescription
Content-Typetext/event-stream
X-Conversation-IdConversation ID. For new conversations, a server-generated ID is returned.
X-Message-IdThe assistant response message ID.

SSE Response Format​

Responses are delivered as SSE events in the following order. Each event is a JSON line prefixed with data:.

SSE Event Flow
1. data: {"choices":[{"delta":{"role":"assistant"}}]}
2. data: {"choices":[{"delta":{"content":"..."}}]} × N
3. data: {"choices":[{"finishReason":"stop"}]}
4. data: [DONE]

Responses are delivered via SSE (Server-Sent Events) streaming. Each chunk is in OpenAI-compatible ChatCompletionChunk format. For details on the connection lifecycle, response objects, agent extension fields, and error handling, see the Streaming Guide.

Response Example​

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":"Analyzing"},"finishReason":null}]}

data: {"createdAt":"2026-03-14T10:30:00Z","model":"AGENTIC STAR","choices":[{"index":0,"delta":{"content":" the sales data."},"finishReason":null}]}

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

data: [DONE]

Error Response​

Errors before the SSE stream starts are returned in JSON format. Errors during the stream are delivered as SSE chunks.

StatusDescription
400Invalid request parameters (missing or malformed model / messages / stream / conversationId / role / content, or more than 20 input_file parts in a single request). A malformed JSON body (code: "invalid_body"). Or the specified conversationId is archived (code: "conversation_archived")
400The messages array has no message with the user role (code: "no_user_message")
415The body Content-Type is not application/json (code: "unsupported_media_type")
403The specified conversation is a project conversation (code: "project_conversation". Messages cannot be sent to a project conversation)
404The fileId of the specified input_file was not found (code: "file_not_found")
409The specified conversation is currently being processed (code: "conversation_processing")

GET/v1/chat/completions/:conversationId

Reconnect to the SSE stream of a conversation in progress. Use this when the agent is processing a long-running task or to recover after a network disconnection.

Path Parameters​

パラメータ型必須説明
conversationIdstring必須The ID of the conversation to reconnect to

Request Example​

Resume SSE stream
1curl https://<your-domain>/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000 \
2-H "Authorization: Bearer <access_token>"

Response (200 OK)​

Reconnects to the SSE stream. The response format is the same as POST /v1/chat/completions. The response headers include X-Conversation-Id and X-Message-Id. For detailed reconnection procedures, see the Streaming Guide.

Error Response​

StatuscodeDescription
404not_foundThe conversation was not found, is not in progress, or is not yours (the same applies when conversationId is an empty value)

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

Cancel a conversation in progress. Use this to abort the agent's execution.

Path Parameters​

パラメータ型必須説明
conversationIdstring必須The ID of the conversation to cancel

Request Body (optional)​

パラメータ型必須説明
messageIdstring—The ID of the message to cancel (UUID). If omitted, cancels the entire conversation.

Request Example​

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"

Response Fields (200 OK)​

FieldTypeDescription
conversationIdstringThe ID of the cancelled conversation (UUID)
cancelledbooleanAlways true on successful cancellation

Response Example​

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

Error Response​

StatusDescription
400Invalid conversationId, messageId is not a string, the body is malformed JSON or not a JSON object (code: "invalid_body"), or the conversation is archived (code: "conversation_archived")
400The message of messageId does not belong to the specified conversation (code: "conversation_mismatch")
400The endpoint of this conversation does not support cancellation (code: "unsupported_endpoint"), or cancellation is not enabled in this environment (code: "post_processing_not_enabled")
415The body Content-Type is not application/json (code: "unsupported_media_type")
404Conversation not found, or the message cannot be canceled (code: "message_not_found"). message_not_found is returned in two cases: the message was just sent and could not be canceled after waiting about 10 seconds (sending again in a few seconds cancels it), or the message of messageId does not exist or is not yours (sending again does not cancel it; check messageId)
404The message of messageId is not being processed (it has already finished) (code: "not_processing")

Registered Agents​

Gets the list of registered agents you can run in chat.

Endpoints​

メソッドエンドポイント説明
GET/v1/marketplace-agentsList registered agents

GET/v1/marketplace-agents

Lists every registered agent you can run in chat (agentId of POST /v1/chat/completions), the active ones only. The same agents also run in MCP (agentId of execute_chat) where the MCP endpoint is enabled and you use the chat toolset (?toolsets=chat, the default), and in A2A (/v1/a2a/agents/{agentId}/) where the A2A endpoint is enabled. It is the same list as the MCP list_agents tool and can be up to 5 minutes old. In chat, pass marketplaceAgentId as agentId.

Request Example​

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

Response Fields (200 OK)​

FieldTypeDescription
marketplaceAgentsarrayRegistered agents (all the active ones)
marketplaceAgents[].marketplaceAgentIdstringID of the registered agent. In chat, pass it as agentId
marketplaceAgents[].displayNamestringDisplay name
marketplaceAgents[].descriptionstringDescription. The display name for an agent without a description
marketplaceAgents[].tagsstring[]Tags
hasMorebooleanAlways false (all of them are returned)

Response Example​

JSON
{
"marketplaceAgents": [
{
"marketplaceAgentId": "sales-report",
"displayName": "Sales report",
"description": "Summarizes sales data into a report",
"tags": ["report"]
}
],
"hasMore": false
}

Error Responses​

StatuscodeDescription
401—The token is missing or invalid (see the common errors section)
502upstream_connection_errorThe list of registered agents could not be read
502upstream_api_errorThe source of the list returned an error
504upstream_timeoutReading the list did not finish in time

Conversation Management​

List, retrieve message history, delete, and update titles of conversations.

Endpoint List​

メソッドエンドポイント説明Scope (SaaS)
GET/v1/conversationsList conversationschat:history
GET/v1/conversations/:conversationId/messagesGet message historychat:history
PATCH/v1/conversations/:conversationIdUpdate conversation titlechat:history
DELETE/v1/conversations/:conversationIdDelete a conversationchat:history
POST/v1/conversations/:conversationId/restoreRestore archived conversationchat:history
POST/v1/conversations/:conversationId/readMark a conversation as readchat:history

Note: The Marketplace edition does not require scopes (authentication only).

Archived conversations are deleted automatically once the retention period set by an administrator has passed since they were archived. Their messages, and the attached and artifact files used only by that conversation, are deleted with them. If no retention period is set, they are not deleted.

Operations on archived conversations​

Conversations retrieved with mode=archive only support read operations (list / message history) and restoration. The following operations return a 400 error (code: "conversation_archived").

OperationBehavior on archived conversations
GET /v1/conversations?mode=archive✅ Allowed
GET /v1/conversations/:id/messages✅ Allowed (messages[].archived: true is added)
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 (continuing an existing conversation)❌ 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✅ Restore to active

GET/v1/conversations

List conversations. Supports cursor-based pagination.

Query Parameters​

パラメータ型必須デフォルト説明
limitinteger—50Number of items to return (1-100)
cursorstring——Cursor for the next page (the cursor value from the previous response)
orderstring—"desc""asc" or "desc"
titlestring——Filter by title
modestring—"active""active" (regular conversations) or "archive" (archived conversations). Switching `mode` switches to a different data store, so a `cursor` cannot be carried over

Request Example​

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

Response Fields (200 OK)​

FieldTypeDescription
conversationsarrayArray of conversation objects
conversations[].conversationIdstringUnique identifier of the conversation (UUID)
conversations[].titlestringConversation title
conversations[].typestring?Kind of conversation: "chat" (chat) or "mail" (started from mail). Conversations of project steps are not in the list (their messages can be read by specifying the conversation ID). Not returned with mode=archive
conversations[].createdAtstringCreation date and time (ISO 8601)
conversations[].updatedAtstringLast updated date and time (ISO 8601)
conversations[].archivedboolean?Whether archived. Always true when retrieved via mode=archive. When mode=active returns this field as true, it is only because the conversation remained in archive state but was returned by the active list — usually omitted
hasMorebooleanWhether the next page exists
cursorstringCursor for fetching the next page. Included only when hasMore is true

Response Example​

JSON
{
"conversations": [
{
"conversationId": "550e8400-e29b-41d4-a716-446655440000",
"title": "Sales data analysis",
"type": "chat",
"createdAt": "2026-03-14T10:30:00Z",
"updatedAt": "2026-03-14T10:35:00Z"
}
],
"hasMore": true,
"cursor": "eyJrIjoiMjAyNi0wMy0xNFQxMDozMDowMC4wMDBaIn0"
}

Error Response​

StatuscodeDescription
400invalid_parameterlimit is invalid (outside 1-100), mode is not "active" / "archive", order is not "asc" / "desc", cursor is invalid (not a value from the previous response), or title is not a string (for example, it was specified more than once)
502upstream_connection_errorThe list of conversations could not be retrieved (retry after a while)

GET/v1/conversations/:conversationId/messages

Retrieve the message history of a specified conversation. Cursor-based pagination is supported. Retrieving it does not mark the conversation as read (the same goes for reading via MCP or A2A). To mark it as read, call Mark a conversation as read.

Path Parameters​

パラメータ型必須説明
conversationIdstring必須Conversation ID (UUID)

Query Parameters​

パラメータ型必須デフォルト説明
limitinteger—50Number of items per page (1-100)
cursorstring——Cursor for the next page (the cursor value from the previous response)
orderstring—"desc""asc" or "desc"

Request Example​

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

Response Fields (200 OK)​

FieldTypeDescription
messagesarrayArray of message objects
messages[].conversationIdstringConversation ID (UUID)
messages[].messageIdstringUnique identifier of the message
messages[].senderstringSender. "User" or "AI"
messages[].textstringThe message body text. If the body is empty, the result (content) of the latest task is returned
messages[].createdAtstringCreation date and time (ISO 8601)
messages[].updatedAtstringLast updated date and time (ISO 8601)
messages[].statusobjectMessage processing status
messages[].status.processingbooleanWhether the agent is currently processing
messages[].status.unfinishedbooleanWhether the agent response was interrupted
messages[].tasksarrayArray of tasks executed by the agent (see below)
messages[].deliverablesarrayArray of artifacts generated by the agent. Included only when present
messages[].deliverables[].filenamestringArtifact file name
messages[].deliverables[].filepathstringArtifact file path
messages[].deliverables[].sourcestring"agent" (agent-generated) or "user" (user-uploaded)
messages[].deliverables[].isPrimarybooleanWhether it is a primary artifact
messages[].deliverables[].createdAtstringCreation date and time (ISO 8601 format). An empty string when unknown
messages[].deliverables[].mimeTypestringMIME type (e.g., "application/pdf", "text/markdown"). "application/octet-stream" when it cannot be determined
messages[].deliverables[].sizenumber?File size (bytes). Omitted when 0 or below
messages[].filesarray?Array of user-uploaded files. Included only when present for messages with sender: "User"
messages[].files[].fileIdstringUnique identifier of the file (UUID)
messages[].files[].mimeTypestringMIME type (e.g., "image/png", "application/pdf")
messages[].files[].widthnumber?Image width in pixels. Only for image files
messages[].files[].heightnumber?Image height in pixels. Only for image files
messages[].archivedboolean?true only for messages retrieved via archive. Added when viewing the message history of a conversation retrieved with GET /v1/conversations?mode=archive
hasMorebooleanWhether a next page exists
cursorstringCursor for the next page. Included only when hasMore is true

Task Object​

FieldTypeDescription
messageIdstringID of the message the task belongs to
conversationIdstringID of the conversation the task belongs to
callIdstring?Tool call ID. In Complex Path, multiple tasks share the same callId and identify a sequence of steps for the same tool call
actionTypestringType of task (e.g., tool execution, code generation)
titlestring?Task title. Omitted when not present
descriptionstring?Task description. Omitted when not present
statusstringTask status. One of: "in_progress" / "completed" / "failed" / "error" / "pending"
contentstring?Task execution result text. Omitted when not present
metadataobject?Auxiliary information that varies by actionType (sub_event_type, url, filepath, etc.). See the Streaming Guide for details
filesarray?Files related to the task (filename / size / filepath / mimeType?. mimeType is omitted when it cannot be determined). The array itself is omitted when there are no related files
timestampnumberTimestamp of task execution (Unix milliseconds)
createdAtstringCreation date and time (ISO 8601)
updatedAtstringLast updated date and time (ISO 8601)
Safely ignore unknown fields

Future implementations may add new fields to actionType / metadata. Client implementations should safely ignore any fields not listed in this table. For detailed metadata structure, refer to the Streaming Guide — Task data model.

Response Example​

JSON
{
"messages": [
{
"conversationId": "550e8400-...",
"messageId": "msg-abc123",
"sender": "User",
"text": "Please analyze the sales data",
"createdAt": "2026-03-14T10:30:00Z",
"updatedAt": "2026-03-14T10:30:00Z",
"status": { "processing": false, "unfinished": false },
"tasks": []
}
],
"hasMore": false
}

Pagination​

Specify limit to fetch items in pages. While hasMore is true, pass the cursor from the response to the next request as-is.

Request example
1# First page
2curl "https://<your-domain>/api/v1/conversations/<conversation_id>/messages?limit=50" \
3-H "Authorization: Bearer <access_token>"
4
5# Second page (use the cursor returned by the first page)
6curl "https://<your-domain>/api/v1/conversations/<conversation_id>/messages?limit=50&cursor=<cursor>" \
7-H "Authorization: Bearer <access_token>"

If limit is omitted, 50 items are returned. To fetch everything, keep following the cursor until hasMore becomes false.

Using the cursor

The cursor represents a position in the result set. Do not change order while you are following the same cursor — changing the conditions changes the target set and causes duplicated or skipped items.

Items may also be duplicated or skipped across pages if messages are added or removed while you are paging.

Error Response​

StatuscodeDescription
400invalid_conversation_idconversationId is the all-zero UUID (00000000-0000-0000-0000-000000000000). This value is not accepted
400invalid_parameterlimit is not an integer from 1 to 100, cursor is invalid (not a value from the previous response), or order is not "asc" / "desc"
404conversation_not_foundThe conversation was not found or is not yours

PATCH/v1/conversations/:conversationId

Update the title of a conversation.

Path Parameters​

パラメータ型必須説明
conversationIdstring必須Conversation ID (UUID)

Request Body​

パラメータ型必須説明
titlestring必須New conversation title (200 characters or less)

Request Example​

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": "New title" }'

Response Fields (200 OK)​

FieldTypeDescription
conversationIdstringConversation ID (UUID)
titlestringUpdated title
typestringKind of conversation: "chat", "mail", or "project" (a conversation of a project step)
createdAtstringCreation timestamp (ISO 8601)
updatedAtstringLast update timestamp (ISO 8601)

Response Example​

JSON
{
"conversationId": "550e8400-...",
"title": "New title",
"type": "chat",
"createdAt": "2026-03-14T10:30:00.000Z",
"updatedAt": "2026-03-14T12:00:00.000Z"
}

Error Response​

StatuscodeDescription
400invalid_conversation_idconversationId is the all-zero UUID (00000000-0000-0000-0000-000000000000). This value is not accepted
400missing_parametertitle is missing
400invalid_titletitle is an empty string, is not a string, or exceeds 200 characters
400invalid_bodyThe body is malformed JSON
400conversation_archivedThe conversation is archived
415unsupported_media_typeThe Content-Type of the body is not application/json
404conversation_not_foundThe conversation was not found or is not yours

DELETE/v1/conversations/:conversationId

Delete a conversation. Of the files attached to its messages and its artifact files, those not used by any other conversation are deleted too (they no longer appear in GET /v1/files).

Path Parameters​

パラメータ型必須説明
conversationIdstring必須Conversation ID (UUID)

Request Example​

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

Response Fields (200 OK)​

FieldTypeDescription
conversationIdstringID of the deleted conversation (UUID)
deletedbooleanAlways true on successful deletion

Response Example​

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

Error Response​

StatuscodeDescription
400invalid_conversation_idconversationId is the all-zero UUID (00000000-0000-0000-0000-000000000000). This value is not accepted
400conversation_archivedThe conversation is archived. Use POST /v1/conversations/:id/restore to restore it
404conversation_not_foundThe conversation was not found or is not yours
409conversation_processingThe conversation cannot be deleted because it is currently being processed
409project_conversationA project conversation. Project conversations cannot be deleted
409legal_holdA conversation under legal hold. It cannot be deleted until an administrator releases the hold

POST/v1/conversations/:conversationId/restore

Restore an archived conversation back to active. After restoration, the conversation can be edited, continued, and deleted just like a regular conversation.

Path Parameters​

パラメータ型必須説明
conversationIdstring必須ID of the archived conversation (UUID)

Request Example​

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

Response Fields (200 OK)​

FieldTypeDescription
conversationIdstringID of the restored conversation (UUID)
restoredbooleanAlways true on successful restoration

Response Example​

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

Error Response​

StatuscodeDescription
400invalid_conversation_idconversationId is the all-zero UUID (00000000-0000-0000-0000-000000000000). This value is not accepted
404conversation_not_foundThe conversation does not exist in the archive, or is already active (not distinguished from the archived state)

POST/v1/conversations/:conversationId/read

Marks a conversation as read. Reading the messages of a conversation through the API (REST, MCP, or A2A) does not mark it as read, so call this when you want to record that it was read. The read position never moves back (specifying an earlier message does not move it before where it is).

Path Parameters​

パラメータ型必須説明
conversationIdstring必須Conversation ID (UUID)

Request Body (optional)​

The body can be omitted. When you send one, use Content-Type: application/json.

パラメータ型必須説明
messageIdstring—ID of the last message you read. If omitted, the conversation is marked as read up to its latest message at that moment (specify it to avoid marking messages that arrived while you were reading)

Request Example​

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

Response (204 No Content)​

There is no body.

Error Responses​

StatuscodeDescription
400invalid_conversation_idconversationId is the all-zero UUID (00000000-0000-0000-0000-000000000000). This value is not accepted
400invalid_parametermessageId is empty or not a string
400invalid_bodyThe body is not a JSON object
400conversation_archivedThe conversation is archived
415unsupported_media_typeThe body is not application/json
404conversation_not_foundThe conversation does not exist or is not yours
404message_not_foundThe messageId is not in that conversation

File Management​

Upload, retrieve, and delete files.

Endpoint List​

メソッドエンドポイント説明Scope (SaaS)
GET/v1/filesList fileschat:file
POST/v1/filesUpload a filechat:file
GET/v1/files/:fileId/contentDownload a filechat:file
DELETE/v1/files/:fileIdDelete a filechat:file

Note: The Marketplace edition does not require scopes (authentication only).

POST/v1/files

Upload a file.

Request Body (multipart/form-data)​

パラメータ型必須説明
filefile必須The file to upload. Maximum size 512 MB.
filenamestring必須File name

Request Example​

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"

Response Fields (201 Created)​

FieldTypeDescription
fileIdstringUnique identifier of the file (UUID)
filenamestringFile name
bytesintegerFile size (bytes)
createdAtstringCreation date and time (ISO 8601)
widthintegerImage width (pixels). Only for image files
heightintegerImage height (pixels). Only for image files

Response Example​

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

Error Response​

StatuscodeDescription
400missing_parameterThe file or filename parameter is missing
400file_too_largeThe file size exceeds 512 MB
400invalid_parameterThe uploaded image file is corrupted or invalid
415unsupported_media_typeThe body is not multipart/form-data, or the file type is not accepted (including extensions and MIME types the environment has decided not to accept)
403feature_not_permittedAn administrator has not permitted file uploads
503feature_permissions_unavailableThe feature permissions could not be checked. Retry after a while

GET/v1/files

List files. Cursor-based pagination is supported.

Query Parameters​

パラメータ型必須デフォルト説明
limitinteger—50Number of items per page (1-100)
cursorstring——Cursor for the next page (the cursor value from the previous response)
orderstring—"desc""asc" (oldest first) or "desc" (newest first). Sorted by the file update time

Request Example​

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

Response Fields (200 OK)​

FieldTypeDescription
filesarrayArray of file objects
files[].fileIdstringUnique identifier of the file (UUID)
files[].filenamestringFile name
files[].bytesintegerFile size (bytes)
files[].createdAtstringCreation date and time (ISO 8601)
files[].widthintegerImage width (pixels). Only for image files
files[].heightintegerImage height (pixels). Only for image files
hasMorebooleanWhether a next page exists
cursorstringCursor for the next page. Included only when hasMore is true

Response Example​

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

Pagination​

Specify limit to fetch items in pages. While hasMore is true, pass the cursor from the response to the next request as-is.

Request example
1# First page
2curl "https://<your-domain>/api/v1/files?limit=50&order=desc" \
3-H "Authorization: Bearer <access_token>"
4
5# Second page (use the cursor returned by the first page)
6curl "https://<your-domain>/api/v1/files?limit=50&order=desc&cursor=<cursor>" \
7-H "Authorization: Bearer <access_token>"

If limit is omitted, 50 items are returned. To fetch everything, keep following the cursor until hasMore becomes false.

Using the cursor

The cursor represents a position in the result set. Do not change order while you are following the same cursor — changing the conditions changes the target set and causes duplicated or skipped items.

Items may also be duplicated or skipped across pages if files are added or removed while you are paging.

Error Response​

StatuscodeDescription
400invalid_parameterlimit is not an integer from 1 to 100
400invalid_parametercursor is invalid (not a value from the previous response)
400invalid_parameterorder is not "asc" / "desc"

GET/v1/files/:fileId/content

Download a file.

Path Parameters​

パラメータ型必須説明
fileIdstring必須File ID (UUID)

Request Example​

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

Response (200 OK)​

The file binary data is returned as a stream.

Response HeaderDescription
Content-TypeMIME type of the file
Content-LengthFile size (bytes)
Content-Dispositionattachment; filename="filename"; filename*=UTF-8''<percent-encoded UTF-8 filename>

When saving the file, use the name in filename* (the UTF-8 name, percent-encoded) if it is present; otherwise use filename. For a name that contains characters such as Japanese, filename is a substitute name, and the original name is only in filename*. For example, for 売上.pdf ("sales.pdf" in Japanese), the header looks like this (the substitute name in filename is only an example).

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

Error Response​

StatuscodeDescription
400invalid_parameterfileId has an invalid format
404file_not_foundThe file was not found
503service_unavailableAuthentication is temporarily unavailable. Please retry later. If the problem persists, contact the service administrator

DELETE/v1/files/:fileId

Delete a file. Deleting a conversation also deletes the files used only by that conversation (see Delete a conversation).

Path Parameters​

パラメータ型必須説明
fileIdstring必須File ID (UUID)

Request Example​

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

Response Fields (200 OK)​

FieldTypeDescription
fileIdstringID of the deleted file (UUID)
deletedbooleanAlways true on successful deletion

Response Example​

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

Error Response​

StatuscodeDescription
400invalid_parameterfileId has an invalid format
404file_not_foundThe file was not found

Artifact Retrieval​

Retrieve artifact files generated by the agent.

Endpoint List​

メソッドエンドポイント説明Scope (SaaS)
GET/v1/files/proxyGet an artifact filechat:exec

Note: The Marketplace edition does not require scopes (authentication only).

GET/v1/files/proxy

Download an artifact file by specifying the path obtained from deliverables[].filepath in the message history.

The Marketplace edition does not enforce scopes. Any authenticated token can download artifacts.

Query Parameters​

パラメータ型必須説明
pathstring必須Artifact file path (obtained from deliverables[].filepath in the message history)

Request Example​

filepath is the value of messages[].deliverables[].filepath from Get message history.

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

Response (200 OK)​

The artifact file binary data is returned as a stream.

Response HeaderDescription
Content-TypeMIME type of the file
Content-LengthFile size (bytes)

Error Response​

StatuscodeDescription
400missing_parameterThe path parameter is missing
400invalid_parameterThe path format is invalid (no UUID-shaped segment)
404not_foundThe file was not found (if the storage response carries another code, that code is returned)
500unknownUnknown error from the storage
500storage_forbiddenAccess to the storage was denied. Contact your administrator
500rejectedThe storage rejected the request. Contact your administrator
503rate_limitedThe storage is temporarily busy. Retry after a while
503transientThe storage is temporarily unavailable. Retry after a while
503service_unavailableAuthentication is temporarily unavailable. Please retry later. If the problem persists, contact the service administrator

Full-text search messages.

Endpoint List​

メソッドエンドポイント説明Scope (SaaS)
GET/v1/search/messagesFull-text search messageschat:history

Note: The Marketplace edition does not require scopes (authentication only).

GET/v1/search/messages

Full-text search messages. Messages of conversations of project steps and of archived conversations are not searched. Results are returned newest first by creation time (oldest first with order=asc), with cursor-based pagination.

Query Parameters​

パラメータ型必須説明
qstring必須Search query
orderstring—Sort order. "asc" (ascending) or "desc" (descending, default)
limitinteger—Number of items per page (1-100). Defaults to 50.
cursorstring—Cursor value for the next page. Pass the cursor from the previous response as is, with the same q and order.

Request Example​

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

Response Fields (200 OK)​

FieldTypeDescription
messagesarrayArray of search result messages (one page, up to limit)
messages[].conversationIdstringConversation ID (UUID)
messages[].messageIdstringUnique identifier of the message
messages[].textstringMessage body text
messages[].titlestringConversation title
messages[].senderstringSender. "User" or "AI"
messages[].createdAtstringCreation date and time (ISO 8601)
messages[].updatedAtstringLast updated date and time (ISO 8601)
messages[].matchedQueriesarrayArray of matched search queries
messages[].statusobjectMessage processing status
messages[].status.processingbooleanWhether the agent is currently processing
messages[].status.unfinishedbooleanWhether the agent response was interrupted
messages[].tasksarrayArray of tasks executed by the agent. See the Task object under GET /v1/conversations/:conversationId/messages for field definitions
messages[].deliverablesarrayArray of artifacts generated by the agent (included only when present)
messages[].deliverables[].filenamestringArtifact file name
messages[].deliverables[].filepathstringArtifact file path
messages[].deliverables[].sourcestring"agent" (agent-generated) or "user" (user-uploaded)
messages[].deliverables[].isPrimarybooleanWhether it is a primary artifact
messages[].deliverables[].createdAtstringCreation date and time (ISO 8601 format). An empty string when unknown
messages[].deliverables[].mimeTypestringMIME type (e.g., "application/pdf", "text/markdown"). "application/octet-stream" when it cannot be determined
messages[].deliverables[].sizenumber?File size (bytes). Omitted when 0 or below
messages[].filesarray?Array of user-uploaded files. Included only when present for messages with sender: "User". The field structure matches the history API (fileId / mimeType / width? / height?). See GET /v1/conversations/:id/messages for details
hasMorebooleantrue when there is a next page. When true, cursor is returned
cursorstringCursor value for the next page. Included only when hasMore is true
limitReachedbooleantrue only when many messages match and only the most relevant results (up to 1,000 each for matches in the message text and in the agent's task progress) are covered. Not included otherwise. To search exhaustively, narrow the query

Response Example​

JSON
{
"messages": [
{
"conversationId": "550e8400-...",
"messageId": "msg-abc123",
"text": "Result of sales data analysis...",
"title": "Sales data analysis",
"sender": "AI",
"createdAt": "2026-03-14T10:30:00Z",
"updatedAt": "2026-03-14T10:35:00Z",
"matchedQueries": ["sales"],
"tasks": []
}
],
"hasMore": false
}

Error Response​

StatusDescription
400q parameter is missing or not a single string (for example, q specified more than once), order is not "asc" / "desc", limit is not an integer from 1 to 100, or cursor cannot be read
501An environment where search is not configured (code: "search_not_configured")
503Search is temporarily unavailable (code: "service_unavailable"). Retry after a while

Projects​

A project is the unit in which multiple agents are placed to carry out work. From an external system you can list projects, start a run, check run status, and get the artifacts of workflow runs.

There are two project types, and each is triggered differently.

TypeDescriptionHow runs are triggered
workflowAdvances through steps in order. A run starts from the first enabled step.POST /v1/projects/{projectId}/runs
cycleKeeps multiple agents running on their own schedules. An external event can add one extra ad-hoc run.POST /v1/projects/{projectId}/triggers/{triggerId}/fire
What you can operate on
With a service account token, you can operate on every project in this environment. An application (sign-in from an external tool) token can also call the nine endpoints here and the other project APIs. What it can operate on then depends on how the user participates in the project and on the organization operations role (User API Reference (Projects)). Calling them with a user token obtained in any other way returns 404 Not Found for every endpoint.

Endpoints​

メソッドエンドポイント説明
GET/v1/projectsList projects
POST/v1/projects/{projectId}/runsStart a project run
POST/v1/projects/{projectId}/triggers/{triggerId}/fireFire a trigger for one ad-hoc run
GET/v1/projects/{projectId}/runs/{runId}Get run status
POST/v1/projects/{projectId}/runs/{runId}/cancelCancel a workflow run
POST/v1/projects/{projectId}/executions/{executionId}/cancelStop a sweep execution of a cycle project
GET/v1/projects/{projectId}/executions/{executionId}Get the status of an execution (status fields only)
GET/v1/projects/{projectId}/artifactsList the artifacts of a workflow run
GET/v1/projects/{projectId}/artifacts/{artifactId}/contentGet the content of an artifact (HEAD also works)

GET/v1/projects

Retrieves the list of all projects in this environment. Supports cursor-based pagination. cycle projects also appear in the list, but they are not valid targets for starting a run (POST /v1/projects/{projectId}/runs).

Query Parameters​

ParameterTypeDefaultDescription
limitinteger50Number of items to retrieve (1-100)
cursorstring—Cursor for the next page (the cursor value from the previous response)

Any other query parameter is ignored.

Request Example​

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

Response Fields (200 OK)​

FieldTypeDescription
projectsarrayArray of project objects
projects[].projectIdstringProject ID (UUID)
projects[].namestringProject name
projects[].typestring"workflow" or "cycle"
projects[].statusstringProject state. One of "active", "paused", "archived" or "admin_stopped" (stopped by an administrator)
projects[].tagsarrayArray of tags. An empty array when none are set
hasMorebooleanWhether a next page exists
cursorstringCursor for the next page. Included only when hasMore is true

Response Example​

JSON
{
"projects": [
{
"projectId": "550e8400-e29b-41d4-a716-446655440000",
"name": "Order processing flow",
"type": "workflow",
"status": "active",
"tags": []
},
{
"projectId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Always-on inquiry handling",
"type": "cycle",
"status": "active",
"tags": []
}
],
"hasMore": false
}

Error Responses​

StatusDescription
400limit is outside 1-100 or cursor is invalid (code is invalid_parameter)

POST/v1/projects/{projectId}/runs

Starts a run of a workflow project. Calling it for a cycle project returns 409 Conflict (unsupported_project_type).

Request Headers​

HeaderRequiredDescription
Idempotency-KeyRequiredA duplicate-run prevention key issued by the caller. 8-128 characters using alphanumerics and _ . : - only

Path Parameters​

パラメータ型必須説明
projectIdstring必須Project ID (UUID)

Request Body​

The body can be omitted. If you send one, make it a JSON object. Fields other than those below are ignored.

パラメータ型必須説明
payloadany—The request for the run. Any JSON value (an object, an array, a string, and so on) is accepted as is. The agent of the first step receives it in context.start_input (see "Request of a run started from outside" in the marketplace workflow guide). Putting a file ID in the request does not attach the file. Omitted or null means no request. Up to 8,000 characters as a JSON string
configobject—Input files and step settings. Write one entry per placement and step, in the form { "placements": [{ "placementId", "stepId", "parameters", "connectionBindings", "fileBindings" }] }. fileBindings maps input file names (inputs[].name from the list of registered Agents that can be placed) to the artifactId of uploaded drafts; parameters are the registered Agent's parameters (in the shape of parametersSchema); connectionBindings maps connection slot names to connector IDs. All fields other than placementId and stepId can be omitted. Omitted or null means no settings

There are two limits. If payload exceeds 8,000 characters as a JSON string, 400 Bad Request (payload_too_large) is returned. If the whole body exceeds 16 KiB, 413 Payload Too Large (body_too_large) is returned.

config also counts toward the 16 KiB limit of the whole body.

Response Fields (201 Created / 200 OK)​

FieldTypeDescription
runIdstringRun ID (UUID). Use it to retrieve run status
existingboolean?true when an existing run was returned for a resend with the same Idempotency-Key. Not included on the first call

The first call returns 201 Created; a resend with the same Idempotency-Key returns 200 OK.

Request Example​

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": "Some users cannot log in"
9 }
10}'

Response Example​

JSON
{
"runId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
How Idempotency-Key is handled
  • Keys are matched per project. They do not expire.
  • Resending with the same key returns the same run even after the project has been paused, after the concurrent-run limit has been reached, or after that run has finished.
  • If a timeout leaves the outcome unknown, simply resend with the same key. Nothing is run twice.
  • To start a different run, always issue a new key.

Resending with the same key but a different payload or config returns 409 Conflict (origin_conflict).

Error Responses​

StatuscodeDescription
400idempotency_key_requiredThe Idempotency-Key header is missing
400idempotency_key_invalidThe Idempotency-Key length or character set is invalid
400invalid_parameterprojectId is not a UUID
400payload_too_largepayload exceeds 8,000 characters as a JSON string
400invalid_bodyThe request body is malformed JSON or is not a JSON object
413body_too_largeThe request body exceeds 16 KiB
415unsupported_media_typeA request body is sent with a Content-Type other than application/json
404project_not_foundThe project does not exist or is not accessible
400approvers_requiredAn enabled review step has no reviewers configured
409unsupported_project_typeA cycle project was specified
409project_inactiveThe project is not active (paused or archived)
409principal_suspendedAn administrator has suspended the user the project runs as. Ask an administrator to transfer the project to another owner, or to lift the suspension
409start_step_in_branch_laneThe start step is in a lane of a branch step. Set the start step of the time trigger to a step outside the lanes of branch steps
409definition_pendingThe first definition of the project is waiting for approval, so it cannot run yet. Start it after an approver (another owner or an administrator of the organization) approves it in the product screen
409relink_requiredThe project cannot be started or resumed until the references that were not found during import are reconnected. The remaining references appear in the project's relink and in the placements' relink. To clear the references that refuse a start: for rows whose kind is "agent", place the agent again (POST /v1/projects/{projectId}/placements); for rows whose kind is "connector", save the connector again on the product screen. Rows whose blocking is false are items to set up again if needed and do not refuse runs; they can be cleared with DELETE /v1/projects/{projectId}/relink, but clearing them alone does not make the project startable
409admin_stoppedAn administrator has stopped the project, or a registered agent placed in it. Ask an administrator to resume it (this API cannot resume it)
409mixed_runtimeRegistered agents and other agents are placed in the same project
409agent_not_certifiedA registered agent placed in the project is not certified for use in workflows
409lanes_not_for_marketplaceThe flow of the project has lanes (a project of registered agents cannot proceed with lanes)
400invalid_parameterA value in the start input is invalid
400missing_inputAn input file the step needs is missing (the previous step did not produce it, or it was not specified)
400duplicate_target_pathTwo or more input files would be placed at the same target path
400mp_placement_not_in_snapshotThe registered agent of the step is not in the configuration taken when the run started
400connection_version_missingThe connection version is not saved
400invalid_runtime_configThe runtime settings of the placement do not match the registered agent definition
400input_binding_cycleThe input bindings form a cycle
400input_binding_forward_referenceAn input refers to the output of a later step that has not run yet
400input_binding_unknown_outputAn output specified as an input does not exist in the source registered agent
400artifact_format_mismatchThe format of an artifact specified as an input differs from the required format
400artifact_digest_missingAn artifact specified as an input has no digest
400invalid_configconfig is malformed, names a placement or step that does not exist, does not match the registered Agent definition, or the project has no registered Agents placed on its steps
409artifact_not_readyAn artifact specified as an input is not ready yet (or differs from the content that was reviewed). With a system integration token, only drafts that a current owner of the project uploaded and that are not yet bound to a run can be specified
409origin_conflictA different payload or config was sent with the same Idempotency-Key (the same origin was already used with different content)
409connection_version_unavailableThe connection version cannot be confirmed (the connection target or permissions changed after approval)
429too_many_active_runsThe project already has the maximum number of runs (3 in total) that are running or awaiting review

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

Fires a webhook trigger configured on a cycle project and runs the target agent once, as an extra ad-hoc run. Calling it for a workflow project returns 404 Not Found.

The scheduled runs stay exactly as configured. A fired run is added separately from the schedule. Each fire is accepted separately and is never merged into an earlier fire. Fires to the same step of the same agent placement are processed one at a time, in the order they were accepted.

Path Parameters​

パラメータ型必須説明
projectIdstring必須Project ID (UUID)
triggerIdstring必須ID of the trigger to fire (UUID)

Request Body​

パラメータ型必須説明
eventIdstring必須A unique ID issued by the sender. Resending the same ID is treated as a duplicate. 1-160 characters using alphanumerics and _ . : @ + - only
payloadany—Arbitrary JSON passed to the agent. It is serialized to a JSON string and added to the request sent to the agent; anything beyond 8,000 characters after serialization is omitted

Request Example​

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

Response Fields (202 Accepted)​

FieldTypeDescription
resultstring"accepted" (newly accepted) or "duplicate" (already accepted for the same eventId)
jobIdstringID of the receiving job. It is fixed per combination of agent placement and step: fires to the same combination return the same value (it does not change per fire). It cannot be used to get run status (GET /v1/projects/{projectId}/runs/{runId})
executionIdstringID of the accepted sweep execution. It can be used to get the result of the execution and to stop the sweep execution. A resend with the same eventId returns the same value (it can be missing from the response to a resend; then find the execution as described in Finding the Execution Started by a Fire). Until it starts (this can take about a minute, and longer when earlier fires to the same step of the same agent placement are waiting), getting the result of the execution returns 404 Not Found (execution_not_found)

Response Example​

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

This 202 Accepted means only that the request was recorded as accepted. The run happens afterwards, and its outcome is not part of this response. Do not treat 202 as business success.

Resending​

Idempotency is decided by the combination of project, trigger, and eventId. Resending the same content returns 202 with result: "duplicate". Sending the same eventId with a different payload returns 409 Conflict (event_conflict).

Error Responses​

StatuscodeDescription
400invalid_event_ideventId is missing or has an invalid format
400invalid_parameterprojectId or triggerId is not a UUID
400invalid_bodyThe request body is malformed JSON or is not a JSON object
415unsupported_media_typeA request body is sent with a Content-Type other than application/json
404trigger_not_foundThe project or trigger does not exist, is not accessible, the trigger is not a webhook trigger, or a workflow project was specified
409trigger_disabledThe trigger is disabled
409project_not_activeThe project is not in a runnable state
409principal_suspendedAn administrator has suspended the user the project runs as. Ask an administrator to transfer the project to another owner, or to lift the suspension
409admin_stoppedAn administrator has stopped the project, or the Agent of the placement the trigger runs. Ask an administrator to resume it
409placement_unavailableThe target agent placement does not exist, or is not in a state that can run
409event_conflictThe same eventId was sent with a different payload
413body_too_largeThe request body exceeds 16 KiB
429queue_fullThe number of fires waiting to run on the same step of the same agent placement has reached the limit (20)

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

Retrieves the status of a run. Besides runs started through the API (POST /v1/projects/{projectId}/runs), runs started from the UI or on a schedule can also be retrieved. cycle projects do not create runs, so they are out of scope for this endpoint.

Path Parameters​

パラメータ型必須説明
projectIdstring必須Project ID (UUID)
runIdstring必須Run ID (UUID)

Request Example​

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

Response Fields (200 OK)​

FieldTypeDescription
runIdstringRun ID (UUID)
statusstringRun state. One of "running" (running), "waiting_gate" (awaiting review), "closed_done" (completed), "closed_rejected" (ended by rejection), "closed_failed" (ended by failure) or "cancelled" (cancelled). Any value other than "running" and "waiting_gate" means the run has ended
originTypestring | nullHow the run started. One of "manual" (started from the UI), "api" (started through the API) or "cron" (scheduled)
originRefstring | nullA reference value that depends on how the run started. For a run started through the API, the Idempotency-Key used to start it
currentStepIdstring | nullID (UUID) of the step in progress. null for a completed run. For a run that ended for another reason, the ID of the step at that time may remain
startedByRefstring | nullWho or what started the run. See the "Who started the run" table below
actorLabelstring | nullDisplay name of a starter that is not a user (the service account name). null if unknown, and null otherwise
startedAtstring | nullStart time (ISO 8601). null before it starts
endedAtstring | nullEnd time (ISO 8601). null before it ends
summarystring | nullFor a completed run, the output of the last completed step that recorded an output (first 2,000 characters). null if there is no such step and for a run that has not completed
runtimeKindstring | nullKind of runtime. "marketplace" (a run of registered agents) or "autonomous". May be null for older runs
cancelRequestedAtstring | nullTime (ISO 8601) when cancellation was requested. null if not requested
deadlineAtstring | nullDeadline of the workflow run (ISO 8601). null if it has no deadline
configRevisionnumber | nullRevision of the case configuration. Used by runs of registered agents; null for other runs
stepsarrayRecords of the step runs, in the order they were recorded
steps[].runStepIdstringID of the step run (starts with "rs:")
steps[].stepIdstring | nullStep ID (UUID)
steps[].placementIdstring | nullID (UUID) of the placement that handled the step. null for rows that do not run an agent (such as review steps)
steps[].executionIdstring | nullID of the agent execution. Set once the agent starts running
steps[].conversationIdstring | nullID of the conversation of the agent execution. null for runs of registered agents
steps[].statusstringOne of "pending" (waiting to run), "running" (running), "waiting_gate" (awaiting review), "done" (done), "failed" (failed) or "skipped" (skipped)
steps[].attemptnumber | nullRetry count within the same visit (starting at 1)
steps[].lanestring | nullAlways "main"
steps[].scheduledAtstring | nullWhen the step has a scheduled time, the time (ISO 8601) this row waits for. null once it starts
steps[].startedAtstring | nullStart time (ISO 8601)
steps[].endedAtstring | nullEnd time (ISO 8601)
steps[].outputSummarystring | nullSummary of the step output
steps[].outcomestring | nullResult of the agent execution. One of "completed", "incomplete", "failed", "timeout", "stopped", "denied" or "skipped". null for rows without a result
steps[].reasonCodestring | nullReason code for the result. "branch_undecided" when a branch could not decide and a person is asked to choose; "branch_not_selected" for a step in a lane the branch did not choose
steps[].heldbooleanWhether the step is held because the project is paused and is waiting to resume
steps[].visitnumber | nullWhich visit to this step this is (increases with send-backs). null for rows without this record
steps[].reworkReasonstring | nullReason for the send-back
steps[].gateForstring | nullFor a review row, the step run (runStepId) it was raised for
steps[].routedFromstring | nullWhen steps were skipped by choosing a destination, the step run (runStepId) that chose it
steps[].latestring | nullWhy a result that arrived late was not used to advance the run
steps[].gateobject | nullSummary of the review. Set on review step rows. null for other rows
steps[].gate.decisionstring | nullOne of "proceed", "send_back" or "reject". null if not decided yet
steps[].gate.waitSourcestring | nullWhat the review waits for. "human" (a person's decision) or "external" (an external condition)
steps[].resumeCommandIdstring | nullAlways null
steps[].resumeReasonstring | nullAlways null
steps[].supersededBystring | nullAlways null
steps[].gateKindstring | nullAlways null
steps[].connectionConfirmOfstring | nullAlways null
plannedPlacementsarrayOrder of steps and placements planned to run, based on the configuration when the run started
plannedPlacements[].stepIdstring | nullStep ID (UUID)
plannedPlacements[].placementIdstring | nullPlacement ID (UUID). null for review steps and steps without an agent
lanesarrayAlways an empty array
Who started the run​
Started bystartedByRefactorLabel
A user (from the UI or the API)User IDnull
A service account"client:" followed by the client ID of the service accountName of the service account (null if unknown)
A schedulenullnull

For runs started by a service account before 2026-09-25, startedByRef is null.

Response Example​

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": []
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId or runId is not a UUID
404run_not_foundThe run does not exist, belongs to another project, or is not accessible

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

Cancels a workflow run that is running or awaiting review (status is "running" or "waiting_gate"). This is the same as Cancel run on the screen.

When it is cancelled:

  • The status of the workflow run becomes "cancelled" (cancelled). This cannot be undone.
  • Steps that have not started are not started. The Agents of running steps are told to stop (the status of such a step row may not change until it stops).
  • Review requests of review steps that have not been decided are withdrawn.

Path Parameters​

パラメータ型必須説明
projectIdstring必須Project ID (UUID)
runIdstring必須ID of the workflow run (UUID)

Request Body​

FieldTypeRequiredDescription
commandIdstringYesA value to identify resends (8 to 128 characters of letters, digits, and _ . : -)
reasonstring—The reason for canceling (up to 500 characters)
  • If you send it for a workflow run that is not running (after it ended or was cancelled), nothing changes: 200 OK is returned with existing set to true. The same applies when you resend after it was cancelled.
  • If you send it around the same time as another cancel or the end of the workflow run, the choice between 202 Accepted and 200 OK and the value of existing may not match what actually happened. Check the result with status of Get a Workflow Run (GET /v1/projects/{projectId}/runs/{runId}).
  • 504 Gateway Timeout does not mean "it was not cancelled". Resend with the same commandId, or check status with Get a Workflow Run.

Request Example​

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": "Because an error in the input data was noticed"
7}'

Response Fields (202 Accepted / 200 OK)​

202 Accepted when this request cancelled the workflow run, and 200 OK when it did not.

FieldTypeDescription
runIdstringID of the workflow run
statusstringThe status of the workflow run after the request ("cancelled" when it was cancelled)
cancelRequestedAtstring | nullWhen the cancel was accepted (ISO 8601). null for a workflow run that was not cancelled
existingbooleantrue when this request did not newly cancel the workflow run (always false with 202 Accepted)

Response Example​

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

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId or runId is not a UUID, commandId is missing or has the wrong form, or reason is not a string or is longer than 500 characters
400invalid_bodyThe body is malformed JSON or not a JSON object
404run_not_foundThe workflow run does not exist, belongs to another project, or the project is not accessible
413body_too_largeThe body exceeds 16 KiB
415unsupported_media_typeThe Content-Type of the body is not application/json

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

For a cycle project, stops a sweep execution. This is the same as Stop on the screen. No body is needed (a body is not used even if sent).

  • Only sweep executions of cycle projects can be stopped. Specifying an execution of a workflow step (rs:<number>) returns 400 Bad Request (invalid_parameter). To stop a workflow run, use Cancel a Workflow Run.
  • After it is accepted, it can take about a minute for the execution to stop. Check whether it stopped with Get the Result of an Execution (GET /v1/projects/{projectId}/executions/{executionId}). It can also be called with a system integration (service account) token (it returns only the status fields). An execution that had not started yet when the stop request was accepted stays 404 Not Found (execution_not_found) in Get the Result of an Execution.
  • For an execution whose stop was already requested, or that had already ended, nothing changes: 200 OK is returned with existing set to true.

Path Parameters​

パラメータ型必須説明
projectIdstring必須Project ID (UUID)
executionIdstring必須ID of the sweep execution (UUID)

Request Example​

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

Response Fields (202 Accepted / 200 OK)​

202 Accepted when a new stop request was accepted, and 200 OK otherwise.

FieldTypeDescription
executionIdstringID of the execution
statestringThe state when the request was accepted. It does not indicate whether the execution actually stopped (see the first bullet of this section for how to check). Example values: "dispatched" (the stop request was passed to the running execution), "cancelled" (an execution that had not started yet was cancelled), "terminal" (the execution had already finished). Other state values of the execution or the dispatch at the time of acceptance may also be returned as they are. Do not fix a list of values and rely on it
existingbooleantrue when a stop had already been requested or the execution had already ended (always false with 202 Accepted)

Response Example​

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

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId is not a UUID, executionId is neither rs:<number> nor a UUID, or executionId is an execution of a workflow step
400invalid_bodyThe body is malformed JSON or not a JSON object
404execution_not_foundThe execution does not exist, belongs to another project, the project is not a cycle, or the project is not accessible
413body_too_largeThe body exceeds 16 KiB
415unsupported_media_typeA request body is sent with a Content-Type other than application/json

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

Gets the status of an execution (whether it is running, whether it has ended, and how it ended). With a service account token, it returns only the status fields below. Called with an application (sign-in from an external tool) token, it returns the same fields as Get the Result of an Execution in the User API Reference (Projects).

  • A sweep execution of a cycle project can be read with executionId in the response of a trigger fire. Until it starts (this can take about a minute), it returns 404 Not Found (execution_not_found). Use it also to check whether a sweep execution stopped after you stopped it.
  • An execution of a workflow step can be read with steps[].executionId (a UUID) of the workflow run. executionId in the response is rs:<number>, and an ID in this form can also be used.

Path Parameters​

パラメータ型必須説明
projectIdstring必須Project ID (UUID)
executionIdstring必須Execution ID (rs:<number> or a UUID)

Request Example​

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

Response Fields (200 OK)​

The fields returned when called with a service account token.

FieldTypeDescription
executionIdstringExecution ID. rs:<number> for a workflow, and a UUID for a cycle
kindstring | null"run_step" (a workflow step) or "sweep" (a cycle sweep)
runIdstring | nullID of the workflow run. null for a cycle
stepIdstring | nullStep ID
placementIdstring | nullPlacement ID
attemptnumber | nullAttempt number (increases when a platform failure is retried. For a cycle, a relaunch is a new execution, and it does not increase)
outcomestring | nullOutcome (see Outcome Values in the User API Reference (Projects))
reasonCodestring | nullReason for the outcome. For a cycle, the reason the execution ended (for example, "guardrail_blocked"); for a workflow, the reason reported by the step
resultStatestring | null"terminal" (has a result), "running" (running), "missing" (insufficient record), "unmeasured" (completion not measured), or "not_applicable" (a row that is not an Agent execution, such as a review step)
terminalbooleanWhether it has finished
startedAtstring | nullStart time (ISO 8601)
endedAtstring | nullEnd time (ISO 8601)

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId is not a UUID, or executionId is neither rs:<number> nor a UUID
404execution_not_foundThe execution does not exist, belongs to another project, is a sweep execution that has not started yet, or the project is not accessible

Response Example​

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

Gets all artifacts of a workflow run (the input files bound at the start and the outputs made by the steps), in the order they were made. Read the content with the API that gets the content of an artifact (GET /v1/projects/{projectId}/artifacts/{artifactId}/content). With a service account token, you can read the artifacts of every project in this environment. run_id is required.

Path Parameters​

パラメータ型必須説明
projectIdstring必須Project ID (UUID)

Query Parameters​

ParameterTypeDefaultDescription
run_idstring—Required. ID of the workflow run (UUID)

Request Example​

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

Response Fields (200 OK)​

FieldTypeDescription
artifactsarrayArray of artifacts
artifacts[].artifactIdstring | nullArtifact ID (UUID)
artifacts[].runIdstring | nullID of the workflow run
artifacts[].namestring | nullName of the artifact
artifacts[].mimeTypestring | nullMIME type of the artifact
artifacts[].sizenumber | nullSize (bytes)
artifacts[].statusstring | null"ready" (readable) or "uploading" (not fully written yet)
artifacts[].createdAtstring | nullWhen the artifact was made (ISO 8601)
hasMorebooleanAlways false (all artifacts are returned)

Response Example​

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
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId is not a UUID, or run_id is missing or not a UUID
404project_not_foundThe project does not exist
404run_not_foundThe workflow run does not exist, or belongs to another project

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

Gets the content of an artifact. You can also call it with HEAD. The same headers are returned without the body, so you can check the size first. Reading it with GET leaves a view (forensic.viewed) in the records (audit trail) (HEAD does not). When read with a service account token, it is recorded as the system integration.

Path Parameters​

パラメータ型必須説明
projectIdstring必須Project ID (UUID)
artifactIdstring必須Artifact ID (UUID). The artifactId in the list of artifacts

Request Example​

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

Response (200 OK)​

The content of the artifact is returned as it is.

Response headerDescription
Content-TypeMIME type of the artifact
Content-LengthSize (bytes)
X-Content-Type-Options"nosniff"
Content-Disposition"attachment" (returned as a download)

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId or artifactId is not a UUID
404artifact_not_foundThe project or the artifact does not exist, the artifact belongs to another project, or it is not an artifact of a workflow run
409artifact_not_readyThe artifact is not fully written yet

Notes on the Project API​

ItemDetail
What 404 meansThe same 404 Not Found is returned whether the project does not exist or is not accessible, and the response does not reveal which of the two applies. The code is fixed per endpoint: project_not_found for starting a run, trigger_not_found for firing a trigger, and run_not_found for run status and for canceling a workflow run. Listing artifacts returns project_not_found (run_not_found when the run does not exist), and getting the content of an artifact returns artifact_not_found. Stopping a sweep execution and getting the status of an execution return execution_not_found.
When the type is out of scopeCalling trigger fire on a workflow project, or run status or canceling a workflow run on a cycle project, returns 404. Stopping a sweep execution on a workflow project also returns 404. Starting a run on a cycle project is the one exception: it returns 409 unsupported_project_type.
Request bodyWhen you send a body, make it a JSON object. Anything other than Content-Type: application/json returns 415, malformed JSON or a body that is not a JSON object returns 400 (invalid_body), and a body larger than 16 KiB returns 413.
Unknown fields / queriesFields and query parameters that are not in the specification are ignored. An invalid value for a documented query parameter, or a cursor that cannot be read, returns 400 Bad Request.
Timeouts504 Gateway Timeout does not mean "it did not run". Resend a run start with the same Idempotency-Key, a trigger fire with the same eventId and the same body, and a workflow run cancel with the same commandId. A sweep execution stop can also be resent as it is.

Error Responses​

HTTP Status Codes​

HTTP status codes that may be returned by all endpoints.

StatusDescription
400 Bad RequestInvalid request parameters
401 UnauthorizedToken is invalid or missing. Also returned for a token of a user whose use was suspended by an administrator (see "Suspended users" below)
403 ForbiddenNo access permission to the resource
404 Not FoundResource does not exist, or the path or method is not defined (405 is not returned)
409 ConflictOperation conflict, such as the resource currently being processed
409 ConflictA person with the organization operations role (the "Operator" role assigned in "Admin Roles" in the admin console) who does not take part in the project called an operation that role cannot use (error.code is forbidden_role). It does not clear by waiting. For an owner-only operation, ask an owner of the project to do it. For other operations, ask an owner to add you to the project; you can then call them as your project role allows
413 Payload Too LargeRequest body exceeds the size limit
415 Unsupported Media TypeThe request body format (Content-Type) is not supported
429 Too Many RequestsRate limit or concurrent-run limit exceeded. error.type is rate_limit_error, and error.code depends on the endpoint (for example monthly_quota_exceeded for the monthly limit and too_many_active_runs for concurrent project runs). Please wait and retry.
500 Internal Server ErrorInternal server error
502 Bad GatewayCommunication error with upstream services (authentication / chat backends, etc.)
503 Service UnavailableService temporarily unavailable
504 Gateway TimeoutUpstream service response timeout

Error Response Format​

All error responses are returned in the following common structure.

FieldTypeDescription
error.typestringError classification. One of: "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.messagestringHuman-readable error message
error.codestringMachine-processable error code (e.g., "missing_parameter", "invalid_parameter", "invalid_token")
error.paramstringThe parameter that caused the error. Included only for validation errors
error.reasonstringThe kind of reason for the refusal. Included only for 409 (definition_invalid) of the project APIs
error.suggested_actionstringRecommended action to take. Included only for some errors
JSON
{
"error": {
"type": "invalid_request_error",
"message": "Invalid parameter: limit",
"code": "invalid_parameter",
"param": "limit",
"suggested_action": "limit must be between 1 and 100"
}
}

Suspended users​

A call with the token of a user whose use was suspended by an administrator returns 401 Unauthorized. error.code is account_suspended.

The following APIs do not check whether the user is suspended: GET /v1/organizations, GET /v1/job-types, GET /v1/user, PATCH /v1/user, GET /v1/marketplace-agents, the MCP tools list_agents and cancel_chat (when no task is in progress), and the Agent Card of a registered Agent (GET /api/v1/a2a/agents/{agentId}/.well-known/agent-card.json).