Chat API

Chat APIを使用すると、プログラムでチャットセッションを作成し、メッセージを送信し、AIエージェントからのレスポンスを受信できます。

公開されたエージェントを一覧表示

ワークスペースで利用可能なすべての公開されたエージェントを取得します。

エンドポイント: GET /api/v1/chats/published-agents

リクエスト

curl -X GET "https://api.codeer.ai/api/v1/chats/published-agents" \
  -H "x-api-key: YOUR_API_KEY"

レスポンス

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "カスタマーサポートエージェント",
      "description": "顧客からの問い合わせを処理",
      "workspace_id": "workspace-uuid-here",
      "publish_state": "public",
      "agent_type": "basic",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "message": null,
  "error_code": 0
}

レスポンスフィールド

レスポンスには system_prompt、unified_tools、suggested_questions、use_search、meta、llm_model、バージョン関連フィールドなどの追加フィールドが含まれます。完全なスキーマについてはコードベースを参照してください。

チャットを作成

特定のエージェントで新しいチャットセッションを作成します。

エンドポイント: POST /api/v1/chats

リクエストボディ

フィールド	型	必須	説明
`name`	string	はい	チャットセッション名（最大256文字）
`agent_id`	UUID	はい	エージェントのID（公開バージョンが必要）
`external_user_id`	string	条件付き	あなたのシステムのユーザー識別子。ワークスペースでホワイトリストモードが有効な場合は必須。

エージェントは公開されている必要があります

APIは有効なagent_idを受け付けますが、チャットはエージェントが公開バージョンを持っている場合にのみ使用可能です。未公開のエージェントで作成したチャットにメッセージを送信しようとすると、「Agent version not found」というメッセージで404 Not Foundが返されます。有効なエージェントIDを取得するには、公開されたエージェントを一覧表示エンドポイントを使用してください。

例

curl -X POST "https://api.codeer.ai/api/v1/chats" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "サポートセッション",
    "agent_id": "550e8400-e29b-41d4-a716-446655440000",
    "external_user_id": "user_123"
  }'

レスポンス

