Resources

Agents

Agents are voice AI workers that handle inbound and outbound calls. Each agent owns a system prompt, voice settings, and optional knowledge documents.

The agent object

Agents have the following shape. Fields marked optional may be null.

id - opaque identifier (agt_…)
name - human label
system_prompt - instructions for the LLM
greeting - first line the agent speaks
voice_provider, llm_provider, stt_provider - model selection (e.g. cartesia/sonic-3)
caller_id_number - optional caller-ID override
voicemail_detection - boolean, AMD on outbound
created_at, updated_at - ISO 8601

Endpoints

GET/api/v1/agentsTry it →

List every agent in the authenticated workspace, newest first.

Response

JSON

{
  "agents": [
    {
      "id": "agt_2k9f1a",
      "name": "Sales Receptionist",
      "voice_provider": "cartesia/sonic-3",
      "llm_provider": "openai/gpt-4o-mini",
      "created_at": "2026-05-01T12: 00: 00Z"
    }
  ]
}

GET/api/v1/agents/:idTry it →

Retrieve a single agent by id.

Response

JSON

{
  "agent": {
    "id": "agt_2k9f1a",
    "name": "Sales Receptionist",
    "system_prompt": "You are a friendly receptionist for…",
    "greeting": "Hi, thanks for calling Acme. How can I help?",
    "voice_provider": "cartesia/sonic-3",
    "llm_provider": "openai/gpt-4o-mini",
    "stt_provider": "deepgram/nova-3",
    "caller_id_number": null,
    "voicemail_detection": false,
    "voicemail_message": null,
    "created_at": "2026-05-01T12: 00: 00Z",
    "updated_at": "2026-05-10T09: 30: 00Z"
  }
}

POST/api/v1/agentsTry it →

Create a new agent. Pass a template_slug to bootstrap from a Floo template (your fields override the template defaults).

Request body

JSON

{
  "name": "Sales Receptionist",
  "system_prompt": "You are a friendly receptionist for Acme Co.",
  "greeting": "Hi, thanks for calling Acme. How can I help?",
  "voice_provider": "cartesia/sonic-3",
  "llm_provider": "openai/gpt-4o-mini",
  "stt_provider": "deepgram/nova-3"
}

Response

JSON

{
  "agent": {
    "id": "agt_2k9f1a",
    "name": "Sales Receptionist",
    "created_at": "2026-05-15T18: 00: 00Z"
  }
}

PATCH/api/v1/agents/:idTry it →

Update an existing agent. Only the fields you send are changed.

Request body

JSON

{
  "greeting": "Hello! Welcome to Acme, how can I help today?",
  "voicemail_detection": true,
  "voicemail_message": "Hi, sorry I missed you - please call back."
}

Response

JSON

{
  "agent": {
    "id": "agt_2k9f1a",
    "greeting": "Hello! Welcome to Acme, how can I help today?",
    "voicemail_detection": true,
    "voicemail_message": "Hi, sorry I missed you - please call back.",
    "updated_at": "2026-05-15T18: 02: 00Z"
  }
}

DELETE/api/v1/agents/:idTry it →

Permanently delete an agent. In-flight calls are not interrupted, but no new calls will route to this agent.

Response

JSON

{
  "ok": true
}

POST/api/v1/agents/:id/knowledgeTry it →

Attach a document to an agent's knowledge base. Accepts JSON (text or URL) or multipart/form-data (PDF, DOCX, TXT, MD). Server extracts text, chunks, and embeds - synchronous for small docs.

Request body

JSON

{
  "name": "Refund Policy",
  "source": "text",
  "text": "Customers may request a refund within 30 days of purchase…"
}

Response

JSON

{
  "ok": true,
  "document_id": "doc_8h2k1m",
  "chunk_count": 14
}