System Integration API Reference

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

note

The Marketplace edition provides Chat, Conversation Management, File Management, Artifact Retrieval, Search and Projects. The Library, Agent, Skills, Playbooks, Review Request, Connector, Persona, User, Master Data, User Management, Logs and Shared Memory APIs are available in the SaaS edition only. The project APIs are limited to the four below (creating and editing projects, retrieving records and metrics, and so on 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.

The Projects API can be called only with a service account token. Calling it with a token obtained by signing in as a user returns 404 Not Found.

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.

Pagination

List endpoints support cursor-based pagination.

Parameter	Type	Description
limit	integer	Number of items per page (1-100). Defaults to 50.
cursor	string	Cursor value for the next page. Pass the cursor from the previous response as is.
order	string	Sort 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 and Projects. Treat cursor as opaque: do not interpret it, just pass the previous value back.

Request handling

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

• Query parameters and body fields that are not in the specification are ignored. However, a field that the service accepts but this page does not document may still return 400 Bad Request if its type or value is invalid.
• An invalid value for a documented query parameter returns 400 Bad Request.
• A malformed JSON body returns 400 Bad Request (invalid_body).
• Sending a body with a Content-Type other than application/json to an endpoint that accepts a JSON body returns 415 Unsupported Media Type (unsupported_media_type). File uploads return 415 for a body other than multipart/form-data. However, if reading the body fails first with 400 (malformed JSON) or 413 (over the size limit), that error is returned instead.
• A body field of the wrong type returns 400 Bad Request.

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/completions	Send a chat message and receive a response via SSE streaming	chat:exec
GET	/v1/chat/completions/:conversationId	Reconnect to the SSE stream of a conversation in progress	chat:exec
POST	/v1/chat/completions/:conversationId/cancel	Cancel a conversation in progress	chat: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

パラメータ	型	必須	説明
model	string	必須	The model ID to use. Specify "AGENTIC STAR".
messages	array	必須	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.
stream	boolean	必須	Specify true. Currently, only streaming mode is supported.
conversationId	string	—	Specify a conversation ID to continue an existing conversation. If omitted, a new conversation is created.

Edition-Specific Parameters

Marketplace

agentId	string	The ID of the agent to use (required).
outputFormat	string	Response text format. "plain" (default) returns plain text with Markdown removed (diagrams dropped, code block bodies kept). "markdown" preserves Markdown as-is.

Message Object

パラメータ	型	必須	説明
role	string	必須	Use "user". "assistant" / "system" are accepted but only "user" is effectively used as the starting point of the agent turn in the current implementation
content	string | 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.

type	Parameter	Description
"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  "stream": true,
7  "messages": [
8    {
9      "role": "user",
10      "content": "Please analyze the sales data"
11    }
12  ]
13}'

Response Headers

Header	Description
Content-Type	text/event-stream
X-Conversation-Id	Conversation ID. For new conversations, a server-generated ID is returned.
X-Message-Id	The 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.

Status	Description
400	Invalid 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")
415	The body Content-Type is not application/json (code: "unsupported_media_type")
404	The specified input_file fileId is not found
409	The specified conversation is currently being processed

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

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

Status	Description
400	Invalid conversationId
404	Conversation not found or not in progress

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

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

Path Parameters

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

Request Body (optional)

パラメータ	型	必須	説明
messageId	string	—	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)

Field	Type	Description
conversationId	string	The ID of the cancelled conversation (UUID)
cancelled	boolean	Always true on successful cancellation

Response Example

JSON

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

Error Response

Status	Description
400	Invalid 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")
415	The body Content-Type is not application/json (code: "unsupported_media_type")
404	Conversation not found

Conversation Management

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

Endpoint List

