# Create from Template

> Generate a voice agent from a natural language description

`POST /api/v1/workflow/create/template`

Menace Voice uses an LLM to generate the initial workflow definition from your description. The result is a fully editable agent — use [Update](/api-reference/agents/update) to refine it after creation.

This is the fastest way to get a working agent, especially for common use cases like appointment booking, lead qualification, or customer support.

## OpenAPI

````yaml api-reference/openapi.json post /api/v1/workflow/create/template
openapi: 3.1.0
info:
  title: Menace Voice API
  description: API for Menace Voice agents
  version: 1.0.0
servers:
  - url: https://voice.menaceui.com
    description: Production
  - url: http://localhost:8000
    description: Local development
paths:
  /api/v1/workflow/create/template:
    post:
      tags:
        - main
      summary: Create Workflow From Template
      description: >-
        Create a new workflow from a natural language template request.


        This endpoint:

        1. Uses mps_service_key_client to call the MPS workflow API

        2. Hardens onboarding drafts to the fixed three-stage canvas when setup
        context is present

        3. Persists a validated draft in the database


        Args:
            request: The template creation request with call_type, use_case, and activity_description
            user: The authenticated user

        Returns:
            The created workflow

        Raises:
            HTTPException: If MPS API call fails
      operationId: create_workflow_from_template_api_v1_workflow_create_template_post
      parameters:
        - name: authorization
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            title: Authorization
        - name: X-API-Key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateWorkflowTemplateRequest"
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowResponse"
        "404":
          description: Not found
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
components:
  schemas:
    AgentOnboardingContext:
      properties:
        agent_brief:
          type: string
          maxLength: 8000
          minLength: 1
          title: Agent Brief
        tone:
          type: string
          maxLength: 100
          minLength: 1
          title: Tone
        language:
          type: string
          maxLength: 100
          minLength: 1
          title: Language
        voice_provider:
          type: string
          maxLength: 100
          minLength: 1
          title: Voice Provider
        voice_name:
          type: string
          maxLength: 255
          minLength: 1
          title: Voice Name
        behavior_notes:
          anyOf:
            - type: string
              maxLength: 4000
            - type: "null"
          title: Behavior Notes
        workflow_stages:
          items:
            type: string
          type: array
          maxItems: 8
          title: Workflow Stages
          description: Optional template hints; the planner chooses the stages from the
            brief.
      type: object
      required:
        - agent_brief
        - tone
        - language
        - voice_provider
        - voice_name
      title: AgentOnboardingContext
    AmbientNoiseConfigurationDefaults:
      properties:
        enabled:
          type: boolean
          title: Enabled
          default: false
        volume:
          type: number
          title: Volume
          default: 0.3
      additionalProperties: true
      type: object
      title: AmbientNoiseConfigurationDefaults
    CallDispositionCodes:
      properties:
        disposition_codes:
          items:
            type: string
          type: array
          title: Disposition Codes
          default: []
      type: object
      title: CallDispositionCodes
    CallDispositionOption:
      properties:
        code:
          type: string
          maxLength: 64
          minLength: 1
          pattern: ^[A-Za-z][A-Za-z0-9_-]*$
          title: Code
          description: Stable code recorded when this outcome is selected.
        description:
          type: string
          maxLength: 1000
          minLength: 1
          title: Description
          description: Business criteria for selecting this disposition.
      type: object
      required:
        - code
        - description
      title: CallDispositionOption
      description: One business outcome the terminal classifier may select.
    CreateWorkflowTemplateRequest:
      properties:
        call_type:
          type: string
          enum:
            - inbound
            - outbound
          title: Call Type
        use_case:
          type: string
          title: Use Case
        activity_description:
          type: string
          title: Activity Description
        name:
          anyOf:
            - type: string
              maxLength: 255
            - type: "null"
          title: Name
        template_id:
          anyOf:
            - type: string
            - type: "null"
          title: Template Id
          description: Agent onboarding template id used to auto-provision recommended
            built-in tools and MCP servers.
        tool_uuids:
          items:
            type: string
          type: array
          maxItems: 100
          title: Tool Uuids
        document_uuids:
          items:
            type: string
          type: array
          maxItems: 100
          title: Document Uuids
        workflow_configurations:
          anyOf:
            - $ref: "#/components/schemas/WorkflowConfigurationDefaults"
            - type: "null"
        pre_call_fetch_url:
          anyOf:
            - type: string
            - type: "null"
          title: Pre Call Fetch Url
          description: Optional URL for Start Call pre-call data fetch. When set, the
            Start Call node posts caller and called numbers here before the
            first spoken turn.
        pre_call_fetch_credential_uuid:
          anyOf:
            - type: string
            - type: "null"
          title: Pre Call Fetch Credential Uuid
          description: Optional credential applied to the pre-call fetch request.
        post_call_webhook_url:
          anyOf:
            - type: string
            - type: "null"
          title: Post Call Webhook Url
          description: Optional URL for a Webhook node that fires after the call ends.
        post_call_webhook_credential_uuid:
          anyOf:
            - type: string
            - type: "null"
          title: Post Call Webhook Credential Uuid
          description: Optional credential applied to the post-call webhook.
        onboarding_context:
          anyOf:
            - $ref: "#/components/schemas/AgentOnboardingContext"
            - type: "null"
          description: Structured answers from agent onboarding. When present, the backend
            enforces the fixed three-stage layout and hardens every generated
            prompt.
      type: object
      required:
        - call_type
        - use_case
        - activity_description
      title: CreateWorkflowTemplateRequest
    ExternalPBXFieldMapping:
      properties:
        context_path:
          type: string
          maxLength: 255
          minLength: 1
          title: Context Path
        destination_field:
          type: string
          pattern: ^[A-Za-z][A-Za-z0-9_]{0,63}$
          title: Destination Field
      type: object
      required:
        - context_path
        - destination_field
      title: ExternalPBXFieldMapping
      description: Map one gathered-context value to a provider-native field.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: "#/components/schemas/ValidationError"
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    OnboardingSetup:
      properties:
        agent_brief:
          type: string
          maxLength: 8000
          minLength: 1
          title: Agent Brief
        tone:
          type: string
          maxLength: 100
          minLength: 1
          title: Tone
        language:
          type: string
          maxLength: 100
          minLength: 1
          title: Language
        voice_provider:
          type: string
          maxLength: 100
          minLength: 1
          title: Voice Provider
        voice_name:
          type: string
          maxLength: 255
          minLength: 1
          title: Voice Name
        behavior_notes:
          anyOf:
            - type: string
              maxLength: 4000
            - type: "null"
          title: Behavior Notes
        workflow_stages:
          items:
            type: string
          type: array
          maxItems: 8
          title: Workflow Stages
          description: Optional template hints; the planner chooses the stages from the
            brief.
        agent_name:
          type: string
          maxLength: 255
          minLength: 1
          title: Agent Name
        use_case:
          type: string
          maxLength: 2000
          minLength: 1
          title: Use Case
        call_type:
          type: string
          enum:
            - inbound
            - outbound
          title: Call Type
      type: object
      required:
        - agent_brief
        - tone
        - language
        - voice_provider
        - voice_name
        - agent_name
        - use_case
        - call_type
      title: OnboardingSetup
    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
    WorkflowConfigurationDefaults:
      properties:
        agent_setup:
          anyOf:
            - $ref: "#/components/schemas/OnboardingSetup"
            - type: "null"
        voice_clone_id:
          anyOf:
            - type: string
              maxLength: 36
              minLength: 1
            - type: "null"
          title: Voice Clone Id
        ambient_noise_configuration:
          $ref: "#/components/schemas/AmbientNoiseConfigurationDefaults"
        max_call_duration:
          type: integer
          maximum: 1200
          exclusiveMinimum: 0
          title: Max Call Duration
          default: 300
        max_user_idle_timeout:
          type: number
          title: Max User Idle Timeout
          default: 10
        smart_turn_stop_secs:
          type: number
          title: Smart Turn Stop Secs
          default: 2
        turn_start_strategy:
          type: string
          enum:
            - default
            - min_words
            - provisional_vad
          title: Turn Start Strategy
          default: default
        turn_start_min_words:
          type: integer
          title: Turn Start Min Words
          default: 3
        provisional_vad_pause_secs:
          type: number
          title: Provisional Vad Pause Secs
          default: 1.5
        turn_stop_strategy:
          type: string
          enum:
            - transcription
            - turn_analyzer
          title: Turn Stop Strategy
          default: transcription
        dictionary:
          type: string
          title: Dictionary
          default: ""
        context_compaction_enabled:
          type: boolean
          title: Context Compaction Enabled
          default: false
        call_dispositions:
          items:
            $ref: "#/components/schemas/CallDispositionOption"
          type: array
          maxItems: 50
          title: Call Dispositions
          description: Allowed business outcomes for terminal call classification. Each
            entry defines the exact stored code and the criteria for selecting
            it.
        text_chat_inactivity_timeout_seconds:
          type: integer
          maximum: 10500
          minimum: 60
          title: Text Chat Inactivity Timeout Seconds
          default: 1800
        external_pbx_field_mappings:
          items:
            $ref: "#/components/schemas/ExternalPBXFieldMapping"
          type: array
          maxItems: 100
          title: External Pbx Field Mappings
        external_pbx_lead_headers:
          items:
            type: string
            pattern: ^[A-Za-z][A-Za-z0-9_]{0,63}$
          type: array
          maxItems: 50
          title: External Pbx Lead Headers
      additionalProperties: true
      type: object
      title: WorkflowConfigurationDefaults
    WorkflowResponse:
      properties:
        id:
          type: integer
          title: Id
        name:
          type: string
          title: Name
        status:
          type: string
          title: Status
        created_at:
          type: string
          format: date-time
          title: Created At
        workflow_definition:
          additionalProperties: true
          type: object
          title: Workflow Definition
        current_definition_id:
          anyOf:
            - type: integer
            - type: "null"
          title: Current Definition Id
        template_context_variables:
          anyOf:
            - additionalProperties: true
              type: object
            - type: "null"
          title: Template Context Variables
        call_disposition_codes:
          anyOf:
            - $ref: "#/components/schemas/CallDispositionCodes"
            - type: "null"
        total_runs:
          anyOf:
            - type: integer
            - type: "null"
          title: Total Runs
        workflow_configurations:
          anyOf:
            - additionalProperties: true
              type: object
            - type: "null"
          title: Workflow Configurations
        version_number:
          anyOf:
            - type: integer
            - type: "null"
          title: Version Number
        version_status:
          anyOf:
            - type: string
            - type: "null"
          title: Version Status
        workflow_uuid:
          anyOf:
            - type: string
            - type: "null"
          title: Workflow Uuid
      type: object
      required:
        - id
        - name
        - status
        - created_at
        - workflow_definition
        - current_definition_id
      title: WorkflowResponse
````