Skip to main content

User API Reference (Conversations, Organizations)

Endpoint specification and error codes for the user-facing APIs of the Marketplace edition. Call them with a user token obtained through an application (sign-in from an external tool). For the project APIs, see the User API Reference (Projects). For the APIs called from a system integration, see the System Integration API Reference.

Base URL​

All API requests are sent to the base URL below. Replace <your-domain> with the domain of your environment.

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 user token obtained through an application (sign-in from an external tool). Sign-in from an external tool is available only in environments where an administrator has opened its entrance (API Setup Guide).
  • 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.
  • Chat, Conversation Management, File Management, Artifact Retrieval and Search can also be called with a system integration token (System Integration API Reference). Calling the User and Master Data APIs with a system integration token 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.

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 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/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).
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")
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 specified input_file fileId is not found
409The 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​

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

StatusDescription
400Invalid conversationId
404Conversation 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​

パラメータ型必須説明
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")
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 messageId is not a message of the conversation (sending again does not cancel it; check messageId)

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

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​

ParameterTypeDefaultDescription
limitinteger50Number of items to retrieve (1-100)
cursorstring—Cursor for fetching the next page (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 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)​

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​

StatusDescription
400Invalid 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)
502The conversation list could not be retrieved (wait and retry)

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​

ParameterTypeDefaultDescription
limitinteger50Number 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[].textstringMessage body text
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)
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​

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

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​

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

DELETE/v1/conversations/:conversationId

Delete a conversation.

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​

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

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​

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

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​

StatusDescription
400Invalid conversationId, messageId, or body (invalid_parameter, etc.), or the conversation is archived (conversation_archived)
404The conversation does not exist or is not yours (conversation_not_found), or messageId is not in the conversation (message_not_found)
415The body is not application/json

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​

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

GET/v1/files

List files. Cursor-based pagination is supported.

Query Parameters​

ParameterTypeDefaultDescription
limitinteger50Number 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​

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​

StatusDescription
400limit is not an integer between 1 and 100
400cursor is invalid (not a value from a previous response)
400order 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"

Error Response​

StatusDescription
400Invalid fileId format
404File not found

DELETE/v1/files/:fileId

Delete a file.

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​

StatusDescription
400Invalid fileId format
404File 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​

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 HeaderDescription
Content-TypeMIME type of the file
Content-LengthFile size (bytes)

Error Response​

StatusDescription
400path parameter is missing or has an invalid format
404File not found (code: "not_found" and others)
500Unknown storage error (code: "unknown")
502Storage access was denied (code: "storage_forbidden"), or storage rejected the request (code: "rejected"). Contact the administrator
503Storage is temporarily busy (code: "rate_limited") or temporarily unavailable (code: "transient"). Wait and retry

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 are not searched.

Query Parameters​

パラメータ型必須説明
qstring必須Search query
orderstring—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)​

FieldTypeDescription
messagesarrayArray of search result messages (up to 50)
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)
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 more than 50 messages match (the newest 50 are returned, and the rest cannot be read; pagination not supported)

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), or order is not "asc" / "desc"

User​

Retrieve, update user information, and change password.

Endpoint List​

メソッドエンドポイント説明
GET/v1/userGet user information
PATCH/v1/userUpdate user information
POST/v1/user/passwordChange password

GET/v1/user

Get user information.

Request Example​

Get user
1curl https://<your-domain>/api/v1/user \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)​

FieldTypeDescription
userIdstringUnique identifier of the user
emailstringEmail address
usernamestringUsername
emailVerifiedbooleanEmail verification status
createdAtstringAccount creation date and time (ISO 8601)
isApprovedbooleanAccount approval status
rolestringUser role
organizationobjectOrganization (included only when set)
organization.valuestringOrganization code
organization.labelstringOrganization name
jobTypeobjectJob type (included only when set)
jobType.valuestringJob type code
jobType.labelstringJob type name
biostringBio (included only when set)
lastLoginAtstringLast login date and time (ISO 8601, included only when present)

Response Example​

