メインコンテンツまでスキップ

API リファレンス

全エンドポイントの仕様とエラーコードのリファレンスです。

ベース URL

すべての API リクエストは以下のベース URL に対して送信します。

SaaS
https://api.agenticstar.jp
Marketplace
https://<your-domain>

本ドキュメントのエンドポイントパスはベース URL からの相対パスで記載しています。

認証

すべてのAPIリクエストには、Authorization ヘッダーに Bearer トークンを含める必要があります。

Authorization: Bearer <access_token>

トークンが無効または未指定の場合、401 Unauthorized が返されます。エンドポイントによっては追加のスコープが必要です。必要なスコープが不足している場合は 403 Forbidden が返されます。

トークンの取得方法・スコープの詳細については、認証ガイドおよび認証リファレンスを参照してください。

ページネーション

一覧取得エンドポイントはカーソルベースのページネーションをサポートしています。

パラメータ説明
limitinteger1ページあたりの取得件数。エンドポイントごとにデフォルト値と上限が異なります
cursorstring次のページを取得するためのカーソル値。前回のレスポンスに含まれる cursor をそのまま指定します
orderstringソート順。"asc"(昇順)または "desc"(降順、デフォルト)

レスポンスには hasMore フィールドが含まれます。true の場合、cursor の値を次のリクエストに渡すことで次ページを取得できます。

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

# 2ページ目(レスポンスの cursor 値を使用)
curl https://api.agenticstar.jp/v1/conversations?limit=10&cursor=2025-01-15T10:30:00.000Z \
-H "Authorization: Bearer <access_token>"

現在、カーソルベースのページネーションに対応しているのは GET /v1/conversations です。他のエンドポイントでは hasMore は常に false です。

チャット

OpenAI互換のChat Completions APIです。エージェントとの対話はSSE(Server-Sent Events)ストリーミングで配信されます。

チャットAPIは3つのエンドポイントで構成されます。メッセージの送信、既存会話への再接続、進行中の会話のキャンセルが可能です。

SaaSMarketplace

SSE ストリーミングガイド

接続フロー・レスポンスオブジェクト・Delta拡張・実行パターン・再接続・エラーハンドリングの詳細解説

ガイドを見る

エンドポイント一覧

メソッドエンドポイント説明スコープ
POST/v1/chat/completionsチャットメッセージを送信し、SSEストリーミングでレスポンスを取得chat:exec
GET/v1/chat/completions/:conversationId進行中の会話のSSEストリームに再接続chat:exec
POST/v1/chat/completions/:conversationId/cancel進行中の会話をキャンセルchat:exec

POST/v1/chat/completions

エージェントにメッセージを送信し、SSEストリーミングでレスポンスを受け取ります。レスポンスはOpenAI互換のChat Completion Chunk形式で配信されます。

リクエストヘッダー

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

リクエストボディ

パラメータ必須説明
modelstring必須使用するモデルID。"AGENTIC STAR" を指定してください。
messagesarray必須メッセージオブジェクトの配列。少なくとも1つの user ロールのメッセージが必要です。
streamboolean必須true を指定してください。現在、ストリーミングモードのみサポートしています。
conversationIdstring既存の会話を継続する場合に会話IDを指定します。省略すると新しい会話が作成されます。

エディション固有のパラメータ

SaaS
agentLevelstring"default" または "high_performance"。省略時は "default"。
agentModebooleanエージェントモードの有効/無効。省略時は true。
privateModebooleanプライベートモードの有効/無効。省略時は false。
Marketplace
agentIdstring使用するエージェントのID。
agentstringagentIdのエイリアス。どちらか一方を指定。

Message オブジェクト

パラメータ必須説明
rolestring必須"user"、"assistant"、または "system"
contentstring | array必須メッセージの内容。文字列、またはコンテンツパーツの配列。

コンテンツパーツ(配列形式の場合)

content を配列で指定する場合、以下のパーツタイプが利用できます。テキストとファイルを組み合わせて送信できます。

typeパラメータ説明
"text"text (string)テキストメッセージ
"file"file_id (string)アップロード済みファイルのID

リクエスト例

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": "売上データを分析してください"
11 }
12 ]
13}'

レスポンスヘッダー

ヘッダー説明
Content-Typetext/event-stream
X-Conversation-Id会話ID。新規会話の場合はサーバーが生成したIDが返されます。
X-Message-Idアシスタントの応答メッセージID。

SSE レスポンス形式

レスポンスは以下の順序でSSEイベントとして配信されます。各イベントは data: プレフィックス付きのJSON行です。

SSEイベントフロー
1. data: {"choices":[{"delta":{"role":"assistant"}}]}
2. data: {"choices":[{"delta":{"content":"..."}}]} × N
3. data: {"choices":[{"finish_reason":"stop"}]}
4. data: [DONE]

レスポンスは SSE(Server-Sent Events)ストリーミングで配信されます。各チャンクは OpenAI 互換の ChatCompletionChunk 形式です。接続ライフサイクル、レスポンスオブジェクトの詳細、エージェント拡張フィールド、エラーハンドリングについてはストリーミングガイドを参照してください。

