Skip to main content
POST
/
agents
Create agent
curl --request POST \
  --url https://api.goyappr.com/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Sales Agent",
  "system_prompt": "You are a friendly sales representative...",
  "type": "prompt",
  "description": "<string>",
  "voice": "Rachel",
  "background_sound_volume": 0.3,
  "language": "he",
  "temperature": 0.5,
  "greeting_message": "שלום! איך אוכל לעזור?",
  "agent_speaks_first": true,
  "lead_memory_enabled": true,
  "vad_stop_secs": 0.5,
  "vad_start_secs": 0.2,
  "vad_confidence": 0.7,
  "silence_timeout_secs": 60,
  "max_continuous_speech_secs": 120,
  "max_call_duration_secs": 600,
  "webhook_url": "<string>",
  "webhook_events": [],
  "idempotency_key": "<string>"
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "type": "prompt",
  "flow_config": {
    "nodes": [
      {
        "id": "<string>",
        "name": "<string>",
        "position": {
          "x": 123,
          "y": 123
        },
        "agent_speaks_first": true,
        "greeting": "<string>",
        "is_literal": false,
        "next_step_id": "<string>",
        "auto_advance": true
      }
    ],
    "flow_config_version": "1",
    "metadata": {
      "custom_metadata_keys": [
        "<string>"
      ]
    }
  },
  "system_prompt": "<string>",
  "description": "<string>",
  "background_sound_volume": 0.3,
  "temperature": 1,
  "greeting_message": "<string>",
  "agent_speaks_first": true,
  "vad_stop_secs": 0.5,
  "vad_start_secs": 0.2,
  "vad_confidence": 0.7,
  "silence_timeout_secs": 60,
  "max_continuous_speech_secs": 120,
  "max_call_duration_secs": 600,
  "lead_memory_enabled": true,
  "is_active": true,
  "webhook_url": "<string>",
  "webhook_events": [],
  "extraction_parameters": [
    {
      "name": "customerName",
      "description": "The caller's full name as mentioned during the conversation"
    }
  ],
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

Documentation Index

Fetch the complete documentation index at: https://docs.goyappr.com/llms.txt

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

Authorizations

​
Authorization
string
header
required

Your Yappr API key (e.g. ypr_live_...). Generate one in the dashboard under Settings → API Keys.

Body

application/json
​
name
string
required
Example:

"Sales Agent"

​
system_prompt
string
required
Example:

"You are a friendly sales representative..."

​
type
enum<string>
default:prompt

prompt (default): single system_prompt drives the call. flow: requires flow_config. Immutable post-create.

Available options:
prompt,
flow
​
flow_config
object

Required when type='flow'. Must be omitted when type='prompt'. See concepts/flow-agents for the full graph spec.

​
description
string
​
voice
enum<string>
default:Rachel
Available options:
Michal,
Yonatan,
David,
Rachel,
Gil,
Noa,
Maya,
Adam,
Shira,
Avigail,
Amir,
Liat,
Omer,
Tamar,
Tom,
Benny,
Nir,
Natan,
Yael,
Dvora,
Yosef,
Shir,
Anat,
Ariel,
Roi,
Shlomo,
Dana,
Alon,
Ruth,
Yuval
​
background_sound
enum<string> | null

Ambient background sound mixed under the agent's voice during calls. Null means silent (default).

Available options:
call_center,
open_office,
cafe,
outdoor
​
background_sound_volume
number
default:0.3

Volume of the background sound, 0.0–0.6. Capped to protect turn-taking.

Required range: 0 <= x <= 0.6
​
language
enum<string>
default:he
Available options:
he,
en
​
temperature
number
default:0.5
Required range: 0 <= x <= 2
​
greeting_message
string
Example:

"שלום! איך אוכל לעזור?"

​
agent_speaks_first
boolean
default:true
​
lead_memory_enabled
boolean
default:true

Inject matched lead's long-term memory into system prompt at call time

