Agent draft

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Response Body

`application/json`

{
  "agent_id": "string",
  "has_draft": true,
  "changed_fields": [
    "name"
  ],
  "config": {},
  "draft_version_number": 0,
  "live_version_number": 0,
  "stale": true,
  "updated_at": "2019-08-24T14:15:22Z",
  "updated_by_user_id": "string"
}

{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}

{
  "error": "agent not found",
  "code": "NOT_FOUND"
}

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

The PATCH /v1/agents/{id} body. webhooks and outboundDtmf are rejected with 400; update them with PATCH. Only fields the draft snapshot carries are stored: name, systemPrompt, voice, voiceInstructions, firstMessage, inboundFirstMessage, outboundFirstMessage, timezone, intent, llmOptions, stackPreferences, sttOptions, ttsOptions, runMode, runtime, backgroundAudio, audioOutput, speechNormalization, idleRePrompts, sttMissRecovery, turnHandling, languageRouting. Other fields pass validation but are not saved.

TypeScript Definitions

Use the request body type in TypeScript.

name?string

Human-readable display name. Does not need to be unique — agents are identified by id.

Length1 <= length <= 120

systemPrompt?string

Length1 <= length

voice?string

intent?

Routing defaults stored on an agent row. Hydrated into a session's RoutingIntent when the session is created with agentId and no inline intent. Note: agents accept a smaller optimizeFor enum than the per-session RoutingIntent.

llmOptions?

Optional LLM tuning defaults stored on an agent. Strict object — only these three keys are accepted.

stackPreferences?

Per-agent stack preferences. Empty / missing layers leave the router unconstrained for that layer; failover stays active within the allowed set.

turnHandling?|

Replaces the stored posture wholesale — supplied keys are not merged into the existing object. null clears it back to the platform defaults.

audioOutput?

Static gain in dB on the agent's own speech, applied before the audio reaches the call (and so before a phone leg), whichever TTS provider spoke. Negative is quieter: -6 roughly halves the amplitude, for voices mastered hotter than telephone speech. Boost saturates at full scale, so it clips a voice that already peaks near 0 dBFS. 0 is a passthrough. Background audio is not affected. Send null to remove the gain.

backgroundAudio?

endCall?Deprecated

Deprecated. The end_call tool is always on for every agent. { "enabled": true } is accepted and ignored; { "enabled": false } is rejected with a 400 VALIDATION_ERROR instead of being silently dropped. Responses always report { "enabled": true }.

firstMessage?string

Opening line for any call without a direction-specific override (inboundFirstMessage / outboundFirstMessage). "" (empty string) means say nothing until the other side speaks; null clears a stored value; once cleared (or never set) the call uses the default greeting for the call language ("Hi, how can I help?" in English).

Lengthlength <= 2000

idleRePrompts?

inboundFirstMessage?string

Opening line on inbound calls. Wins over firstMessage. "" (empty string) means say nothing until the caller speaks; null clears a stored value; once cleared (or never set) the call falls back to firstMessage, then to the default greeting for the call language.

Lengthlength <= 2000

languageRouting?

outboundFirstMessage?string

Opening line on outbound calls. Wins over firstMessage. A non-empty string is spoken as soon as the call connects. "" (empty string) means say nothing: the agent listens until the callee speaks. null clears a stored value, and a cleared (or never set) value is NOT silence: the call falls back to firstMessage, and if that is also unset, to the default greeting for the call language ("Hi, how can I help?" in English). Set "" to open in silence.

Lengthlength <= 2000

promptVariables?array<>

Itemsitems <= 100

runMode?string

Value in"cascade" | "s2s"

graphClassifier?string

Which judge answers llm edge conditions in graph mode. llm (the default) runs a temperature-0 one-shot on this agent's own cascade model. jev routes the decision through TypeSafe's System One as a choice over the candidate edges, returning a calibrated confidence per branch. Ignored by agents with no graph. gpt-live walks the graph on the agent's own GPT-Live speech-to-speech session; a call that runs on the cascade judges with llm. Any failure of the jev judge falls back to the llm path rather than failing the call.

Default"llm"

Value in"llm" | "jev" | "gpt-live"

ringTimeoutSeconds?|

How long this agent's outbound calls ring before they end as a no-answer, in whole seconds (20–45). null restores the 45-second default. A per-call ringTimeoutSeconds on POST /v1/sessions/phone wins. A value outside 20–45 is rejected with 400 RING_TIMEOUT_OUT_OF_RANGE.

Range20 <= value <= 45

outboundDtmf?|

Keys this agent's outbound calls press after answer, before the agent's first turn (see outboundDtmf on create). null stops pressing keys.

Match^[0-9*#wW,]*[0-9*#][0-9*#wW,]*$

Lengthlength <= 64

runtime?string

Managed-agent runtime. Omit it: the runtime that actually serves the agent is chosen for the whole organization, and agent responses carry that effective value, never the value sent here. A value sent here is stored on the agent without changing the organization's runtime, and while the stored value is pipecat, runMode: s2s is refused with 400 INCOMPATIBLE_RUNTIME_MODE (the pipecat runtime runs runMode: cascade only).

Value in"livekit" | "pipecat"

speechNormalization?

sttMissRecovery?

sttOptions?

timezone?string

Length1 <= length <= 64

ttsOptions?

voiceInstructions?string

Lengthlength <= 2000

webhooks?

extractionFields?array<>

Itemsitems <= 30

maxDurationSeconds?|

Hard cap on each of this agent's phone calls, in whole seconds (30-14400), used when the call names none. A per-call maxDurationSeconds on POST /v1/sessions/phone wins. Omit for the default (3600). A Realtime (runMode: s2s) call is still held to its one-hour ceiling. It takes effect on the agent at once and is not part of drafts: a draft save that includes it is rejected with 400 MAX_DURATION_NOT_DRAFTABLE. null restores the default.

Range30 <= value <= 14400

Response Body

`application/json`

{
  "agent_id": "string",
  "has_draft": true,
  "changed_fields": [
    "name"
  ],
  "config": {},
  "draft_version_number": 0,
  "live_version_number": 0,
  "stale": true,
  "updated_at": "2019-08-24T14:15:22Z",
  "updated_by_user_id": "string"
}

{
  "error": "Request body is not valid JSON.",
  "code": "INVALID_JSON"
}

{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}

{
  "error": "agent not found",
  "code": "NOT_FOUND"
}

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Resource id.

Response Body

`application/json`

{
  "agent_id": "string",
  "has_draft": true,
  "changed_fields": [
    "name"
  ],
  "config": {},
  "draft_version_number": 0,
  "live_version_number": 0,
  "stale": true,
  "updated_at": "2019-08-24T14:15:22Z",
  "updated_by_user_id": "string"
}

{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}

{
  "error": "agent not found",
  "code": "NOT_FOUND"
}

200application/json

401application/json

404application/json

200application/json

400application/json

401application/json

404application/json

Example invalidJson

Example validation

Example webhooksNotDraftable

Example outboundDtmfNotDraftable

Example invalidWorkflow

200application/json

401application/json

404application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`