Create Agent

POST/v2/agents

Create a new agent with unified configuration.

No parameters for this endpoint.

Request Body

Core

Field	Type	Required	Default	Description
`name`	string	Yes	—	Agent display name
`model`	string	No	`gpt-4o`	LLM model identifier. Use `provider/model` format or just model name (see LLM Models)
`instructions`	string	No	`You are a helpful assistant.`	System prompt that defines the agent's behavior, personality, and constraints
`description`	string	No	`null`	Internal description (not shown to end users)
`agentType`	string	No	`simple`	Agent type: `simple`, `graph`, `workflow`
`voiceEnabled`	boolean	No	`false`	Enable voice/phone call capabilities
`firstMessage`	string	No	`null`	Greeting message the agent speaks when a voice call starts
`temperature`	float	No	`null`	LLM temperature (0.0–2.0). Lower = more deterministic, higher = more creative
`maxTokens`	integer	No	`null`	Maximum tokens in the LLM response
`endCallEnabled`	boolean	No	`true`	Allow the agent to end voice calls
`maxDurationSeconds`	integer	No	`0`	Maximum voice call duration in seconds. `0` = unlimited
`noiseCancellation`	string	No	`none`	Noise cancellation: `none`, `bvc`, `krisp`

LLM Models

The model field accepts a string in provider/model format, or just the model name for auto-detection.

Subscription Tiers: Trial (default) — limited to gpt-4o-mini and Sarvam models. PAYG (after first top-up) — all models, OCR, and multimodal unlocked. Enterprise — all features including branding removal, teams, observability, and priority support.

Provider auto-detection rules:

Model prefix	Detected provider
`gpt-`, `o1-`, `o3-*`	`openai`
`claude-*`	`anthropic`
`gemini*`	`google`
`sarvam*`	`sarvam`
`llama-`, `mixtral-`	`groq`

Or use explicit format: "openai/gpt-4o", "anthropic/claude-3-5-sonnet-20241022".

Transcriber (STT)

Speech-to-text configuration. Only used when voiceEnabled is true.

{
  "transcriber": {
    "provider": "deepgram",
    "model": "nova-2-conversationalai",
    "language": "en"
  }
}

Field	Type	Required	Default	Description
`provider`	string	No	`deepgram`	STT provider
`model`	string	No	Provider default	STT model ID
`language`	string	No	`en`	Language code (`en`, `hi`, `es`, `fr`, etc.)

Voice (TTS)

Text-to-speech configuration. Only used when voiceEnabled is true.

{
  "voice": {
    "provider": "deepgram",
    "voiceId": "aura-2-thalia-en",
    "speed": 1.0
  }
}

Field	Type	Required	Default	Description
`provider`	string	No	`deepgram`	TTS provider
`voiceId`	string	No	`asteria`	Voice identifier
`model`	string	No	Provider default	TTS model (if provider has multiple)
`speed`	float	No	`1.0`	Speech speed multiplier

Tools

Array of tool identifiers to attach to the agent.

{
  "tools": ["duckduckgo", "email", "calculator"]
}

Field	Type	Required	Default	Description
`tools`	string[]	No	`[]`	List of tool type identifiers

Knowledge Base

Attach knowledge sources by passing their IDs. Knowledge sources must be created first via the Knowledge API.

{
  "sourceIds": [1, 2, 5]
}

Field	Type	Required	Default	Description
`sourceIds`	integer[]	No	`[]`	IDs of knowledge sources to attach

Voice Configuration

These sections configure voice call behavior. Only used when voiceEnabled is true.

Graph Data

Workflow configuration for graph or workflow agent types. Used with the visual flow editor.

Full Example — Voice Agent with Tools

