> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thinnest.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Agent
> Create a new AI agent with model, voice, tools, and knowledge configuration.
```bash cURL theme={null}
curl -X POST https://api.thinnest.ai/v2/agents \
-H "Authorization: Bearer $THINNESTAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Sales Agent",
"model": "gpt-4o",
"instructions": "You are a helpful sales assistant.",
"description": "Handles product inquiries and purchase decisions",
"voiceEnabled": true,
"tools": [
"duckduckgo",
"email"
],
"transcriber": {
"provider": "deepgram",
"model": "nova-2-conversationalai",
"language": "en"
},
"voice": {
"provider": "deepgram",
"voiceId": "aura-2-thalia-en",
"speed": 1.0
},
"firstMessage": "Hello! How can I help you today?",
"temperature": 0.7,
"maxTokens": 4096
}'
```
```python Python theme={null}
import requests
url = "https://api.thinnest.ai/v2/agents"
headers = {
"Authorization": "Bearer " + "YOUR_THINNESTAI_API_KEY",
"Content-Type": "application/json",
}
payload = {
"name": "Sales Agent",
"model": "gpt-4o",
"instructions": "You are a helpful sales assistant.",
"description": "Handles product inquiries and purchase decisions",
"voiceEnabled": true,
"tools": [
"duckduckgo",
"email"
],
"transcriber": {
"provider": "deepgram",
"model": "nova-2-conversationalai",
"language": "en"
},
"voice": {
"provider": "deepgram",
"voiceId": "aura-2-thalia-en",
"speed": 1.0
},
"firstMessage": "Hello! How can I help you today?",
"temperature": 0.7,
"maxTokens": 4096
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```
```javascript JavaScript theme={null}
const response = await fetch("https://api.thinnest.ai/v2/agents", {
method: "POST",
headers: {
"Authorization": "Bearer " + "YOUR_THINNESTAI_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
"name": "Sales Agent",
"model": "gpt-4o",
"instructions": "You are a helpful sales assistant.",
"description": "Handles product inquiries and purchase decisions",
"voiceEnabled": true,
"tools": [
"duckduckgo",
"email"
],
"transcriber": {
"provider": "deepgram",
"model": "nova-2-conversationalai",
"language": "en"
},
"voice": {
"provider": "deepgram",
"voiceId": "aura-2-thalia-en",
"speed": 1.0
},
"firstMessage": "Hello! How can I help you today?",
"temperature": 0.7,
"maxTokens": 4096
}),
});
const data = await response.json();
console.log(data);
```
```go Go theme={null}
package main
import (
"bytes"
"fmt"
"io"
"net/http"
)
func main() {
payload := []byte(`{
"name": "Sales Agent",
"model": "gpt-4o",
"instructions": "You are a helpful sales assistant.",
"description": "Handles product inquiries and purchase decisions",
"voiceEnabled": true,
"tools": [
"duckduckgo",
"email"
],
"transcriber": {
"provider": "deepgram",
"model": "nova-2-conversationalai",
"language": "en"
},
"voice": {
"provider": "deepgram",
"voiceId": "aura-2-thalia-en",
"speed": 1.0
},
"firstMessage": "Hello! How can I help you today?",
"temperature": 0.7,
"maxTokens": 4096
}`)
req, _ := http.NewRequest("POST", "https://api.thinnest.ai/v2/agents", bytes.NewBuffer(payload))
req.Header.Set("Authorization", "Bearer YOUR_THINNESTAI_API_KEY")
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { panic(err) }
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
```
***
## Request Body
### Core
Agent display name
LLM model identifier. Use provider/model format or just model name (see [LLM Models](#llm-models))
System prompt that defines the agent's behavior, personality, and constraints
Internal description (not shown to end users)
Agent type: simple, graph, workflow
Enable voice/phone call capabilities
Greeting message the agent speaks when a voice call starts
LLM temperature (0.0–2.0). Lower = more deterministic, higher = more creative
Maximum tokens in the LLM response
Allow the agent to end voice calls
Maximum voice call duration in seconds. 0 = unlimited
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"`.
| Model ID | Min. Tier | Notes |
| --------------- | --------- | ---------------------------------------- |
| `gpt-4o-mini` | Trial | Fast, cost-effective for simple tasks |
| `gpt-4o` | PAYG | Most capable, recommended for production |
| `gpt-4-turbo` | PAYG | High capability, large context |
| `gpt-3.5-turbo` | PAYG | Legacy, fastest |
| `o3` | PAYG | Reasoning model |
| `o3-mini` | PAYG | Lightweight reasoning |
| `o1` | PAYG | Advanced reasoning |
| `o1-mini` | PAYG | Lightweight reasoning |
```json theme={null}
{ "model": "gpt-4o" }
// or explicitly:
{ "model": "openai/gpt-4o" }
```
| Model ID | Min. Tier | Notes |
| ---------------------------- | --------- | ---------------------- |
| `claude-3-5-haiku-20241022` | PAYG | Fast, affordable |
| `claude-3-5-sonnet-20241022` | PAYG | Best for complex tasks |
| `claude-3-opus-20240229` | PAYG | Highest capability |
```json theme={null}
{ "model": "claude-3-5-sonnet-20241022" }
// or explicitly:
{ "model": "anthropic/claude-3-5-sonnet-20241022" }
```
| Model ID | Min. Tier | Notes |
| ---------------------- | --------- | ------------------ |
| `gemini-2.0-flash-exp` | PAYG | Fast, experimental |
| `gemini-1.5-flash` | PAYG | Lightweight |
| `gemini-1.5-pro` | PAYG | High capability |
```json theme={null}
{ "model": "gemini-2.0-flash-exp" }
// or explicitly:
{ "model": "google/gemini-2.0-flash-exp" }
```
Groq delivers the fastest LLM inference — **200-400ms TTFT** for voice agents. Recommended for low-latency voice calls.
| Model ID | Min. Tier | Notes |
| ------------------------------------------- | --------- | --------------------------------------------- |
| `llama-3.3-70b-versatile` | Trial | Best for voice agents, tool calling supported |
| `llama-3.1-8b-instant` | Trial | Fastest, lightweight |
| `llama-3.1-70b-versatile` | PAYG | 70B with tool calling |
| `qwen/qwen3-32b` | PAYG | Qwen 3, strong multilingual |
| `meta-llama/llama-4-scout-17b-16e-instruct` | PAYG | Llama 4 Scout |
| `deepseek-r1-distill-llama-70b` | PAYG | DeepSeek reasoning |
| `gemma2-9b-it` | PAYG | Google Gemma 2 |
| `mixtral-8x7b-32768` | PAYG | 32K context MoE |
```json theme={null}
{ "model": "groq/llama-3.3-70b-versatile" }
```
All Sarvam models are available on **Trial** tier (no top-up needed).
| Model ID | Min. Tier | Notes |
| ----------------- | --------- | --------------------- |
| `sarvam-m` | Trial | General purpose |
| `sarvam-30b` | Trial | 30B parameters |
| `sarvam-30b-16k` | Trial | 30B with 16K context |
| `sarvam-105b` | Trial | 105B parameters |
| `sarvam-105b-32k` | Trial | 105B with 32K context |
```json theme={null}
{ "model": "sarvam-m" }
// or explicitly:
{ "model": "sarvam/sarvam-m" }
```
***
### Transcriber (STT)
Speech-to-text configuration. Only used when `voiceEnabled` is `true`.
```json theme={null}
{
"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.) |
Default provider. Best accuracy and lowest latency for voice agents.
| Model | Description |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `nova-2-conversationalai` | Best for voice agents and phone calls **(default)** |
| `nova-2-phonecall` | Optimized for phone audio |
| `nova-2-medical` | Medical terminology |
| `nova-2` | Base Nova 2 model |
| `nova-3` | Latest generation, highest accuracy |
| `nova-3-multilingual` | Multi-language support |
| `nova-3-medical` | Medical + Nova 3 |
| `flux-general-en` | **Recommended for voice agents** — Deepgram v2 streaming API, \~200ms latency, native turn detection. Picking this auto-sets `turn_detection_mode: "stt_endpointing"`. |
| `flux-general-multi` | Same as flux-general-en, multilingual variant |
```json theme={null}
{ "transcriber": { "provider": "deepgram", "model": "nova-2-conversationalai" } }
```
| Model | Description |
| ------------------------ | ---------------------------- |
| `whisper-1` | Whisper model |
| `gpt-4o-transcribe` | GPT-4o powered transcription |
| `gpt-4o-mini-transcribe` | GPT-4o Mini transcription |
```json theme={null}
{ "transcriber": { "provider": "openai", "model": "gpt-4o-mini-transcribe" } }
```
| Model | Description |
| -------------------- | ----------------------- |
| `scribe-v2-realtime` | Real-time transcription |
```json theme={null}
{ "transcriber": { "provider": "elevenlabs", "model": "scribe-v2-realtime" } }
```
| Model | Description |
| ------------- | ------------------ |
| `ink-whisper` | Fast transcription |
```json theme={null}
{ "transcriber": { "provider": "cartesia", "model": "ink-whisper" } }
```
Supports Hindi, Tamil, Telugu, Kannada, Malayalam, Bengali, Marathi, Gujarati, and more.
| Model | Description |
| -------------- | --------------------------------------- |
| `saarika:v2.5` | Latest Sarvam STT, 10+ Indian languages |
| `saarika:v2` | Sarvam STT v2 |
```json theme={null}
{ "transcriber": { "provider": "sarvam", "model": "saarika:v2.5" } }
```
| Model | Description | Pricing |
| ---------------------------------- | ----------------------------------------------------------- | --------- |
| `u3-rt-pro` | Universal-3 Pro Streaming — most accurate for voice agents | \$0.45/hr |
| `universal-streaming` | Universal Streaming — fastest English transcription | \$0.15/hr |
| `universal-streaming-multilingual` | Universal Streaming Multilingual | \$0.15/hr |
| `whisper-streaming` | Whisper Streaming — open-source Whisper on AssemblyAI infra | \$0.30/hr |
| `universal-3-pro` | Universal-3 Pro (file/batch only) | \$0.21/hr |
| `universal-2` | Universal-2 (file/batch only) | \$0.15/hr |
```json theme={null}
{ "transcriber": { "provider": "assemblyai", "model": "u3-rt-pro" } }
```
> **Free on Trial tier** — AssemblyAI STT is included free during trial (no STT charges).
***
### Voice (TTS)
Text-to-speech configuration. Only used when `voiceEnabled` is `true`.
```json theme={null}
{
"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 |
Default provider. Low-latency, high-quality voices.
**Models:** `aura-2` (default), `aura`
**Featured Voices (Aura-2):**
| Voice ID | Gender | Accent |
| --------------------- | ------ | ---------- |
| `aura-2-thalia-en` | Female | US English |
| `aura-2-andromeda-en` | Female | US English |
| `aura-2-helena-en` | Female | US English |
| `aura-2-athena-en` | Female | US English |
| `aura-2-aurora-en` | Female | US English |
| `aura-2-apollo-en` | Male | US English |
| `aura-2-arcas-en` | Male | US English |
| `aura-2-atlas-en` | Male | US English |
| `aura-2-aries-en` | Male | US English |
**Multilingual:** Append language code — `aura-2-thalia-es` (Spanish), `aura-2-thalia-de` (German), `aura-2-thalia-fr` (French), `aura-2-thalia-nl` (Dutch), `aura-2-thalia-it` (Italian), `aura-2-thalia-ja` (Japanese).
```json theme={null}
{ "voice": { "provider": "deepgram", "model": "aura-2", "voiceId": "aura-2-thalia-en" } }
```
High-quality, multi-language voices with low latency.
**Models:** `sonic-3`, `sonic-2`, `sonic-turbo`, `sonic`
50+ voices available — fetched dynamically. Use the voice ID from Cartesia's library.
```json theme={null}
{ "voice": { "provider": "cartesia", "model": "sonic-3", "voiceId": "your-cartesia-voice-id" } }
```
Premium voice cloning and 100+ voices.
**Models:** `eleven_flash_v2_5`, `eleven_flash_v2`, `eleven_turbo_v2_5`, `eleven_turbo_v2`, `eleven_multilingual_v2`
Use the voice ID from your ElevenLabs account (premade or cloned voices).
```json theme={null}
{ "voice": { "provider": "elevenlabs", "model": "eleven_flash_v2_5", "voiceId": "your-voice-id" } }
```
**Models:** `tts-1`, `tts-1-hd`
| Voice ID | Gender |
| --------- | ------- |
| `alloy` | Neutral |
| `echo` | Male |
| `fable` | Male |
| `onyx` | Male |
| `nova` | Female |
| `shimmer` | Female |
```json theme={null}
{ "voice": { "provider": "openai", "model": "tts-1", "voiceId": "nova" } }
```
**Model:** `bulbul:v2`
| Voice ID | Gender |
| ---------- | ------ |
| `anushka` | Female |
| `manisha` | Female |
| `vidya` | Female |
| `arya` | Male |
| `abhilash` | Male |
| `karun` | Male |
| `hitesh` | Male |
```json theme={null}
{ "voice": { "provider": "sarvam", "model": "bulbul:v2", "voiceId": "anushka" } }
```
**Models:** `arcana-v3`, `mist-v2`
```json theme={null}
{ "voice": { "provider": "rime", "model": "arcana-v3", "voiceId": "your-rime-voice-id" } }
```
**Models:** `inworld-tts-1.5-max`, `inworld-tts-1.5-mini`, `inworld-tts-1-max`, `inworld-tts-1`
```json theme={null}
{ "voice": { "provider": "inworld", "model": "inworld-tts-1.5-max", "voiceId": "your-voice-id" } }
```
***
### Tools
Array of tool identifiers to attach to the agent.
```json theme={null}
{
"tools": ["duckduckgo", "email", "calculator"]
}
```
| Field | Type | Required | Default | Description |
| ------- | --------- | -------- | ------- | ----------------------------- |
| `tools` | string\[] | No | `[]` | List of tool type identifiers |
| Tool ID | Description |
| ------------ | ------------------------- |
| `duckduckgo` | DuckDuckGo web search |
| `tavily` | Tavily AI search |
| `exa` | Exa neural search |
| `serpapi` | SerpAPI Google results |
| `serper` | Serper.dev search |
| `wikipedia` | Wikipedia lookup |
| `arxiv` | arXiv paper search |
| `hackernews` | Hacker News search |
| `pubmed` | PubMed medical literature |
| Tool ID | Description |
| ------------- | --------------------- |
| `website` | Basic URL scraping |
| `firecrawl` | Firecrawl web scraper |
| `crawl4ai` | Crawl4AI scraper |
| `jinareader` | Jina Reader API |
| `spider` | Spider web crawler |
| `scrapling` | Scrapling scraper |
| `newspaper` | Article extraction |
| `trafilatura` | Content extraction |
| Tool ID | Description |
| ---------- | ------------------ |
| `email` | Send emails |
| `gmail` | Gmail integration |
| `slack` | Slack messaging |
| `discord` | Discord messaging |
| `telegram` | Telegram bot |
| `twilio` | Twilio SMS/voice |
| `whatsapp` | WhatsApp messaging |
| `sms` | SMS sending |
| `x` | X (Twitter) |
| `zoom` | Zoom meetings |
| `reddit` | Reddit |
| `sendgrid` | SendGrid email |
| `resend` | Resend email |
| Tool ID | Description |
| ---------- | ------------------ |
| `postgres` | PostgreSQL queries |
| `mysql` | MySQL queries |
| `mongodb` | MongoDB operations |
| `duckdb` | DuckDB analytics |
| `bigquery` | Google BigQuery |
| `sql` | Generic SQL |
| `neo4j` | Neo4j graph DB |
| `supabase` | Supabase |
| `firebase` | Firebase |
| `airtable` | Airtable |
| `redshift` | AWS Redshift |
| Tool ID | Description |
| ------------ | ----------------------- |
| `github` | GitHub repos/issues/PRs |
| `gitlab` | GitLab integration |
| `jira` | Jira issues |
| `notion` | Notion pages |
| `linear` | Linear issues |
| `trello` | Trello boards |
| `confluence` | Confluence docs |
| `asana` | Asana tasks |
| `monday` | Monday.com |
| `todoist` | Todoist tasks |
| `clickup` | ClickUp tasks |
| `calcom` | Cal.com scheduling |
| Tool ID | Description |
| ---------------- | ------------------------ |
| `googlecalendar` | Google Calendar events |
| `googlesheets` | Google Sheets read/write |
| `googlemaps` | Google Maps lookup |
| `googledrive` | Google Drive files |
| Tool ID | Description |
| ---------------- | --------------------- |
| `hubspot` | HubSpot CRM |
| `salesforce` | Salesforce CRM |
| `activecampaign` | ActiveCampaign |
| `apollo` | Apollo.io prospecting |
| `linkedin` | LinkedIn |
| `intercom` | Intercom support |
| `mailchimp` | Mailchimp campaigns |
| `shopify` | Shopify e-commerce |
| `zendesk` | Zendesk support |
| Tool ID | Description |
| ------------ | ----------------------- |
| `dalle` | DALL·E image generation |
| `elevenlabs` | ElevenLabs TTS |
| `replicate` | Replicate AI models |
| `fal` | Fal.ai models |
| `lumalabs` | Luma Labs video |
| `giphy` | Giphy GIFs |
| `unsplash` | Unsplash photos |
| `youtube` | YouTube data |
| `spotify` | Spotify data |
| Tool ID | Description |
| ----------- | --------------------- |
| `awslambda` | AWS Lambda functions |
| `awsses` | AWS SES email |
| `s3` | AWS S3 storage |
| `dropbox` | Dropbox files |
| `onedrive` | OneDrive files |
| `sentry` | Sentry error tracking |
| `datadog` | Datadog monitoring |
| `msteams` | Microsoft Teams |
| Tool ID | Description |
| ---------- | --------------------- |
| `yfinance` | Yahoo Finance data |
| `openbb` | OpenBB financial data |
| `stripe` | Stripe payments |
| Tool ID | Description |
| ------------- | ---------------------- |
| `calculator` | Math calculations |
| `python` | Execute Python code |
| `shell` | Execute shell commands |
| `file` | File operations |
| `custom_api` | Custom HTTP API calls |
| `openweather` | Weather data |
| `mem0` | Memory storage |
| `mcp` | Model Context Protocol |
| `get_user` | Get caller/user info |
***
### Knowledge Base
Attach knowledge sources by passing their IDs. Knowledge sources must be created first via the [Knowledge API](/api-reference/knowledge).
```json theme={null}
{
"sourceIds": [1, 2, 5]
}
```
| Field | Type | Required | Default | Description |
| ----------- | ---------- | -------- | ------- | ---------------------------------- |
| `sourceIds` | integer\[] | No | `[]` | IDs of knowledge sources to attach |
Sources are created via the Knowledge API and can be of these types:
| Type | Description |
| ------------- | -------------------------------- |
| `url` | Web page — crawled and indexed |
| `text` | Raw text content |
| `file` | Document upload (PDF, DOCX, TXT) |
| `csv` | CSV data |
| `json` | JSON data |
| `markdown` | Markdown documents |
| `youtube` | YouTube video transcript |
| `excel` | Excel spreadsheets |
| `github_repo` | GitHub repository |
| `azure_blob` | Azure Blob Storage |
| `sharepoint` | SharePoint documents |
| `ocr` | OCR-processed documents |
***
### Voice Configuration
These sections configure voice call behavior. Only used when `voiceEnabled` is `true`.
Controls how the agent handles user interruptions during voice calls.
```json theme={null}
{
"interruptionConfig": {
"enabled": true,
"threshold": 0.5,
"minSilenceDuration": 0.3,
"minSpeechDuration": 0.1
}
}
```
| Field | Type | Default | Description |
| -------------------- | ------- | ------- | ------------------------------------------------------- |
| `enabled` | boolean | `true` | Allow users to interrupt the agent mid-speech |
| `threshold` | float | `0.5` | Sensitivity threshold (0.0–1.0). Lower = more sensitive |
| `minSilenceDuration` | float | `0.3` | Seconds of silence before detecting end of speech |
| `minSpeechDuration` | float | `0.1` | Minimum speech duration to trigger interruption |
Configure call recording for voice agents.
```json theme={null}
{
"recordingConfig": {
"enabled": true,
"downloadEnabled": true
}
}
```
| Field | Type | Default | Description |
| ----------------- | ------- | ------- | --------------------------------- |
| `enabled` | boolean | `false` | Enable call recording |
| `downloadEnabled` | boolean | `true` | Allow recording downloads via API |
Dual-tone multi-frequency (keypad) detection for IVR systems.
```json theme={null}
{
"dtmfConfig": {
"enabled": true,
"ivrDetection": true,
"menuEnabled": true
}
}
```
| Field | Type | Default | Description |
| -------------- | ------- | ------- | ---------------------------- |
| `enabled` | boolean | `false` | Enable DTMF keypad detection |
| `ivrDetection` | boolean | `false` | Detect IVR system prompts |
| `menuEnabled` | boolean | `false` | Enable DTMF menu navigation |
Control agent behavior during silence and unresponsive callers.
```json theme={null}
{
"silenceConfig": {
"unresponsiveTimeoutSeconds": 30,
"unresponsiveFinalSeconds": 15,
"fillersEnabled": true,
"fillerPhrases": ["Let me think about that...", "One moment please..."]
}
}
```
| Field | Type | Default | Description |
| ---------------------------- | --------- | ------- | ------------------------------------ |
| `unresponsiveTimeoutSeconds` | integer | `30` | Seconds before first silence prompt |
| `unresponsiveFinalSeconds` | integer | `15` | Seconds before ending the call |
| `fillersEnabled` | boolean | `false` | Use filler phrases during processing |
| `fillerPhrases` | string\[] | `[]` | Custom filler phrases |
Enable multi-language support in voice calls.
```json theme={null}
{
"multilingualConfig": {
"enabled": true,
"primaryLanguage": "en"
}
}
```
| Field | Type | Default | Description |
| ----------------- | ------- | ------- | ----------------------------- |
| `enabled` | boolean | `false` | Enable multilingual detection |
| `primaryLanguage` | string | `en` | Primary language code |
Automatically generate a summary after each voice call ends.
```json theme={null}
{
"callSummaryConfig": {
"enabled": true,
"prompt": "Summarize the call including: key topics discussed, action items, and customer sentiment."
}
}
```
| Field | Type | Default | Description |
| --------- | ------- | ------- | --------------------------- |
| `enabled` | boolean | `false` | Enable post-call summaries |
| `prompt` | string | `""` | Custom summarization prompt |
Receive real-time event notifications for voice calls.
```json theme={null}
{
"webhookConfig": {
"url": "https://your-server.com/webhook",
"events": ["call_started", "call_ended", "message_received"],
"retryCount": 3
}
}
```
| Field | Type | Default | Description |
| ------------ | --------- | ------- | -------------------------------------------------------------------------- |
| `url` | string | `""` | Webhook endpoint URL |
| `events` | string\[] | `[]` | Events: `call_started`, `call_ended`, `message_received`, `error_occurred` |
| `retryCount` | integer | `3` | Number of retry attempts on failure |
***
### Graph Data
Workflow configuration for `graph` or `workflow` agent types. Used with the visual flow editor.
```json theme={null}
{
"agentType": "graph",
"graphData": {
"nodes": [
{
"id": "trigger-1",
"type": "trigger",
"data": { "label": "Start" }
},
{
"id": "agent-1",
"type": "agent",
"data": {
"label": "Support Agent",
"model": "gpt-4o",
"instructions": "Handle customer support queries."
}
}
],
"edges": [
{
"id": "e1",
"source": "trigger-1",
"target": "agent-1"
}
]
}
}
```
**Node Types:**
| Type | Description |
| -------------- | --------------------------------- |
| `trigger` | Entry point — starts the workflow |
| `agent` | LLM agent node |
| `team` | Multi-agent team node |
| `condition` | Conditional branching |
| `tool` | Tool execution |
| `llm` | Direct LLM call |
| `http-request` | External API call |
| `python` | Python code execution |
| `variable` | Set/get variables |
| `memory` | Memory operations |
| `delay` | Wait/pause |
| `webhook` | Webhook trigger |
| `approval` | Human approval gate |
| `loop` | Loop iteration |
***
## Full Example — Voice Agent with Tools
```json theme={null}
{
"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
```json theme={null}
{
"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](/api-reference/agents/get) for complete response schema).
```json 200 theme={null}
{
"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"
}
```
## Voice configuration
For voice agents, pass a `voice` object with the cascaded TTS picker,
Speech-to-Speech settings (Gemini Live or OpenAI Realtime), noise
cancellation, and audio ambience. See the dedicated
[Voice Config Reference](/api-reference/agents/voice-config) for every
field, default, and accepted values.
## Errors
| Code | Description |
| ----- | --------------------------------- |
| `401` | Missing or invalid API key |
| `403` | Agent limit reached for your plan |
| `422` | Invalid request body |