Skip to main content
PUT
Update Agent

Authorizations

Authorization
string
header
required

Use Tuner API key (tr_api_...) or user session token. Find your API key in Workspace Settings > API Keys.

Path Parameters

agent_id
string
required

Tuner's numeric agent ID, or your Agent ID from Agent Settings > Agent Connection. Digits-only values are read as the numeric ID.

workspace_id
integer
required

Workspace ID. Find this in Workspace > General Settings.

Body

application/json

Request schema for agent update (agent fields only).

agent_name
string
required

Display name for the agent (e.g., 'Support Bot', 'Sales Agent').

Required string length: 1 - 200
Example:

"Support Bot"

provider_name
string
required

Voice provider this agent is connected to (e.g., 'retell', 'vapi'). Must match a provider name supported by Tuner. Changing it re-links the agent to the matching integration, creating one if none exists.

Required string length: 1 - 200
Example:

"retell"

agent_id
string
required

Your voice provider's unique identifier for this agent. Find this in your provider's agent configuration.

Required string length: 1 - 36
Example:

"3f2b8c1e-5d4a-4e7b-9a6c-1d2e3f4a5b6c"

summary
string | null

Brief description of what this agent does (e.g., 'Handles billing inquiries').

Example:

"Handles billing inquiries"

agent_lang
string | null

BCP 47 language tag for the agent's primary language (e.g., 'en', 'es', 'fr'). Omit to clear.

Maximum string length: 10
Example:

"en"

call_direction
string
default:inbound

Whether this agent handles 'inbound' (customer-initiated) or 'outbound' (agent-initiated) calls.

Pattern: ^(inbound|outbound)$
prompt
string | null

System prompt or instructions given to the agent.

workflow
Workflow · object | null

Agent workflow configuration as a JSON object (must be JSON-serializable).

webhook_url
string | null

Destination URL for outbound webhook notifications. Omit or pass null to clear an existing webhook URL.

Maximum string length: 2048
Example:

"https://example.com/webhooks/tuner"

api_key
string | null

Vendor API key for your voice provider (Retell, Vapi) -- find it in that provider's account settings. Not required for the SDK providers (Custom API, LiveKit, Pipecat, Dograh): those authenticate with your workspace's Tuner API key, which Tuner already knows. Replaces the API key stored on the workspace's integration for this provider, which is shared by all agents using that provider. Omit to keep the current key.

Maximum string length: 500
Example:

"<your-provider-api-key>"

Response

Successful Response

Agent schema for API responses with nested relationships.

id
integer
required

Tuner's internal numeric ID for this agent. Use it in the agent-specific endpoints; it is distinct from remote_identifier.

integration_id
integer
required

ID of the voice provider integration this agent uses.

name
string
required

Display name of the agent.

call_direction
string
required

'inbound' for customer-initiated calls, 'outbound' for agent-initiated calls.

remote_identifier
string
required

Your voice provider's unique identifier for this agent (the agent_id sent on creation). Distinct from Tuner's id.

created_at
string<date-time>
required

ISO 8601 timestamp when the agent was created.

updated_at
string<date-time>
required

ISO 8601 timestamp when the agent was last updated.

description
string | null

Brief description of what this agent does.

lang
string | null

BCP 47 language tag for the agent's primary language (e.g., 'en', 'es').

persona
AgentPersona · object | null

Nested language and accent for the agent. Null when the agent has no language configured.

prompt
string | null

System prompt or instructions given to the agent.

workflow
Workflow · object | null

Agent workflow configuration. Must be valid JSON.

webhook_url
string | null

Destination URL for outbound webhook notifications. Null if not configured.

integration_name
string | null

Name of the voice provider for this agent's integration.

source_template_id
integer | null

ID of the template this agent was created from. Null if none.

setup_method
string
default:pending

How this agent's config was set up: 'pending', 'template', 'manual', 'mcp', or 'skipped'.

setup_code_confirmed_at
string<date-time> | null

Timestamp when the integration/code step of the setup wizard was confirmed. Null if not yet confirmed.

setup_completed_at
string<date-time> | null

Timestamp when the setup wizard was completed. Null if not yet completed.

is_sample
boolean
default:false

True for the auto-provisioned demo/sample agent. Excluded from real-agent counts that drive the welcome flow and zero-agent empty state.

deleted_at
string<date-time> | null

Timestamp when the agent was deleted. Null if the agent is active.

created_by
integer | null

ID of the user who created this agent.

updated_by
integer | null

ID of the user who last updated this agent.

integration
IntegrationWithProvider · object | null

Integration schema with nested provider object.