Skip to main content
POST
/
api
/
v1
/
agents
Create agent (full)
curl --request POST \
  --url https://api.kupe.in/api/v1/agents \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "agent": {
    "name": "Support Voice Agent",
    "first_response_message": "Hi, thanks for calling. How can I help?"
  },
  "agent_model_config": {
    "model_name": "gpt-4.1-mini",
    "system_prompt": "You are a concise billing assistant."
  },
  "transcriber_config": {
    "transcriber_model_name": "saarika:2.5",
    "language": "hi-IN"
  },
  "tts_config": {
    "tts_model_name": "bulbul:v2",
    "language": "hi-IN",
    "voice_name": "Anushka"
  },
  "agent_specific_config": {
    "session_timeout": 300,
    "auto_terminate_call": true,
    "llm_conversation_stop_enabled": true,
    "timezone": "Asia/Kolkata"
  }
}
'
{
  "agent": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "is_active": true
  },
  "configurations": {},
  "validation_status": "valid"
}

Authorizations

​
x-api-key
string
header
default:YOUR_KUPE_API_KEY
required

Kupe dashboard API key for your user.

Body

application/json

Body for POST /api/v1/agents (full create). Requires agent.name; all other top-level keys are optional. Set runtime behavior (timeouts, auto hangup, inbound transfer routes, audio tuning) under agent_specific_config — values are merged onto platform defaults and stored in agent_specific_configs.configuration (separate from share/branding info). Enable inbound noise reduction on agent.apply_noise_reduction. Welcome line: agent.first_response_message or agent.welcome_message (alias). Not used for POST /api/v1/agents/simple.

​
agent
object
required
​
agent_model_config
object

model_name: LLM catalog code or row UUID. Requests may also send the legacy property model_provider_id with the same meaning (OpenAPI lists one field to avoid duplicate inputs).

​
tts_config
object

tts_model_name selects the TTS row (catalog code or UUID). Optional language sets voice_parameters.language (e.g. en, hi-IN). Legacy body key tts_provider_id is accepted as an alias for tts_model_name only (not listed as a second field).

​
transcriber_config
object

transcriber_model_name selects the STT row (catalog code or UUID, e.g. saarika:2.5). language is a locale string (e.g. hi-IN); a single-element array ["hi-IN"] is coerced to that string. The pipeline STT model id is derived from the catalog row only — it is not sent in this object. Legacy provider_id is an alias for transcriber_model_name.

​
agent_specific_config
object

Per-agent behavior stored in agent_specific_configs.configuration. On create (POST /api/v1/agents) and update (PUT /api/v1/agents/{agent_id}), send under agent_specific_config; omitted keys keep platform or existing values (partial PUT merges). Returned on GET /api/v1/agents/{agent_id} under configurations.agent_specific_config. Dashboard may use camelCase aliases (e.g. autoTerminate → auto_terminate_call).

Response

Created — returns CreateAgentResponse (agent.id is agent_id)

Complete agent response (abridged).

​
agent
object
​
configurations
object
​
validation_status
string
Example:

"valid"