Agents

Agents are voice personas — a name, an avatar, and an ElevenLabs voice ID. Behavior (system prompt, tools, business context) lives on the Business profile that the agent is linked to via Campaign.

List agents

GET /api/v1/agents
Authorization: Bearer <token>

Query params:

• page (default 1)
• limit (default 20, max 100)
• isActive (boolean) — filter by active status

Response:

{
  "success": true,
  "data": [
    {
      "id": "agt_xxx",
      "name": "Sarah",
      "description": "Friendly female assistant for daytime calls",
      "voiceId": "a0e99841-...",
      "language": "en-US",
      "primaryLanguage": "en",
      "additionalLanguages": [],
      "isActive": true,
      "_count": { "calls": 142, "phoneNumbers": 1 },
      "createdAt": "2026-03-12T08:30:00.000Z"
    }
  ],
  "pagination": { ... }
}

Get one agent

GET /api/v1/agents/:id

404 if the agent doesn’t exist or belongs to another tenant (we don’t distinguish).

Create an agent

POST /api/v1/agents
Content-Type: application/json
Authorization: Bearer <token>
 
{
  "name": "Sarah",
  "voiceId": "a0e99841-438c-4a64-b679-ae501e7d6091",
  "language": "en-US",
  "description": "Friendly assistant"
}

Required: name, voiceId. The voice ID must be one returned from GET /api/v1/voices — arbitrary IDs are rejected.

Update an agent

PATCH /api/v1/agents/:id
Content-Type: application/json
 
{ "name": "New Name" }

Only the fields you send are updated.

Delete an agent (soft)

DELETE /api/v1/agents/:id

Soft delete — sets deletedAt and the agent stops appearing in lists. Calls that referenced the agent retain the reference (no cascade).

409 Conflict if any active campaign still uses this agent. Detach or terminate those campaigns first.