> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.vellum.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.vellum.ai/_mcp/server.

# Retrieve Provider Payload

POST https://api.vellum.ai/v1/deployments/provider-payload
Content-Type: application/json

Given a set of input variable values, compile the exact payload that Vellum would send to the configured model provider
for execution if the execute-prompt endpoint had been invoked. Note that this endpoint does not actually execute the
prompt or make an API call to the model provider.

This endpoint is useful if you don't want to proxy LLM provider requests through Vellum and prefer to send them directly
to the provider yourself. Note that no guarantees are made on the format of this API's response schema, other than
that it will be a valid payload for the configured model provider. It's not recommended that you try to parse or
derive meaning from the response body and instead, should simply pass it directly to the model provider as is.

We encourage you to seek advise from Vellum Support before integrating with this API for production use.


Reference: https://docs.vellum.ai/developers/client-sdk/prompts/retrieve-provider-payload

## Authentication

- `X-API-KEY` header (required) — API Key authentication via header

## Request

### Body (application/json)

This endpoint expects a DeploymentProviderPayloadRequest.

- `inputs` (list of PromptDeploymentInputRequest, required) — The list of inputs defined in the Prompt's deployment with their corresponding values.
- `deployment_id` (string, optional, nullable) — The ID of the deployment. Must provide either this or deployment_name.
- `deployment_name` (string, optional, nullable) — The name of the deployment. Must provide either this or deployment_id.
- `release_tag` (string, optional, nullable) — Optionally specify a release tag if you want to pin to a specific release of the Workflow Deployment
- `expand_meta` (CompilePromptDeploymentExpandMetaRequest, optional, nullable)

## Response

### 200

- `payload` (DeploymentProviderPayloadResponsePayload, required)
- `meta` (CompilePromptMeta, required, nullable) — The subset of the metadata tracked by Vellum during Prompt Deployment compilation that the request opted into with `expand_meta`.

## Errors

### 400 Bad Request Error

- `detail` (string, required) — Details about why the request failed.
- `raw_data` (map from string to any, optional, nullable) — The raw error data structure, if available.

### 403 Forbidden Error

- `detail` (string, required) — Details about why the request failed.
- `raw_data` (map from string to any, optional, nullable) — The raw error data structure, if available.

### 404 Not Found Error

- `detail` (string, required) — Details about why the request failed.
- `raw_data` (map from string to any, optional, nullable) — The raw error data structure, if available.

### 500 Internal Server Error

- `detail` (string, required) — Details about why the request failed.
- `raw_data` (map from string to any, optional, nullable) — The raw error data structure, if available.

## Types

### PromptDeploymentInputRequest

### CompilePromptDeploymentExpandMetaRequest

- `model_name` (boolean, optional, nullable) — If enabled, the response will include the model identifier representing the ML Model invoked by the Prompt.
- `deployment_release_tag` (boolean, optional, nullable) — If enabled, the response will include the release tag of the Prompt Deployment.
- `prompt_version_id` (boolean, optional, nullable) — If enabled, the response will include the ID of the Prompt Version backing the deployment.

### DeploymentProviderPayloadResponsePayload

### CompilePromptMeta

The subset of the metadata tracked by Vellum during Prompt Deployment compilation that the request opted into with `expand_meta`.

- `model_name` (string, optional, nullable)
- `deployment_release_tag` (string, optional, nullable)
- `prompt_version_id` (string, optional, nullable)

### StringInputRequest

A user input representing a string value

- `name` (string, required) — The variable's name
- `type` (enum, required)
  - Allowed values: `STRING`
- `value` (string, required)

### JSONInputRequest

A user input representing a JSON object

- `name` (string, required) — The variable's name
- `type` (enum, required)
  - Allowed values: `JSON`
- `value` (any, required, nullable)

### ChatHistoryInputRequest

A user input representing a list of chat messages