​
vad_stop_secs
number
default:0.5
Required range: 0.05 <= x <= 5
​
vad_start_secs
number
default:0.2
Required range: 0.05 <= x <= 2
​
vad_confidence
number
default:0.7
Required range: 0 <= x <= 1
​
silence_timeout_secs
number
default:60
Required range: 10 <= x <= 900
​
max_continuous_speech_secs
number
default:120

0 = disabled

Required range: 0 <= x <= 300
​
max_call_duration_secs
number
default:600

0 = disabled

Required range: 0 <= x <= 3600
​
webhook_url
string<uri> | null
​
webhook_events
enum<string>[]
Available options:
call.started,
call.answered,
call.ended,
call.failed,
call.no_answer,
call.dnc_blocked,
transcript.ready
​
idempotency_key
string

If a key is supplied and a prior request used the same key, the existing agent is returned instead of creating a duplicate.

Response

Agent created

​
id
string<uuid>
​
name
string
​
type
enum<string>
default:prompt

prompt (default, legacy): a single system_prompt drives the call; the LLM decides when to call attached tools. flow: the call is driven by a flow_config graph of conversation, tool-call, and routing nodes. type is immutable post-create — to change types, create a new agent.

Available options:
prompt,
flow
​
flow_config
object

The flow graph. Required when type='flow', must be omitted/null when type='prompt'.

​
system_prompt
string
​
description
string | null
​
voice
enum<string>
Available options:
Michal,
Yonatan,
David,
Rachel,
Gil,
Noa,
Maya,
Adam,
Shira,
Avigail,
Amir,
Liat,
Omer,
Tamar,
Tom,
Benny,
Nir,
Natan,
Yael,
Dvora,
Yosef,
Shir,
Anat,
Ariel,
Roi,
Shlomo,
Dana,
Alon,
Ruth,
Yuval
​
background_sound
enum<string> | null

Ambient background sound mixed under the agent's voice during calls. Null means silent (default).

Available options:
call_center,
open_office,
cafe,
outdoor
​
background_sound_volume
number
default:0.3

Volume of the background sound, 0.0–0.6. Capped to protect turn-taking.

Required range: 0 <= x <= 0.6
​
language
enum<string>
Available options:
he,
en
​
temperature
number
Required range: 0 <= x <= 2
​
greeting_message
string | null
​
agent_speaks_first
boolean
​
vad_stop_secs
number
default:0.5

Seconds of silence before VAD confirms speech has stopped

Required range: 0.05 <= x <= 5
​
vad_start_secs
number
default:0.2

Seconds of speech before VAD confirms speech has started

Required range: 0.05 <= x <= 2
​
vad_confidence
number
default:0.7

Minimum confidence threshold for voice detection

Required range: 0 <= x <= 1
​
silence_timeout_secs
number
default:60

Seconds of caller silence before auto-hangup. Prevents idle calls wasting credits.

Required range: 10 <= x <= 900
​
max_continuous_speech_secs
number
default:120

Max seconds one party can speak non-stop before auto-hangup. Catches answering machines. 0 = disabled.

Required range: 0 <= x <= 300
​
max_call_duration_secs
number
default:600

Hard cap on total call duration regardless of activity. 0 = disabled.

Required range: 0 <= x <= 3600
​
lead_memory_enabled
boolean
default:true

When true, the matched lead's long-term memory context is injected into the system prompt at call time.

​
is_active
boolean
​
webhook_url
string<uri> | null
​
webhook_events
enum<string>[]
Available options:
call.started,
call.answered,
call.ended,
call.failed,
call.no_answer,
call.dnc_blocked,
transcript.ready,
call.analyzed
​
extraction_parameters
object[]

AI extraction parameters — after each call, values are extracted from the transcript and included in the call.analyzed webhook payload (and stored on the call log).

​
created_at
string<date-time>
​
updated_at
string<date-time>