> ## Documentation Index
> Fetch the complete documentation index at: https://docs.persistence.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents API

> Create, configure, and publish AI voice agents with the Persistence 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.

```bash theme={null}
curl https://api.persistence.dev/v1/agents \
  --header "X-API-Key: $PERSISTENCE_API_KEY"
```

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

## Endpoints

<CardGroup cols={1}>
  <Card title="Create agent" icon="plus" href="/api-reference/agents/create-agent">
    `POST /v1/agents` — create an agent from an agent template.
  </Card>

  <Card title="Save agent draft" icon="save" href="/api-reference/agents/save-agent-draft">
    `PUT /v1/agents/{agentId}/save` — store configuration without affecting live calls.
  </Card>

  <Card title="Publish agent" icon="rocket" href="/api-reference/agents/publish-agent">
    `POST /v1/agents/{agentId}/publish` — release the configuration used for live calls.
  </Card>
</CardGroup>

## Build an agent

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Publish the configuration">
    Send the configuration to `POST /v1/agents/{agentId}/publish`. The published version is the one used for live calls.
  </Step>
</Steps>

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

## 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.

```json theme={null}
{
  "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.          |