Chat API

The Chat API enables you to create chat sessions, send messages, and receive responses from your AI agents programmatically.

List Published Agents

Retrieve all published agents available in your workspace.

Endpoint: GET /api/v1/chats/published-agents

Request

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

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Customer Support Agent",
      "description": "Handles customer inquiries",
      "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
}

Response Fields

The response includes additional fields like system_prompt, unified_tools, suggested_questions, use_search, meta, llm_model, and versioning fields. See the full schema in the codebase for complete details.

Create Chat

Create a new chat session with a specific agent.

Endpoint: POST /api/v1/chats

Request Body

Field	Type	Required	Description
`name`	string	Yes	Chat session name (max 256 characters)
`agent_id`	UUID	Yes	The agent's ID (must have a published version)
`external_user_id`	string	Conditional	Your system's user identifier. Required if workspace has whitelist mode enabled.

Agent Must Be Published

While the API accepts any valid agent_id, the chat will only be usable if the agent has a published version. Attempting to send messages to a chat created with an unpublished agent will return 404 Not Found with message "Agent version not found". Use the List Published Agents endpoint to get valid agent IDs.

Example

curl -X POST "https://api.codeer.ai/api/v1/chats" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Session",
    "agent_id": "550e8400-e29b-41d4-a716-446655440000",
    "external_user_id": "user_123"
  }'

Response

{
  "data": {
    "id": 12345,
    "name": "Support Session",
    "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
}

List Chats

Retrieve chat sessions with pagination and filtering.

Endpoint: GET /api/v1/chats

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	50	Results per page (max 1000)
`offset`	integer	0	Number of results to skip
`order_by`	string	`-created_at`	Sort order: `created_at`, `-created_at`, `asc`, `desc`
`agent_id`	UUID	-	Filter by agent
`external_user_id`	string	-	Filter by external user

Example

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"

Response

{
  "data": [
    {
      "id": 12345,
      "name": "Support Session",
      "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 Chat Messages

Retrieve the message history for a specific chat.

Endpoint: GET /api/v1/chats/{chat_id}/messages

Path Parameters

Parameter	Type	Description
`chat_id`	integer	The chat session ID

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	50	Results per page
`offset`	integer	0	Number of results to skip
`external_user_id`	string	-	Your system's user identifier. Required for API key authentication. Can also be passed via `x-external-user-id` header.

Example

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

Response

{
  "data": [
    {
      "id": 1001,
      "role": "user",
      "group_id": "group_abc",
      "content": "Hello, I need help with my order",
      "meta": {},
      "attached_files": [],
      "feedback_counts": {}
    },
    {
      "id": 1002,
      "role": "assistant",
      "group_id": "group_abc",
      "content": "Hello! I'd be happy to help you with your order. Could you please provide your order number?",
      "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
}

Send Message

Send a message to a chat and receive the agent's response. Supports both streaming (SSE) and non-streaming modes.

Endpoint: POST /api/v1/chats/{chat_id}/messages

Path Parameters

Parameter	Type	Description
`chat_id`	integer	The chat session ID

Request Body

Field	Type	Required	Description
`message`	string	Yes	The user's message
`stream`	boolean	No	Enable SSE streaming (default: `true`)
`agent_id`	UUID	Yes	The agent ID (must match chat's agent)
`attached_file_uuids`	array	No	UUIDs of uploaded files to attach
`external_user_id`	string	Conditional	Your system's user identifier. Required if workspace has whitelist mode enabled.

Possible Error Responses

404 Not Found with "Agent not found" - The agent_id doesn't exist in this workspace
404 Not Found with "Agent version not found" - The agent exists but has no published version
404 Not Found with "Chat not found" - The chat_id doesn't exist
400 Bad Request with "Agent mismatch" - The agent_id doesn't match the agent used to create the chat
403 Forbidden with error code 14103 - Workspace has whitelist mode and external_user_id is missing or not whitelisted

Non-Streaming Example

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": "What are your business hours?",
    "stream": false,
    "agent_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

Non-Streaming Response

{
  "data": "Our business hours are Monday to Friday, 9 AM to 6 PM EST. We're closed on weekends and major holidays. Is there anything specific you'd like to know about our availability?",
  "message": null,
  "error_code": 0
}

Streaming Example

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": "What are your business hours?",
    "stream": true,
    "agent_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

For detailed information on streaming responses, see SSE Streaming.

Upload File

Upload a file to attach to chat messages.

Endpoint: POST /api/v1/chats/upload-file

Constraints

Constraint	Value
Maximum file size	50 MB
Allowed MIME types	`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`
Allowed extensions	`.pdf`, `.txt`, `.md`, `.csv`, `.docx`, `.doc`, `.pptx`, `.jpeg`, `.jpg`, `.png`, `.gif`, `.webp`, `.html`

Request

Use multipart/form-data encoding:

Field	Type	Required	Description
`file`	binary	Yes	The file to upload
`data`	JSON string	No	JSON object with `scope` field (`persistent` or `ephemeral`, default: `persistent`)

Example

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

Response

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

Error Response

When validation fails, the response includes an error_msg field in the data:

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

Common validation errors:

"File size check failed (max size: 50 MB)" - File exceeds 50 MB limit
"Unsupported content type: {type}" - MIME type not in allowed list
"Unsupported file extension: {ext}" - Extension not in allowed list
"File name is missing" - No filename provided
"File is empty (size must be greater than 0 bytes)" - Empty file

Using Uploaded Files

After uploading, include the file UUID when sending a message:

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": "Please analyze this document",
    "stream": true,
    "agent_id": "550e8400-e29b-41d4-a716-446655440000",
    "attached_file_uuids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
  }'

Create Message Feedback

Submit feedback on an assistant's response.

Endpoint: POST /api/v1/chats/{chat_id}/messages/{message_id}/feedbacks

Path Parameters

Parameter	Type	Description
`chat_id`	integer	The chat session ID
`message_id`	integer	The message ID to provide feedback on

Request Body

Field	Type	Required	Description
`external_user_id`	string	Yes	Your system's user identifier
`type`	string	Yes	Feedback type: `sys_helpful` or `sys_improve`
`content`	string	No	Additional feedback text (only for `sys_improve` type, max 500 characters)

Example

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

Response

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

Code Examples

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

# Create a chat
chat_response = requests.post(
    f"{BASE_URL}/chats",
    headers=headers,
    json={
        "name": "API Test",
        "agent_id": "your-agent-id",
        "external_user_id": "user_123"
    }
)
chat_id = chat_response.json()["data"]["id"]

# Send a message (non-streaming)
message_response = requests.post(
    f"{BASE_URL}/chats/{chat_id}/messages",
    headers=headers,
    json={
        "message": "Hello!",
        "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'
};

// Create a chat
const chatResponse = await fetch(`${BASE_URL}/chats`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    name: 'API Test',
    agent_id: 'your-agent-id',
    external_user_id: 'user_123'
  })
});
const { data: chat } = await chatResponse.json();

// Send a message (non-streaming)
const messageResponse = await fetch(`${BASE_URL}/chats/${chat.id}/messages`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    message: 'Hello!',
    stream: false,
    agent_id: 'your-agent-id'
  })
});
const { data: reply } = await messageResponse.json();
console.log(reply);

For more examples including streaming implementations, see the official examples repository.