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.
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.
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.
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.
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.
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.
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.
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")
403
The specified conversation is a project conversation (code: "project_conversation". Messages cannot be sent to a project conversation)
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.
import requests
response = requests.get(
"https://<your-domain>/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000",
headers={"Authorization": f"Bearer {token}"},
stream=True,
)
for line in response.iter_lines():
if line:
print(line.decode("utf-8"))
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.
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, 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)
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.
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
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[].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
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)
502
The 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.
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"). "application/octet-stream" 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 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.
# First page
curl "https://<your-domain>/api/v1/conversations/<conversation_id>/messages?limit=50" \
-H "Authorization: Bearer <access_token>"
# Second page (use the cursor returned by the first page)
curl "https://<your-domain>/api/v1/conversations/<conversation_id>/messages?limit=50&cursor=<cursor>" \
-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.
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")
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, 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.
No 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).
The body can be omitted. When you send one, use Content-Type: application/json.
パラメータ
型
必須
説明
messageId
string
—
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)
# First page
curl "https://<your-domain>/api/v1/files?limit=50&order=desc" \
-H "Authorization: Bearer <access_token>"
# Second page (use the cursor returned by the first page)
curl "https://<your-domain>/api/v1/files?limit=50&order=desc&cursor=<cursor>" \
-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.
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"). "application/octet-stream" 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
true when more than 50 messages match (the newest 50 are returned, and the rest cannot be read; pagination not supported)
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
jobType
string
—
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
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.
Missing 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
415
The body Content-Type is not application/json (code: "unsupported_media_type")
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, or the path or method is not defined (405 is not returned)
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.)
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" } }