Chat API

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

基本認証

このページのすべての例では、次のヘッダーを使用します。

x-api-key: YOUR_API_KEY

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

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

エンドポイント: 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	条件付き	あなたのシステムのユーザー識別子。ワークスペースでホワイトリストモードが有効な場合は必須。

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

チャット作成自体は有効なワークスペース agent_id で行えますが、実際にメッセージを送るにはその Agent に公開済みバージョンが必要です。未公開の場合、後続のメッセージ送信で 404 Not Found と Agent version not found が返ります。公開可能な Agent 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
}

---

チャットを更新

既存のチャットセッション名を変更します。

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

パスパラメータ

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

リクエストボディ

フィールド	型	必須	説明
name	string	はい	新しいチャットセッション名（最大256文字）
external_user_id	string	条件付き	あなたのシステムのユーザー識別子。特定の外部ユーザーが所有するチャットを更新する場合に指定します。client-token認証では、この値はリクエストボディではなく token から解決されます。

例

curl -X PUT "https://api.codeer.ai/api/v1/chats/12345" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "名前を変更したサポートセッション",
    "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:40:00Z"
  },
  "message": null,
  "error_code": 0
}

---

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

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

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

パスパラメータ

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

クエリパラメータ

パラメータ	型	デフォルト	説明
limit	integer	50	ページあたりの結果数
offset	integer	0	スキップする結果数
include_tool_tags	boolean	false	assistantメッセージ内の <tool ...>...</tool> ブロックを保持するかどうか。false の場合、assistant の content から tool ブロックを削除します。
external_user_id	string	-	あなたのシステムのユーザー識別子。APIキー認証では任意です。client-token認証では、この値はクエリパラメータではなく token から解決されます。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
}

Assistant Tool ブロックの表示

• include_tool_tags=false（デフォルト）の場合、このエンドポイントはassistantメッセージから <tool ...>...</tool> ブロックを削除します。
• 生のtoolブロックが必要な場合は include_tool_tags=true を指定してください。

---

メッセージを送信

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

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

パスパラメータ

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

リクエストボディ

フィールド	型	必須	説明
message	string	はい	ユーザーのメッセージ
stream	boolean	いいえ	SSEストリーミングを有効化（デフォルト：true）
include_tool_tags	boolean	いいえ	非ストリーム data と SSE delta/completed テキストで <tool ...>...</tool> ブロックを保持（デフォルト：false）
agent_id	UUID	はい	エージェントID（チャットのエージェントと一致する必要があります）
attached_file_uuids	array	いいえ	添付するアップロード済みファイルのUUID
resume_form_request_id	string	いいえ	フォームリクエストの送信または拒否後に、直前のユーザーターンから処理を再開
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時までです。週末と主要な祝日は休業しています。他に営業時間についてご質問はありますか？",
  "structured_message": {
    "final_text": "営業時間は月曜日から金曜日の午前9時から午後6時までです。週末と主要な祝日は休業しています。他に営業時間についてご質問はありますか？",
    "conversation_group_id": "group_abc",
    "user_conversation_id": 1001,
    "assistant_conversation_id": 1002
  },
  "message": null,
  "error_code": 0
}

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

• data は後方互換のため、引き続きプレーンテキストを返します。
• structured_message には、追加の list-messages 呼び出しなしで使える会話 ID 情報が入ります。

ストリーミングの例

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ストリーミングを参照してください。

Tool Tag ロールアウト方針

• 外部API呼び出しはデフォルトで <tool> ブロックを非表示にします（include_tool_tags 未指定または false）。
• toolブロックが必要な内部クライアントは、include_tool_tags=true を明示的に指定してください。
• 同じフラグは POST /chats/{chat_id}/messages、POST /chats/{chat_id}/regenerate、GET /chats/{chat_id}/messages に適用されます。

---

フォームリクエストの送信または拒否

保留中のフォームリクエストを送信するか、拒否として確定します。

エンドポイント: POST /api/v1/chats/{chat_id}/form-requests/{form_request_id}/submit

パスパラメータ

パラメータ	型	説明
chat_id	integer	チャットセッション ID
form_request_id	UUID	保留中のフォームリクエスト ID

リクエストボディ

フィールド	型	必須	説明
conversation_group_id	string	はい	このフォームを開いた会話グループ ID
rejected	boolean	いいえ	true の場合は送信せず拒否扱いにします
submission	object	条件付き	rejected=false の場合は必須、rejected=true の場合は空である必要があります
external_user_id	string	条件付き	あなたのシステムのユーザー識別子。ワークスペースでホワイトリストモードが有効な場合は必須。

送信例

curl -X POST "https://api.codeer.ai/api/v1/chats/12345/form-requests/form-uuid-here/submit" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_group_id": "group_abc",
    "rejected": false,
    "submission": {
      "email": "user@example.com"
    },
    "external_user_id": "user_123"
  }'

拒否例

curl -X POST "https://api.codeer.ai/api/v1/chats/12345/form-requests/form-uuid-here/submit" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_group_id": "group_abc",
    "rejected": true,
    "submission": null,
    "external_user_id": "user_123"
  }'

レスポンス

{
  "data": null,
  "message": null,
  "error_code": 0
}

送信後に会話を続ける

フォーム送信または拒否のあとに、元のユーザーターンから Agent の処理を再開したい場合は、POST /api/v1/chats/{chat_id}/messages を再度呼び、同じ form_request_id を resume_form_request_id に渡してください。

よくあるエラー

• 404 Not Found：form_request_id がこのチャットに存在しない
• 400 Bad Request：conversation_group_id が一致しない、またはフォームが既に保留状態ではない

---

メッセージの再生成

指定したグループ内の元のユーザーメッセージを再処理して、そのターンを再生成します。

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

パスパラメータ

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

リクエストボディ

フィールド	型	必須	説明
conversation_group_id	string	はい	再生成対象の会話グループID
stream	boolean	いいえ	SSEストリーミングを有効化（デフォルト：true）
include_tool_tags	boolean	いいえ	非ストリーム data と SSE delta/completed テキストで <tool ...>...</tool> ブロックを保持（デフォルト：false）
external_user_id	string	条件付き	あなたのシステムのユーザー識別子。ワークスペースでホワイトリストモードが有効な場合は必須。

非ストリーミングの例

curl -X POST "https://api.codeer.ai/api/v1/chats/12345/regenerate" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_group_id": "group_abc",
    "stream": false
  }'

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

{
  "data": "営業時間は月曜日から金曜日の午前9時から午後6時までです。",
  "structured_message": {
    "final_text": "営業時間は月曜日から金曜日の午前9時から午後6時までです。",
    "conversation_group_id": "group_abc",
    "user_conversation_id": 1001,
    "assistant_conversation_id": 1002
  },
  "message": null,
  "error_code": 0
}

ストリーミングの例

curl -N -X POST "https://api.codeer.ai/api/v1/chats/12345/regenerate" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "conversation_group_id": "group_abc",
    "stream": true
  }'

ストリーミングレスポンスの詳細については、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（persistent または ephemeral、デフォルト: persistent）と任意の external_user_id を含む JSON オブジェクト

APIキーリクエストでアップロードを特定の external user に紐づけたい場合は、data に external_user_id を含めてください。client-token リクエストでは external_user_id は token から解決されるため、追加で送る必要はありません。

例

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","external_user_id":"user_123"}'

レスポンス

{
  "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);

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