Skip to content

API Reference

This section provides comprehensive documentation for the Codeer API, enabling you to build custom integrations with your AI agents.

Base URL

All API requests should be made to:

https://api.codeer.ai/api/v1

Authentication

All API requests require authentication using an API key. Include your API key in the request header:

x-api-key: YOUR_API_KEY

For information on obtaining an API key, see API Access Setup.

Response Format

All API responses follow a standard envelope format:

{
  "data": { ... },
  "message": null,
  "error_code": 0,
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total_records": 100,
    "total_pages": 2,
    "current_page": 1,
    "next_page": "https://api.codeer.ai/api/v1/chats?offset=50&limit=50",
    "prev_page": null
  }
}
Field Description
data The response payload (object, array, or null)
message Human-readable status message (null on success, error description on failure)
error_code Error code as integer (0 on success)
pagination Pagination info (only for list endpoints)

Available Endpoints

Chat API

Method Endpoint Description
GET /chats/published-agents List published agents
POST /chats Create a new chat session
GET /chats List chat sessions
GET /chats/{chat_id}/messages Get messages in a chat
POST /chats/{chat_id}/messages Send a message (supports SSE streaming)
POST /chats/upload-file Upload a file attachment
POST /chats/{chat_id}/messages/{message_id}/feedbacks Submit feedback on a message

For detailed documentation, see Chat API.

Batch API

Method Endpoint Description
POST /batches Create a batch of requests
GET /batches List batches
GET /batches/{batch_id} Get batch status
GET /batches/{batch_id}/results Get batch results
POST /batches/{batch_id}/cancel Cancel a batch

For detailed documentation, see Batch API.

Error Codes

When an error occurs, the response includes an error_code field (integer):

HTTP Status Error Code Name Description
400 10001 SYS_PERMISSION_DENIED Missing or invalid API key
400 10006 SYS_BAD_REQUEST Invalid request parameters
403 10001 SYS_PERMISSION_DENIED Access denied
403 14103 WORKSPACE_CLIENT_NOT_ALLOWED Client not in whitelist (see note below)
404 10003 SYS_NOT_FOUND Resource not found
500 10005 SYS_SERVER_ERROR Internal server error

Whitelist Mode and external_user_id

When a workspace has whitelist mode enabled, the external_user_id parameter becomes effectively required. Requests without a valid whitelisted external_user_id will receive a 403 response with error code 14103.

Rate Limiting

API requests are subject to rate limiting. If you exceed the limit, you'll receive a 429 Too Many Requests response.

Handling Rate Limits

  • Implement exponential backoff with jitter in your client
  • Start with a 1-second delay, doubling on each retry (1s, 2s, 4s, 8s...)
  • Add random jitter (±10-25%) to prevent thundering herd
  • Set a maximum retry count (e.g., 5 retries) or maximum delay (e.g., 32s)

Next Steps