System Integration API Reference
Endpoint specification and error codes for the System Integration API of the Marketplace edition.
The Marketplace edition provides Chat, Conversation Management, File Management, Artifact Retrieval and Search. The Library, Skills, Playbooks, User, Master Data, User Management, Logs, Shared Memory and Projects APIs are available in the SaaS edition only. See the User API Reference (SaaS) and the System Integration API Reference (SaaS) for those.
Base URL
Send all API requests to the following base URL. Replace <your-domain> with the domain of your deployment.
https://<your-domain>/apiEndpoint 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.
For how to obtain a token, see the Authentication Guide and the Authentication API Reference.
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). 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 Message search. Treat cursor as opaque: do not interpret it, just pass the previous value back.
Chat
OpenAI-compatible Chat Completions API. Conversations with the agent are delivered via SSE (Server-Sent Events) streaming.
The Chat API consists of three endpoints. You can send messages, reconnect to existing conversations, and cancel conversations in progress.
SSE Streaming Guide
Detailed explanation of connection flow, response objects, Delta extensions, execution patterns, reconnection, and error handling
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
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
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}'curl -X POST https://<your-domain>/api/v1/chat/completions \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"model": "AGENTIC STAR",
"stream": true,
"messages": [
{
"role": "user",
"content": "Please analyze the sales data"
}
]
}'import requests
response = requests.post(
"https://<your-domain>/api/v1/chat/completions",
headers={
"Authorization": f"Bearer {token}",
"Content-Type": "application/json",
},
json={
"model": "AGENTIC STAR",
"stream": True,
"messages": [{"role": "user", "content": "Please analyze the sales data"}],
},
stream=True,
)
for line in response.iter_lines():
if line:
print(line.decode("utf-8"))const response = await fetch(
"https://<your-domain>/api/v1/chat/completions",
{
method: "POST",
headers: {
"Authorization": "Bearer " + accessToken,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "AGENTIC STAR",
stream: true,
messages: [{ role: "user", content: "Please analyze the sales data" }],
}),
}
);
const reader = response.body.getReader();
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break;
console.log(decoder.decode(value));
}package main
import (
"bufio"
"bytes"
"encoding/json"
"fmt"
"net/http"
"strings"
)
func main() {
token := "<access_token>" // Access token obtained in Step 1
body, _ := json.Marshal(map[string]interface{}{
"model": "AGENTIC STAR",
"stream": true,
"messages": []map[string]string{
{"role": "user", "content": "Please analyze the sales data"},
},
})
req, _ := http.NewRequest("POST",
"https://<your-domain>/api/v1/chat/completions",
bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
scanner := bufio.NewScanner(resp.Body)
for scanner.Scan() {
line := scanner.Text()
if strings.HasPrefix(line, "data: ") {
data := line[6:]
if data == "[DONE]" { break }
var chunk map[string]interface{}
json.Unmarshal([]byte(data), &chunk)
choices, _ := chunk["choices"].([]interface{})
if len(choices) > 0 {
delta, _ := choices[0].(map[string]interface{})["delta"].(map[string]interface{})
if content, ok := delta["content"].(string); ok {
fmt.Print(content)
}
}
}
}
}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:.
data: {"choices":[{"delta":{"role":"assistant"}}]}data: {"choices":[{"delta":{"content":"..."}}]} × Ndata: {"choices":[{"finishReason":"stop"}]}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
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). Or the specified conversationId is archived (code: "conversation_archived") |
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
1curl https://<your-domain>/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000 \2-H "Authorization: Bearer <access_token>"curl https://<your-domain>/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000 \ -H "Authorization: Bearer <access_token>"
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"))const response = await fetch(
"https://<your-domain>/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000",
{
headers: { "Authorization": "Bearer " + accessToken },
}
);
const reader = response.body.getReader();
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break;
console.log(decoder.decode(value));
}req, _ := http.NewRequest("GET",
"https://<your-domain>/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
scanner := bufio.NewScanner(resp.Body)
for scanner.Scan() {
fmt.Println(scanner.Text())
}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
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"curl -X POST https://<your-domain>/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000/cancel \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json"
import requests
response = requests.post(
"https://<your-domain>/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000/cancel",
headers={"Authorization": f"Bearer {token}"},
)
data = response.json()
print(f"Cancelled: {data['cancelled']}")const response = await fetch(
"https://<your-domain>/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000/cancel",
{
method: "POST",
headers: { "Authorization": "Bearer " + accessToken },
}
);
const data = await response.json();
console.log("Cancelled: " + data.cancelled);req, _ := http.NewRequest("POST",
"https://<your-domain>/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000/cancel",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)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
{ "conversationId": "550e8400-...", "cancelled": true }
Error Response
| Status | Description |
|---|---|
400 | Invalid conversationId, the conversation is archived (code: "conversation_archived"), the message in messageId belongs to a different conversation (code: "conversation_mismatch"), or the agent you are connected to does not support cancellation (code: "unsupported_endpoint" or code: "post_processing_not_enabled") |
404 | Conversation not found (code: "conversation_not_found"), the message in messageId is not found (code: "message_not_found"), or the message in messageId is not being processed (code: "not_processing") |
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
| パラメータ | 型 | 必須 | デフォルト | 説明 |
|---|---|---|---|---|
limit | integer | — | 50 | Number of items to return (1-100) |
cursor | string | — | — | Cursor for the next page (the 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` switches to a different data store, so a `cursor` cannot be carried over |
Request Example
1curl "https://<your-domain>/api/v1/conversations?limit=10&order=desc" \2-H "Authorization: Bearer <access_token>"curl "https://<your-domain>/api/v1/conversations?limit=10&order=desc" \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://<your-domain>/api/v1/conversations",
headers={"Authorization": f"Bearer {token}"},
params={"limit": 10, "order": "desc"},
)
data = response.json()
for conv in data["conversations"]:
print(conv["title"], conv["conversationId"])const params = new URLSearchParams({ limit: "10", order: "desc" });
const response = await fetch(
"https://<your-domain>/api/v1/conversations?" + params,
{
headers: { "Authorization": "Bearer " + accessToken },
}
);
const data = await response.json();
data.conversations.forEach((conv) => {
console.log(conv.title, conv.conversationId);
});req, _ := http.NewRequest("GET",
"https://<your-domain>/api/v1/conversations?limit=10&order=desc",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)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
{
"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), or mode is not "active" / "archive" |
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
| パラメータ | 型 | 必須 | デフォルト | 説明 |
|---|---|---|---|---|
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
1curl https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/messages?order=asc \2-H "Authorization: Bearer <access_token>"curl https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/messages?order=asc \ -H "Authorization: Bearer <access_token>"
response = requests.get(
"https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/messages",
headers={"Authorization": f"Bearer {token}"},
params={"order": "asc"},
)
messages = response.json()["messages"]
for msg in messages:
print(f"[{msg['sender']}] {msg['text'][:50]}")const response = await fetch(
"https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/messages?order=asc",
{
headers: { "Authorization": "Bearer " + accessToken },
}
);
const { messages } = await response.json();
messages.forEach((msg) => console.log("[" + msg.sender + "] " + msg.text));req, _ := http.NewRequest("GET",
"https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/messages?order=asc",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)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). An empty string when unknown |
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 | A string for the task state. When the agent omits it, the platform fills in a default (in_progress or pending). The values are not a fixed list, so do not assume only these values |
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) |
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
{
"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.
1# First page2curl "https://<your-domain>/api/v1/conversations/<conversation_id>/messages?limit=50" \3-H "Authorization: Bearer <access_token>"45# 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>"# 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.
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) |
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
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" }'curl -X PATCH https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{ "title": "New title" }'import requests
response = requests.patch(
"https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000",
headers={"Authorization": f"Bearer {token}"},
json={"title": "New title"},
)
data = response.json()
print(f"Updated: {data['title']}")const response = await fetch(
"https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000",
{
method: "PATCH",
headers: {
"Authorization": "Bearer " + accessToken,
"Content-Type": "application/json",
},
body: JSON.stringify({ title: "New title" }),
}
);
const data = await response.json();
console.log("Updated: " + data.title);payload := map[string]string{"title": "New title"}
body, _ := json.Marshal(payload)
req, _ := http.NewRequest("PATCH",
"https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000",
bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()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
{
"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, or the conversation is archived (code: "conversation_archived") |
404 | Conversation not found |
DELETE/v1/conversations/:conversationId
Delete a conversation.
Path Parameters
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
conversationId | string | 必須 | Conversation ID (UUID) |
Request Example
1curl -X DELETE https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000 \2-H "Authorization: Bearer <access_token>"curl -X DELETE https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000 \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.delete(
"https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000",
headers={"Authorization": f"Bearer {token}"},
)
data = response.json()
print(f"Deleted: {data['deleted']}")const response = await fetch(
"https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000",
{
method: "DELETE",
headers: { "Authorization": "Bearer " + accessToken },
}
);
const data = await response.json();
console.log("Deleted: " + data.deleted);req, _ := http.NewRequest("DELETE",
"https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response Fields (200 OK)
| Field | Type | Description |
|---|---|---|
conversationId | string | ID of the deleted conversation (UUID) |
deleted | boolean | Always true on successful deletion |
Response Example
{ "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
1curl -X POST https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/restore \2-H "Authorization: Bearer <access_token>"curl -X POST https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/restore \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.post(
"https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/restore",
headers={"Authorization": f"Bearer {token}"},
)
data = response.json()
print(f"Restored: {data['restored']}")const response = await fetch(
"https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/restore",
{
method: "POST",
headers: { "Authorization": "Bearer " + accessToken },
}
);
const data = await response.json();
console.log("Restored: " + data.restored);req, _ := http.NewRequest("POST",
"https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/restore",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response Fields (200 OK)
| Field | Type | Description |
|---|---|---|
conversationId | string | ID of the restored conversation (UUID) |
restored | boolean | Always true on successful restoration |
Response Example
{ "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
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"curl -X POST https://<your-domain>/api/v1/files \ -H "Authorization: Bearer <access_token>" \ -F "file=@report.pdf" \ -F "filename=report.pdf"
import requests
with open("report.pdf", "rb") as f:
response = requests.post(
"https://<your-domain>/api/v1/files",
headers={"Authorization": f"Bearer {token}"},
files={"file": f},
data={"filename": "report.pdf"},
)
data = response.json()
print(data["fileId"])const formData = new FormData();
formData.append("file", file); // File object from input
formData.append("filename", "report.pdf");
const response = await fetch(
"https://<your-domain>/api/v1/files",
{
method: "POST",
headers: { "Authorization": "Bearer " + accessToken },
body: formData,
}
);
const data = await response.json();
console.log(data.fileId);file, _ := os.Open("report.pdf")
defer file.Close()
body := &bytes.Buffer{}
writer := multipart.NewWriter(body)
part, _ := writer.CreateFormFile("file", "report.pdf")
io.Copy(part, file)
writer.WriteField("filename", "report.pdf")
writer.Close()
req, _ := http.NewRequest("POST",
"https://<your-domain>/api/v1/files",
body)
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", writer.FormDataContentType())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
{
"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 |
GET/v1/files
List files. Cursor-based pagination is supported.
Query Parameters
| パラメータ | 型 | 必須 | デフォルト | 説明 |
|---|---|---|---|---|
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
1curl https://<your-domain>/api/v1/files?order=desc \2-H "Authorization: Bearer <access_token>"curl https://<your-domain>/api/v1/files?order=desc \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://<your-domain>/api/v1/files",
headers={"Authorization": f"Bearer {token}"},
params={"order": "desc"},
)
files = response.json()["files"]
for file in files:
print(f"{file['filename']} ({file['bytes']} bytes)")const params = new URLSearchParams({ order: "desc" });
const response = await fetch(
"https://<your-domain>/api/v1/files?" + params,
{
headers: { "Authorization": "Bearer " + accessToken },
}
);
const data = await response.json();
data.files.forEach((file) => {
console.log(file.filename + " (" + file.bytes + " bytes)");
});req, _ := http.NewRequest("GET",
"https://<your-domain>/api/v1/files?order=desc",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)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
{
"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.
1# First page2curl "https://<your-domain>/api/v1/files?limit=50&order=desc" \3-H "Authorization: Bearer <access_token>"45# 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>"# 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.
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) |
GET/v1/files/:file_id/content
Download a file.
Path Parameters
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
file_id | string | 必須 | File ID (UUID) |
Request Example
1curl https://<your-domain>/api/v1/files/550e8400-e29b-41d4-a716-446655440001/content \2-H "Authorization: Bearer <access_token>" \3-o downloaded_file.pdfcurl https://<your-domain>/api/v1/files/550e8400-e29b-41d4-a716-446655440001/content \ -H "Authorization: Bearer <access_token>" \ -o downloaded_file.pdf
import requests
response = requests.get(
"https://<your-domain>/api/v1/files/550e8400-e29b-41d4-a716-446655440001/content",
headers={"Authorization": f"Bearer {token}"},
stream=True,
)
with open("downloaded_file.pdf", "wb") as f:
for chunk in response.iter_content(chunk_size=8192):
f.write(chunk)const fs = require("fs");
const response = await fetch(
"https://<your-domain>/api/v1/files/550e8400-e29b-41d4-a716-446655440001/content",
{
headers: { "Authorization": "Bearer " + accessToken },
}
);
const buffer = await response.arrayBuffer();
fs.writeFileSync("downloaded_file.pdf", new Uint8Array(buffer));req, _ := http.NewRequest("GET",
"https://<your-domain>/api/v1/files/550e8400-e29b-41d4-a716-446655440001/content",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
file, _ := os.Create("downloaded_file.pdf")
defer file.Close()
io.Copy(file, resp.Body)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"; filename*=UTF-8''<percent-encoded UTF-8 filename> |
When saving the file, use the name in filename* (the UTF-8 name, percent-encoded) if it is present; otherwise use filename. For a name that contains characters such as Japanese, filename is a substitute name, and the original name is only in filename*. For example, for 売上.pdf ("sales.pdf" in Japanese), the header looks like this (the substitute name in filename is only an example).
Content-Disposition: attachment; filename="file_1731650000000.pdf"; filename*=UTF-8''%E5%A3%B2%E4%B8%8A.pdf
Error Response
| 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
1curl -X DELETE https://<your-domain>/api/v1/files/550e8400-e29b-41d4-a716-446655440001 \2-H "Authorization: Bearer <access_token>"curl -X DELETE https://<your-domain>/api/v1/files/550e8400-e29b-41d4-a716-446655440001 \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.delete(
"https://<your-domain>/api/v1/files/550e8400-e29b-41d4-a716-446655440001",
headers={"Authorization": f"Bearer {token}"},
)
data = response.json()
print(f"File deleted: {data['deleted']}")const response = await fetch(
"https://<your-domain>/api/v1/files/550e8400-e29b-41d4-a716-446655440001",
{
method: "DELETE",
headers: { "Authorization": "Bearer " + accessToken },
}
);
const data = await response.json();
console.log("File deleted: " + data.deleted);req, _ := http.NewRequest("DELETE",
"https://<your-domain>/api/v1/files/550e8400-e29b-41d4-a716-446655440001",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response Fields (200 OK)
| Field | Type | Description |
|---|---|---|
fileId | string | ID of the deleted file (UUID) |
deleted | boolean | Always true on successful deletion |
Response Example
{ "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.
Query Parameters
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
path | string | 必須 | Artifact file path (obtained from deliverables[].filepath in the message history) |
Request Example
filepath is the value of messages[].deliverables[].filepath from Get message history.
1FILEPATH='<filepath>'23curl --get "https://<your-domain>/api/v1/files/proxy" \4--data-urlencode "path=$FILEPATH" \5-H "Authorization: Bearer <access_token>" \6-o artifact.xlsxFILEPATH='<filepath>' curl --get "https://<your-domain>/api/v1/files/proxy" \ --data-urlencode "path=$FILEPATH" \ -H "Authorization: Bearer <access_token>" \ -o artifact.xlsx
import requests
filepath = "<filepath>"
response = requests.get(
"https://<your-domain>/api/v1/files/proxy",
headers={"Authorization": "Bearer " + token},
params={"path": filepath},
stream=True,
)
with open("artifact.xlsx", "wb") as f:
for chunk in response.iter_content(chunk_size=8192):
f.write(chunk)const filepath = "<filepath>";
const params = new URLSearchParams({
path: filepath,
});
const response = await fetch(
"https://<your-domain>/api/v1/files/proxy?" + params,
{
headers: { "Authorization": "Bearer " + accessToken },
}
);
const blob = await response.blob();import (
"io"
"net/http"
"net/url"
"os"
)
filepath := "<filepath>"
req, _ := http.NewRequest("GET",
"https://<your-domain>/api/v1/files/proxy?"+url.Values{"path": {filepath}}.Encode(),
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
out, _ := os.Create("artifact.xlsx")
defer out.Close()
io.Copy(out, resp.Body)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. Results are returned newest first by creation time (oldest first with order=asc), with cursor-based pagination.
Query Parameters
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
q | string | 必須 | Search query |
order | string | — | Sort order. "asc" (ascending) or "desc" (descending, default) |
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, with the same q and order. |
Request Example
1curl "https://<your-domain>/api/v1/search/messages?q=sales" \2-H "Authorization: Bearer <access_token>"curl "https://<your-domain>/api/v1/search/messages?q=sales" \ -H "Authorization: Bearer <access_token>"
import requests
from urllib.parse import quote
query = "sales"
response = requests.get(
"https://<your-domain>/api/v1/search/messages",
headers={"Authorization": f"Bearer {token}"},
params={"q": query, "order": "desc"},
)
messages = response.json()["messages"]
for msg in messages:
print(f"{msg['title']}: {msg['text'][:50]}")const query = "sales";
const params = new URLSearchParams({ q: query, order: "desc" });
const response = await fetch(
"https://<your-domain>/api/v1/search/messages?" + params,
{
headers: { "Authorization": "Bearer " + accessToken },
}
);
const data = await response.json();
data.messages.forEach((msg) => {
console.log(msg.title + ": " + msg.text);
});query := "sales"
req, _ := http.NewRequest("GET",
fmt.Sprintf("https://<your-domain>/api/v1/search/messages?q=%s&order=desc",
url.QueryEscape(query)),
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response Fields (200 OK)
| Field | Type | Description |
|---|---|---|
messages | array | Array of search result messages (one page, up to limit) |
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). An empty string when unknown |
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 | true when there is a next page. When true, cursor is returned |
cursor | string | Cursor value for the next page. Included only when hasMore is true |
limitReached | boolean | true only when many messages match and only the most relevant results (up to 1,000 each for matches in the message text and in the agent's task progress) are covered. Not included otherwise. To search exhaustively, narrow the query |
Response Example
{
"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), order is not "asc" / "desc", limit is not an integer from 1 to 100, or cursor cannot be read |
501 | The search provider is not configured in this environment (code: "search_not_configured") |
503 | Search is temporarily unavailable (code: "service_unavailable"). Retry after a while |
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 |
429 Too Many Requests | Rate limit or quota exceeded. error.type is rate_limit_error, and error.code depends on the endpoint (for example monthly_quota_exceeded for the monthly limit). 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 |
{
"error": {
"type": "invalid_request_error",
"message": "Invalid parameter: limit",
"code": "invalid_parameter",
"param": "limit",
"suggested_action": "limit must be between 1 and 100"
}
}