{
  "data": {
    "id": 12345,
    "name": "サポートセッション",
    "meta": {
      "external_user_id": "user_123",
      "conversation_agent_id": "550e8400-e29b-41d4-a716-446655440000"
    },
    "external_user_id": "user_123",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  "message": null,
  "error_code": 0
}

チャットを一覧表示

ページネーションとフィルタリングでチャットセッションを取得します。

エンドポイント: GET /api/v1/chats

クエリパラメータ

パラメータ	型	デフォルト	説明
`limit`	integer	50	ページあたりの結果数（最大1000）
`offset`	integer	0	スキップする結果数
`order_by`	string	`-created_at`	ソート順：`created_at`、`-created_at`、`asc`、`desc`
`agent_id`	UUID	-	エージェントでフィルタリング
`external_user_id`	string	-	外部ユーザーでフィルタリング

例

curl -X GET "https://api.codeer.ai/api/v1/chats?limit=10&agent_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: YOUR_API_KEY"

レスポンス

{
  "data": [
    {
      "id": 12345,
      "name": "サポートセッション",
      "meta": { ... },
      "external_user_id": "user_123",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:35:00Z"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total_records": 100,
    "total_pages": 10,
    "current_page": 1,
    "next_page": "https://api.codeer.ai/api/v1/chats?offset=10&limit=10",
    "prev_page": null
  },
  "message": null,
  "error_code": 0
}

チャットメッセージを取得

特定のチャットのメッセージ履歴を取得します。

エンドポイント: GET /api/v1/chats/{chat_id}/messages

パスパラメータ

パラメータ	型	説明
`chat_id`	integer	チャットセッションID

クエリパラメータ

パラメータ	型	デフォルト	説明
`limit`	integer	50	ページあたりの結果数
`offset`	integer	0	スキップする結果数
`external_user_id`	string	-	あなたのシステムのユーザー識別子。APIキー認証時は必須です。`x-external-user-id`ヘッダーでも渡せます。

例

curl -X GET "https://api.codeer.ai/api/v1/chats/12345/messages?external_user_id=user_123" \
  -H "x-api-key: YOUR_API_KEY"

レスポンス

{
  "data": [
    {
      "id": 1001,
      "role": "user",
      "group_id": "group_abc",
      "content": "注文について助けが必要です",
      "meta": {},
      "attached_files": [],
      "feedback_counts": {}
    },
    {
      "id": 1002,
      "role": "assistant",
      "group_id": "group_abc",
      "content": "こんにちは！ご注文のお手伝いをさせていただきます。注文番号を教えていただけますか？",
      "meta": {
        "reasoning_steps": [...],
        "token_usage": {
          "total_prompt_tokens": 150,
          "total_completion_tokens": 45,
          "total_tokens": 195,
          "total_calls": 1
        }
      },
      "attached_files": [],
      "feedback_counts": {
        "sys_helpful": 1
      }
    }
  ],
  "pagination": { ... },
  "message": null,
  "error_code": 0
}

メッセージを送信

チャットにメッセージを送信し、エージェントのレスポンスを受信します。ストリーミング（SSE）と非ストリーミングの両方のモードをサポートしています。

エンドポイント: POST /api/v1/chats/{chat_id}/messages

パスパラメータ

パラメータ	型	説明
`chat_id`	integer	チャットセッションID

リクエストボディ

フィールド	型	必須	説明
`message`	string	はい	ユーザーのメッセージ
`stream`	boolean	いいえ	SSEストリーミングを有効化（デフォルト：`true`）
`agent_id`	UUID	はい	エージェントID（チャットのエージェントと一致する必要があります）
`attached_file_uuids`	array	いいえ	添付するアップロード済みファイルのUUID
`external_user_id`	string	条件付き	あなたのシステムのユーザー識別子。ワークスペースでホワイトリストモードが有効な場合は必須。

発生しうるエラーレスポンス

404 Not Found「Agent not found」 - agent_idがこのワークスペースに存在しません
404 Not Found「Agent version not found」 - エージェントは存在しますが公開バージョンがありません
404 Not Found「Chat not found」 - chat_idが存在しません
400 Bad Request「Agent mismatch」 - agent_idがチャット作成時に使用したエージェントと一致しません
403 Forbidden エラーコード14103 - ワークスペースでホワイトリストモードが有効で、external_user_idがないかホワイトリストに登録されていません

非ストリーミングの例

curl -X POST "https://api.codeer.ai/api/v1/chats/12345/messages" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "営業時間は何時ですか？",
    "stream": false,
    "agent_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

非ストリーミングレスポンス

{
  "data": "営業時間は月曜日から金曜日の午前9時から午後6時までです。週末と主要な祝日は休業しています。他に営業時間についてご質問はありますか？",
  "message": null,
  "error_code": 0
}

ストリーミングの例

curl -N -X POST "https://api.codeer.ai/api/v1/chats/12345/messages" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "message": "営業時間は何時ですか？",
    "stream": true,
    "agent_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

ストリーミングレスポンスの詳細については、SSEストリーミングを参照してください。

ファイルをアップロード

チャットメッセージに添付するファイルをアップロードします。

エンドポイント: POST /api/v1/chats/upload-file

制約

制約	値
最大ファイルサイズ	50 MB
許可されるMIMEタイプ	`application/pdf`、`text/*`、`application/msword`、`application/vnd.openxmlformats-officedocument.wordprocessingml.document`、`application/vnd.openxmlformats-officedocument.presentationml.presentation`、`image/jpeg`、`image/png`、`image/gif`、`image/webp`、`text/html`
許可される拡張子	`.pdf`、`.txt`、`.md`、`.csv`、`.docx`、`.doc`、`.pptx`、`.jpeg`、`.jpg`、`.png`、`.gif`、`.webp`、`.html`

リクエスト

multipart/form-dataエンコーディングを使用：

フィールド	型	必須	説明
`file`	binary	はい	アップロードするファイル
`data`	JSON string	いいえ	`scope`フィールドを含むJSONオブジェクト（`persistent`または`ephemeral`、デフォルト：`persistent`）

例

curl -X POST "https://api.codeer.ai/api/v1/chats/upload-file" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F 'data={"scope":"persistent"}'

レスポンス

{
  "data": {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "original_name": "document.pdf",
    "content_type": "application/pdf",
    "size": 102400,
    "file_url": "https://storage.codeer.ai/files/...",
    "scope": "persistent"
  },
  "message": null,
  "error_code": 0
}

エラーレスポンス

バリデーションが失敗した場合、レスポンスのdataにerror_msgフィールドが含まれます：

{
  "data": {
    "original_name": "large-file.pdf",
    "content_type": "application/pdf",
    "size": 104857600,
    "scope": "persistent",
    "error_msg": "File size check failed (max size: 50 MB)"
  },
  "message": "File size check failed (max size: 50 MB)",
  "error_code": 10006
}

一般的なバリデーションエラー：

"File size check failed (max size: 50 MB)" - ファイルが50MB制限を超えています
"Unsupported content type: {type}" - MIMEタイプが許可リストにありません
"Unsupported file extension: {ext}" - 拡張子が許可リストにありません
"File name is missing" - ファイル名が指定されていません
"File is empty (size must be greater than 0 bytes)" - 空のファイルです

アップロードしたファイルの使用

アップロード後、メッセージ送信時にファイルUUIDを含めます：

curl -X POST "https://api.codeer.ai/api/v1/chats/12345/messages" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "このドキュメントを分析してください",
    "stream": true,
    "agent_id": "550e8400-e29b-41d4-a716-446655440000",
    "attached_file_uuids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
  }'

メッセージフィードバックを作成

アシスタントのレスポンスにフィードバックを送信します。

エンドポイント: POST /api/v1/chats/{chat_id}/messages/{message_id}/feedbacks

パスパラメータ

パラメータ	型	説明
`chat_id`	integer	チャットセッションID
`message_id`	integer	フィードバックを提供するメッセージID

リクエストボディ

フィールド	型	必須	説明
`external_user_id`	string	はい	あなたのシステムのユーザー識別子
`type`	string	はい	フィードバックタイプ：`sys_helpful`または`sys_improve`
`content`	string	いいえ	追加のフィードバックテキスト（`sys_improve`タイプのみ、最大500文字）

例

curl -X POST "https://api.codeer.ai/api/v1/chats/12345/messages/1002/feedbacks" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "user_123",
    "type": "sys_helpful"
  }'