{
  "name": "Sales Support Agent",
  "model": "gpt-4o",
  "instructions": "You are a sales support agent for Acme Corp. Help customers with product questions, pricing, and order status.",
  "description": "Handles inbound sales calls",
  "voiceEnabled": true,
  "firstMessage": "Hi there! Thanks for calling Acme Corp. How can I help you today?",
  "temperature": 0.7,
  "maxTokens": 4096,

  "transcriber": {
    "provider": "deepgram",
    "model": "nova-2-conversationalai",
    "language": "en"
  },

  "voice": {
    "provider": "deepgram",
    "voiceId": "aura-2-thalia-en",
    "speed": 1.0
  },

  "tools": ["duckduckgo", "email", "calculator", "googlesheets"],
  "sourceIds": [1, 3],

  "interruptionConfig": { "enabled": true, "threshold": 0.5 },
  "silenceConfig": {
    "unresponsiveTimeoutSeconds": 20,
    "fillersEnabled": true,
    "fillerPhrases": ["Let me check that for you...", "One moment please..."]
  },
  "recordingConfig": { "enabled": true },
  "callSummaryConfig": {
    "enabled": true,
    "prompt": "Summarize: topics discussed, products mentioned, next steps, and customer sentiment."
  },
  "webhookConfig": {
    "url": "https://api.acme.com/call-events",
    "events": ["call_started", "call_ended"]
  },

  "maxDurationSeconds": 900,
  "noiseCancellation": "krisp",
  "endCallEnabled": true
}

Full Example — Simple Chat Agent

{
  "name": "FAQ Bot",
  "model": "gpt-4o-mini",
  "instructions": "You are a helpful FAQ assistant. Answer questions based on the provided knowledge base. If you don't know the answer, say so.",
  "tools": ["duckduckgo"],
  "sourceIds": [2]
}

Response `201`

Returns the full agent object with nested configuration (see Get Agent for complete response schema).

{
  "id": "ag_c47e7c97_b2f2",
  "name": "Sales Support Agent",
  "createdAt": "2026-03-07T10:00:00Z",
  "updatedAt": null,
  "model": {
    "provider": "openai",
    "model": "gpt-4o",
    "temperature": 0.7,
    "maxTokens": 4096,
    "instructions": "You are a sales support agent for Acme Corp..."
  },
  "transcriber": {
    "provider": "deepgram",
    "model": "nova-2-conversationalai",
    "language": "en"
  },
  "voice": {
    "provider": "deepgram",
    "model": "aura-2",
    "voiceId": "aura-2-thalia-en",
    "speed": 1.0
  },
  "tools": [
    { "name": "duckduckgo", "type": "duckduckgo", "enabled": true },
    { "name": "email", "type": "email", "enabled": true },
    { "name": "calculator", "type": "calculator", "enabled": true },
    { "name": "googlesheets", "type": "googlesheets", "enabled": true }
  ],
  "knowledgeBase": {
    "sources": [
      { "id": "1", "name": "Product Catalog", "type": "file", "status": "ready" },
      { "id": "3", "name": "Pricing FAQ", "type": "text", "status": "ready" }
    ]
  },
  "voiceEnabled": true,
  "agentType": "simple",
  "firstMessage": "Hi there! Thanks for calling Acme Corp. How can I help you today?",
  "endCallEnabled": true,
  "maxDurationSeconds": 900,
  "noiseCancellation": "krisp"
}

Errors

Code	Description
`401`	Missing or invalid API key
`403`	Agent limit reached for your plan
`422`	Invalid request body

OpenAI

Anthropic

Google

Groq (Ultra-Fast Inference)

Sarvam AI (Indian LLM)

Deepgram (default)

OpenAI

ElevenLabs

Cartesia

Sarvam (Indian Languages)

AssemblyAI

ThinnestAI Vega (Indian Languages)

Deepgram Aura (default)

Cartesia

ElevenLabs

OpenAI

Sarvam (Hindi / Indian)

Rime

Inworld

Aero (thinnestAI built-in)

Search

Web Scraping

Communication

Databases

Productivity

Google

CRM & Sales

AI & Media

Cloud & DevOps

Finance

Utility

Knowledge Source Types

Interruption Config

Recording Config

DTMF Config

Silence Config

Multilingual Config

Call Summary Config

Webhook Config

Graph Data Structure

On this page