Skip to main content
POST
/
api
/
v1
/
agents
Create an agent
curl --request POST \
  --url https://api.kataven.ai/v1/api/v1/agents \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "active_prompt_id": "<string>",
  "auth_mode": "authenticated",
  "background_audio_enabled": false,
  "background_audio_volume": 0.8,
  "category": "customer_support",
  "created_at": "<string>",
  "created_by": "user_01HZ2N…",
  "description": "Greets web visitors and answers product FAQs.",
  "faqs": [
    {
      "category": "<string>",
      "content": "<string>",
      "id": "<string>",
      "name": "<string>",
      "summary": "<string>",
      "title": "<string>"
    }
  ],
  "greeting_message": "Hi, this is the ACME front desk — how can I help?",
  "greeting_mode": "interruptible",
  "id": "agent_01HZ2N…",
  "llm_model": "gpt-4o",
  "name": "Front Desk",
  "noise_suppression_enabled": true,
  "playbooks": [
    {
      "category": "<string>",
      "description": "<string>",
      "display_name": "<string>",
      "id": "<string>",
      "name": "<string>",
      "tool_names": [
        "<string>"
      ]
    }
  ],
  "ringing_enabled": true,
  "status": "active",
  "system_prompt": "You are a friendly front-desk assistant for ACME Corp.",
  "template_id": "tmpl_general_intake",
  "updated_at": "<string>",
  "voice_id": "v1_friendly_female",
  "voice_provider": "cartesia"
}
'
{
  "active_prompt_id": "<string>",
  "auth_mode": "authenticated",
  "background_audio_enabled": false,
  "background_audio_volume": 0.8,
  "category": "customer_support",
  "created_at": "<string>",
  "created_by": "user_01HZ2N…",
  "description": "Greets web visitors and answers product FAQs.",
  "faqs": [
    {
      "category": "<string>",
      "content": "<string>",
      "id": "<string>",
      "name": "<string>",
      "summary": "<string>",
      "title": "<string>"
    }
  ],
  "greeting_message": "Hi, this is the ACME front desk — how can I help?",
  "greeting_mode": "interruptible",
  "id": "agent_01HZ2N…",
  "llm_model": "gpt-4o",
  "name": "Front Desk",
  "noise_suppression_enabled": true,
  "playbooks": [
    {
      "category": "<string>",
      "description": "<string>",
      "display_name": "<string>",
      "id": "<string>",
      "name": "<string>",
      "tool_names": [
        "<string>"
      ]
    }
  ],
  "ringing_enabled": true,
  "status": "active",
  "system_prompt": "You are a friendly front-desk assistant for ACME Corp.",
  "template_id": "tmpl_general_intake",
  "updated_at": "<string>",
  "voice_id": "v1_friendly_female",
  "voice_provider": "cartesia"
}

Documentation Index

Fetch the complete documentation index at: https://docs.kataven.ai/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

Headers

​
X-Account-ID
string

Tenant database (required only when using a Zitadel JWT).

Body

application/json

Agent fields. id, created_at, updated_at, and created_by are server-set and ignored if supplied.

Agent fields. id, created_at, updated_at, and created_by are server-set and ignored if supplied.

​
active_prompt_id
string
​
auth_mode
enum<string>

AuthMode gates whether the embeddable widget allows anonymous visitors. public accepts any visitor JWT; authenticated rejects guest tokens.

Available options:
public,
authenticated
Example:

"authenticated"

​
background_audio_enabled
boolean
Example:

false

​
background_audio_volume
number
Example:

0.8

​
category
enum<string>
Available options:
customer_support,
sales,
operations,
custom
Example:

"customer_support"

​
created_at
string
​
created_by
string
Example:

"user_01HZ2N…"

​
description
string
Example:

"Greets web visitors and answers product FAQs."

​
faqs
object[]
​
greeting_message
string
Example:

"Hi, this is the ACME front desk — how can I help?"

​
greeting_mode
enum<string>

GreetingMode controls whether the agent's opening line can be barged-in by the caller (interruptible) or must finish (locked).

Available options:
interruptible,
locked
Example:

"interruptible"

​
id
string
Example:

"agent_01HZ2N…"

​
llm_model
enum<string>
Available options:
gpt-4o,
gpt-4o-mini,
claude-3-5-sonnet
Example:

"gpt-4o"

​
name
string
Example:

"Front Desk"

​
noise_suppression_enabled
boolean
Example:

true

​
playbooks
object[]
​
ringing_enabled
boolean
Example:

true

​
status
enum<string>
Available options:
draft,
active,
archived
Example:

"active"

​
system_prompt
string
Example:

"You are a friendly front-desk assistant for ACME Corp."

​
template_id
string
Example:

"tmpl_general_intake"

​
updated_at
string
​
voice_id
string
Example:

"v1_friendly_female"

​
voice_provider
enum<string>
Available options:
cartesia,
elevenlabs,
deepgram
Example:

"cartesia"

Response

Agent persisted; the response carries the canonical row.

​
active_prompt_id
string
​
auth_mode
enum<string>

AuthMode gates whether the embeddable widget allows anonymous visitors. public accepts any visitor JWT; authenticated rejects guest tokens.

Available options:
public,
authenticated
Example:

"authenticated"

​
background_audio_enabled
boolean
Example:

false

​
background_audio_volume
number
Example:

0.8

​
category
enum<string>
Available options:
customer_support,
sales,
operations,
custom
Example:

"customer_support"

​
created_at
string
​
created_by
string
Example:

"user_01HZ2N…"

​
description
string
Example:

"Greets web visitors and answers product FAQs."

​
faqs
object[]
​
greeting_message
string
Example:

"Hi, this is the ACME front desk — how can I help?"

​
greeting_mode
enum<string>

GreetingMode controls whether the agent's opening line can be barged-in by the caller (interruptible) or must finish (locked).

Available options:
interruptible,
locked
Example:

"interruptible"

​
id
string
Example:

"agent_01HZ2N…"

​
llm_model
enum<string>
Available options:
gpt-4o,
gpt-4o-mini,
claude-3-5-sonnet
Example:

"gpt-4o"

​
name
string
Example:

"Front Desk"

​
noise_suppression_enabled
boolean
Example:

true

​
playbooks
object[]
​
ringing_enabled
boolean
Example:

true

​
status
enum<string>
Available options:
draft,
active,
archived
Example:

"active"

​
system_prompt
string
Example:

"You are a friendly front-desk assistant for ACME Corp."

​
template_id
string
Example:

"tmpl_general_intake"

​
updated_at
string
​
voice_id
string
Example:

"v1_friendly_female"

​
voice_provider
enum<string>
Available options:
cartesia,
elevenlabs,
deepgram
Example:

"cartesia"