- `name` (string, required) — The variable's name, as defined in the deployment.
- `type` (enum, required)
  - Allowed values: `CHAT_HISTORY`
- `value` (list of ChatMessageRequest, required)

### AudioInputRequest

A user input representing a Vellum Audio value

- `name` (string, required) — The variable's name
- `type` (enum, required)
  - Allowed values: `AUDIO`
- `value` (VellumAudioRequest, required)

### VideoInputRequest

A user input representing a Vellum Video value

- `name` (string, required) — The variable's name
- `type` (enum, required)
  - Allowed values: `VIDEO`
- `value` (VellumVideoRequest, required)

### ImageInputRequest

A user input representing a Vellum Image value

- `name` (string, required) — The variable's name
- `type` (enum, required)
  - Allowed values: `IMAGE`
- `value` (VellumImageRequest, required)

### DocumentInputRequest

A user input representing a Vellum Document value

- `name` (string, required) — The variable's name
- `type` (enum, required)
  - Allowed values: `DOCUMENT`
- `value` (VellumDocumentRequest, required)

### ChatMessageRequest

- `role` (enum, required) — * `SYSTEM` - System * `ASSISTANT` - Assistant * `USER` - User * `FUNCTION` - Function
  - Allowed values: `SYSTEM`, `ASSISTANT`, `USER`, `FUNCTION`
- `text` (string, optional, nullable)
- `content` (ChatMessageContentRequest, optional, nullable)
- `source` (string, optional, nullable) — An optional identifier representing who or what generated this message.
- `metadata` (map from string to any, optional, nullable)

### VellumAudioRequest

- `src` (string, required) — The reference to the source data. This can be one of the following formats: 1. A base64-encoded data URL (e.g., 'data:application/pdf;base64,JVBERi0xLjQKJcfs...'). 2. A url pointing to a file accessible over HTTP or HTTPS. 3. A reference to a file that's been previously uploaded to Vellum, in the form of 'vellum:uploaded-file:\{uploaded\_file\_id}'. 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](https://docs.vellum.ai/developers/client-sdk/uploaded-files/retrieve) for details.
- `metadata` (map from string to any, optional, nullable)

### VellumVideoRequest

- `src` (string, required) — The reference to the source data. This can be one of the following formats: 1. A base64-encoded data URL (e.g., 'data:application/pdf;base64,JVBERi0xLjQKJcfs...'). 2. A url pointing to a file accessible over HTTP or HTTPS. 3. A reference to a file that's been previously uploaded to Vellum, in the form of 'vellum:uploaded-file:\{uploaded\_file\_id}'. 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](https://docs.vellum.ai/developers/client-sdk/uploaded-files/retrieve) for details.
- `metadata` (map from string to any, optional, nullable)

### VellumImageRequest

- `src` (string, required) — The reference to the source data. This can be one of the following formats: 1. A base64-encoded data URL (e.g., 'data:application/pdf;base64,JVBERi0xLjQKJcfs...'). 2. A url pointing to a file accessible over HTTP or HTTPS. 3. A reference to a file that's been previously uploaded to Vellum, in the form of 'vellum:uploaded-file:\{uploaded\_file\_id}'. 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](https://docs.vellum.ai/developers/client-sdk/uploaded-files/retrieve) for details.
- `metadata` (map from string to any, optional, nullable)

### VellumDocumentRequest

- `src` (string, required) — The reference to the source data. This can be one of the following formats: 1. A base64-encoded data URL (e.g., 'data:application/pdf;base64,JVBERi0xLjQKJcfs...'). 2. A url pointing to a file accessible over HTTP or HTTPS. 3. A reference to a file that's been previously uploaded to Vellum, in the form of 'vellum:uploaded-file:\{uploaded\_file\_id}'. 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](https://docs.vellum.ai/developers/client-sdk/uploaded-files/retrieve) for details.
- `metadata` (map from string to any, optional, nullable)

### ChatMessageContentRequest

