Agents

Agents API

Create and manage the AI voice agents that handle calls. See Building agents for the concepts.

Agents are exposed on both API surfaces (see Two API surfaces):

• Dashboard API (/api/agents) — full CRUD, the complete agent object, { success, data } envelope. Auth with a user JWT + X-Org-Id or an API key.
• Integration API (/api/v1/agents) — a read‑only slim list for dropdowns in automation tools, flat JSON, X-API-Key only.

Dashboard API

All endpoints are organization‑scoped — authenticate with an API key (org implicit, no X-Org-Id needed) or a user JWT plus X-Org-Id.

Two things to know when using a key here:

• Writes need a privileged key. POST, PUT, DELETE and version‑restore require a key with the owner, admin, or developer role. A viewer or member key can read agents but gets 403 — "This API key's role ('viewer') is read-only on this endpoint." Reads work with any valid key.
• The AI builder routes are dashboard‑only. /api/agents/copilot/* and /api/agents/{id}/simulate/* require a user JWT — they back interactive panels in the agent builder, not programmatic use. An API key gets 401 on those.

GET /api/agents supports search, isActive, limit (default 50), and offset query params. search and isActive are mutually exclusive — when a search term is present it takes the search path and the isActive filter is ignored.

List agents

curl "https://api.telenow.ai/api/agents?isActive=true&limit=50" \
  -H "X-API-Key: vai_live_…"

{
  "success": true,
  "data": { "agents": [ /* full agent objects */ ], "total": 12, "limit": 50, "offset": 0 }
}

Create an agent

POST /api/agents

An agent is assembled from four provider slots (LLM, STT, TTS, telephony). Use the Catalog API (GET /api/catalog) to discover valid provider, model, and voice identifiers.

curl -X POST https://api.telenow.ai/api/agents \
  -H "X-API-Key: vai_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot",
    "systemPrompt": "You are Acme'\''s friendly support agent…",
    "llmProvider": "openai",
    "llmModel": "gpt-4o-mini",
    "sttProvider": "deepgram",
    "ttsProvider": "elevenlabs",
    "ttsVoice": "rachel",
    "sessionConfig": {}
  }'

Request fields

Field names are camelCase.

Response: 201 Created with { "success": true, "data": { /* the agent */ } }.

Tools & custom models

• Tools (function calling, including call transfer) are defined in metadata.tools — see Tools & function calling.
• Custom / self‑hosted models are configured via llmProvider: "customllm" (OpenAI‑compatible) or "customapi" (your agentic backend) plus llmConfig — see Custom LLM & API.
• Context variables ({placeholder} substitution) are configured in metadata — see Context variables.

Update an agent

PUT /api/agents/{id}

Send only the fields you want to change (all are optional on update, including isActive to enable/disable the agent). Returns the updated agent. Every update creates a new version — see Agent versioning.

Get / delete / stats

GET    /api/agents/{id}          # the agent (public agents are viewable unauthenticated)
DELETE /api/agents/{id}          # soft-deletes the agent
GET    /api/agents/{id}/stats    # totals: sessions, messages, duration

Integration API (slim list)

GET /api/v1/agents

Built for dynamic dropdowns in automation platforms (Zapier, Make, n8n, viaSocket). Authenticate with X-API-Key only — the org comes from the key. The response is flat JSON (no success/data envelope) and a slim projection: it returns ids and labels only. The full system prompt and provider configuration are deliberately excluded so they're never shipped to a third‑party app.

curl "https://api.telenow.ai/api/v1/agents?is_active=true&limit=100" \
  -H "X-API-Key: vai_live_…"

{
  "agents": [
    {
      "id": "…",
      "name": "Support Bot",
      "description": "Handles tier‑1 support",
      "is_active": true,
      "created_at": "2026-01-01T12:00:00Z",
      "updated_at": "2026-01-02T09:30:00Z"
    }
  ],
  "total": 12
}

Query params: is_active (also accepts isActive / active), limit (default 100, max 200), offset (default 0).

Full /api/v1 surface

The Integration API exposes a curated slice of functionality. All endpoints take X-API-Key and return flat JSON.

See Automation platforms for connector setup, Webhooks for hooks, and the Chat API guide for the /chat endpoints.

Using an agent

Once created, attach the agent to a phone number, start a web call, place an outbound call, publish it, or talk to it over text via the Chat API.

Tips

• Validate provider/model/voice ids against the Catalog before creating an agent — bad ids fail at create time.
• Use /api/v1/me as a cheap health check that a key is valid and to read its role before attempting writes.
• The slim /api/v1/agents list is the right source for "pick an agent" dropdowns; use the Dashboard GET /api/agents/{id} when you actually need the full configuration.