Assistants API

Assistants are reusable voice agent configurations. Each assistant stores a system prompt, voice ID, LLM model, and optional provider config (webhook URLs, secrets, etc.). Create multiple assistants for different use cases and assign them to calls.

CRUD Endpoints

All endpoints require Authorization: Bearer <api_key> or a valid JWT session token.

Create an assistant

POST /api/v1/assistants

{
  "name": "Customer Support",
  "system_prompt": "You are a helpful customer support agent...",
  "voice_id": "a0e99841-438c-4a64-b679-ae501e7d6091",
  "llm_model": "llama-3.3-70b-versatile",
  "provider_config": {
    "webhook_url": "https://example.com/webhook",
    "webhook_secret": "whsec_abc123"
  },
  "is_default": false
}

List assistants

GET /api/v1/assistants?limit=50&offset=0

Returns an array of assistant objects sorted by creation date (newest first).

Get a single assistant

GET /api/v1/assistants/{assistant_id}

Update an assistant

PATCH /api/v1/assistants/{assistant_id}

Send only the fields you want to change:

{
  "system_prompt": "Updated prompt...",
  "voice_id": "new-voice-id"
}

Delete an assistant

DELETE /api/v1/assistants/{assistant_id}

Returns 204 No Content on success.

Using with the SDK

import echoai

client = echoai.Client(api_key="ek_...")

# Create
assistant = client.assistants.create(
    name="Sales Bot",
    system_prompt="You are a sales assistant...",
    voice_id="a0e99841-438c-4a64-b679-ae501e7d6091",
)

# List
assistants = client.assistants.list()

# Update
client.assistants.update(assistant["id"], name="Updated Name")

# Delete
client.assistants.delete(assistant["id"])

Assigning to calls

Pass assistant_id when creating a call to use that assistant's config:

client.calls.create(
    phone_number="+14155551234",
    assistant_id="your-assistant-id",
)

The voice worker automatically loads the assistant's system prompt, voice, and LLM model for that call session.

provider_config

The provider_config field is a flexible JSON object for storing provider-specific settings:

Any key-value pairs can be stored here and will be passed to the worker at session start.