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

# Run Prompt Version

> Run a specific version of a prompt



## OpenAPI

````yaml /public-apis/openapi/prompts.json post /v1/prompts/run
openapi: 3.0.0
info:
  version: 1.0.0
  contact:
    name: Maxim Engineering
    email: eng@getmaxim.ai
  title: Maxim SDK API - prompts
  description: API documentation for Maxim SDK prompts endpoints
servers:
  - url: https://api.getmaxim.ai
security: []
paths:
  /v1/prompts/run:
    post:
      tags:
        - Prompt Version
      summary: Run Prompt Version
      description: Run a specific version of a prompt
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                promptId:
                  type: string
                  description: Unique identifier for the prompt
                versionId:
                  type: string
                  description: Unique identifier for the version
                workspaceId:
                  type: string
                  description: Unique identifier for the workspace
                messages:
                  type: array
                  items:
                    type: object
                    properties:
                      role:
                        type: string
                        enum:
                          - assistant
                          - user
                          - system
                          - model
                          - chatbot
                          - tool
                        description: Role of the message sender
                      content:
                        anyOf:
                          - type: string
                          - type: array
                            items:
                              anyOf:
                                - type: object
                                  properties:
                                    type:
                                      type: string
                                      enum:
                                        - text
                                      description: Content type
                                    text:
                                      type: string
                                      description: Text content
                                  required:
                                    - type
                                    - text
                                  description: Text content object
                                - type: object
                                  properties:
                                    type:
                                      type: string
                                      enum:
                                        - image_url
                                      description: Content type
                                    image_url:
                                      type: object
                                      properties:
                                        url:
                                          type: string
                                          description: Image URL
                                        detail:
                                          type: string
                                          enum:
                                            - auto
                                            - low
                                            - high
                                          description: Image detail level
                                      required:
                                        - url
                                      description: Image URL configuration
                                  required:
                                    - type
                                    - image_url
                                  description: Image URL content object
                              description: Content schema
                          - nullable: true
                        description: Message content
                      tool_call_id:
                        type: string
                        description: Tool call ID for tool messages
                      tool_calls:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              description: Tool call identifier
                            type:
                              type: string
                              enum:
                                - function
                              description: Tool call type
                            function:
                              type: object
                              properties:
                                name:
                                  type: string
                                  description: Function name
                                arguments:
                                  type: string
                                  description: Function arguments as JSON string
                              required:
                                - name
                                - arguments
                              description: Function call details
                          required:
                            - id
                            - type
                            - function
                          description: Tool call object
                        description: Tool calls made by the assistant in this message
                    required:
                      - role
                    description: Message to send to the model
                  description: Array of messages
                modelName:
                  type: string
                  description: Name of the model to use
                modelProvider:
                  type: string
                  enum:
                    - openai
                    - azure
                    - huggingface
                    - anthropic
                    - together
                    - google
                    - groq
                    - bedrock
                    - maxim
                    - cohere
                    - ollama
                    - lmstudio
                    - xai
                    - vertex
                    - mistral
                    - fireworks
                  description: Provider of the model
                modelParameters:
                  allOf:
                    - type: object
                      additionalProperties:
                        nullable: true
                    - type: object
                      properties:
                        tools:
                          type: array
                          items:
                            type: object
                            properties:
                              type:
                                type: string
                                enum:
                                  - function
                                description: Type of tool
                              function:
                                type: object
                                properties:
                                  name:
                                    type: string
                                    description: Function name
                                  description:
                                    type: string
                                    description: Function description
                                  parameters:
                                    type: object
                                    properties:
                                      type:
                                        type: string
                                        description: JSON Schema type
                                      properties:
                                        type: object
                                        additionalProperties:
                                          nullable: true
                                        description: Object properties schema definitions
                                      description:
                                        type: string
                                        description: Schema description
                                      items:
                                        nullable: true
                                        description: Array items schema
                                      required:
                                        type: array
                                        items:
                                          type: string
                                        description: Required property names
                                    required:
                                      - type
                                    description: JSON Schema definition
                                required:
                                  - name
                                  - description
                                  - parameters
                                description: Function configuration
                            required:
                              - type
                              - function
                            description: Tool configuration
                          description: Array of tools
                  default: {}
                  description: Model parameters configuration
              required:
                - promptId
                - versionId
                - workspaceId
      responses:
        '200':
          description: Prompt version executed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      output:
                        nullable: true
                      usage:
                        type: object
                        properties:
                          totalTokens:
                            type: number
                          promptTokens:
                            type: number
                          completionTokens:
                            type: number
                        required:
                          - totalTokens
                          - promptTokens
                          - completionTokens
                    required:
                      - usage
                required:
                  - data
        '400':
          description: Invalid request parameters
        '401':
          description: Unauthorized
        '404':
          description: Prompt or version not found
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-maxim-api-key
      description: API key for authentication

````