Skip to main content
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
}'

Request Body

Core

name
string
required
Agent display name
model
string
default:"gpt-4o"
LLM model identifier. Use provider/model format or just model name (see LLM Models)
instructions
string
default:"You are a helpful assistant."
System prompt that defines the agent’s behavior, personality, and constraints
description
string
default:"null"
Internal description (not shown to end users)
agentType
string
default:"simple"
Agent type: simple, graph, workflow
voiceEnabled
boolean
default:"false"
Enable voice/phone call capabilities
firstMessage
string
default:"null"
Greeting message the agent speaks when a voice call starts
temperature
number
default:"null"
LLM temperature (0.0–2.0). Lower = more deterministic, higher = more creative
maxTokens
integer
default:"null"
Maximum tokens in the LLM response
endCallEnabled
boolean
default:"true"
Allow the agent to end voice calls
maxDurationSeconds
integer
default:"0"
Maximum voice call duration in seconds. 0 = unlimited
noiseCancellation
string
default:"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 prefixDetected 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 IDMin. TierNotes
gpt-4o-miniTrialFast, cost-effective for simple tasks
gpt-4oPAYGMost capable, recommended for production
gpt-4-turboPAYGHigh capability, large context
gpt-3.5-turboPAYGLegacy, fastest
o3PAYGReasoning model
o3-miniPAYGLightweight reasoning
o1PAYGAdvanced reasoning
o1-miniPAYGLightweight reasoning
{ "model": "gpt-4o" }
// or explicitly:
{ "model": "openai/gpt-4o" }
Model IDMin. TierNotes
claude-3-5-haiku-20241022PAYGFast, affordable
claude-3-5-sonnet-20241022PAYGBest for complex tasks
claude-3-opus-20240229PAYGHighest capability
{ "model": "claude-3-5-sonnet-20241022" }
// or explicitly:
{ "model": "anthropic/claude-3-5-sonnet-20241022" }
Model IDMin. TierNotes
gemini-2.0-flash-expPAYGFast, experimental
gemini-1.5-flashPAYGLightweight
gemini-1.5-proPAYGHigh capability
{ "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 IDMin. TierNotes
llama-3.3-70b-versatileTrialBest for voice agents, tool calling supported
llama-3.1-8b-instantTrialFastest, lightweight
llama-3.1-70b-versatilePAYG70B with tool calling
qwen/qwen3-32bPAYGQwen 3, strong multilingual
meta-llama/llama-4-scout-17b-16e-instructPAYGLlama 4 Scout
deepseek-r1-distill-llama-70bPAYGDeepSeek reasoning
gemma2-9b-itPAYGGoogle Gemma 2
mixtral-8x7b-32768PAYG32K context MoE
{ "model": "groq/llama-3.3-70b-versatile" }
All Sarvam models are available on Trial tier (no top-up needed).
Model IDMin. TierNotes
sarvam-mTrialGeneral purpose
sarvam-30bTrial30B parameters
sarvam-30b-16kTrial30B with 16K context
sarvam-105bTrial105B parameters
sarvam-105b-32kTrial105B with 32K context
{ "model": "sarvam-m" }
// or explicitly:
{ "model": "sarvam/sarvam-m" }

Transcriber (STT)

Speech-to-text configuration. Only used when voiceEnabled is true.
{
  "transcriber": {
    "provider": "deepgram",
    "model": "nova-2-conversationalai",
    "language": "en"
  }
}
FieldTypeRequiredDefaultDescription
providerstringNodeepgramSTT provider
modelstringNoProvider defaultSTT model ID
languagestringNoenLanguage code (en, hi, es, fr, etc.)
Default provider. Best accuracy and lowest latency for voice agents.
ModelDescription
nova-2-conversationalaiBest for voice agents and phone calls (default)
nova-2-phonecallOptimized for phone audio
nova-2-medicalMedical terminology
nova-2Base Nova 2 model
nova-3Latest generation, highest accuracy
nova-3-multilingualMulti-language support
nova-3-medicalMedical + Nova 3
flux-general-enRecommended for voice agents — Deepgram v2 streaming API, ~200ms latency, native turn detection. Picking this auto-sets turn_detection_mode: "stt_endpointing".
flux-general-multiSame as flux-general-en, multilingual variant
{ "transcriber": { "provider": "deepgram", "model": "nova-2-conversationalai" } }
ModelDescription
whisper-1Whisper model
gpt-4o-transcribeGPT-4o powered transcription
gpt-4o-mini-transcribeGPT-4o Mini transcription
{ "transcriber": { "provider": "openai", "model": "gpt-4o-mini-transcribe" } }
ModelDescription
scribe-v2-realtimeReal-time transcription
{ "transcriber": { "provider": "elevenlabs", "model": "scribe-v2-realtime" } }
ModelDescription
ink-whisperFast transcription
{ "transcriber": { "provider": "cartesia", "model": "ink-whisper" } }
Supports Hindi, Tamil, Telugu, Kannada, Malayalam, Bengali, Marathi, Gujarati, and more.
ModelDescription
saarika:v2.5Latest Sarvam STT, 10+ Indian languages
saarika:v2Sarvam STT v2
{ "transcriber": { "provider": "sarvam", "model": "saarika:v2.5" } }
ModelDescriptionPricing
u3-rt-proUniversal-3 Pro Streaming — most accurate for voice agents$0.45/hr
universal-streamingUniversal Streaming — fastest English transcription$0.15/hr
universal-streaming-multilingualUniversal Streaming Multilingual$0.15/hr
whisper-streamingWhisper Streaming — open-source Whisper on AssemblyAI infra$0.30/hr
universal-3-proUniversal-3 Pro (file/batch only)$0.21/hr
universal-2Universal-2 (file/batch only)$0.15/hr
{ "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.
{
  "voice": {
    "provider": "deepgram",
    "voiceId": "aura-2-thalia-en",
    "speed": 1.0
  }
}
FieldTypeRequiredDefaultDescription
providerstringNodeepgramTTS provider
voiceIdstringNoasteriaVoice identifier
modelstringNoProvider defaultTTS model (if provider has multiple)
speedfloatNo1.0Speech speed multiplier
Default provider. Low-latency, high-quality voices.Models: aura-2 (default), auraFeatured Voices (Aura-2):
Voice IDGenderAccent
aura-2-thalia-enFemaleUS English
aura-2-andromeda-enFemaleUS English
aura-2-helena-enFemaleUS English
aura-2-athena-enFemaleUS English
aura-2-aurora-enFemaleUS English
aura-2-apollo-enMaleUS English
aura-2-arcas-enMaleUS English
aura-2-atlas-enMaleUS English
aura-2-aries-enMaleUS 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).
{ "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, sonic50+ voices available — fetched dynamically. Use the voice ID from Cartesia’s library.
{ "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_v2Use the voice ID from your ElevenLabs account (premade or cloned voices).
{ "voice": { "provider": "elevenlabs", "model": "eleven_flash_v2_5", "voiceId": "your-voice-id" } }
Models: tts-1, tts-1-hd
Voice IDGender
alloyNeutral
echoMale
fableMale
onyxMale
novaFemale
shimmerFemale
{ "voice": { "provider": "openai", "model": "tts-1", "voiceId": "nova" } }
Model: bulbul:v2
Voice IDGender
anushkaFemale
manishaFemale
vidyaFemale
aryaMale
abhilashMale
karunMale
hiteshMale
{ "voice": { "provider": "sarvam", "model": "bulbul:v2", "voiceId": "anushka" } }
Models: arcana-v3, mist-v2
{ "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
{ "voice": { "provider": "inworld", "model": "inworld-tts-1.5-max", "voiceId": "your-voice-id" } }

Tools

Array of tool identifiers to attach to the agent.
{
  "tools": ["duckduckgo", "email", "calculator"]
}
FieldTypeRequiredDefaultDescription
toolsstring[]No[]List of tool type identifiers
Tool IDDescription
websiteBasic URL scraping
firecrawlFirecrawl web scraper
crawl4aiCrawl4AI scraper
jinareaderJina Reader API
spiderSpider web crawler
scraplingScrapling scraper
newspaperArticle extraction
trafilaturaContent extraction
Tool IDDescription
emailSend emails
gmailGmail integration
slackSlack messaging
discordDiscord messaging
telegramTelegram bot
twilioTwilio SMS/voice
whatsappWhatsApp messaging
smsSMS sending
xX (Twitter)
zoomZoom meetings
redditReddit
sendgridSendGrid email
resendResend email
Tool IDDescription
postgresPostgreSQL queries
mysqlMySQL queries
mongodbMongoDB operations
duckdbDuckDB analytics
bigqueryGoogle BigQuery
sqlGeneric SQL
neo4jNeo4j graph DB
supabaseSupabase
firebaseFirebase
airtableAirtable
redshiftAWS Redshift
Tool IDDescription
githubGitHub repos/issues/PRs
gitlabGitLab integration
jiraJira issues
notionNotion pages
linearLinear issues
trelloTrello boards
confluenceConfluence docs
asanaAsana tasks
mondayMonday.com
todoistTodoist tasks
clickupClickUp tasks
calcomCal.com scheduling
Tool IDDescription
googlecalendarGoogle Calendar events
googlesheetsGoogle Sheets read/write
googlemapsGoogle Maps lookup
googledriveGoogle Drive files
Tool IDDescription
hubspotHubSpot CRM
salesforceSalesforce CRM
activecampaignActiveCampaign
apolloApollo.io prospecting
linkedinLinkedIn
intercomIntercom support
mailchimpMailchimp campaigns
shopifyShopify e-commerce
zendeskZendesk support
Tool IDDescription
dalleDALL·E image generation
elevenlabsElevenLabs TTS
replicateReplicate AI models
falFal.ai models
lumalabsLuma Labs video
giphyGiphy GIFs
unsplashUnsplash photos
youtubeYouTube data
spotifySpotify data
Tool IDDescription
awslambdaAWS Lambda functions
awssesAWS SES email
s3AWS S3 storage
dropboxDropbox files
onedriveOneDrive files
sentrySentry error tracking
datadogDatadog monitoring
msteamsMicrosoft Teams
Tool IDDescription
yfinanceYahoo Finance data
openbbOpenBB financial data
stripeStripe payments
Tool IDDescription
calculatorMath calculations
pythonExecute Python code
shellExecute shell commands
fileFile operations
custom_apiCustom HTTP API calls
openweatherWeather data
mem0Memory storage
mcpModel Context Protocol
get_userGet caller/user info

Knowledge Base

Attach knowledge sources by passing their IDs. Knowledge sources must be created first via the Knowledge API.
{
  "sourceIds": [1, 2, 5]
}
FieldTypeRequiredDefaultDescription
sourceIdsinteger[]No[]IDs of knowledge sources to attach
Sources are created via the Knowledge API and can be of these types:
TypeDescription
urlWeb page — crawled and indexed
textRaw text content
fileDocument upload (PDF, DOCX, TXT)
csvCSV data
jsonJSON data
markdownMarkdown documents
youtubeYouTube video transcript
excelExcel spreadsheets
github_repoGitHub repository
azure_blobAzure Blob Storage
sharepointSharePoint documents
ocrOCR-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.
{
  "interruptionConfig": {
    "enabled": true,
    "threshold": 0.5,
    "minSilenceDuration": 0.3,
    "minSpeechDuration": 0.1
  }
}
FieldTypeDefaultDescription
enabledbooleantrueAllow users to interrupt the agent mid-speech
thresholdfloat0.5Sensitivity threshold (0.0–1.0). Lower = more sensitive
minSilenceDurationfloat0.3Seconds of silence before detecting end of speech
minSpeechDurationfloat0.1Minimum speech duration to trigger interruption
Configure call recording for voice agents.
{
  "recordingConfig": {
    "enabled": true,
    "downloadEnabled": true
  }
}
FieldTypeDefaultDescription
enabledbooleanfalseEnable call recording
downloadEnabledbooleantrueAllow recording downloads via API
Dual-tone multi-frequency (keypad) detection for IVR systems.
{
  "dtmfConfig": {
    "enabled": true,
    "ivrDetection": true,
    "menuEnabled": true
  }
}
FieldTypeDefaultDescription
enabledbooleanfalseEnable DTMF keypad detection
ivrDetectionbooleanfalseDetect IVR system prompts
menuEnabledbooleanfalseEnable DTMF menu navigation
Control agent behavior during silence and unresponsive callers.
{
  "silenceConfig": {
    "unresponsiveTimeoutSeconds": 30,
    "unresponsiveFinalSeconds": 15,
    "fillersEnabled": true,
    "fillerPhrases": ["Let me think about that...", "One moment please..."]
  }
}
FieldTypeDefaultDescription
unresponsiveTimeoutSecondsinteger30Seconds before first silence prompt
unresponsiveFinalSecondsinteger15Seconds before ending the call
fillersEnabledbooleanfalseUse filler phrases during processing
fillerPhrasesstring[][]Custom filler phrases
Enable multi-language support in voice calls.
{
  "multilingualConfig": {
    "enabled": true,
    "primaryLanguage": "en"
  }
}
FieldTypeDefaultDescription
enabledbooleanfalseEnable multilingual detection
primaryLanguagestringenPrimary language code
Automatically generate a summary after each voice call ends.
{
  "callSummaryConfig": {
    "enabled": true,
    "prompt": "Summarize the call including: key topics discussed, action items, and customer sentiment."
  }
}
FieldTypeDefaultDescription
enabledbooleanfalseEnable post-call summaries
promptstring""Custom summarization prompt
Receive real-time event notifications for voice calls.
{
  "webhookConfig": {
    "url": "https://your-server.com/webhook",
    "events": ["call_started", "call_ended", "message_received"],
    "retryCount": 3
  }
}
FieldTypeDefaultDescription
urlstring""Webhook endpoint URL
eventsstring[][]Events: call_started, call_ended, message_received, error_occurred
retryCountinteger3Number of retry attempts on failure

Graph Data

Workflow configuration for graph or workflow agent types. Used with the visual flow editor.
{
  "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:
TypeDescription
triggerEntry point — starts the workflow
agentLLM agent node
teamMulti-agent team node
conditionConditional branching
toolTool execution
llmDirect LLM call
http-requestExternal API call
pythonPython code execution
variableSet/get variables
memoryMemory operations
delayWait/pause
webhookWebhook trigger
approvalHuman approval gate
loopLoop iteration

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"
}

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 for every field, default, and accepted values.

Errors

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