レスポンス例

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":"売上データ"},"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":"を分析します。"},"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

進行中の会話のSSEストリームに再接続します。エージェントが長時間実行タスクを処理している場合や、ネットワーク切断後の復帰に使用します。

リクエスト例

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

パスパラメータ

パラメータ必須説明
conversationIdstring必須再接続する会話のID

レスポンス(200 OK)

SSE ストリームに再接続します。レスポンス形式は POST /v1/chat/completions と同じです。レスポンスヘッダーに X-Conversation-IdX-Message-Id が含まれます。再接続の詳細な手順についてはストリーミングガイドを参照してください。

エラーレスポンス

ステータス説明
404会話が見つからない、または進行中でない

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

進行中の会話をキャンセルします。エージェントの実行を中断する場合に使用します。

パスパラメータ

パラメータ必須説明
conversationIdstring必須キャンセルする会話のID

レスポンスフィールド(200 OK)

フィールド説明
conversationIdstringキャンセルされた会話のID(UUID)
cancelledbooleanキャンセル成功時は常に true

レスポンス例

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

エラーレスポンス

ステータス説明
400conversationId が不正
404会話が見つからない

エラーレスポンス

SSEストリーム開始前のエラーはJSON形式で返されます。ストリーム中のエラーはSSEチャンクとして配信されます。

ステータス説明
400リクエストパラメータ不正(model, messages, stream等)
401認証トークンが無効または未指定
403chat:exec スコープが不足
409指定した会話が現在処理中

リソース API

会話・ファイル・検索・ユーザー・マスターデータのリソース操作APIです。

SaaS

エンドポイント一覧

メソッドエンドポイント説明スコープ
GET/v1/conversations会話一覧を取得chat:history
GET/v1/conversations/:id/messagesメッセージ履歴を取得chat:history
PATCH/v1/conversations/:id会話のタイトルを更新chat:history
DELETE/v1/conversations/:id会話を削除chat:history
GET/v1/filesファイル一覧を取得chat:file
POST/v1/filesファイルをアップロードchat:file
GET/v1/files/:id/contentファイルをダウンロードchat:file
DELETE/v1/files/:idファイルを削除chat:file
GET/v1/files/proxy成果物ファイルを取得chat:exec
GET/v1/search/messagesメッセージを全文検索chat:history
GET/v1/userユーザー情報を取得
PATCH/v1/userユーザー情報を更新
POST/v1/user/passwordパスワードを変更
GET/v1/organizations組織一覧を取得
GET/v1/job-typesジョブタイプ一覧を取得

スコープ欄が「—」のエンドポイントは JWT 認証のみで利用可能です(追加のスコープ不要)。スコープの割当方法については認証リファレンスを参照してください。

会話管理

会話の一覧取得・メッセージ履歴参照・削除・タイトル更新を行います。

SaaS スコープ: chat:history

GET/v1/conversations

会話一覧を取得します。カーソルベースのページネーションに対応しています。

リクエスト例

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

クエリパラメータ

パラメータデフォルト説明
limitinteger25取得件数(1〜100)
cursorstring次ページ取得用カーソル(前回レスポンスの cursor 値)
orderstring"desc""asc" または "desc"
titlestringタイトルで絞り込み

レスポンスフィールド(200 OK)

フィールド説明
conversationsarray会話オブジェクトの配列
conversations[].conversationIdstring会話の一意識別子(UUID)
conversations[].titlestring会話のタイトル
conversations[].createdAtstring作成日時(ISO 8601)
conversations[].updatedAtstring最終更新日時(ISO 8601)
hasMoreboolean次のページが存在するかどうか
cursorstring次ページ取得用カーソル。hasMore が true の場合のみ含まれます

レスポンス例

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

エラーレスポンス

ステータス説明
400limit パラメータが不正(1〜100の範囲外)
403chat:history スコープが不足

GET/v1/conversations/:conversationId/messages

指定した会話のメッセージ履歴を取得します。

リクエスト例

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

クエリパラメータ

パラメータデフォルト説明
limitinteger取得件数の上限
orderstring"desc""asc" または "desc"

レスポンスフィールド(200 OK)

フィールド説明
messagesarrayメッセージオブジェクトの配列
messages[].conversationIdstring会話ID(UUID)
messages[].messageIdstringメッセージの一意識別子
messages[].parentMessageIdstring親メッセージのID(会話ツリー構造の参照)
messages[].senderstring送信者。"User" または "AI"
messages[].textstringメッセージの本文テキスト
messages[].createdAtstring作成日時(ISO 8601)
messages[].updatedAtstring最終更新日時(ISO 8601)
messages[].statusobjectメッセージの処理状態
messages[].status.processingbooleanエージェントが現在処理中かどうか
messages[].status.unfinishedbooleanエージェントの応答が中断されたかどうか
messages[].tasksarrayエージェントが実行したタスクの配列(後述)
messages[].deliverablesarrayエージェントが生成した成果物の配列。存在する場合のみ含まれます
messages[].deliverables[].filenamestring成果物のファイル名
messages[].deliverables[].filepathstring成果物のファイルパス
messages[].deliverables[].fileTypestringファイルの種類
hasMoreboolean常に false(ページネーション非対応)