メソッド	エンドポイント	説明	Scope (SaaS)
GET	/v1/conversations	List conversations	chat:history
GET	/v1/conversations/:conversationId/messages	Get message history	chat:history
PATCH	/v1/conversations/:conversationId	Update conversation title	chat:history
DELETE	/v1/conversations/:conversationId	Delete a conversation	chat:history
POST	/v1/conversations/:conversationId/restore	Restore archived conversation	chat:history

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

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

Operation	Behavior 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

Parameter	Type	Default	Description
limit	integer	50	Number of items to retrieve (1-100)
cursor	string	—	Cursor for fetching the next page (cursor value from the previous response)
order	string	"desc"	"asc" or "desc"
title	string	—	Filter by title
mode	string	"active"	"active" (regular conversations) or "archive" (archived conversations). Switching mode queries a different data store, so 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)

Field	Type	Description
conversations	array	Array of conversation objects
conversations[].conversationId	string	Unique identifier of the conversation (UUID)
conversations[].title	string	Conversation title
conversations[].createdAt	string	Creation date and time (ISO 8601)
conversations[].updatedAt	string	Last updated date and time (ISO 8601)
conversations[].archived	boolean?	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
hasMore	boolean	Whether the next page exists
cursor	string	Cursor 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",
      "createdAt": "2026-03-14T10:30:00Z",
      "updatedAt": "2026-03-14T10:35:00Z"
    }
  ],
  "hasMore": true,
  "cursor": "eyJrIjoiMjAyNi0wMy0xNFQxMDozMDowMC4wMDBaIn0"
}

Error Response

Status	Description
400	Invalid limit parameter (outside the range of 1-100), mode is not "active" / "archive", order is not "asc" / "desc", or title is not a string (for example, specified more than once)

GET/v1/conversations/:conversationId/messages

Retrieve the message history of a specified conversation. Cursor-based pagination is supported.

Path Parameters

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

Query Parameters

Parameter	Type	Default	Description
limit	integer	50	Number of items per page (1-100)
cursor	string	—	Cursor for the next page (the cursor value from the previous response)
order	string	"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)

Field	Type	Description
messages	array	Array of message objects
messages[].conversationId	string	Conversation ID (UUID)
messages[].messageId	string	Unique identifier of the message
messages[].sender	string	Sender. "User" or "AI"
messages[].text	string	Message body text
messages[].createdAt	string	Creation date and time (ISO 8601)
messages[].updatedAt	string	Last updated date and time (ISO 8601)
messages[].status	object	Message processing status
messages[].status.processing	boolean	Whether the agent is currently processing
messages[].status.unfinished	boolean	Whether the agent response was interrupted
messages[].tasks	array	Array of tasks executed by the agent (see below)
messages[].deliverables	array	Array of artifacts generated by the agent. Included only when present
messages[].deliverables[].filename	string	Artifact file name
messages[].deliverables[].filepath	string	Artifact file path
messages[].deliverables[].source	string	"agent" (agent-generated) or "user" (user-uploaded)
messages[].deliverables[].isPrimary	boolean	Whether it is a primary artifact
messages[].deliverables[].createdAt	string	Creation date and time (ISO 8601 format)
messages[].deliverables[].mimeType	string?	MIME type (e.g., "application/pdf", "text/markdown"). Omitted when it cannot be determined
messages[].deliverables[].size	number?	File size (bytes). Omitted when 0 or below
messages[].files	array?	Array of user-uploaded files. Included only when present for messages with sender: "User"
messages[].files[].fileId	string	Unique identifier of the file (UUID)
messages[].files[].mimeType	string	MIME type (e.g., "image/png", "application/pdf")
messages[].files[].width	number?	Image width in pixels. Only for image files
messages[].files[].height	number?	Image height in pixels. Only for image files
messages[].archived	boolean?	true only for messages retrieved via archive. Added when viewing the message history of a conversation retrieved with GET /v1/conversations?mode=archive
hasMore	boolean	Whether a next page exists
cursor	string	Cursor for the next page. Included only when hasMore is true

Task Object

