# Agents

Manage AI voice agents and text agents under the unified /agents endpoint. Use ?type=voice or ?type=text to filter listings. The type field is required in the create body.

**Base URL:** `https://api.trustpager.com/functions/v1/api/v1`

## Endpoints

### GET /agents?type=voice|text

List agents. type query param is required: "voice" for voice agents, "text" for text agents.

**Scopes:** `voice-agents:read` — [full detail](./agents/get-agents-type-voice-text.md)

### GET /agents/:id

Retrieve an agent by ID. Auto-detects type (voice or text) from the ID.

**Scopes:** `voice-agents:read` — [full detail](./agents/get-agents-id.md)

### POST /agents

Create an agent. Include "type": "voice" or "type": "text" in the request body. For voice: agent_name is required. For text: name is required.

**Scopes:** `voice-agents:write` — [full detail](./agents/post-agents.md)

### PATCH /agents/:id

Update an agent. Auto-detects type from the ID.

**Scopes:** `voice-agents:write` — [full detail](./agents/patch-agents-id.md)

### DELETE /agents/:id

Delete an agent. Auto-detects type from the ID.

**Scopes:** `voice-agents:write` — [full detail](./agents/delete-agents-id.md)

### POST /agents/:id/sync

Sync a voice agent configuration with Retell (voice only).

**Scopes:** `voice-agents:write` — [full detail](./agents/post-agents-id-sync.md)

### POST /agents/:id/update-flow

Save a conversation flow draft to Retell (voice only). Requires the full ConversationFlow object in the "flow" field. Does not go live until /publish is called.

**Scopes:** `voice-agents:write` — [full detail](./agents/post-agents-id-update-flow.md)

### POST /agents/:id/update-settings

Update voice and behavior settings on the voice provider without touching the conversation flow (voice only). Accepted fields: voice_id, voice_model, language, fallback_voice_ids, voice_speed, voice_temperature, volume, responsiveness, interruption_sensitivity, enable_backchannel, backchannel_frequency, normalize_for_speech, max_call_duration_ms, end_call_after_silence_ms, reminder_trigger_ms, reminder_max_count, ambient_sound, ambient_sound_volume, data_storage_setting.

**Scopes:** `voice-agents:write` — [full detail](./agents/post-agents-id-update-settings.md)

### POST /agents/:id/publish

Publish the voice agent draft to live on Retell. Makes the current draft (flow + settings) active (voice only).

**Scopes:** `voice-agents:write` — [full detail](./agents/post-agents-id-publish.md)

### POST /agents/:id/call

Initiate an outbound voice call using this agent (voice only). from_number is optional -- if omitted the API falls back to the agent's first configured outbound number (phone_numbers.outbound[0]). Returns a validation error if neither from_number nor an outbound number is configured. Optionally pass dynamic_variables (object) to inject variables into the agent at call start. The response includes a warnings array if expected dynamic variables are missing.

**Scopes:** `calls:initiate` — [full detail](./agents/post-agents-id-call.md)

### GET /agents/:id/calls

List call logs for a voice agent (voice only).

**Scopes:** `calls:read` — [full detail](./agents/get-agents-id-calls.md)

### GET /agents/calls/:callId

Get detailed call log including transcript (voice only).

**Scopes:** `calls:read` — [full detail](./agents/get-agents-calls-callId.md)

### GET /agents/:id/website-config

List website configs for a voice agent (voice only).

**Scopes:** `voice-agents:read` — [full detail](./agents/get-agents-id-website-config.md)

### POST /agents/:id/website-config

Create a website config for a voice agent. website_id is required (voice only).

**Scopes:** `voice-agents:write` — [full detail](./agents/post-agents-id-website-config.md)

### PATCH /agents/:id/website-config/:configId

Update a voice agent website config (voice only).

**Scopes:** `voice-agents:write` — [full detail](./agents/patch-agents-id-website-config-configId.md)

### DELETE /agents/:id/website-config/:configId

Delete a voice agent website config (voice only).

**Scopes:** `voice-agents:write` — [full detail](./agents/delete-agents-id-website-config-configId.md)

### GET /agents/:id/outbound-config

List outbound configs for a voice agent (voice only).

**Scopes:** `voice-agents:read` — [full detail](./agents/get-agents-id-outbound-config.md)

### POST /agents/:id/outbound-config

Create an outbound config for a voice agent. website_id is required (voice only).

**Scopes:** `voice-agents:write` — [full detail](./agents/post-agents-id-outbound-config.md)

### PATCH /agents/:id/outbound-config/:configId

Update a voice agent outbound config (voice only).

**Scopes:** `voice-agents:write` — [full detail](./agents/patch-agents-id-outbound-config-configId.md)

### DELETE /agents/:id/outbound-config/:configId

Delete a voice agent outbound config (voice only).

**Scopes:** `voice-agents:write` — [full detail](./agents/delete-agents-id-outbound-config-configId.md)

### GET /agents/:id/responses

List responses generated by a text agent (text only).

**Scopes:** `voice-agents:read` — [full detail](./agents/get-agents-id-responses.md)

### POST /agents/:id/provision

Recover an orphan voice agent row (created locally with a UUID agent_id before the provisioning fix). Registers the agent with the voice provider and updates the local row with the real agent_id. Guard: rejects if the agent_id already starts with "agent_" (already provisioned). After provisioning, call /update-flow and /publish to go live.

**Scopes:** `voice-agents:write` — [full detail](./agents/post-agents-id-provision.md)

### POST /agents/:id/apply-template

Stamp the default FinalPiece voice agent profile (prompt, settings, knowledge base) onto a provisioned agent, OR copy the full configuration from another source agent. Pass source_agent_id to copy from a specific agent; omit it to apply the platform default profile. Overwrites the conversation flow and settings in place -- the agent must be provisioned first (agent_id starts with "agent_").

**Scopes:** `voice-agents:write` — [full detail](./agents/post-agents-id-apply-template.md)