API Reference

Base URL

https://api.customagents.io/v1

Authentication

All endpoints require Bearer token authentication:

Authorization: Bearer ca_acct_YOUR_KEY

Pass your API key in the Authorization header on every request. Account keys are prefixed ca_acct_; per-agent keys are prefixed ca_agt_. Generate and manage keys in Settings → API Keys — see API Keys & Scopes for the full scope model, rotation, IP allowlists, and expiry.

Every key is capped at member-level access and is gated by its scopes: a request to a route whose required scope your key lacks returns 403. A request from an IP outside the key's allowlist, or after the key's expiresAt, is rejected.

Per-agent keys reach only /v1/agents/<their-agentId>/** — see Per-Agent API & MCP.

Rate limits

Limits are enforced per key. Read routes get a higher budget than writes; money-spending routes (messages:send, trigger:agents) get a tighter one. Every response carries the IETF draft-7 RateLimit-* headers:

When you exceed the budget the API responds 429 Too Many Requests. Back off until RateLimit-Reset.

Agents

List Agents

GET /v1/agents

Returns a list of all agents on your account.

Response:

{
  "data": [
    {
      "id": "agent_abc123",
      "name": "Customer Support",
      "email": "support@yourdomain.com",
      "status": "active",
      "autonomyMode": "auto-respond",
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ]
}

Create Agent

POST /v1/agents

Body:

{
  "name": "Sales Agent",
  "instructions": "You are a sales qualification agent...",
  "tone": "professional",
  "autonomyMode": "draft"
}

Get Agent

GET /v1/agents/:id

Update Agent

PATCH /v1/agents/:id

Delete Agent

DELETE /v1/agents/:id

Messages

Send Message

POST /v1/messages

Body:

{
  "agentId": "agent_abc123",
  "to": "customer@example.com",
  "subject": "Re: Your inquiry",
  "body": "Thanks for reaching out!",
  "threadId": "thread_xyz789"
}

List Messages

GET /v1/agents/:id/messages

Get Message

GET /v1/messages/:id

Contacts

List Contacts

GET /v1/agents/:id/contacts

Get Contact

GET /v1/contacts/:id

Update Contact

PATCH /v1/contacts/:id

Webhooks

Create Webhook

POST /v1/webhooks

Body:

{
  "url": "https://yourapp.com/webhook",
  "events": ["message.received", "message.sent", "contact.created"]
}

See the Webhooks documentation for the full list of events.