Task オブジェクト

フィールド説明
taskIdstringタスクの一意識別子
messageIdstringタスクが属するメッセージのID
conversationIdstringタスクが属する会話のID
actionTypestringタスクの種類(例: ツール実行、コード生成)
titlestringタスクのタイトル
descriptionstringタスクの説明
statusstringタスクの状態(例: "completed"、"running")
contentstringタスクの実行結果テキスト
filesarrayタスクに関連するファイル(filename, fileType, size, filepath)
timestampnumberタスク実行時のタイムスタンプ(Unix ミリ秒)

レスポンス例

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

エラーレスポンス

ステータス説明
400conversationId が不正なフォーマット
403chat:history スコープが不足
404会話が見つからない

PATCH/v1/conversations/:conversationId

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

リクエスト例

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": "新しいタイトル" }'

リクエストボディ

パラメータ必須説明
titlestring必須新しい会話タイトル

レスポンスフィールド(200 OK)

フィールド説明
conversationIdstring会話ID(UUID)
titlestring更新後のタイトル

エラーレスポンス

ステータス説明
400title が未指定または空文字
403chat:history スコープが不足
404会話が見つからない

DELETE/v1/conversations/:conversationId

会話を削除します。

リクエスト例

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

レスポンス(200 OK)

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

エラーレスポンス

ステータス説明
403chat:history スコープが不足
404会話が見つからない

ファイル管理

ファイルのアップロード・取得・削除を行います。

SaaS スコープ: chat:file

POST/v1/files

ファイルをアップロードします。

リクエスト例

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

ファイル一覧を取得します。

リクエスト例

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

GET/v1/files/:fileId/content

ファイルをダウンロードします。

リクエスト例

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

GET/v1/files/proxy

エージェントが生成した成果物ファイルを取得します。

クエリパラメータ

パラメータ必須説明
filepathstring必須成果物のファイルパス(メッセージ履歴の deliverables[].filepath で取得)

リクエスト例

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

検索

GET/v1/search/messages

メッセージを全文検索します。

クエリパラメータ

パラメータ必須説明
qstring必須検索クエリ

リクエスト例

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

ユーザー

GET/v1/user

ユーザー情報を取得します。

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

PATCH/v1/user

ユーザー情報を更新します。

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": "エンジニアリング部門" }'

POST/v1/user/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}'

マスターデータ

GET/v1/organizations

組織一覧を取得します。

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

GET/v1/job-types

ジョブタイプ一覧を取得します。

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

共通エラーレスポンス

すべてのエンドポイントで返される可能性のある共通エラーです。

ステータス説明
400リクエストパラメータが不正
401認証トークンが無効または未指定
403必要なスコープが不足
404リソースが見つからない
429レート制限超過
500サーバー内部エラー

エラーレスポンス形式

すべてのエラーレスポンスは以下の共通構造で返されます。

フィールド説明
error.typestringエラーの分類。"invalid_request_error"、"authentication_error"、"insufficient_scope_error"、"forbidden_error"、"not_found_error"、"conflict_error"、"payload_too_large_error"、"server_error" のいずれか
error.messagestring人間が読めるエラーメッセージ
error.codestring機械的に処理可能なエラーコード(例: "missing_parameter"、"invalid_parameter"、"invalid_token")
error.paramstringエラーの原因となったパラメータ名。バリデーションエラー時のみ含まれます
error.suggested_actionstring推奨される対処方法。一部のエラーでのみ含まれます
JSON
{
"error": {
"type": "invalid_request_error",
"message": "Invalid parameter: limit",
"code": "invalid_parameter",
"param": "limit",
"suggested_action": "limit must be between 1 and 100"
}
}

レート制限

APIにはリクエストのレート制限が適用されています。制限を超過すると 429 Too Many Requests が返されます。

レート制限に達した場合は、レスポンスヘッダーの Retry-After(秒数)を確認し、指定された時間が経過してからリトライしてください。

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

リトライ時は、固定間隔ではなく指数バックオフ(exponential backoff)の採用を推奨します。これにより、制限解除後の集中アクセスを防ぎ、安定した利用が可能になります。

詳細エラーコード

すべてのエンドポイントで返される可能性のある詳細なHTTPステータスコードです。

ステータス説明
400 Bad Requestリクエストパラメータが不正
401 Unauthorizedトークンが無効または未指定
403 Forbiddenリソースへのアクセス権限なし
404 Not Foundリソースが存在しない
409 Conflictリソースが現在処理中など、操作が競合
413 Payload Too Largeリクエストボディがサイズ上限を超過
429 Too Many Requestsレート制限を超過
500 Internal Server Errorサーバー内部エラー