This document provides comprehensive reference documentation for the CoAgent REST API, including endpoints, request/response schemas, authentication, error handling, and client examples for Python and Rust.
Base URL and Versioning
The CoAgent API uses versioned endpoints with the following base URL structure:
http://localhost:3000/api/v1
For production deployments, replace localhost:3000 with your CoAgent instance URL.
Authentication
Currently, CoAgent operates without authentication for local development. For production deployments, authentication may be implemented at the infrastructure level (API Gateway, reverse proxy, etc.).
Content Type
All API requests must include the Content-Type: application/json header when sending JSON data.
Rate Limiting
CoAgent implements rate limiting to protect against abuse. When rate limits are exceeded, the API returns HTTP 429 (Too Many Requests).
Default limit: 100 requests per minute per client
Burst limit: 20 concurrent requests
Retry behavior: Clients should implement exponential backoff
Error Handling
HTTP Status Codes
Status Code
Description
200
OK - Request succeeded
201
Created - Resource created successfully
400
Bad Request - Invalid request parameters
404
Not Found - Resource not found
409
Conflict - Resource already exists
429
Too Many Requests - Rate limit exceeded
500
Internal Server Error - Server error
502
Bad Gateway - Upstream service error
503
Service Unavailable - Service temporarily unavailable
Error Response Format
All error responses follow this consistent format:
{"error":{"code":"INVALID_REQUEST","message":"The request parameters are invalid","details":{"field":"prompt","reason":"Prompt cannot be empty"}}}
{"run_id":"eval_123e4567-e89b-12d3-a456-426614174000","preamble":"You are a helpful customer support assistant.","prompt":"I need help with returning a product I bought last week","model_ref":{"provider_id":"openai-prod","model_name":"gpt-4"},"log_meta":{"user_id":"user_456","session_id":"session_789","component":"customer-support"}}
Response
Field
Type
Description
response
string
Generated response from the AI model
token_usage
object
Token usage statistics
run_id
string
Echo of the request run_id
Token Usage Object
Field
Type
Description
prompt_tokens
integer
Tokens used for the prompt
completion_tokens
integer
Tokens used for the completion
total_tokens
integer
Total tokens used
Response Example
{"response":"I'd be happy to help you with your return. To process your return efficiently, I'll need a few details: What product are you looking to return, and do you have your order number or receipt?","token_usage":{"prompt_tokens":45,"completion_tokens":38,"total_tokens":83},"run_id":"eval_123e4567-e89b-12d3-a456-426614174000"}
Error Responses
Invalid Request (400)
{"error":{"code":"INVALID_REQUEST","message":"Missing required field: prompt","details":{"field":"prompt","reason":"Prompt field is required and cannot be empty"}}}
Model Not Found (404)
{"error":{"code":"MODEL_NOT_FOUND","message":"The specified model was not found","details":{"provider_id":"openai-prod","model_name":"gpt-5","available_models":["gpt-4","gpt-3.5-turbo"]}}}
Rate Limited (429)
{"error":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","details":{"retry_after_seconds":60,"limit":"100 requests per minute"}}}
Agent Management Endpoints
List Agents
Retrieve all configured agents.
GET /api/v1/agents
Response
{"agents":[{"id":"agent_123","name":"customer-support-agent","description":"Agent for handling customer support queries","preamble":"You are a helpful customer support assistant.","created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T10:30:00Z"}]}
Create Agent
Create a new agent configuration.
POST /api/v1/agents
Request Body
Field
Type
Required
Description
name
string
Yes
Unique name for the agent
description
string
No
Human-readable description
preamble
string
Yes
System message for the agent
Request Example
{"name":"technical-support-agent","description":"Agent specialized in technical support queries","preamble":"You are a knowledgeable technical support specialist. Provide clear, step-by-step solutions to technical problems."}
Response
{"id":"agent_456","name":"technical-support-agent","description":"Agent specialized in technical support queries","preamble":"You are a knowledgeable technical support specialist. Provide clear, step-by-step solutions to technical problems.","created_at":"2024-01-15T11:00:00Z","updated_at":"2024-01-15T11:00:00Z"}
Get Agent
Retrieve a specific agent by ID.
GET /api/v1/agents/{agent_id}
Response
{"id":"agent_123","name":"customer-support-agent","description":"Agent for handling customer support queries","preamble":"You are a helpful customer support assistant.","created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T10:30:00Z"}
{"testsets":[{"id":"testset_123","name":"Customer Support Evaluation","description":"Test cases for customer support scenarios","case_count":15,"created_at":"2024-01-15T08:00:00Z"}]}
Create Test Set
Create a new test set.
POST /api/v1/testsets
Request Body
Field
Type
Required
Description
name
string
Yes
Name of the test set
description
string
No
Description of the test set
cases
array
Yes
Array of test cases
Run Test Set
Execute a test set against specified configurations.