API Reference
Build integrations with the Custom Agents API.
API Reference
The Custom Agents API lets you programmatically manage agents, send emails, retrieve message history, and more.
Authentication
All API requests require an API key. You can generate API keys in your dashboard under Settings > API Keys.
Include your API key in the Authorization header:
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://api.customagents.io/v1/agentsBase URL
https://api.customagents.io/v1Rate Limiting
API requests are rate limited to:
- Free plan: 100 requests/minute
- Starter plan: 500 requests/minute
- Professional plan: 2,000 requests/minute
- Enterprise: Custom limits
Rate limit headers are included in every response:
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 499
X-RateLimit-Reset: 1234567890Agents
List Agents
GET /agentsReturns a list of all your agents.
Response:
{
"agents": [
{
"id": "agent_123",
"name": "Support Bot",
"email": "support@customagents.io",
"status": "active",
"autonomy_mode": "semi-auto",
"created_at": "2024-01-15T10:30:00Z"
}
]
}Get Agent
GET /agents/:idReturns details for a specific agent.
Create Agent
POST /agents
Content-Type: application/json
{
"name": "Support Bot",
"system_prompt": "You are a helpful customer support agent...",
"autonomy_mode": "semi-auto",
"knowledge_base_id": "kb_123"
}Response:
{
"id": "agent_123",
"name": "Support Bot",
"email": "support@customagents.io",
"status": "active"
}Update Agent
PATCH /agents/:id
Content-Type: application/json
{
"system_prompt": "Updated instructions...",
"autonomy_mode": "full-auto"
}Delete Agent
DELETE /agents/:idMessages
Send Email
POST /messages
Content-Type: application/json
{
"agent_id": "agent_123",
"to": "customer@example.com",
"subject": "Your Support Request",
"body": "Thank you for contacting us..."
}Get Message
GET /messages/:idReturns details for a specific message.
List Messages
GET /agents/:id/messagesReturns all messages for a specific agent.
Query Parameters:
limit(default: 50, max: 100)offset(default: 0)status(draft, sent, escalated)
Webhooks
Create Webhook
POST /webhooks
Content-Type: application/json
{
"agent_id": "agent_123",
"url": "https://your-domain.com/webhook",
"events": ["message.received", "message.sent", "escalation.triggered"]
}List Webhooks
GET /webhooksDelete Webhook
DELETE /webhooks/:idWebhook Events
message.received
Triggered when an email is received by an agent.
{
"event": "message.received",
"timestamp": "2024-01-15T10:30:00Z",
"data": {
"message_id": "msg_123",
"agent_id": "agent_123",
"from": "customer@example.com",
"subject": "Help with my account",
"body": "I can't log in..."
}
}message.sent
Triggered when an agent sends a response.
{
"event": "message.sent",
"timestamp": "2024-01-15T10:31:00Z",
"data": {
"message_id": "msg_124",
"agent_id": "agent_123",
"to": "customer@example.com",
"subject": "Re: Help with my account",
"body": "Thank you for contacting us..."
}
}escalation.triggered
Triggered when an email is escalated.
{
"event": "escalation.triggered",
"timestamp": "2024-01-15T10:32:00Z",
"data": {
"message_id": "msg_123",
"agent_id": "agent_123",
"reason": "angry_customer",
"sentiment_score": -0.85
}
}Error Handling
Errors are returned with appropriate HTTP status codes and error messages:
{
"error": "Invalid API key",
"code": "INVALID_API_KEY",
"status": 401
}Common Status Codes:
200- Success201- Created400- Bad Request401- Unauthorized403- Forbidden404- Not Found429- Rate Limited500- Server Error
SDK Examples
Node.js
import { CustomAgentsClient } from '@customagents/node-sdk';
const client = new CustomAgentsClient({
apiKey: 'your-api-key'
});
// List agents
const agents = await client.agents.list();
// Create agent
const agent = await client.agents.create({
name: 'Support Bot',
system_prompt: 'You are a helpful support agent...'
});
// Send message
await client.messages.send({
agent_id: agent.id,
to: 'customer@example.com',
subject: 'Your Support Request',
body: 'Thank you for contacting us...'
});Python
from customagents import Client
client = Client(api_key='your-api-key')
# List agents
agents = client.agents.list()
# Create agent
agent = client.agents.create(
name='Support Bot',
system_prompt='You are a helpful support agent...'
)
# Send message
client.messages.send(
agent_id=agent.id,
to='customer@example.com',
subject='Your Support Request',
body='Thank you for contacting us...'
)