API Reference

Complete reference for all endpoint specifications and error codes.

Base URL

All API requests are sent to the following base URL.

SaaS

https://api.agenticstar.jp

Marketplace

https://<your-domain>

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

Authentication

All API requests must include a Bearer token in the Authorization header.

Authorization: Bearer <access_token>

If the token is invalid or not specified, 401 Unauthorized is returned. Some endpoints require additional scopes. If required scopes are missing, 403 Forbidden is returned.

For details on obtaining tokens and scopes, see the Authentication Guide and Authentication Reference.

Pagination

List retrieval endpoints support cursor-based pagination.

Parameter	Type	Description
`limit`	`integer`	1Number of items per page。Default values and limits vary by endpoint
`cursor`	`string`	次のページを取得するためのカーソルValue。Included in previous response cursor specify as is
`order`	`string`	Sort order。"asc"（昇順）or "desc"（降順、Default）

The response includes a hasMore field. If true, you can obtain the next page by passing the cursor value to the next request.

curl
# 1 page
curl https://api.agenticstar.jp/v1/conversations?limit=10 \
  -H "Authorization: Bearer <access_token>"

# 2 page（Response cursor Valueを使用）
curl https://api.agenticstar.jp/v1/conversations?limit=10&cursor=2025-01-15T10:30:00.000Z \
  -H "Authorization: Bearer <access_token>"

Currently, only GET /v1/conversations supports cursor-based pagination. For other endpoints, hasMore is always false.

Chat

OpenAI-compatible Chat Completions API. Agent interactions 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 ongoing conversations.

SaaSMarketplace

SSE Streaming Guide

Connection flow, response objects, Delta拡張・実行パターン・再接続・エラーハンドリングの詳細解説

View Guide

Endpoint List

メソッド	エンドポイント	説明	スコープ
POST	`/v1/chat/completions`	Send chat message and、SSEGet response via streaming	`chat:exec`
GET	`/v1/chat/completions/:conversationId`	進行中のConversationのSSEReconnect to stream	`chat:exec`
POST	`/v1/chat/completions/:conversationId/cancel`	進行中のConversationをキャンセル	`chat:exec`

POST`/v1/chat/completions`

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

Request Headers

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

Request Body

パラメータ	型	必須	説明
`model`	`string`	必須	Model ID to use. Specify "AGENTIC STAR".
`messages`	`array`	必須	Array of message objects. At least one message with user role is required.
`stream`	`boolean`	必須	Specify true. Currently, only streaming mode is supported.
`conversationId`	`string`	—	Specify conversation ID to continue an existing conversation. If omitted, a new conversation is created.

Edition-Specific Parameters

SaaS

`agentLevel`	`string`	"default" or "high_performance". Defaults to "default".
`agentMode`	`boolean`	Enable/disable agent mode. Defaults to true.
`privateMode`	`boolean`	Enable/disable private mode. Defaults to false.

Marketplace

`agentId`	`string`	Agent ID to use.
`agent`	`string`	Alias for agentId. Specify one or the other.

Message Object

パラメータ	型	必須	説明
`role`	`string`	必須	"user", "assistant", or "system"
`content`	`string \| array`	必須	Message content. String or array of content parts.

Content Parts (Array Format)

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

type	Parameter	Description
`"text"`	`text (string)`	Text message
`"file"`	`file_id (string)`	Uploaded fileID

Request Example

Create chat completion

1curl -X POST https://api.agenticstar.jp/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": "Salesデータを分析してください"
11    }
12  ]
13}'

Response Headers

Header	Description
`Content-Type`	text/event-stream
`X-Conversation-Id`	ConversationID。新規Conversationの場合はサーバーが生成したID is returned。
`X-Message-Id`	Assistant response messageID。

SSE Response Format

The response is delivered as SSE events in the following order. Each event is a JSON line with a data: prefix.

SSEEvent Flow

data: {"choices":[{"delta":{"role":"assistant"}}]}
data: {"choices":[{"delta":{"content":"..."}}]} × N
data: {"choices":[{"finish_reason":"stop"}]}
data: [DONE]

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

Response Example