### StringChatMessageContentRequest

A string value that is used in a chat message.

- `type` (enum, required)
  - Allowed values: `STRING`
- `value` (string, required)

### FunctionCallChatMessageContentRequest

A function call value that is used in a chat message.

- `type` (enum, required)
  - Allowed values: `FUNCTION_CALL`
- `value` (FunctionCallChatMessageContentValueRequest, required) — The final resolved function call value.

### ArrayChatMessageContentRequest

A list of chat message content items.

- `type` (enum, required)
  - Allowed values: `ARRAY`
- `value` (list of ArrayChatMessageContentItemRequest, required)

### AudioChatMessageContentRequest

An audio value that is used in a chat message.

- `type` (enum, required)
  - Allowed values: `AUDIO`
- `value` (VellumAudioRequest, required)

### VideoChatMessageContentRequest

A video value that is used in a chat message.

- `type` (enum, required)
  - Allowed values: `VIDEO`
- `value` (VellumVideoRequest, required)

### ImageChatMessageContentRequest

An image value that is used in a chat message.

- `type` (enum, required)
  - Allowed values: `IMAGE`
- `value` (VellumImageRequest, required)

### DocumentChatMessageContentRequest

A document value that is used in a chat message.

- `type` (enum, required)
  - Allowed values: `DOCUMENT`
- `value` (VellumDocumentRequest, required)

### FunctionCallChatMessageContentValueRequest

The final resolved function call value.

- `name` (string, required)
- `arguments` (map from string to any, required)
- `id` (string, optional, nullable)

### ArrayChatMessageContentItemRequest

## Examples

**Request**

```json
{
  "inputs": [
    {
      "name": "string",
      "type": "STRING",
      "value": "string"
    }
  ]
}
```

**Response**

```json
{
  "payload": {},
  "meta": {
    "model_name": "string",
    "deployment_release_tag": "string",
    "prompt_version_id": "string"
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.vellum.ai/v1/deployments/provider-payload"

payload = { "inputs": [
        {
            "name": "string",
            "type": "STRING",
            "value": "string"
        }
    ] }
headers = {
    "X-API-KEY": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```typescript
import { VellumClient } from "vellum-ai";

const client = new VellumClient({ apiKey: "YOUR_API_KEY", apiVersion: "YOUR_API_VERSION" });
await client.deployments.retrieveProviderPayload({
    inputs: [{
            name: "x",
            type: "STRING",
            value: "value"
        }, {
            name: "x",
            type: "STRING",
            value: "value"
        }]
});

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vellum.ai/v1/deployments/provider-payload"

	payload := strings.NewReader("{\n  \"inputs\": [\n    {\n      \"name\": \"string\",\n      \"type\": \"STRING\",\n      \"value\": \"string\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.vellum.ai/v1/deployments/provider-payload")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"inputs\": [\n    {\n      \"name\": \"string\",\n      \"type\": \"STRING\",\n      \"value\": \"string\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.vellum.ai/v1/deployments/provider-payload")
  .header("X-API-KEY", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"inputs\": [\n    {\n      \"name\": \"string\",\n      \"type\": \"STRING\",\n      \"value\": \"string\"\n    }\n  ]\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.vellum.ai/v1/deployments/provider-payload', [
  'body' => '{
  "inputs": [
    {
      "name": "string",
      "type": "STRING",
      "value": "string"
    }
  ]
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'X-API-KEY' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.vellum.ai/v1/deployments/provider-payload");
var request = new RestRequest(Method.POST);
request.AddHeader("X-API-KEY", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"inputs\": [\n    {\n      \"name\": \"string\",\n      \"type\": \"STRING\",\n      \"value\": \"string\"\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "X-API-KEY": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = ["inputs": [
    [
      "name": "string",
      "type": "STRING",
      "value": "string"
    ]
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.vellum.ai/v1/deployments/provider-payload")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```