レスポンス

{
  "message": "Feedback created",
  "error_code": 0
}

コード例

Python

import requests

API_KEY = "your-api-key"
BASE_URL = "https://api.codeer.ai/api/v1"

headers = {
    "x-api-key": API_KEY,
    "Content-Type": "application/json"
}

# チャットを作成
chat_response = requests.post(
    f"{BASE_URL}/chats",
    headers=headers,
    json={
        "name": "APIテスト",
        "agent_id": "your-agent-id",
        "external_user_id": "user_123"
    }
)
chat_id = chat_response.json()["data"]["id"]

# メッセージを送信（非ストリーミング）
message_response = requests.post(
    f"{BASE_URL}/chats/{chat_id}/messages",
    headers=headers,
    json={
        "message": "こんにちは！",
        "stream": False,
        "agent_id": "your-agent-id"
    }
)
print(message_response.json()["data"])

JavaScript

const API_KEY = 'your-api-key';
const BASE_URL = 'https://api.codeer.ai/api/v1';

const headers = {
  'x-api-key': API_KEY,
  'Content-Type': 'application/json'
};

// チャットを作成
const chatResponse = await fetch(`${BASE_URL}/chats`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    name: 'APIテスト',
    agent_id: 'your-agent-id',
    external_user_id: 'user_123'
  })
});
const { data: chat } = await chatResponse.json();

// メッセージを送信（非ストリーミング）
const messageResponse = await fetch(`${BASE_URL}/chats/${chat.id}/messages`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    message: 'こんにちは！',
    stream: false,
    agent_id: 'your-agent-id'
  })
});
const { data: reply } = await messageResponse.json();
console.log(reply);

ストリーミング実装を含むその他の例については、公式サンプルリポジトリを参照してください。