Field	Type	Description
messageId	string	ID of the message the task belongs to
conversationId	string	ID of the conversation the task belongs to
callId	string?	Tool call ID. In Complex Path, multiple tasks share the same callId and identify a sequence of steps for the same tool call
actionType	string	Type of task (e.g., tool execution, code generation)
title	string?	Task title. Omitted when not present
description	string?	Task description. Omitted when not present
status	string	Task status. One of: "in_progress" / "completed" / "failed" / "error" / "pending"
content	string?	Task execution result text. Omitted when not present
metadata	object?	Auxiliary information that varies by actionType (sub_event_type, url, filepath, etc.). See the Streaming Guide for details
files	array?	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
timestamp	number	Timestamp of task execution (Unix milliseconds)
createdAt	string	Creation date and time (ISO 8601)
updatedAt	string	Last 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

Status	Description
400	Invalid conversationId format
400	limit is not an integer between 1 and 100
400	cursor is invalid (not a value from a previous response)
400	order is not "asc" / "desc"
404	Conversation not found

PATCH/v1/conversations/:conversationId

Update the title of a conversation.

Path Parameters

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

Request Body

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

Field	Type	Description
conversationId	string	Conversation ID (UUID)
title	string	Updated title
createdAt	string	Creation timestamp (ISO 8601)
updatedAt	string	Last update timestamp (ISO 8601)

Response Example

JSON

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

Error Response

Status	Description
400	title is missing, empty, or exceeds 200 characters, the body is malformed JSON (code: "invalid_body"), or the conversation is archived (code: "conversation_archived")
415	The body Content-Type is not application/json (code: "unsupported_media_type")
404	Conversation not found

DELETE/v1/conversations/:conversationId

Delete a conversation.

Path Parameters

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

Field	Type	Description
conversationId	string	ID of the deleted conversation (UUID)
deleted	boolean	Always true on successful deletion

Response Example

JSON

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

Error Response

Status	Description
400	Invalid conversationId, or the conversation is archived (code: "conversation_archived"; use POST /v1/conversations/:id/restore to restore it)
404	Conversation not found
409	Conversation cannot be deleted because it is currently being processed

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

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

Field	Type	Description
conversationId	string	ID of the restored conversation (UUID)
restored	boolean	Always true on successful restoration

Response Example

JSON

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

Error Response

Status	Description
400	Invalid conversationId
404	No matching conversation in archive, or it is already active (archive state is not distinguished)

File Management

Upload, retrieve, and delete files.

Endpoint List

メソッド	エンドポイント	説明	Scope (SaaS)
GET	/v1/files	List files	chat:file
POST	/v1/files	Upload a file	chat:file
GET	/v1/files/:file_id/content	Download a file	chat:file
DELETE	/v1/files/:file_id	Delete a file	chat:file

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

POST/v1/files

Upload a file.

Request Body (multipart/form-data)

パラメータ	型	必須	説明
file	file	必須	The file to upload. Maximum size 512 MB.
filename	string	必須	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)

Field	Type	Description
fileId	string	Unique identifier of the file (UUID)
filename	string	File name
bytes	integer	File size (bytes)
createdAt	string	Creation date and time (ISO 8601)
width	integer	Image width (pixels). Only for image files
height	integer	Image 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

Status	Description
400	file or filename parameter is missing, file size exceeds 512 MB, or the uploaded image file is corrupted or invalid
415	The body is not multipart/form-data (code: "unsupported_media_type")

GET/v1/files

List files. Cursor-based pagination is supported.

Query Parameters

Parameter	Type	Default	Description
limit	integer	50	Number of items per page (1-100)
cursor	string	—	Cursor for the next page (the cursor value from the previous response)
order	string	"desc"	"asc" or "desc"

Request Example

List files

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

Response Fields (200 OK)

