> ## 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 prompt run

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



## OpenAPI

````yaml /openapi.json post /api/v1/prompts/{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/prompts/{slug}/{version}/runs:
    post:
      tags:
        - Prompt Runs
      summary: Create and trigger a prompt run
      description: >-
        Triggers an asynchronous prompt run with the given inputs and returns a
        run ID and thread ID. Reference the prompt by version number, tag, or
        `__latest__`. Pass a thread ID to continue an existing conversation.
      operationId: create_prompt_run
      parameters:
        - name: slug
          in: path
          description: Prompt 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/CreatePromptRun'
      responses:
        '200':
          description: Prompt run created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePromptRunResponse'
        '401':
          description: Missing or invalid API key
        '403':
          description: No active subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Prompt version not found
        '422':
          description: Invalid request payload
      x-codeSamples:
        - lang: PHP
          label: PromptJuggler PHP SDK
          source: >-
            $run = $pj->runPrompt('greeting', 'production', inputs: ['name' =>
            'Ada']);
        - lang: TypeScript
          label: PromptJuggler TypeScript SDK
          source: >-
            const run = await pj.runPrompt('greeting', 'production', { name:
            'Ada' });
        - lang: Python
          label: PromptJuggler Python SDK
          source: 'run = pj.run_prompt(''greeting'', ''production'', {''name'': ''Ada''})'
        - lang: Java
          label: PromptJuggler Java SDK
          source: >-
            CreatePromptRunResponse run = pj.runPrompt("greeting", "production",
            Map.of("name", "Ada"));
        - lang: Go
          label: PromptJuggler Go SDK
          source: >-
            run, err := pj.RunPrompt(ctx, "greeting", "production",
            map[string]string{"name": "Ada"})
components:
  schemas:
    CreatePromptRun:
      description: Request payload for creating a prompt 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
        channel:
          description: >-
            Memory channel within the thread. Prompts on the same channel share
            conversational history; different channels are isolated.
          type: string
          default: default
      type: object
    CreatePromptRunResponse:
      required:
        - id
        - thread
      properties:
        id:
          description: Prompt 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

````