Agents API

Create Agent

POST /v1/agents

Request Body

{
  "name": "My Agent",
  "description": "A helpful voice assistant",
  "systemPrompt": "You are a helpful assistant...",
  "firstMessage": "Hello! How can I help?",
  "voiceId": "default",
  "ttsProvider": "cartesia",
  "ttsModel": null,
  "llmProvider": "openai",
  "llmModel": "gpt-4.1",
  "collectionId": "coll_abc123",
  "language": "en",
  "temperature": 0.7,
  "maxTokens": 4096,
  "metadata": { "team": "support" }
}

Field	Type	Required	Description
name	string	yes	1-100 characters
id	string	no	Custom ID (1-60 chars). Auto-generated if omitted.
description	string	no	Up to 1000 characters
systemPrompt	string	no	Up to 10,000 characters
firstMessage	string	no	Greeting spoken at session start (up to 1000 chars)
voiceId	string	no	TTS voice identifier. Default: "default"
ttsProvider	string	no	default, cartesia, elevenlabs, deepgram, fish-audio, pocket-tts, chatterbox, resemble-ai, inworld, kokoro, f5-tts, cosyvoice, qwen-tts
ttsModel	string	no	Provider-specific model name
llmProvider	string	no	openai, anthropic, groq. Default: "openai"
llmModel	string	no	e.g. gpt-4.1, claude-sonnet-4, llama-4-maverick
collectionId	string	no	RAG collection to attach
styleProfile	object	no	Voice style configuration
language	string	no	Language code. Default: "en"
temperature	number	no	0-2. Default: 0.7
maxTokens	number	no	1-16384
metadata	object	no	Arbitrary key-value pairs

Response 201

{
  "id": "agent_abc123",
  "name": "My Agent",
  "description": "A helpful voice assistant",
  "systemPrompt": "You are a helpful assistant...",
  "firstMessage": "Hello! How can I help?",
  "voiceId": "default",
  "ttsProvider": "cartesia",
  "ttsModel": null,
  "llmProvider": "openai",
  "llmModel": "gpt-4.1",
  "collectionId": "coll_abc123",
  "styleProfile": null,
  "language": "en",
  "temperature": 0.7,
  "maxTokens": 4096,
  "status": "active",
  "metadata": { "team": "support" },
  "createdAt": "2026-03-21T00:00:00.000Z",
  "updatedAt": "2026-03-21T00:00:00.000Z"
}

List Agents

GET /v1/agents?limit=20&cursor=agent_xyz

Returns agents owned by the authenticated developer. Archived agents are excluded.

Response 200

{
  "data": [{ "id": "agent_abc123", "name": "My Agent", "..." : "..." }],
  "nextCursor": "agent_xyz",
  "hasMore": true
}

Get Agent

GET /v1/agents/:id

Response 200

Full agent object (same shape as create response).

Update Agent

PUT /v1/agents/:id

All fields from create are accepted, all optional. Only provided fields are updated.

Response 200

Updated agent object.

Delete Agent

DELETE /v1/agents/:id

Response 204

No content.

Provision

Create an agent with a knowledge collection and initial content in one atomic operation.

POST /v1/agents/provision

Request Body

{
  "name": "Knowledge Agent",
  "systemPrompt": "Answer questions from the knowledge base.",
  "collection": {
    "name": "FAQ",
    "description": "Frequently asked questions"
  },
  "initialContent": [
    {
      "content": "Our hours are 9am-5pm EST Monday through Friday.",
      "contentType": "text"
    }
  ],
  "ttsProvider": "cartesia",
  "llmProvider": "openai"
}

Response 201

{
  "agent": { "id": "agent_abc123", "..." : "..." },
  "collection": { "id": "coll_xyz789", "..." : "..." },
  "ingestResults": [
    { "documentId": "doc_1", "chunksCreated": 3, "tokensUsed": 450 }
  ]
}

Chat

Send a message and get a response.

POST /v1/agents/:id/chat

Request Body

{
  "message": "What are your hours?",
  "conversationId": "conv_abc123",
  "instanceId": "inst_xyz",
  "callerPhone": "+19005551234",
  "maxSteps": 5
}

Field	Type	Required	Description
message	string	yes	User message (1-10,000 chars)
conversationId	string	no	Continue an existing conversation
instanceId	string	no	Agent instance for personalized context
callerPhone	string	no	Auto-match instance by phone number
maxSteps	number	no	Max tool execution steps per turn (1-8, default 5)

Response 200

{
  "reply": "Our hours are 9am to 5pm, Monday through Friday.",
  "conversationId": "conv_abc123",
  "turnIndex": 1,
  "toolCalls": [],
  "usage": { "inputTokens": 150, "outputTokens": 45 }
}

Speak

Synthesize speech using the agent's configured voice.

POST /v1/agents/:id/speak

Request Body

{
  "text": "Hello, welcome to our service!",
  "format": "mp3",
  "speed": 1.0
}

Response 200

Binary audio data with appropriate Content-Type header (audio/mpeg, audio/wav, or audio/ogg).

Sync

Sync agent configuration to an external platform (e.g., ElevenLabs).

POST /v1/agents/:id/sync

Response 200

{
  "synced": true,
  "externalAgentId": "ext_abc123",
  "provider": "elevenlabs"
}