Field	Type	Description
files	array	Array of file objects
files[].fileId	string	Unique identifier of the file (UUID)
files[].filename	string	File name
files[].bytes	integer	File size (bytes)
files[].createdAt	string	Creation date and time (ISO 8601)
files[].width	integer	Image width (pixels). Only for image files
files[].height	integer	Image height (pixels). Only for image files
hasMore	boolean	Whether a next page exists
cursor	string	Cursor 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

Status	Description
400	limit is not an integer between 1 and 100
400	cursor is invalid (not a value from a previous response)
400	order is not "asc" / "desc"

GET/v1/files/:file_id/content

Download a file.

Path Parameters

パラメータ	型	必須	説明
file_id	string	必須	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 Header	Description
Content-Type	MIME type of the file
Content-Length	File size (bytes)
Content-Disposition	attachment; filename="filename"

Error Response

Status	Description
400	Invalid fileId format
404	File not found

DELETE/v1/files/:file_id

Delete a file.

Path Parameters

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

Field	Type	Description
fileId	string	ID of the deleted file (UUID)
deleted	boolean	Always true on successful deletion

Response Example

JSON

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

Error Response

Status	Description
400	Invalid fileId format
404	File not found

Artifact Retrieval

Retrieve artifact files generated by the agent.

Endpoint List

メソッド	エンドポイント	説明	Scope (SaaS)
GET	/v1/files/proxy	Get an artifact file	chat: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

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

Request Example

Get artifact file

1curl "https://<your-domain>/api/v1/files/proxy?path=/path/to/artifact.xlsx" \
2-H "Authorization: Bearer <access_token>" \
3-o artifact.xlsx

Response (200 OK)

The artifact file binary data is returned as a stream.

Response Header	Description
Content-Type	MIME type of the file
Content-Length	File size (bytes)

Error Response

Status	Description
400	path parameter is missing or has an invalid format
404	File not found

Search

Full-text search messages.

Endpoint List

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

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

GET/v1/search/messages

Full-text search messages.

Query Parameters

パラメータ	型	必須	説明
q	string	必須	Search query
order	string	—	Sort order. "asc" (ascending) or "desc" (descending, default)

Request Example

Search messages

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

Response Fields (200 OK)

Field	Type	Description
messages	array	Array of search result messages (up to 50)
messages[].conversationId	string	Conversation ID (UUID)
messages[].messageId	string	Unique identifier of the message
messages[].text	string	Message body text
messages[].title	string	Conversation title
messages[].sender	string	Sender. "User" or "AI"
messages[].createdAt	string	Creation date and time (ISO 8601)
messages[].updatedAt	string	Last updated date and time (ISO 8601)
messages[].matchedQueries	array	Array of matched search queries
messages[].status	object	Message processing status
messages[].status.processing	boolean	Whether the agent is currently processing
messages[].status.unfinished	boolean	Whether the agent response was interrupted
messages[].tasks	array	Array of tasks executed by the agent. See the Task object under GET /v1/conversations/:conversationId/messages for field definitions
messages[].deliverables	array	Array of artifacts generated by the agent (included only when present)
messages[].deliverables[].filename	string	Artifact file name
messages[].deliverables[].filepath	string	Artifact file path
messages[].deliverables[].source	string	"agent" (agent-generated) or "user" (user-uploaded)
messages[].deliverables[].isPrimary	boolean	Whether it is a primary artifact
messages[].deliverables[].createdAt	string	Creation date and time (ISO 8601 format)
messages[].deliverables[].mimeType	string?	MIME type (e.g., "application/pdf", "text/markdown"). Omitted when it cannot be determined
messages[].deliverables[].size	number?	File size (bytes). Omitted when 0 or below
messages[].files	array?	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
hasMore	boolean	Always false (pagination not supported). It is false even when more than 50 messages match, so there is no guarantee that every match is included

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

Status	Description
400	q parameter is missing or not a single string (for example, q specified more than once), or order is not "asc" / "desc"

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, and check run status.

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

