Documentation

Create from Template

Generate a voice agent from a natural language description

Generate a voice agent from a natural language description

Paladin uses an LLM to generate the initial workflow definition from your description. The result is a fully editable agent — use 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.

Quick reference#

Generate a voice agent from a natural language description. Send the request to POST /api/v1/workflow/create/template on the Paladin API base URL.

Method	`POST`
Path	`/api/v1/workflow/create/template`
Path parameters	None in the path.
Authentication	Use the authentication method shown in the OpenAPI block and the Authentication docs. Keep API keys server-side.

Before you call#

Confirm you are using the production base URL shown in the API reference.
Make sure any path IDs belong to the same Paladin organization as the credential you are using.
Validate request bodies and required fields before sending production traffic.

Common error checks#

Use 401 or 403 responses to check credentials, organization scope, and permissions.
Use 404 responses to check whether the referenced resource exists in the current organization.
Use 422 responses to inspect missing or invalid request fields.

OpenAPI#

POST /api/v1/workflow/create/template

openapi: 3.1.0
info:
  title: Paladin API
  description: API for the Paladin app
  version: 1.0.0
servers:
  - url: https://app.paladin.northmanngrp.com
    description: Production

security: []
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 MPS workflow API
        2. Passes organization ID (authenticated mode) or created_by (managed mode)
        3. Creates the workflow 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:
    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
      type: object
      required:
        - call_type
        - use_case
        - activity_description
      title: CreateWorkflowTemplateRequest
    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
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CallDispositionCodes:
      properties:
        disposition_codes:
          items:
            type: string
          type: array
          title: Disposition Codes
          default: []
      type: object
      title: CallDispositionCodes
    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