Agents Endpoints

Endpoints for creating, updating, and managing voice agents.

List Agents

GET /api/v1/agents

List all agents for the current tenant.

Query Parameters:

Parameter	Type	Description
`limit`	integer	Max results (default: 50)
`offset`	integer	Pagination offset
`is_active`	boolean	Filter by active status

Response:

{
  "items": [
    {
      "id": "uuid",
      "name": "meal-agent",
      "display_name": "Meal Tracking Agent",
      "is_active": true,
      "created_at": "2026-01-17T10:30:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Get Agent

GET /api/v1/agents/{name}

Get a single agent by name.

Path Parameters:

Parameter	Type	Description
`name`	string	Agent name (unique per tenant)

Response:

{
  "id": "uuid",
  "name": "meal-agent",
  "display_name": "Meal Tracking Agent",
  "config": {
    "prompt": {
      "system": "You are a friendly meal tracking assistant...",
      "greeting": "Hello {{user.name}}!"
    },
    "stt": { "provider": "deepgram", "model": "nova-3" },
    "tts": { "provider": "cartesia", "voice_id": "..." },
    "llm": { "provider": "gemini", "model": "gemini-2.5-flash" },
    "tools": ["save_meal", "transfer_to_glucose"],
    "handoffs": [
      { "target_agent": "glucose-agent" }
    ]
  },
  "is_active": true
}

Create Agent

POST /api/v1/agents

Create a new agent.

Request Body:

{
  "name": "meal-agent",
  "display_name": "Meal Tracking Agent",
  "config": {
    "prompt": {
      "system": "You are a friendly meal tracking assistant.",
      "greeting": "Hello! What did you have today?"
    },
    "stt": { "provider": "deepgram", "model": "nova-3" },
    "tts": { "provider": "cartesia", "voice_id": "voice-id" },
    "llm": { "provider": "gemini", "model": "gemini-2.5-flash" },
    "tools": ["save_meal"],
    "languages": ["en", "hi"],
    "default_language": "en"
  }
}

Required Fields:

Field	Type	Description
`name`	string	Unique agent identifier (lowercase, hyphens allowed)
`config.prompt.system`	string	System prompt for the agent
`config.stt`	object	Speech-to-text provider configuration
`config.tts`	object	Text-to-speech provider configuration
`config.llm`	object	Language model configuration

Optional Fields:

Field	Type	Description
`display_name`	string	Human-readable name
`config.prompt.greeting`	string	Initial greeting message
`config.tools`	array	Tool names available to this agent
`config.handoffs`	array	Agents this agent can hand off to
`config.languages`	array	Supported language codes
`config.default_language`	string	Default language code

Update Agent

PUT /api/v1/agents/{name}

Update an existing agent. Supports partial updates.

Path Parameters:

Parameter	Type	Description
`name`	string	Agent name

Request Body:

{
  "display_name": "Updated Meal Agent",
  "config": {
    "prompt": {
      "system": "Updated system prompt..."
    }
  }
}

Delete Agent

DELETE /api/v1/agents/{name}

Delete an agent. Returns 204 on success.

Path Parameters:

Parameter	Type	Description
`name`	string	Agent name

Deleting an agent that is used in active workflows may cause errors. Deactivate the agent first or remove it from workflows.

Activate Agent

POST /api/v1/agents/{name}/activate

Activate a deactivated agent.

Deactivate Agent

POST /api/v1/agents/{name}/deactivate

Deactivate an agent without deleting it. Deactivated agents cannot be used in new calls.

Agent Configuration Schema

Provider Configuration

{
  "stt": {
    "provider": "deepgram",
    "model": "nova-3",
    "language": "en"
  },
  "tts": {
    "provider": "cartesia",
    "voice_id": "voice-uuid",
    "speed": 1.0
  },
  "llm": {
    "provider": "openai",
    "model": "gpt-4.1",
    "temperature": 0.7,
    "max_tokens": 1000
  }
}

Supported Providers

Type	Provider	Models
STT	deepgram	nova-3
STT	sarvam	saarika-v2
TTS	cartesia	sonic-3
TTS	sarvam	bulbul-v2
LLM	openai	gpt-4.1
LLM	gemini	gemini-2.5-flash, gemini-2.5-pro

Handoff Configuration

{
  "handoffs": [
    {
      "target_agent": "glucose-agent",
      "condition": "{{flags.meal_logged}}",
      "context_pass": ["logged_meals"]
    }
  ]
}

Agents Endpoints

On this page