Type	Description	How runs are triggered
workflow	Advances through steps in order. A run starts from the first enabled step.	POST /v1/projects/{projectId}/runs
cycle	Keeps 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

You can call the project API only with a service account token. Calling it with a token obtained by signing in as a user returns 404 Not Found for every endpoint. You can operate on every project in this environment.

Endpoints

メソッド	エンドポイント	説明
GET	/v1/projects	List projects
POST	/v1/projects/{projectId}/runs	Start a project run
POST	/v1/projects/{projectId}/triggers/{triggerId}/fire	Fire a trigger for one ad-hoc run
GET	/v1/projects/{projectId}/runs/{runId}	Get run status

GET/v1/projects

Retrieves the list of projects you can access. 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

Parameter	Type	Default	Description
limit	integer	50	Number of items to retrieve (1-100)
cursor	string	—	Cursor for the next page (the cursor value from the previous response)

Any other query parameter is ignored.

Response Fields (200 OK)

Field	Type	Description
projects	array	Array of project objects
projects[].projectId	string	Project ID (UUID)
projects[].name	string	Project name
projects[].type	string	"workflow" or "cycle"
projects[].status	string	Project state. One of "active", "paused" or "archived"
projects[].tags	array	Array of tags. An empty array when none are set
hasMore	boolean	Whether a next page exists
cursor	string	Cursor 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

Status	Description
400	limit 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

Header	Required	Description
Idempotency-Key	Required	A duplicate-run prevention key issued by the caller. 8-128 characters using alphanumerics and _ . : - only

Path Parameters

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

Request Body

No body is required. If you send one, make it a JSON object. Any fields it contains are ignored.

Response Fields (201 Created / 200 OK)

Field	Type	Description
runId	string	Run ID (UUID). Use it to retrieve run status
existing	boolean?	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

curl

curl -X POST https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/runs \
  -H "Authorization: Bearer <access_token>" \
  -H "Idempotency-Key: nightly-batch-20260917" \
  -H "Content-Type: application/json" \
  -d '{}'

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.

Error Responses

Status	code	Description
400	idempotency_key_required	The Idempotency-Key header is missing
400	idempotency_key_invalid	The Idempotency-Key length or character set is invalid
400	invalid_parameter	projectId is not a UUID
400	invalid_body	The request body is malformed JSON or is not a JSON object
413	body_too_large	The request body exceeds 16 KiB
415	unsupported_media_type	A request body is sent with a Content-Type other than application/json
404	project_not_found	The project does not exist or is not accessible
400	approvers_required	An enabled review step has no reviewers configured
409	unsupported_project_type	A cycle project was specified
409	project_inactive	The project is not active (paused or archived)
409	mixed_runtime	Registered agents and other agents are placed in the same project
409	agent_not_certified	A registered agent placed in the project is not certified for use in workflows
409	lanes_not_for_marketplace	Lanes are configured in the step flow (lanes cannot be used in a project that runs registered agents)
429	too_many_active_runs	The 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

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

Request Body

パラメータ	型	必須	説明
eventId	string	必須	A unique ID issued by the sender. Resending the same ID is treated as a duplicate. 1-160 characters using alphanumerics and _ . : @ + - only
payload	any	—	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

Response Fields (202 Accepted)

Field	Type	Description
result	string	"accepted" (newly accepted) or "duplicate" (already accepted for the same eventId)
jobId	string	ID 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})

Response Example

JSON

{
  "result": "accepted",
  "jobId": "9b2e4c61-0f3a-4a9b-9c1d-2f7e5a8b3c40"
}

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

Status	code	Description
400	invalid_event_id	eventId is missing or has an invalid format
400	invalid_parameter	projectId or triggerId is not a UUID
400	invalid_body	The request body is malformed JSON or is not a JSON object
415	unsupported_media_type	A request body is sent with a Content-Type other than application/json
404	trigger_not_found	The project or trigger does not exist, is not accessible, the trigger is not a webhook trigger, or a workflow project was specified
409	trigger_disabled	The trigger is disabled
409	project_not_active	The project is not in a runnable state
409	placement_unavailable	The target agent placement does not exist, or is not in a state that can run
409	event_conflict	The same eventId was sent with a different payload
413	body_too_large	The request body exceeds 16 KiB
429	queue_full	The 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