JSON
{
"userId": "user-abc123",
"email": "tanaka@example.com",
"username": "John Doe",
"emailVerified": true,
"createdAt": "2026-03-10T09:00:00.000Z",
"isApproved": true,
"role": "user",
"organization": { "value": "eng", "label": "Engineering Department" },
"jobType": { "value": "dev", "label": "Developer" },
"bio": "AI Engineer",
"lastLoginAt": "2026-03-14T10:00:00.000Z"
}

PATCH/v1/user

Update user information.

Request Body​

パラメータ型必須説明
usernamestring—Username
organizationstring—Organization code. It can be set only while it is not set. Changing an organization that is already set (including clearing it) returns 403. Ask an administrator to change it
jobTypestring—Job type code. It can be set only while it is not set. Changing a job type that is already set (including clearing it) returns 403. Ask an administrator to change it
biostring—Bio

Request Example​

Update user
1curl -X PATCH https://<your-domain>/api/v1/user \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{ "username": "John Doe", "bio": "Engineering Department" }'

Response Fields (200 OK)​

Returns the same user object as GET /v1/user (with updated values).

Response Example​

JSON
{
"userId": "user-abc123",
"email": "tanaka@example.com",
"username": "John Doe",
"emailVerified": true,
"createdAt": "2026-03-10T09:00:00.000Z",
"isApproved": true,
"role": "user",
"organization": { "value": "eng", "label": "Engineering Department" },
"jobType": { "value": "dev", "label": "Developer" },
"bio": "Engineering Department",
"lastLoginAt": "2026-03-14T10:00:00.000Z"
}

Error Response​

StatusDescription
400No fields specified for update
400username / organization / jobType / bio is not a string, or the body is malformed JSON (code: "invalid_body")
403Tried to change an organization / jobType that is already set, including clearing it (code: "affiliation_locked"). Ask an administrator to change it
409Another update of the same user is in progress (code: "conflict"). Wait a moment and send the request again
415The body Content-Type is not application/json (code: "unsupported_media_type")

POST/v1/user/password

Change password.

Request Body​

パラメータ型必須説明
currentPasswordstring必須Current password
newPasswordstring必須New password
confirmPasswordstring必須New password (confirmation)

Request Example​

Change password
1curl -X POST https://<your-domain>/api/v1/user/password \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "currentPassword": "OldPass123!",
6 "newPassword": "NewPass456!",
7 "confirmPassword": "NewPass456!"
8}'

Response Fields (200 OK)​

FieldTypeDescription
userIdstringUnique identifier of the user
changedbooleanAlways true on successful password change

Response Example​

JSON
{ "userId": "user-abc123", "changed": true }

After you change the password, do not keep using the tokens obtained before the change; sign in again and get new tokens. An access token obtained before the change can still be used with the API until it expires.

Error Response​

StatusDescription
400Missing required parameters, currentPassword / newPassword / confirmPassword is not a string, the body is malformed JSON (code: "invalid_body"), password validation failed, or the current password is incorrect
415The body Content-Type is not application/json (code: "unsupported_media_type")
401Authentication token is invalid

Master Data​

Retrieve master data such as organizations and job types.

Endpoint List​

メソッドエンドポイント説明
GET/v1/organizationsList organizations
GET/v1/job-typesList job types

GET/v1/organizations

List organizations. Inactive organizations are not included.

Request Example​

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

Response Fields (200 OK)​

FieldTypeDescription
organizationsarrayArray of organization objects
organizations[].valuestringOrganization code
organizations[].labelstringOrganization name
hasMorebooleanAlways false (pagination not supported)

Response Example​

JSON
{
"organizations": [
{ "value": "eng", "label": "Engineering Department" },
{ "value": "sales", "label": "Sales Department" }
],
"hasMore": false
}

GET/v1/job-types

List job types. Inactive job types are not included.

Request Example​

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

Response Fields (200 OK)​

FieldTypeDescription
jobTypesarrayArray of job type objects
jobTypes[].valuestringJob type code
jobTypes[].labelstringJob type name
hasMorebooleanAlways false (pagination not supported)

Response Example​

JSON
{
"jobTypes": [
{ "value": "dev", "label": "Developer" },
{ "value": "pm", "label": "Project Manager" }
],
"hasMore": false
}

Projects​

The project APIs are in the User API Reference (Projects).

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