> ## Documentation Index > Fetch the complete documentation index at: https://docs.usetuner.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create Agent > Create a new agent in a workspace. Creates an agent and links it to a voice provider integration identified by `provider_name` and `api_key`. If a matching integration already exists in the workspace it will be reused; otherwise a new one is created. Returns the newly created agent including its Tuner ID (`id`), which you can use in subsequent `GET` or `PUT` requests. - **workspace_id**: Get this from Workspace > General Settings. ## OpenAPI ````yaml POST /api/v1/workspaces/{workspace_id}/agents/ openapi: 3.1.0 info: title: My Public API version: 1.0.0 servers: - url: https://api.usetuner.ai security: [] tags: - name: public description: Public endpoints paths: /api/v1/workspaces/{workspace_id}/agents/: post: tags: - public summary: Create Agent description: >- Create a new agent in a workspace. Creates an agent and links it to a voice provider integration identified by `provider_name` and `api_key`. If a matching integration already exists in the workspace it will be reused; otherwise a new one is created. Returns the newly created agent including its Tuner ID (`id`), which you can use in subsequent `GET` or `PUT` requests. - **workspace_id**: Get this from Workspace > General Settings. operationId: create_agent_api_v1_workspaces__workspace_id__agents__post parameters: - name: workspace_id in: path required: true schema: type: integer title: Workspace Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentCreateRequest' responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Agent' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - Bearer: [] components: schemas: AgentCreateRequest: properties: agent_name: type: string maxLength: 200 minLength: 1 title: Agent Name description: Display name for the agent (e.g., 'Support Bot', 'Sales Agent'). summary: anyOf: - type: string - type: 'null' title: Summary description: >- Brief description of what this agent does (e.g., 'Handles billing inquiries'). provider_name: type: string maxLength: 200 minLength: 1 title: Provider Name description: >- Voice provider this agent is connected to (e.g., 'retell', 'vapi'). Must match a provider name supported by Tuner. api_key: type: string maxLength: 500 minLength: 1 title: Api Key description: >- API key for authenticating with your voice provider. Find this in your provider's account settings. agent_id: type: string maxLength: 36 minLength: 1 title: Agent Id description: >- Your voice provider's unique identifier for this agent. Find this in your provider's agent configuration. agent_lang: anyOf: - type: string maxLength: 10 - type: 'null' title: Agent Lang description: >- BCP 47 language tag for the agent's primary language (e.g., 'en', 'es', 'fr'). Defaults to workspace language if omitted. call_direction: type: string pattern: ^(inbound|outbound)$ title: Call Direction description: >- Whether this agent handles 'inbound' (customer-initiated) or 'outbound' (agent-initiated) calls. Defaults to 'inbound'. default: inbound prompt: anyOf: - type: string - type: 'null' title: Prompt description: System prompt or instructions given to the agent. workflow: anyOf: - additionalProperties: true type: object - type: 'null' title: Workflow description: >- Agent workflow configuration as a JSON object (must be JSON-serializable). webhook_url: anyOf: - type: string maxLength: 2048 - type: 'null' title: Webhook Url description: >- Destination URL for outbound webhook notifications. When set, the agent will POST events to this URL via the webhook delivery queue. type: object required: - agent_name - provider_name - api_key - agent_id title: AgentCreateRequest description: Request schema for agent creation. Agent: properties: id: type: integer title: Id description: Tuner's internal numeric ID for this agent. integration_id: type: integer title: Integration Id description: ID of the voice provider integration this agent uses. name: type: string title: Name description: Display name of the agent. description: anyOf: - type: string - type: 'null' title: Description description: Brief description of what this agent does. lang: anyOf: - type: string - type: 'null' title: Lang description: >- BCP 47 language tag for the agent's primary language (e.g., 'en', 'es'). persona: anyOf: - $ref: '#/components/schemas/AgentPersona' - type: 'null' description: >- Nested language and accent for the agent. Null when the agent has no language configured. call_direction: type: string title: Call Direction description: >- 'inbound' for customer-initiated calls, 'outbound' for agent-initiated calls. remote_identifier: type: string title: Remote Identifier description: Your voice provider's unique identifier for this agent. prompt: anyOf: - type: string - type: 'null' title: Prompt description: System prompt or instructions given to the agent. workflow: anyOf: - additionalProperties: true type: object - type: 'null' title: Workflow description: Agent workflow configuration. Must be valid JSON. webhook_url: anyOf: - type: string - type: 'null' title: Webhook Url description: >- Destination URL for outbound webhook notifications. Null if not configured. integration_name: anyOf: - type: string - type: 'null' title: Integration Name description: Name of the voice provider for this agent's integration. source_template_id: anyOf: - type: integer - type: 'null' title: Source Template Id description: ID of the template this agent was created from. Null if none. setup_method: type: string title: Setup Method description: >- How this agent's config was set up: 'pending', 'template', 'manual', 'mcp', or 'skipped'. default: pending setup_code_confirmed_at: anyOf: - type: string format: date-time - type: 'null' title: Setup Code Confirmed At description: >- Timestamp when the integration/code step of the setup wizard was confirmed. Null if not yet confirmed. setup_completed_at: anyOf: - type: string format: date-time - type: 'null' title: Setup Completed At description: >- Timestamp when the setup wizard was completed. Null if not yet completed. deleted_at: anyOf: - type: string format: date-time - type: 'null' title: Deleted At description: Timestamp when the agent was deleted. Null if the agent is active. created_at: type: string format: date-time title: Created At description: ISO 8601 timestamp when the agent was created. updated_at: type: string format: date-time title: Updated At description: ISO 8601 timestamp when the agent was last updated. created_by: anyOf: - type: integer - type: 'null' title: Created By description: ID of the user who created this agent. updated_by: anyOf: - type: integer - type: 'null' title: Updated By description: ID of the user who last updated this agent. integration: anyOf: - $ref: '#/components/schemas/IntegrationWithProvider' - type: 'null' type: object required: - id - integration_id - name - call_direction - remote_identifier - created_at - updated_at title: Agent description: Agent schema for API responses with nested relationships. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError AgentPersona: properties: language: anyOf: - type: string - type: 'null' title: Language description: The agent's primary language (BCP 47 tag). accent: anyOf: - type: string - type: 'null' title: Accent description: >- Default accent code for the agent's language. Null if not configured. type: object title: AgentPersona description: Nested persona object carrying language and accent for an agent. IntegrationWithProvider: properties: id: type: integer title: Id uuid: type: string format: uuid title: Uuid workspace_id: type: integer title: Workspace Id provider_id: type: integer title: Provider Id deleted_at: anyOf: - type: string format: date-time - type: 'null' title: Deleted At created_at: type: string format: date-time title: Created At updated_at: type: string format: date-time title: Updated At created_by: anyOf: - type: integer - type: 'null' title: Created By updated_by: anyOf: - type: integer - type: 'null' title: Updated By api_key: type: string maxLength: 500 minLength: 1 title: Api Key provider: anyOf: - $ref: '#/components/schemas/ProviderResponse' - type: 'null' type: object required: - id - uuid - workspace_id - provider_id - created_at - updated_at - api_key title: IntegrationWithProvider description: Integration schema with nested provider object. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError ProviderResponse: properties: id: type: integer title: Id name: type: string title: Name type: object required: - id - name title: ProviderResponse description: Response schema for provider. securitySchemes: Bearer: type: http description: >- Use Tuner API key (tr_api_...) or user session token. Find your API key in Workspace Settings > API Keys. scheme: bearer ````