パラメータ	型	必須	説明
projectId	string	必須	Project ID (UUID)
runId	string	必須	Run ID (UUID)

Response Fields (200 OK)

Field	Type	Description
runId	string	Run ID (UUID)
status	string	Run 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
originType	string | null	How the run started. One of "manual" (started from the UI), "api" (started through the API) or "cron" (scheduled)
originRef	string | null	A reference value that depends on how the run started. For a run started through the API, the Idempotency-Key used to start it
currentStepId	string | null	ID (UUID) of the step in progress. While the run proceeds in separate lanes, the ID of the step before the branch. null for a completed run. For a run that ended for another reason, the ID of the step at that time may remain
startedByRef	string | null	Who or what started the run. See the "Who started the run" table below
actorLabel	string | null	Display name of a starter that is not a user (the service account name). null if unknown, and null otherwise
startedAt	string | null	Start time (ISO 8601). null before it starts
endedAt	string | null	End time (ISO 8601). null before it ends
summary	string | null	For 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
runtimeKind	string | null	Kind of runtime. "marketplace" (a run of registered agents) or "autonomous". May be null for older runs
cancelRequestedAt	string | null	Time (ISO 8601) when cancellation was requested. null if not requested
configRevision	number | null	Revision of the case configuration. Used by runs of registered agents; null for other runs
steps	array	Records of the step runs, in the order they were recorded
steps[].runStepId	string	ID of the step run (starts with "rs:")
steps[].stepId	string | null	Step ID (UUID)
steps[].placementId	string | null	ID (UUID) of the placement that handled the step. null for rows that do not run an agent (such as review steps)
steps[].executionId	string | null	ID of the agent execution. Set once the agent starts running
steps[].conversationId	string | null	ID of the conversation of the agent execution. null for runs of registered agents
steps[].status	string	One of "pending" (waiting to run), "running" (running), "waiting_gate" (awaiting review), "done" (done), "failed" (failed) or "skipped" (skipped)
steps[].attempt	number | null	Retry count within the same visit (starting at 1)
steps[].lane	string | null	ID of the lane the step belongs to. "main" for steps that are not in a separate lane
steps[].scheduledAt	string | null	When the step has a scheduled time, the time (ISO 8601) this row waits for. null once it starts
steps[].startedAt	string | null	Start time (ISO 8601)
steps[].endedAt	string | null	End time (ISO 8601)
steps[].outputSummary	string | null	Summary of the step output
steps[].outcome	string | null	Result of the agent execution. One of "completed", "incomplete", "failed", "timeout", "stopped", "denied" or "skipped". null for rows without a result
steps[].reasonCode	string | null	Reason code for the result
steps[].held	boolean	Whether the step is held because the project is paused and is waiting to resume
steps[].visit	number | null	Which visit to this step this is (increases with send-backs). null for rows without this record
steps[].reworkReason	string | null	Reason for the send-back
steps[].gateFor	string | null	For a review row, the step run (runStepId) it was raised for
steps[].routedFrom	string | null	When steps were skipped by choosing a destination, the step run (runStepId) that chose it
steps[].late	string | null	Why a result that arrived late was not used to advance the run
steps[].gate	object | null	Summary of a review step. null for rows that are not review steps
steps[].gate.decision	string | null	One of "proceed", "send_back" or "reject". null if not decided yet
steps[].gate.waitSource	string | null	What the review waits for. "human" (a person's decision) or "external" (an external condition)
plannedPlacements	array	Order of steps and placements planned to run, based on the configuration when the run started
plannedPlacements[].stepId	string | null	Step ID (UUID)
plannedPlacements[].placementId	string | null	Placement ID (UUID). null for review steps and steps without an agent
lanes	array	Status of each lane after the branch. An empty array before the branch and for runs that do not use lanes
lanes[].laneId	string	Lane ID
lanes[].name	string | null	Lane name
lanes[].position	number | null	Lane order (starting at 1)
lanes[].state	string	One of "running" (running), "waiting_gate" (awaiting review), "arrived" (waiting to join) or "closed" (ended)
lanes[].currentStepId	string | null	ID (UUID) of the step in progress in that lane. null for a lane waiting to join. For a lane that has ended, the ID of its last step may remain
lanes[].arrived	boolean	Whether the lane has reached the join point

Who started the run

Started by	startedByRef	actorLabel
A user (from the UI)	User ID	null
A service account	"client:" followed by the client ID of the service account	Name of the service account (null if unknown)
A schedule	null	null

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

Response Example

JSON

{
  "runId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "running",
  "originType": "api",
  "originRef": "nightly-batch-20260917",
  "currentStepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
  "startedByRef": "client:order-batch",
  "actorLabel": null,
  "startedAt": "2026-09-17T01:30:00.000Z",
  "endedAt": null,
  "summary": null,
  "runtimeKind": "marketplace",
  "cancelRequestedAt": null,
  "configRevision": 1,
  "steps": [
    {
      "runStepId": "rs:1042",
      "stepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
      "placementId": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8",
      "executionId": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
      "conversationId": null,
      "status": "running",
      "attempt": 1,
      "lane": "main",
      "scheduledAt": null,
      "startedAt": "2026-09-17T01:30:01.000Z",
      "endedAt": null,
      "outputSummary": null,
      "outcome": null,
      "reasonCode": null,
      "held": false,
      "visit": 1,
      "reworkReason": null,
      "gateFor": null,
      "routedFrom": null,
      "late": null,
      "gate": null
    }
  ],
  "plannedPlacements": [
    { "stepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f", "placementId": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8" },
    { "stepId": "c2f1a8e4-6b3d-4e7a-9c15-8d2e4f6a7b90", "placementId": null }
  ],
  "lanes": []
}

Error Responses

Status	code	Description
400	invalid_parameter	projectId or runId is not a UUID
404	run_not_found	The run does not exist, belongs to another project, or is not accessible

Notes on the Project API

Item	Detail
What 404 means	The 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.
When the type is out of scope	Calling trigger fire on a workflow project, or run status on a cycle project, returns 404. Starting a run on a cycle project is the one exception: it returns 409 unsupported_project_type.
Request body	When you send a body to start a run or fire a trigger, 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 / queries	Fields 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.
Timeouts	504 Gateway Timeout does not mean "it did not run". Resend a run start with the same Idempotency-Key, and a trigger fire with the same eventId and the same body.

Error Responses

HTTP Status Codes

HTTP status codes that may be returned by all endpoints.

Status	Description
400 Bad Request	Invalid request parameters
401 Unauthorized	Token is invalid or missing
403 Forbidden	No access permission to the resource
404 Not Found	Resource does not exist
409 Conflict	Operation conflict, such as the resource currently being processed
413 Payload Too Large	Request body exceeds the size limit
415 Unsupported Media Type	The request body format (Content-Type) is not supported
429 Too Many Requests	Rate 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 Error	Internal server error
502 Bad Gateway	Communication error with upstream services (authentication / chat backends, etc.)
503 Service Unavailable	Service temporarily unavailable
504 Gateway Timeout	Upstream service response timeout

Error Response Format

All error responses are returned in the following common structure.

Field	Type	Description
error.type	string	Error 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.message	string	Human-readable error message
error.code	string	Machine-processable error code (e.g., "missing_parameter", "invalid_parameter", "invalid_token")
error.param	string	The parameter that caused the error. Included only for validation errors
error.suggested_action	string	Recommended 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"
  }
}