Vellum AI Execute Prompt API

openapi: 3.2.0
info:
  title: Client SDK Execute Prompt API
  version: 1.0.0
servers:
- url: https://predict.vellum.ai
- url: https://api.vellum.ai
- url: https://documents.vellum.ai
tags:
- name: Execute Prompt
paths:
  /v1/execute-prompt:
    post:
      operationId: execute-prompt
      summary: Execute Prompt
      description: Executes a deployed Prompt and returns the result.
      tags:
      - Execute Prompt
      parameters:
      - name: X-API-KEY
        in: header
        required: true
        schema:
          type: string
      - name: X-API-Version
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutePromptResponse'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutePromptApiErrorResponse'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutePromptApiErrorResponse'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutePromptApiErrorResponse'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutePromptApiErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecutePromptRequest'
components:
  schemas:
    DocumentChatMessageContentRequest:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/DocumentEnum'
        value:
          $ref: '#/components/schemas/VellumDocumentRequest'
      required:
      - type
      - value
      description: A document value that is used in a chat message.
      title: DocumentChatMessageContentRequest
    PromptExecutionMeta:
      type: object
      properties:
        model_name:
          type:
          - string
          - 'null'
        latency:
          type:
          - integer
          - 'null'
        deployment_release_tag:
          type:
          - string
          - 'null'
        prompt_version_id:
          type:
          - string
          - 'null'
        finish_reason:
          oneOf:
          - $ref: '#/components/schemas/FinishReasonEnum'
          - type: 'null'
        usage:
          oneOf:
          - $ref: '#/components/schemas/MLModelUsage'
          - type: 'null'
        cost:
          oneOf:
          - $ref: '#/components/schemas/Price'
          - type: 'null'
      description: The subset of the metadata tracked by Vellum during prompt execution that the request opted into with `expand_meta`.
      title: PromptExecutionMeta
    JSONInputRequest:
      type: object
      properties:
        name:
          type: string
          description: The variable's name
        type:
          $ref: '#/components/schemas/JsonEnum'
        value:
          oneOf:
          - description: Any type
          - type: 'null'
      required:
      - name
      - type
      - value
      description: A user input representing a JSON object
      title: JSONInputRequest
    UnitEnum:
      type: string
      enum:
      - USD
      description: '* `USD` - USD'
      title: UnitEnum
    ArrayChatMessageContentRequest:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ArrayEnum'
        value:
          type: array
          items:
            $ref: '#/components/schemas/ArrayChatMessageContentItemRequest'
      required:
      - type
      - value
      description: A list of chat message content items.
      title: ArrayChatMessageContentRequest
    RejectedEnum:
      type: string
      enum:
      - REJECTED
      title: RejectedEnum
    StringChatMessageContentRequest:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/StringEnum'
        value:
          type: string
      required:
      - type
      - value
      description: A string value that is used in a chat message.
      title: StringChatMessageContentRequest
    StringVellumValue:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/StringEnum'
        value:
          type:
          - string
          - 'null'
      required:
      - type
      - value
      description: A value representing a string.
      title: StringVellumValue
    VellumAudioRequest:
      type: object
      properties:
        src:
          type: string
          description: "The reference to the source data. This can be one of the following formats:\n1. A base64-encoded data URL (e.g., 'data:application/pdf;base64,JVBERi0xLjQKJcfs...').\n2. A url pointing to a file accessible over HTTP or HTTPS.\n3. A reference to a file that's been previously uploaded to Vellum, in the form of 'vellum:uploaded-file:{uploaded_file_id}'.\n    You can use the Uploaded Files API to retrieve the url of the uploaded file given its ID. See https://docs.vellum.ai/developers/client-sdk/uploaded-files/retrieve for details."
        metadata:
          type:
          - object
          - 'null'
          additionalProperties:
            description: Any type
      required:
      - src
      title: VellumAudioRequest
    ChatMessageRole:
      type: string
      enum:
      - SYSTEM
      - ASSISTANT
      - USER
      - FUNCTION
      description: '* `SYSTEM` - System

        * `ASSISTANT` - Assistant

        * `USER` - User

        * `FUNCTION` - Function'
      title: ChatMessageRole
    AudioChatMessageContentRequest:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/AudioEnum'
        value:
          $ref: '#/components/schemas/VellumAudioRequest'
      required:
      - type
      - value
      description: An audio value that is used in a chat message.
      title: AudioChatMessageContentRequest
    RejectedExecutePromptResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/PromptExecutionMeta'
        raw:
          type: object
          additionalProperties:
            description: Any type
          description: The subset of the raw response from the model that the request opted into with `expand_raw`.
        execution_id:
          type: string
          description: The ID of the execution.
        state:
          $ref: '#/components/schemas/RejectedEnum'
        error:
          $ref: '#/components/schemas/VellumError'
      required:
      - execution_id
      - state
      - error
      description: The unsuccessful response from the model containing an error of what went wrong.
      title: RejectedExecutePromptResponse
    ChatHistoryEnum:
      type: string
      enum:
      - CHAT_HISTORY
      title: ChatHistoryEnum
    FunctionCallVellumValue:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/FunctionCallEnum'
        value:
          oneOf:
          - $ref: '#/components/schemas/FunctionCall'
          - type: 'null'
      required:
      - type
      - value
      description: A value representing a Function Call.
      title: FunctionCallVellumValue
    AudioInputRequest:
      type: object
      properties:
        name:
          type: string
          description: The variable's name
        type:
          $ref: '#/components/schemas/AudioEnum'
        value:
          $ref: '#/components/schemas/VellumAudioRequest'
      required:
      - name
      - type
      - value
      description: A user input representing a Vellum Audio value
      title: AudioInputRequest
    PromptOutput:
      oneOf:
      - $ref: '#/components/schemas/StringVellumValue'
      - $ref: '#/components/schemas/JsonVellumValue'
      - $ref: '#/components/schemas/ErrorVellumValue'
      - $ref: '#/components/schemas/FunctionCallVellumValue'
      - $ref: '#/components/schemas/ThinkingVellumValue'
      title: PromptOutput
    ArrayEnum:
      type: string
      enum:
      - ARRAY
      title: ArrayEnum
    ArrayChatMessageContentItemRequest:
      oneOf:
      - $ref: '#/components/schemas/StringChatMessageContentRequest'
      - $ref: '#/components/schemas/FunctionCallChatMessageContentRequest'
      - $ref: '#/components/schemas/AudioChatMessageContentRequest'
      - $ref: '#/components/schemas/VideoChatMessageContentRequest'
      - $ref: '#/components/schemas/ImageChatMessageContentRequest'
      - $ref: '#/components/schemas/DocumentChatMessageContentRequest'
      title: ArrayChatMessageContentItemRequest
    StringInputRequest:
      type: object
      properties:
        name:
          type: string
          description: The variable's name
        type:
          $ref: '#/components/schemas/StringEnum'
        value:
          type: string
      required:
      - name
      - type
      - value
      description: A user input representing a string value
      title: StringInputRequest
    VellumErrorCodeEnum:
      type: string
      enum:
      - INVALID_REQUEST
      - INVALID_INPUTS
      - PROVIDER_ERROR
      - PROVIDER_CREDENTIALS_UNAVAILABLE
      - INTEGRATION_CREDENTIALS_UNAVAILABLE
      - REQUEST_TIMEOUT
      - INTERNAL_SERVER_ERROR
      - USER_DEFINED_ERROR
      - WORKFLOW_CANCELLED
      - NODE_CANCELLED
      - PROVIDER_QUOTA_EXCEEDED
      - CHAT_QUOTA_EXCEEDED
      description: '* `INVALID_REQUEST` - INVALID_REQUEST

        * `INVALID_INPUTS` - INVALID_INPUTS

        * `PROVIDER_ERROR` - PROVIDER_ERROR

        * `PROVIDER_CREDENTIALS_UNAVAILABLE` - PROVIDER_CREDENTIALS_UNAVAILABLE

        * `INTEGRATION_CREDENTIALS_UNAVAILABLE` - INTEGRATION_CREDENTIALS_UNAVAILABLE

        * `REQUEST_TIMEOUT` - REQUEST_TIMEOUT

        * `INTERNAL_SERVER_ERROR` - INTERNAL_SERVER_ERROR

        * `USER_DEFINED_ERROR` - USER_DEFINED_ERROR

        * `WORKFLOW_CANCELLED` - WORKFLOW_CANCELLED

        * `NODE_CANCELLED` - NODE_CANCELLED

        * `PROVIDER_QUOTA_EXCEEDED` - PROVIDER_QUOTA_EXCEEDED

        * `CHAT_QUOTA_EXCEEDED` - CHAT_QUOTA_EXCEEDED'
      title: VellumErrorCodeEnum
    FunctionCallEnum:
      type: string
      enum:
      - FUNCTION_CALL
      title: FunctionCallEnum
    JsonVellumValue:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/JsonEnum'
        value:
          oneOf:
          - description: Any type
          - type: 'null'
      required:
      - type
      - value
      description: A value representing a JSON object.
      title: JsonVellumValue
    VellumVideoRequest:
      type: object
      properties:
        src:
          type: string
          description: "The reference to the source data. This can be one of the following formats:\n1. A base64-encoded data URL (e.g., 'data:application/pdf;base64,JVBERi0xLjQKJcfs...').\n2. A url pointing to a file accessible over HTTP or HTTPS.\n3. A reference to a file that's been previously uploaded to Vellum, in the form of 'vellum:uploaded-file:{uploaded_file_id}'.\n    You can use the Uploaded Files API to retrieve the url of the uploaded file given its ID. See https://docs.vellum.ai/developers/client-sdk/uploaded-files/retrieve for details."
        metadata:
          type:
          - object
          - 'null'
          additionalProperties:
            description: Any type
      required:
      - src
      title: VellumVideoRequest
    ErrorVellumValue:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ErrorEnum'
        value:
          oneOf:
          - $ref: '#/components/schemas/VellumError'
          - type: 'null'
      required:
      - type
      - value
      description: A value representing an Error.
      title: ErrorVellumValue
    VideoEnum:
      type: string
      enum:
      - VIDEO
      title: VideoEnum
    ImageInputRequest:
      type: object
      properties:
        name:
          type: string
          description: The variable's name
        type:
          $ref: '#/components/schemas/ImageEnum'
        value:
          $ref: '#/components/schemas/VellumImageRequest'
      required:
      - name
      - type
      - value
      description: A user input representing a Vellum Image value
      title: ImageInputRequest
    ThinkingEnum:
      type: string
      enum:
      - THINKING
      title: ThinkingEnum
    FulfilledEnum:
      type: string
      enum:
      - FULFILLED
      title: FulfilledEnum
    PromptDeploymentExpandMetaRequest:
      type: object
      properties:
        model_name:
          type:
          - boolean
          - 'null'
          description: If enabled, the response will include the model identifier representing the ML Model invoked by the Prompt.
        usage:
          type:
          - boolean
          - 'null'
          description: If enabled, the response will include model host usage tracking. This may increase latency for some model hosts.
        cost:
          type:
          - boolean
          - 'null'
          description: If enabled, the response will include model host cost tracking. This may increase latency for some model hosts.
        finish_reason:
          type:
          - boolean
          - 'null'
          description: If enabled, the response will include the reason provided by the model for why the execution finished.
        latency:
          type:
          - boolean
          - 'null'
          description: If enabled, the response will include the time in nanoseconds it took to execute the Prompt Deployment.
        deployment_release_tag:
          type:
          - boolean
          - 'null'
          description: If enabled, the response will include the release tag of the Prompt Deployment.
        prompt_version_id:
          type:
          - boolean
          - 'null'
          description: If enabled, the response will include the ID of the Prompt Version backing the deployment.
      title: PromptDeploymentExpandMetaRequest
    VellumDocumentRequest:
      type: object
      properties:
        src:
          type: string
          description: "The reference to the source data. This can be one of the following formats:\n1. A base64-encoded data URL (e.g., 'data:application/pdf;base64,JVBERi0xLjQKJcfs...').\n2. A url pointing to a file accessible over HTTP or HTTPS.\n3. A reference to a file that's been previously uploaded to Vellum, in the form of 'vellum:uploaded-file:{uploaded_file_id}'.\n    You can use the Uploaded Files API to retrieve the url of the uploaded file given its ID. See https://docs.vellum.ai/developers/client-sdk/uploaded-files/retrieve for details."
        metadata:
          type:
          - object
          - 'null'
          additionalProperties:
            description: Any type
      required:
      - src
      title: VellumDocumentRequest
    FunctionCallChatMessageContentValueRequest:
      type: object
      properties:
        name:
          type: string
        arguments:
          type: object
          additionalProperties:
            description: Any type
        id:
          type:
          - string
          - 'null'
      required:
      - name
      - arguments
      description: The final resolved function call value.
      title: FunctionCallChatMessageContentValueRequest
    ImageEnum:
      type: string
      enum:
      - IMAGE
      title: ImageEnum
    Price:
      type: object
      properties:
        value:
          type: number
          format: double
        unit:
          $ref: '#/components/schemas/UnitEnum'
      required:
      - value
      - unit
      title: Price
    VellumImageRequest:
      type: object
      properties:
        src:
          type: string
          description: "The reference to the source data. This can be one of the following formats:\n1. A base64-encoded data URL (e.g., 'data:application/pdf;base64,JVBERi0xLjQKJcfs...').\n2. A url pointing to a file accessible over HTTP or HTTPS.\n3. A reference to a file that's been previously uploaded to Vellum, in the form of 'vellum:uploaded-file:{uploaded_file_id}'.\n    You can use the Uploaded Files API to retrieve the url of the uploaded file given its ID. See https://docs.vellum.ai/developers/client-sdk/uploaded-files/retrieve for details."
        metadata:
          type:
          - object
          - 'null'
          additionalProperties:
            description: Any type
      required:
      - src
      title: VellumImageRequest
    JsonEnum:
      type: string
      enum:
      - JSON
      title: JsonEnum
    VideoInputRequest:
      type: object
      properties:
        name:
          type: string
          description: The variable's name
        type:
          $ref: '#/components/schemas/VideoEnum'
        value:
          $ref: '#/components/schemas/VellumVideoRequest'
      required:
      - name
      - type
      - value
      description: A user input representing a Vellum Video value
      title: VideoInputRequest
    ChatMessageContentRequest:
      oneOf:
      - $ref: '#/components/schemas/StringChatMessageContentRequest'
      - $ref: '#/components/schemas/FunctionCallChatMessageContentRequest'
      - $ref: '#/components/schemas/ArrayChatMessageContentRequest'
      - $ref: '#/components/schemas/AudioChatMessageContentRequest'
      - $ref: '#/components/schemas/VideoChatMessageContentRequest'
      - $ref: '#/components/schemas/ImageChatMessageContentRequest'
      - $ref: '#/components/schemas/DocumentChatMessageContentRequest'
      title: ChatMessageContentRequest
    FulfilledExecutePromptResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/PromptExecutionMeta'
        raw:
          type: object
          additionalProperties:
            description: Any type
          description: The subset of the raw response from the model that the request opted into with `expand_raw`.
        execution_id:
          type: string
          description: The ID of the execution.
        state:
          $ref: '#/components/schemas/FulfilledEnum'
        outputs:
          type: array
          items:
            $ref: '#/components/schemas/PromptOutput'
        chat_message_metadata:
          type:
          - object
          - 'null'
          additionalProperties:
            description: Any type
      required:
      - execution_id
      - state
      - outputs
      description: The successful response from the model containing all of the resolved values generated by the prompt.
      title: FulfilledExecutePromptResponse
    ChatMessageRequest:
      type: object
      properties:
        text:
          type:
          - string
          - 'null'
        role:
          $ref: '#/components/schemas/ChatMessageRole'
        content:
          oneOf:
          - $ref: '#/components/schemas/ChatMessageContentRequest'
          - type: 'null'
        source:
          type:
          - string
          - 'null'
          description: An optional identifier representing who or what generated this message.
        metadata:
          type:
          - object
          - 'null'
          additionalProperties:
            description: Any type
      required:
      - role
      title: ChatMessageRequest
    ExecutePromptRequest:
      type: object
      properties:
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/PromptDeploymentInputRequest'
          description: A list consisting of the Prompt Deployment's input variables and their values.
        prompt_deployment_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The ID of the Prompt Deployment. Must provide either this or prompt_deployment_name.
        prompt_deployment_name:
          type:
          - string
          - 'null'
          description: The unique name of the Prompt Deployment. Must provide either this or prompt_deployment_id.
        release_tag:
          type:
          - string
          - 'null'
          description: Optionally specify a release tag if you want to pin to a specific release of the Prompt Deployment
        external_id:
          type:
          - string
          - 'null'
          description: Optionally include a unique identifier for tracking purposes. Must be unique within a given Workspace.
        expand_meta:
          oneOf:
          - $ref: '#/components/schemas/PromptDeploymentExpandMetaRequest'
          - type: 'null'
          description: An optionally specified configuration used to opt in to including additional metadata about this prompt execution in the API response. Corresponding values will be returned under the `meta` key of the API response.
        raw_overrides:
          oneOf:
          - $ref: '#/components/schemas/RawPromptExecutionOverridesRequest'
          - type: 'null'
          description: Overrides for the raw API request sent to the model host. Combined with `expand_raw`, it can be used to access new features from models.
        expand_raw:
          type:
          - array
          - 'null'
          items:
            type: string
          description: A list of keys whose values you'd like to directly return from the JSON response of the model provider. Useful if you need lower-level info returned by model providers that Vellum would otherwise omit. Corresponding key/value pairs will be returned under the `raw` key of the API response.
        metadata:
          type:
          - object
          - 'null'
          additionalProperties:
            description: Any type
          description: Arbitrary JSON metadata associated with this request. Can be used to capture additional monitoring data such as user id, session id, etc. for future analysis.
      required:
      - inputs
      title: ExecutePromptRequest
    VellumError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/VellumErrorCodeEnum'
        message:
          type: string
        raw_data:
          type:
          - object
          - 'null'
          additionalProperties:
            description: Any type
      required:
      - code
      - message
      title: VellumError
    FinishReasonEnum:
      type: string
      enum:
      - LENGTH
      - STOP
      - UNKNOWN
      description: '* `LENGTH` - LENGTH

        * `STOP` - STOP

        * `UNKNOWN` - UNKNOWN'
      title: FinishReasonEnum
    AudioEnum:
      type: string
      enum:
      - AUDIO
      title: AudioEnum
    ChatHistoryInputRequest:
      type: object
      properties:
        name:
          type: string
          description: The variable's name, as defined in the deployment.
        type:
          $ref: '#/components/schemas/ChatHistoryEnum'
        value:
          type: array
          items:
            $ref: '#/components/schemas/ChatMessageRequest'
      required:
      - name
      - type
      - value
      description: A user input representing a list of chat messages
      title: ChatHistoryInputRequest
    ImageChatMessageContentRequest:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ImageEnum'
        value:
          $ref: '#/components/schemas/VellumImageRequest'
      required:
      - type
      - value
      description: An image value that is used in a chat message.
      title: ImageChatMessageContentRequest
    ExecutePromptResponse:
      oneOf:
      - $ref: '#/components/schemas/FulfilledExecutePromptResponse'
      - $ref: '#/components/schemas/RejectedExecutePromptResponse'
      title: ExecutePromptResponse
    ErrorEnum:
      type: string
      enum:
      - ERROR
      title: ErrorEnum
    StringEnum:
      type: string
      enum:
      - STRING
      title: StringEnum
    FunctionCall:
      type: object
      properties:
        arguments:
          type: object
          additionalProperties:
            description: Any type
        id:
          type:
          - string
          - 'null'
        name:
          type: string
      required:
      - arguments
      - name
      description: The final resolved function call value.
      title: FunctionCall
    PromptDeploymentInputRequest:
      oneOf:
      - $ref: '#/components/schemas/StringInputRequest'
      - $ref: '#/components/schemas/JSONInputRequest'
      - $ref: '#/components/schemas/ChatHistoryInputRequest'
      - $ref: '#/components/schemas/AudioInputRequest'
      - $ref: '#/components/schemas/VideoInputRequest'
      - $ref: '#/components/schemas/ImageInputRequest'
      - $ref: '#/components/schemas/DocumentInputRequest'
      title: PromptDeploymentInputRequest
    RawPromptExecutionOverridesRequest:
      type: object
      properties:
        body:
          type:
          - object
          - 'null'
          additionalProperties:
            description: Any type
        headers:
          type:
          - object
          - 'null'
          additionalProperties:
            type: string
          description: The raw headers to send to the model host.
        url:
          type:
          - string
          - 'null'
          description: The raw URL to send to the model host.
      title: RawPromptExecutionOverridesRequest
    DocumentEnum:
      type: string
      enum:
      - DOCUMENT
      title: DocumentEnum
    MLModelUsage:
      type: object
      properties:
        output_token_count:
          type:
          - integer
          - 'null'
        input_token_count:
          type:
          - integer
          - 'null'
        input_char_count:
          type:
          - integer
          - 'null'
        output_char_count:
          type:
          - integer
          - 'null'
        compute_nanos:
          type:
          - integer
          - 'null'
        cache_creation_input_tokens:
          type:
          - integer
          - 'null'
        cache_read_input_tokens:
          type:
          - integer
          - 'null'
      title: MLModelUsage
    FunctionCallChatMessageContentRequest:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/FunctionCallEnum'
        value:
          $ref: '#/components/schemas/FunctionCallChatMessageContentValueRequest'
      required:
      - type
      - value
      description: A function call value that is used in a chat message.
      title: FunctionCallChatMessageContentRequest
    ExecutePromptApiErrorResponse:
      type: object
      properties:
        detail:
          type: string
          description: Details about why the request failed.
        raw_data:
          type:
          - object
          - 'null'
          additionalProperties:
            description: Any type
          description: The raw error data structure, if available.
      required:
      - detail
      title: ExecutePromptApiErrorResponse
    DocumentInputRequest:
      type: object
      properties:
        name:
          type: string
          description: The variable's name
        type:
          $ref: '#/components/schemas/DocumentEnum'
        value:
          $ref: '#/components/schemas/VellumDocumentRequest'
      required:
      - name
      - type
      - value
      description: A user input representing a Vellum Document value
      title: DocumentInputRequest
    ThinkingVellumValue:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ThinkingEnum'
        value:
          oneOf:
          - $ref: '#/components/schemas/StringVellumValue'
          - type: 'null'
      required:
      - type
      - value
      description: A value representing Thinking mode output.
      title: ThinkingVellumValue
    VideoChatMessageContentRequest:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/VideoEnum'
        value:
          $ref: '#/components/schemas/VellumVideoRequest'
      required:
      - type
      - value
      description: A video value that is used in a chat message.
      title: VideoChatMessageContentRequest
  securitySchemes:
    default:
      type: apiKey
      in: header
      name: X-API-KEY