Documentation

Create Test Run

Execute a workflow without placing a real phone call

Execute a workflow without placing a real phone call

Creates a test execution of the workflow. No outbound call is placed — this is useful for validating agent behavior, checking prompt outputs, and testing tool integrations before going live.

Quick reference#

Execute a workflow without placing a real phone call. Send the request to POST /api/v1/workflow/{workflowid}/runs on the Paladin API base URL.

Method	`POST`
Path	`/api/v1/workflow/{workflowid}/runs`
Path parameters	workflowid
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/{workflowid}/runs

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/{workflow_id}/runs:
    post:
      tags:
        - main
      summary: Create Workflow Run
      description: >-
        Create a new workflow run when the user decides to execute the workflow
        via chat or voice

        Args:
            workflow_id: The ID of the workflow to run
            request: The create workflow run request
            user: The user to create the workflow run for
      operationId: create_workflow_run_api_v1_workflow__workflow_id__runs_post
      parameters:
        - name: workflow_id
          in: path
          required: true
          schema:
            type: integer
            title: Workflow Id
        - 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/CreateWorkflowRunRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateWorkflowRunResponse'
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    CreateWorkflowRunRequest:
      properties:
        mode:
          type: string
          title: Mode
        name:
          type: string
          title: Name
      type: object
      required:
        - mode
        - name
      title: CreateWorkflowRunRequest
    CreateWorkflowRunResponse:
      properties:
        id:
          type: integer
          title: Id
        workflow_id:
          type: integer
          title: Workflow Id
        name:
          type: string
          title: Name
        mode:
          type: string
          title: Mode
        created_at:
          type: string
          format: date-time
          title: Created At
        definition_id:
          type: integer
          title: Definition Id
        initial_context:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Initial Context
      type: object
      required:
        - id
        - workflow_id
        - name
        - mode
        - created_at
        - definition_id
      title: CreateWorkflowRunResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    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