Create Agent
Create an agent and link it to a voice provider.
Pass provider_name and api_key for the platform running this agent.
Tuner reuses a matching integration in the workspace if one exists, so
sending the same credentials for multiple agents won’t create duplicates.
Note: the integration is keyed by provider per workspace, so creating a
second agent with different credentials for the same provider updates the
shared integration’s credentials — it doesn’t create per-agent credential
isolation.
Returns the agent including its Tuner id. Use that for
[Get Agent] and [Update Agent] — it’s distinct from
remote_identifier (returned here, sent as agent_id on creation),
which is the agent’s ID in your own voice provider’s stack.
Authorizations
Use Tuner API key (tr_api_...) or user session token. Find your API key in Workspace Settings > API Keys.
Path Parameters
Workspace ID. Find this in Workspace > General Settings.
Body
Request schema for agent creation.
Display name for the agent (e.g., 'Support Bot', 'Sales Agent').
1 - 200Voice provider this agent is connected to (e.g., 'retell', 'vapi'). Must match a provider name supported by Tuner.
1 - 200API key for authenticating with your voice provider. Find this in your provider's account settings.
1 - 500Your voice provider's unique identifier for this agent. Find this in your provider's agent configuration.
1 - 36Brief description of what this agent does (e.g., 'Handles billing inquiries').
BCP 47 language tag for the agent's primary language (e.g., 'en', 'es', 'fr'). Defaults to workspace language if omitted.
10Whether this agent handles 'inbound' (customer-initiated) or 'outbound' (agent-initiated) calls. Defaults to 'inbound'.
^(inbound|outbound)$System prompt or instructions given to the agent.
Agent workflow configuration as a JSON object (must be JSON-serializable).
Destination URL for outbound webhook notifications. When set, the agent will POST events to this URL via the webhook delivery queue.
2048Response
Successful Response
Agent schema for API responses with nested relationships.
Tuner's internal numeric ID for this agent.
ID of the voice provider integration this agent uses.
Display name of the agent.
'inbound' for customer-initiated calls, 'outbound' for agent-initiated calls.
Your voice provider's unique identifier for this agent.
ISO 8601 timestamp when the agent was created.
ISO 8601 timestamp when the agent was last updated.
Brief description of what this agent does.
BCP 47 language tag for the agent's primary language (e.g., 'en', 'es').
Nested language and accent for the agent. Null when the agent has no language configured.
System prompt or instructions given to the agent.
Agent workflow configuration. Must be valid JSON.
Destination URL for outbound webhook notifications. Null if not configured.
Name of the voice provider for this agent's integration.
ID of the template this agent was created from. Null if none.
How this agent's config was set up: 'pending', 'template', 'manual', 'mcp', or 'skipped'.
Timestamp when the integration/code step of the setup wizard was confirmed. Null if not yet confirmed.
Timestamp when the setup wizard was completed. Null if not yet completed.
True for the auto-provisioned demo/sample agent. Excluded from real-agent counts that drive the welcome flow and zero-agent empty state.
Timestamp when the agent was deleted. Null if the agent is active.
ID of the user who created this agent.
ID of the user who last updated this agent.
Integration schema with nested provider object.