> ## Documentation Index
> Fetch the complete documentation index at: https://docs.promptjuggler.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create and trigger a workflow run

> Triggers an asynchronous workflow run with the given inputs and returns a run ID and thread ID. Reference the workflow by version number, tag, or `__latest__`. Pass a thread ID to continue an existing conversation across runs.



## OpenAPI

````yaml /openapi.json post /api/v1/workflows/{slug}/{version}/runs
openapi: 3.1.1
info:
  title: PromptJuggler
  description: PromptJuggler API
  version: 1.0.0
servers:
  - url: https://promptjuggler.com
security:
  - Bearer: []
tags:
  - name: Prompts
    description: Fetch prompts and revisions.
  - name: Prompt Runs
    description: Execute published prompts and retrieve results.
  - name: Workflow Runs
    description: Execute multi-step workflows and retrieve results.
  - name: Knowledge Bases
    description: Upload and manage documents used for retrieval-augmented generation.
paths:
  /api/v1/workflows/{slug}/{version}/runs:
    post:
      tags:
        - Workflow Runs
      summary: Create and trigger a workflow run
      description: >-
        Triggers an asynchronous workflow run with the given inputs and returns
        a run ID and thread ID. Reference the workflow by version number, tag,
        or `__latest__`. Pass a thread ID to continue an existing conversation
        across runs.
      operationId: create_workflow_run
      parameters:
        - name: slug
          in: path
          description: Workflow Handle
          required: true
          schema:
            type: string
        - name: version
          in: path
          description: Specific version or tag or id
          required: true
          schema:
            type:
              - integer
              - string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkflowRun'
      responses:
        '200':
          description: Workflow run created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateWorkflowRunResponse'
        '401':
          description: Missing or invalid API key
        '403':
          description: No active subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Workflow version not found
        '422':
          description: Invalid request payload
      x-codeSamples:
        - lang: PHP
          label: PromptJuggler PHP SDK
          source: >-
            $run = $pj->runWorkflow('research-pipeline', 'production', inputs:
            ['topic' => 'AI safety']);
        - lang: TypeScript
          label: PromptJuggler TypeScript SDK
          source: >-
            const run = await pj.runWorkflow('research-pipeline', 'production',
            { topic: 'AI safety' });
        - lang: Python
          label: PromptJuggler Python SDK
          source: >-
            run = pj.run_workflow('research-pipeline', 'production', {'topic':
            'AI safety'})
        - lang: Java
          label: PromptJuggler Java SDK
          source: >-
            CreateWorkflowRunResponse run = pj.runWorkflow("research-pipeline",
            "production", Map.of("topic", "AI safety"));
        - lang: Go
          label: PromptJuggler Go SDK
          source: >-
            run, err := pj.RunWorkflow(ctx, "research-pipeline", "production",
            map[string]string{"topic": "AI safety"})
components:
  schemas:
    CreateWorkflowRun:
      description: Request payload for creating a workflow run.
      required:
        - inputs
      properties:
        inputs:
          description: Key-value map of input variable names to their values.
          type: object
          example:
            topic: AI safety
          additionalProperties:
            type: string
        thread:
          description: >-
            Thread ID to continue a multi-turn conversation. Omit to start a new
            thread.
          type:
            - string
            - 'null'
          format: uuid
          default: null
        priority:
          description: Processing priority.
          type: string
          default: normal
          enum:
            - onsite
            - normal
            - low
        environment:
          description: >-
            Environment that scopes which webhooks fire and which environment
            variables the run can access. Uses the default environment when
            omitted.
          type:
            - string
            - 'null'
          default: null
        envVars:
          description: >-
            Runtime environment variable overrides for this run. Keys must be
            UPPER_CASE. At most 50 entries, 64 KB total.
          type: object
          example:
            MY_API_KEY: sk-...
          default: {}
          additionalProperties:
            type: string
        metadata:
          description: >-
            Arbitrary key-value metadata attached to the run. Values can be
            strings or arrays of strings.
          type: object
          example:
            user_id: '42'
          default: {}
          additionalProperties:
            oneOf:
              - type: string
              - type: array
                items:
                  type: string
      type: object
    CreateWorkflowRunResponse:
      required:
        - id
        - thread
      properties:
        id:
          description: Workflow run ID
          type: string
          format: uuid
        thread:
          description: Thread ID for multi-turn runs
          type: string
          format: uuid
      type: object
    ErrorResponse:
      description: Error response.
      required:
        - error
      properties:
        error:
          description: Error message.
          type: string
      type: object
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer

````