Documentation

Create from Definition

Create a voice agent from an explicit workflow definition

Create a voice agent from an explicit workflow definition

Creates an agent from a node and edge graph you provide directly. Use this when you want full control over the workflow structure, or when programmatically generating agents.

The workflow_definition object contains nodes (the steps in the conversation) and edges (transitions between steps). See Editing a Workflow for the full schema.

Quick reference#

Create a voice agent from an explicit workflow definition. Send the request to POST /api/v1/workflow/create/definition on the Paladin API base URL.

Method	`POST`
Path	`/api/v1/workflow/create/definition`
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/definition

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/definition:
    post:
      tags:
        - main
      summary: Create Workflow
      description: |-
        Create a new workflow from the client

        Args:
            request: The create workflow request
            user: The user to create the workflow for
      operationId: create_workflow_api_v1_workflow_create_definition_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/CreateWorkflowRequest'
      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:
    CreateWorkflowRequest:
      properties:
        name:
          type: string
          title: Name
        workflow_definition:
          additionalProperties: true
          type: object
          title: Workflow Definition
      type: object
      required:
        - name
        - workflow_definition
      title: CreateWorkflowRequest
    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