Agents API

Use the Agents API to build an AI voice agent programmatically instead of through the dashboard. The API covers the build stage of the lifecycle: create the agent, save its configuration as a draft, then publish the configuration you want live calls to use.

Base URL

https://api.persistence.dev

Authentication

Every request requires your workspace API key in the X-API-Key header.

curl https://api.persistence.dev/v1/agents \
  --header "X-API-Key: $PERSISTENCE_API_KEY"

Treat the API key as a secret. Send it only from server-side code and never commit it to source control.

Endpoints

Create agent

POST /v1/agents — create an agent from an agent template.

Save agent draft

PUT /v1/agents/{agentId}/save — store configuration without affecting live calls.

Publish agent

POST /v1/agents/{agentId}/publish — release the configuration used for live calls.

Build an agent

Create the agent

Send a name and a templateId to POST /v1/agents. The response returns the agent id, which is the agentId path parameter for the remaining calls.

Save the configuration as a draft

Send the configuration to PUT /v1/agents/{agentId}/save. A draft lets you iterate without changing the behavior of live calls.

Publish the configuration

Send the configuration to POST /v1/agents/{agentId}/publish. The published version is the one used for live calls.

The save and publish requests take the full agent configuration, not a partial patch. Both require systemPrompt, pipelineType, ambienceId, and triggers.

Configuration reference

The save and publish request bodies share the same fields. The tables below group them by purpose. See the individual endpoint pages for every field, type, and constraint.

Core

Field	Type	Description
`systemPrompt`	string	Required. Instructions that define the agent behavior.
`pipelineType`	string	Required. `cascaded` or `realtime_native`.
`triggers`	array	Required. Trigger definitions evaluated during the call.
`name`	string	Agent name, up to 64 characters.
`description`	string	Agent description, up to 512 characters.
`languageCode`	string	Language code, up to 10 characters.
`knowledgeBaseIds`	array of string	Public IDs of the knowledge bases to attach.
`tools`	array	Actions the agent can call during a conversation.
`dynamicVariables`	object	Variable keys and default values available to the prompt.

Language model

Field	Type	Description
`llmProvider`	string	One of `openai`, `anthropic`, `google`, `groq`, `together`, `azure`, or `cerebras`.
`llmModel`	string	Model identifier for the selected provider.
`llmTemperature`	number	Between `0` and `2`.
`llmMaxTokens`	integer	Minimum `1`.

Voice and audio

Field	Type	Description
`ttsVoiceModelId`	integer	Voice model used for speech synthesis.
`ttsSpeed`	number	Between `0.5` and `2`.
`voiceVolume`	number	Between `0` and `2`.
`ambienceId`	string	Required. Ambient sound applied to the call.
`ambienceVolume`	number	Between `0` and `2`.
`noiseCancellationConfig`	object	`mode` of `noise_only`, `noise_and_speech`, or `none`.
`digitPronunciation`	boolean	Read digits individually.
`vocabularySpecialization`	string	`general` or `medical`.

Conversation behavior

Field	Type	Description
`greetingConfig`	object	`mode` of `agent_first` or `user_first`, plus the message to use.
`interruptionSensitivity`	number	How readily the caller can interrupt the agent.
`endpointingPatience`	number	How long the agent waits before deciding the caller finished.
`responseEagerness`	number	How quickly the agent starts responding.
`minConsecutiveSpeechDelay`	number	Minimum `0`.
`silenceTimeoutSec`	integer	Minimum `1`.
`maxCallDurationSec`	integer	Minimum `1`.
`presenceDetectionConfig`	object	`checkIntervalSec` and `maxAwayChecks`.

Privacy

Field	Type	Description
`piiAnonymisation`	boolean	Anonymise detected personal information.
`piiRedaction`	boolean	Redact detected personal information.
`piiCategories`	array of string	Categories to detect.

Errors

Errors return a code and an error message.

{
  "code": "bad_request",
  "error": "systemPrompt is required"
}

Status	Meaning
`400`	The request body or a path parameter is invalid.
`401`	The `X-API-Key` header is missing or invalid.
`403`	The key is not permitted to perform the operation.
`404`	The agent does not exist.
`409`	The agent conflicts with an existing one.

API reference

Agents

Calls

Accounts and workspaces

Billing

Campaign audience

Campaigns

Telephony

Number pools

Knowledge bases

Base URL

Authentication

Endpoints

Create agent

Save agent draft

Publish agent

Build an agent

Configuration reference

Core

Language model

Voice and audio

Conversation behavior

Privacy

Errors

​Base URL

​Authentication

​Endpoints

Create agent

Save agent draft

Publish agent

​Build an agent

​Configuration reference

​Core

​Language model

​Voice and audio

​Conversation behavior

​Privacy

​Errors

Base URL

Authentication

Endpoints

Build an agent

Configuration reference

Core

Language model

Voice and audio

Conversation behavior

Privacy

Errors