API リファレンス
全エンドポイントの仕様とエラーコードのリファレンスです。
ベース URL
すべての API リクエストは以下のベース URL に対して送信します。
https://api.agenticstar.jphttps://<your-domain>本ドキュメントのエンドポイントパスはベース URL からの相対パスで記載しています。
認証
すべてのAPIリクエストには、Authorization ヘッダーに Bearer トークンを含める必要があります。
Authorization: Bearer <access_token>
トークンが無効または未指定の場合、401 Unauthorized が返されます。エンドポイントによっては追加のスコープが必要です。必要なスコープが不足している場合は 403 Forbidden が返されます。
トークンの取得方法・スコープの詳細については、認証ガイドおよび認証リファレンスを参照してください。
ページネーション
一覧取得エンドポイントはカーソルベースのページネーションをサポートしています。
| パラメータ | 型 | 説明 |
|---|---|---|
limit | integer | 1ページあたりの取得件数。エンドポイントごとにデフォルト値と上限が異なります |
cursor | string | 次のページを取得するためのカーソル値。前回のレスポンスに含まれる cursor をそのまま指定します |
order | string | ソート順。"asc"(昇順)または "desc"(降順、デフォルト) |
レスポンスには hasMore フィールドが含まれます。true の場合、cursor の値を次のリクエストに渡すことで次ページを取得できます。
# 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つのエンドポイントで構成されます。メッセージの送信、既存会話への再接続、進行中の会話のキャンセルが可能です。
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 |
リクエストボディ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
model | string | 必須 | 使用するモデルID。"AGENTIC STAR" を指定してください。 |
messages | array | 必須 | メッセージオブジェクトの配列。少なくとも1つの user ロールのメッセージが必要です。 |
stream | boolean | 必須 | true を指定してください。現在、ストリーミングモードのみサポートしています。 |
conversationId | string | — | 既存の会話を継続する場合に会話IDを指定します。省略すると新しい会話が作成されます。 |
エディション固有のパラメータ
agentLevel | string | "default" または "high_performance"。省略時は "default"。 |
agentMode | boolean | エージェントモードの有効/無効。省略時は true。 |
privateMode | boolean | プライベートモードの有効/無効。省略時は false。 |
agentId | string | 使用するエージェントのID。 |
agent | string | agentIdのエイリアス。どちらか一方を指定。 |
Message オブジェクト
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
role | string | 必須 | "user"、"assistant"、または "system" |
content | string | array | 必須 | メッセージの内容。文字列、またはコンテンツパーツの配列。 |
コンテンツパーツ(配列形式の場合)
content を配列で指定する場合、以下のパーツタイプが利用できます。テキストとファイルを組み合わせて送信できます。
| type | パラメータ | 説明 |
|---|---|---|
"text" | text (string) | テキストメッセージ |
"file" | file_id (string) | アップロード済みファイルのID |
リクエスト例
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-Type | text/event-stream |
X-Conversation-Id | 会話ID。新規会話の場合はサーバーが生成したIDが返されます。 |
X-Message-Id | アシスタントの応答メッセージID。 |
SSE レスポンス形式
レスポンスは以下の順序でSSEイベントとして配信されます。各イベントは data: プレフィックス付きのJSON行です。
data: {"choices":[{"delta":{"role":"assistant"}}]}data: {"choices":[{"delta":{"content":"..."}}]} × Ndata: {"choices":[{"finish_reason":"stop"}]}data: [DONE]レスポンスは SSE(Server-Sent Events)ストリーミングで配信されます。各チャンクは OpenAI 互換の ChatCompletionChunk 形式です。接続ライフサイクル、レスポンスオブジェクトの詳細、エージェント拡張フィールド、エラーハンドリングについてはストリーミングガイドを参照してください。
レスポンス例
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ストリームに再接続します。エージェントが長時間実行タスクを処理している場合や、ネットワーク切断後の復帰に使用します。
リクエスト例
1curl https://api.agenticstar.jp/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000 \2-H "Authorization: Bearer <access_token>"パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
conversationId | string | 必須 | 再接続する会話のID |
レスポンス(200 OK)
SSE ストリームに再接続します。レスポンス形式は POST /v1/chat/completions と同じです。レスポンスヘッダーに X-Conversation-Id と X-Message-Id が含まれます。再接続の詳細な手順についてはストリーミングガイドを参照してください。
エラーレスポンス
| ステータス | 説明 |
|---|---|
404 | 会話が見つからない、または進行中でない |
POST/v1/chat/completions/:conversationId/cancel
進行中の会話をキャンセルします。エージェントの実行を中断する場合に使用します。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
conversationId | string | 必須 | キャンセルする会話のID |
レスポンスフィールド(200 OK)
| フィールド | 型 | 説明 |
|---|---|---|
conversationId | string | キャンセルされた会話のID(UUID) |
cancelled | boolean | キャンセル成功時は常に true |
レスポンス例
{ "conversationId": "550e8400-...", "cancelled": true }
エラーレスポンス
| ステータス | 説明 |
|---|---|
400 | conversationId が不正 |
404 | 会話が見つからない |
エラーレスポンス
SSEストリーム開始前のエラーはJSON形式で返されます。ストリーム中のエラーはSSEチャンクとして配信されます。
| ステータス | 説明 |
|---|---|
400 | リクエストパラメータ不正(model, messages, stream等) |
401 | 認証トークンが無効または未指定 |
403 | chat:exec スコープが不足 |
409 | 指定した会話が現在処理中 |
リソース API
会話・ファイル・検索・ユーザー・マスターデータのリソース操作APIです。
エンドポイント一覧
| メソッド | エンドポイント | 説明 | スコープ |
|---|---|---|---|
| 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 認証のみで利用可能です(追加のスコープ不要)。スコープの割当方法については認証リファレンスを参照してください。
会話管理
会話の一覧取得・メッセージ履歴参照・削除・タイトル更新を行います。
chat:historyGET/v1/conversations
会話一覧を取得します。カーソルベースのページネーションに対応しています。
リクエスト例
1curl https://api.agenticstar.jp/v1/conversations?limit=10&order=desc \2-H "Authorization: Bearer <access_token>"クエリパラメータ
| パラメータ | 型 | デフォルト | 説明 |
|---|---|---|---|
limit | integer | 25 | 取得件数(1〜100) |
cursor | string | — | 次ページ取得用カーソル(前回レスポンスの cursor 値) |
order | string | "desc" | "asc" または "desc" |
title | string | — | タイトルで絞り込み |
レスポンスフィールド(200 OK)
| フィールド | 型 | 説明 |
|---|---|---|
conversations | array | 会話オブジェクトの配列 |
conversations[].conversationId | string | 会話の一意識別子(UUID) |
conversations[].title | string | 会話のタイトル |
conversations[].createdAt | string | 作成日時(ISO 8601) |
conversations[].updatedAt | string | 最終更新日時(ISO 8601) |
hasMore | boolean | 次のページが存在するかどうか |
cursor | string | 次ページ取得用カーソル。hasMore が true の場合のみ含まれます |
レスポンス例
{
"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"
}
エラーレスポンス
| ステータス | 説明 |
|---|---|
400 | limit パラメータが不正(1〜100の範囲外) |
403 | chat:history スコープが不足 |
GET/v1/conversations/:conversationId/messages
指定した会話のメッセージ履歴を取得します。
リクエスト例
1curl https://api.agenticstar.jp/v1/conversations/550e8400-e29b-41d4-a716-446655440000/messages?order=asc \2-H "Authorization: Bearer <access_token>"クエリパラメータ
| パラメータ | 型 | デフォルト | 説明 |
|---|---|---|---|
limit | integer | — | 取得件数の上限 |
order | string | "desc" | "asc" または "desc" |
レスポンスフィールド(200 OK)
| フィールド | 型 | 説明 |
|---|---|---|
messages | array | メッセージオブジェクトの配列 |
messages[].conversationId | string | 会話ID(UUID) |
messages[].messageId | string | メッセージの一意識別子 |
messages[].parentMessageId | string | 親メッセージのID(会話ツリー構造の参照) |
messages[].sender | string | 送信者。"User" または "AI" |
messages[].text | string | メッセージの本文テキスト |
messages[].createdAt | string | 作成日時(ISO 8601) |
messages[].updatedAt | string | 最終更新日時(ISO 8601) |
messages[].status | object | メッセージの処理状態 |
messages[].status.processing | boolean | エージェントが現在処理中かどうか |
messages[].status.unfinished | boolean | エージェントの応答が中断されたかどうか |
messages[].tasks | array | エージェントが実行したタスクの配列(後述) |
messages[].deliverables | array | エージェントが生成した成果物の配列。存在する場合のみ含まれます |
messages[].deliverables[].filename | string | 成果物のファイル名 |
messages[].deliverables[].filepath | string | 成果物のファイルパス |
messages[].deliverables[].fileType | string | ファイルの種類 |
hasMore | boolean | 常に false(ページネーション非対応) |
Task オブジェクト
| フィールド | 型 | 説明 |
|---|---|---|
taskId | string | タスクの一意識別子 |
messageId | string | タスクが属するメッセージのID |
conversationId | string | タスクが属する会話のID |
actionType | string | タスクの種類(例: ツール実行、コード生成) |
title | string | タスクのタイトル |
description | string | タスクの説明 |
status | string | タスクの状態(例: "completed"、"running") |
content | string | タスクの実行結果テキスト |
files | array | タスクに関連するファイル(filename, fileType, size, filepath) |
timestamp | number | タスク実行時のタイムスタンプ(Unix ミリ秒) |
レスポンス例
{
"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
}
エラーレスポンス
| ステータス | 説明 |
|---|---|
400 | conversationId が不正なフォーマット |
403 | chat:history スコープが不足 |
404 | 会話が見つからない |
PATCH/v1/conversations/:conversationId
会話のタイトルを更新します。
リクエスト例
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": "新しいタイトル" }'リクエストボディ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
title | string | 必須 | 新しい会話タイトル |
レスポンスフィールド(200 OK)
| フィールド | 型 | 説明 |
|---|---|---|
conversationId | string | 会話ID(UUID) |
title | string | 更新後のタイトル |
エラーレスポンス
| ステータス | 説明 |
|---|---|
400 | title が未指定または空文字 |
403 | chat:history スコープが不足 |
404 | 会話が見つからない |
DELETE/v1/conversations/:conversationId
会話を削除します。
リクエスト例
1curl -X DELETE https://api.agenticstar.jp/v1/conversations/550e8400-e29b-41d4-a716-446655440000 \2-H "Authorization: Bearer <access_token>"レスポンス(200 OK)
{ "conversationId": "550e8400-...", "deleted": true }
エラーレスポンス
| ステータス | 説明 |
|---|---|
403 | chat:history スコープが不足 |
404 | 会話が見つからない |
ファイル管理
ファイルのアップロード・取得・削除を行います。
chat:filePOST/v1/files
ファイルをアップロードします。
リクエスト例
1curl -X POST https://api.agenticstar.jp/v1/files \2-H "Authorization: Bearer <access_token>" \3-F "file=@report.pdf"GET/v1/files
ファイル一覧を取得します。
リクエスト例
1curl https://api.agenticstar.jp/v1/files?order=desc \2-H "Authorization: Bearer <access_token>"GET/v1/files/:fileId/content
ファイルをダウンロードします。
リクエスト例
1curl https://api.agenticstar.jp/v1/files/f-abc123/content \2-H "Authorization: Bearer <access_token>" \3-o downloaded_file.pdfDELETE/v1/files/:fileId
ファイルを削除します。
リクエスト例
1curl -X DELETE https://api.agenticstar.jp/v1/files/f-abc123 \2-H "Authorization: Bearer <access_token>"GET/v1/files/proxy
エージェントが生成した成果物ファイルを取得します。
クエリパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
filepath | string | 必須 | 成果物のファイルパス(メッセージ履歴の deliverables[].filepath で取得) |
リクエスト例
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
メッセージを全文検索します。
クエリパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
q | string | 必須 | 検索クエリ |
リクエスト例
1curl "https://api.agenticstar.jp/v1/search/messages?q=売上" \2-H "Authorization: Bearer <access_token>"ユーザー
GET/v1/user
ユーザー情報を取得します。
1curl https://api.agenticstar.jp/v1/user \2-H "Authorization: Bearer <access_token>"PATCH/v1/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
パスワードを変更します。
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
組織一覧を取得します。
1curl https://api.agenticstar.jp/v1/organizations \2-H "Authorization: Bearer <access_token>"GET/v1/job-types
ジョブタイプ一覧を取得します。
1curl https://api.agenticstar.jp/v1/job-types \2-H "Authorization: Bearer <access_token>"共通エラーレスポンス
すべてのエンドポイントで返される可能性のある共通エラーです。
| ステータス | 説明 |
|---|---|
400 | リクエストパラメータが不正 |
401 | 認証トークンが無効または未指定 |
403 | 必要なスコープが不足 |
404 | リソースが見つからない |
429 | レート制限超過 |
500 | サーバー内部エラー |
エラーレスポンス形式
すべてのエラーレスポンスは以下の共通構造で返されます。
| フィールド | 型 | 説明 |
|---|---|---|
error.type | string | エラーの分類。"invalid_request_error"、"authentication_error"、"insufficient_scope_error"、"forbidden_error"、"not_found_error"、"conflict_error"、"payload_too_large_error"、"server_error" のいずれか |
error.message | string | 人間が読めるエラーメッセージ |
error.code | string | 機械的に処理可能なエラーコード(例: "missing_parameter"、"invalid_parameter"、"invalid_token") |
error.param | string | エラーの原因となったパラメータ名。バリデーションエラー時のみ含まれます |
error.suggested_action | string | 推奨される対処方法。一部のエラーでのみ含まれます |
{
"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 | サーバー内部エラー |