SSE
data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created_at":"2025-01-15T10:30:00Z","model":"AGENTIC STAR","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created_at":"2025-01-15T10:30:00Z","model":"AGENTIC STAR","choices":[{"index":0,"delta":{"content":"Salesデータ"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created_at":"2025-01-15T10:30:00Z","model":"AGENTIC STAR","choices":[{"index":0,"delta":{"content":" to analyze。"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created_at":"2025-01-15T10:30:01Z","model":"AGENTIC STAR","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

GET`/v1/chat/completions/:conversationId`

Reconnect to the SSE stream of an ongoing conversation. Use this when the agent is processing long-running tasks or when recovering from network disconnection.

Request Example

Resume SSE stream

1curl https://api.agenticstar.jp/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000 \
2-H "Authorization: Bearer <access_token>"

Path Parameters

パラメータ	型	必須	説明
`conversationId`	`string`	必須	再接続するConversationのID

Response (200 OK)

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

Error Response

Status	Description
`404`	Conversationが見つからない、or not in progress

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

Cancel an ongoing conversation. Use when you want to interrupt agent execution.

Path Parameters

パラメータ	型	必須	説明
`conversationId`	`string`	必須	Conversation to cancelID

Response Fields (200 OK)

Field	Type	Description
`conversationId`	`string`	Cancelled conversationID（UUID）
`cancelled`	`boolean`	Always true on successful cancellation true

Response Example

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

Error Response

Status	Description
`400`	conversationId is invalid
`404`	Conversation not found

Error Response

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

Status	Description
`400`	RequestInvalid parameter（model, messages, stream等）
`401`	Authentication token is invalid or unspecified
`403`	chat:exec Insufficient scope
`409`	指定したConversationが現在処理中

Resource API

Resource operation API for conversations, files, search, users, and master data.

SaaS

Endpoint List

メソッド	エンドポイント	説明	スコープ
GET	`/v1/conversations`	Conversation一覧を取得	`chat:history`
GET	`/v1/conversations/:id/messages`	Get message history	`chat:history`
PATCH	`/v1/conversations/:id`	Update conversation title	`chat:history`
DELETE	`/v1/conversations/:id`	Delete conversation	`chat:history`
GET	`/v1/files`	Retrieve file list	`chat:file`
POST	`/v1/files`	Upload file	`chat:file`
GET	`/v1/files/:id/content`	Download file	`chat:file`
DELETE	`/v1/files/:id`	Delete file	`chat:file`
GET	`/v1/files/proxy`	Retrieve artifact file	`chat:exec`
GET	`/v1/search/messages`	Full-text search messages	`chat:history`
GET	`/v1/user`	Retrieve user information	—
PATCH	`/v1/user`	Update user information	—
POST	`/v1/user/password`	Change password	—
GET	`/v1/organizations`	Retrieve organization list	—
GET	`/v1/job-types`	Retrieve job type list	—

Endpoints with "—" in the scope column are available with JWT authentication only (no additional scope required). For details on scope assignment, see Authentication Reference.

Conversation Management

Retrieve conversation lists, view message history, delete, and update titles.

SaaS スコープ: chat:history

GET`/v1/conversations`

Retrieve conversation list. Supports cursor-based pagination.

Request Example

List conversations

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

Query Parameters

Parameter	Type	Default	Description
`limit`	`integer`	`25`	Number of items to retrieve (1-100)
`cursor`	`string`	`—`	次ページ取得用カーソル（前回Response cursor Value）
`order`	`string`	`"desc"`	"asc" or "desc"
`title`	`string`	`—`	Filter by title

Response Fields (200 OK)

Field	Type	Description
`conversations`	`array`	Array of conversation objects
`conversations[].conversationId`	`string`	Unique identifier for conversation (UUID)
`conversations[].title`	`string`	Conversation title
`conversations[].createdAt`	`string`	Creation date (ISO 8601)
`conversations[].updatedAt`	`string`	Last updated date (ISO 8601)
`hasMore`	`boolean`	Whether next page exists
`cursor`	`string`	Cursor for next page. Included only if hasMore is true

Response Example

JSON
{
  "conversations": [
    {
      "conversationId": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Salesデータ分析",
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-01-15T10:35:00Z"
    }
  ],
  "hasMore": true,
  "cursor": "2025-01-15T10:30:00.000Z"
}

Error Response

Status	Description
`400`	limit parameter is invalid (out of 1-100 range)
`403`	chat:history scope is insufficient

GET`/v1/conversations/:conversationId/messages`

Retrieve message history for specified conversation.

Request Example

Get messages

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

Query Parameters

Parameter	Type	Default	Description
`limit`	`integer`	`—`	Maximum number of items to retrieve
`order`	`string`	`"desc"`	"asc" or "desc"

Response Fields (200 OK)

Field	Type	Description
`messages`	`array`	Messageobject array
`messages[].conversationId`	`string`	ConversationID（UUID）
`messages[].messageId`	`string`	Messageの一意識別子
`messages[].parentMessageId`	`string`	親MessageのID（Conversationツリー構造の参照）
`messages[].sender`	`string`	送信者。"User" or "AI"
`messages[].text`	`string`	Messageの本文テキスト
`messages[].createdAt`	`string`	Creation date (ISO 8601)
`messages[].updatedAt`	`string`	Last updated date (ISO 8601)
`messages[].status`	`object`	Messageの処理状態
`messages[].status.processing`	`boolean`	Whether agent is currently processing
`messages[].status.unfinished`	`boolean`	Whether agent response was interrupted
`messages[].tasks`	`array`	Array of tasks executed by agent（後述）
`messages[].deliverables`	`array`	Array of artifacts generated by agent。存在する場合のみ含まれます
`messages[].deliverables[].filename`	`string`	成果物のファイル名
`messages[].deliverables[].filepath`	`string`	成果物のファイルパス
`messages[].deliverables[].fileType`	`string`	File type
`hasMore`	`boolean`	常に false（Pagination not supported）

Task object

Field	Type	Description
`taskId`	`string`	Unique task identifier
`messageId`	`string`	Message containing the taskID
`conversationId`	`string`	Conversation containing the taskID
`actionType`	`string`	Task type（Example: Tool execution、Code Generation）
`title`	`string`	Task title
`description`	`string`	Task description
`status`	`string`	Task status（Example: "completed"、"running"）
`content`	`string`	Task execution result text
`files`	`array`	Files related to task（filename, fileType, size, filepath）
`timestamp`	`number`	Timestamp when task was executed（Unix milliseconds）

Response Example

JSON
{
  "messages": [
    {
      "conversationId": "550e8400-...",
      "messageId": "msg-abc123",
      "parentMessageId": "msg-parent",
      "sender": "User",
      "text": "Salesデータを分析してください",
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-01-15T10:30:00Z",
      "status": { "processing": false, "unfinished": false },
      "tasks": [],
      "deliverables": []
    }
  ],
  "hasMore": false
}

Error Response

Status	Description
`400`	conversationId is invalid format
`403`	chat:history scope is insufficient
`404`	Conversation not found

PATCH`/v1/conversations/:conversationId`

Conversationのタイトルを更新します。

Request Example

Update conversation

1curl -X PATCH https://api.agenticstar.jp/v1/conversations/550e8400-e29b-41d4-a716-446655440000 \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{ "title": "新しいタイトル" }'

Request Body

パラメータ	型	必須	説明
`title`	`string`	必須	新しいConversationタイトル

Response Fields (200 OK)

Field	Type	Description
`conversationId`	`string`	ConversationID（UUID）
`title`	`string`	更新後のタイトル

Error Response

Status	Description
`400`	title is unspecified or empty
`403`	chat:history scope is insufficient
`404`	Conversation not found

DELETE`/v1/conversations/:conversationId`

Conversationを削除します。

Request Example

Delete conversation

1curl -X DELETE https://api.agenticstar.jp/v1/conversations/550e8400-e29b-41d4-a716-446655440000 \
2-H "Authorization: Bearer <access_token>"

Response (200 OK)

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

Error Response

Status	Description
`403`	chat:history scope is insufficient
`404`	Conversation not found

File Management

Upload, retrieve, and delete files。

SaaS スコープ: chat:file

POST`/v1/files`

Upload file。

Request Example

Upload file

1curl -X POST https://api.agenticstar.jp/v1/files \
2-H "Authorization: Bearer <access_token>" \
3-F "file=@report.pdf"

GET`/v1/files`

Retrieve file list。

Request Example

List files

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

GET`/v1/files/:fileId/content`

Download file。

Request Example

Download file

1curl https://api.agenticstar.jp/v1/files/f-abc123/content \
2-H "Authorization: Bearer <access_token>" \
3-o downloaded_file.pdf

DELETE`/v1/files/:fileId`

Delete fileします。

Request Example

Delete file

1curl -X DELETE https://api.agenticstar.jp/v1/files/f-abc123 \
2-H "Authorization: Bearer <access_token>"

GET`/v1/files/proxy`

Retrieve artifact files generated by agent。

Query Parameters

パラメータ	型	必須	説明
`filepath`	`string`	必須	成果物のファイルパス（Message履歴の deliverables[].filepath to retrieve）

Request Example

Get artifact file

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

Search

GET`/v1/search/messages`

Messageを全文検索します。

Query Parameters

パラメータ	型	必須	説明
`q`	`string`	必須	検索クエリ

Request Example

Search messages

1curl "https://api.agenticstar.jp/v1/search/messages?q=Sales" \
2-H "Authorization: Bearer <access_token>"

User

GET`/v1/user`

Retrieve user information。

Get user

1curl https://api.agenticstar.jp/v1/user \
2-H "Authorization: Bearer <access_token>"

PATCH`/v1/user`

Update user information。

Update user

1curl -X PATCH https://api.agenticstar.jp/v1/user \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{ "username": "田中太郎", "bio": "Engineering Department" }'

POST`/v1/user/password`

Change password。

Change password

1curl -X POST https://api.agenticstar.jp/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}'

Master Data

GET`/v1/organizations`

組織一覧を取得します。

List organizations

1curl https://api.agenticstar.jp/v1/organizations \
2-H "Authorization: Bearer <access_token>"

GET`/v1/job-types`

Retrieve job type list。

List job types

1curl https://api.agenticstar.jp/v1/job-types \
2-H "Authorization: Bearer <access_token>"

Common Error Response

Common errors that may be returned from all endpoints.

Status	Description
`400`	Request parameters are invalid
`401`	Authentication token is invalid or unspecified
`403`	Required scope is insufficient
`404`	Resource not found
`429`	Rate limit exceeded
`500`	Server internal error

Error Response Format

All error responses are returned with 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", "server_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`	Parameter name that caused the error. Included only on validation errors
`error.suggested_action`	`string`	Recommended action. 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"
  }
}

Rate Limiting

Rate limits are applied to API requests. When exceeded, 429 Too Many Requests is returned.

When rate limit is reached, check the Retry-After header (in seconds) in the response and retry after the specified time has passed.

HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{
  "error": {
    "type": "server_error",
    "message": "Rate limit exceeded",
    "code": "rate_limit_exceeded",
    "suggested_action": "Retry after 30 seconds"
  }
}

For retries, it is recommended to use exponential backoff instead of fixed intervals. This prevents concentrated access after the limit is lifted and enables stable use.

Detailed Error Codes

Detailed HTTP status codes that may be returned from all endpoints.

Status	Description
`400 Bad Request`	Request parameters are invalid
`401 Unauthorized`	Token is invalid or unspecified
`403 Forbidden`	No access rights to resource
`404 Not Found`	Resource does not exist
`409 Conflict`	Operation conflicts, such as resource being processed
`413 Payload Too Large`	Request body exceeds size limit
`429 Too Many Requests`	Rate limit exceeded
`500 Internal Server Error`	Server internal error

Base URL​

Authentication​

Pagination​

Chat​

Endpoint List​

POST/v1/chat/completions

Request Headers​

Request Body​

Edition-Specific Parameters​

Message Object​

Content Parts (Array Format)​

Request Example​

Response Headers​

SSE Response Format​

Response Example​

GET/v1/chat/completions/:conversationId

Request Example​

Path Parameters​

Response (200 OK)​

Error Response​

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

Path Parameters​

Response Fields (200 OK)​

Response Example​

Error Response​

Error Response​

Resource API​

Endpoint List​

Conversation Management​

GET/v1/conversations

Request Example​

Query Parameters​

Response Fields (200 OK)​

Response Example​

Error Response​

GET/v1/conversations/:conversationId/messages

Request Example​

Query Parameters​

Response Fields (200 OK)​

Task object​

Response Example​

Error Response​

PATCH/v1/conversations/:conversationId

Request Example​

Request Body​

Response Fields (200 OK)​

Error Response​

DELETE/v1/conversations/:conversationId

Request Example​

Response (200 OK)​

Error Response​

File Management​

POST/v1/files

Request Example​

GET/v1/files

Request Example​

GET/v1/files/:fileId/content

Request Example​

DELETE/v1/files/:fileId

Request Example​

GET/v1/files/proxy

Query Parameters​

Request Example​

Search​

GET/v1/search/messages

Query Parameters​

Request Example​

User​

GET/v1/user

PATCH/v1/user

POST/v1/user/password

Master Data​

GET/v1/organizations

GET/v1/job-types

Common Error Response​

Error Response Format​

Rate Limiting​

Detailed Error Codes​

Base URL

Authentication

Pagination

Chat

Endpoint List

POST`/v1/chat/completions`

Request Headers

Request Body

Edition-Specific Parameters

Message Object

Content Parts (Array Format)

Request Example

Response Headers

SSE Response Format

Response Example

GET`/v1/chat/completions/:conversationId`

Request Example

Path Parameters

Response (200 OK)

Error Response

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

Path Parameters

Response Fields (200 OK)

Response Example

Error Response

Error Response

Resource API

Endpoint List

Conversation Management

GET`/v1/conversations`

Request Example

Query Parameters

Response Fields (200 OK)

Response Example

Error Response

GET`/v1/conversations/:conversationId/messages`

Request Example

Query Parameters

Response Fields (200 OK)

Task object

Response Example

Error Response

PATCH`/v1/conversations/:conversationId`

Request Example

Request Body

Response Fields (200 OK)

Error Response

DELETE`/v1/conversations/:conversationId`

Request Example

Response (200 OK)

Error Response

File Management

POST`/v1/files`

Request Example

GET`/v1/files`

Request Example

GET`/v1/files/:fileId/content`

Request Example

DELETE`/v1/files/:fileId`

Request Example

GET`/v1/files/proxy`

Query Parameters

Request Example

Search

GET`/v1/search/messages`

Query Parameters

Request Example

User

GET`/v1/user`

PATCH`/v1/user`

POST`/v1/user/password`

Master Data

GET`/v1/organizations`

GET`/v1/job-types`

Common Error Response

Error Response Format

Rate Limiting

Detailed Error Codes