Prompt Render

Renders a prompt template with its variable values filled in

POST /prompts/{promptId}/render

cURL

Default

curl -X POST "https://api.portkey.ai/v1/prompts/YOUR_PROMPT_ID/render" \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -d '{
    "variables": {
      "user_input": "Hello world"
    },
    "max_completion_tokens": 250,
    "presence_penalty": 0.2
  }'

200

{
  "success": true,
  "data": {
    "messages": [
      {
        "content": "<string>",
        "role": "system",
        "name": "<string>"
      }
    ],
    "model": "gpt-5",
    "frequency_penalty": 0,
    "logit_bias": null,
    "logprobs": false,
    "top_logprobs": 10,
    "max_tokens": 123,
    "max_completion_tokens": 123,
    "n": 1,
    "presence_penalty": 0,
    "response_format": {
      "type": "text"
    },
    "seed": 0,
    "stop": "<string>",
    "stream": false,
    "stream_options": null,
    "thinking": {
      "type": "enabled",
      "budget_tokens": 2030
    },
    "temperature": 1,
    "top_p": 1,
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "<string>",
          "description": "<string>",
          "parameters": {},
          "strict": false
        }
      }
    ],
    "parallel_tool_calls": true,
    "user": "user-1234",
    "functions": [
      {
        "name": "<string>",
        "description": "<string>",
        "parameters": {}
      }
    ]
  }
}

Given a prompt ID, variable values, and optionally any hyperparameters, this API returns a JSON object containing the raw prompt template.

Note: Unlike inference requests, Prompt Render API calls are processed through Portkey’s Control Plane services.

Example: Using Prompt Render output in a new request

Here’s how you can take the output from the render API and use it for making a separate LLM call. We’ll take example of OpenAI SDKs, but you can use it simlarly for any other frameworks like Langchain etc. as well.

OpenAI Python

from portkey_ai import Portkey
from openai import OpenAI

# Retrieving the Prompt from Portkey

portkey = Portkey(
  api_key="PORTKEY_API_KEY"
)

render_response = portkey.prompts.render(
  prompt_id="PROMPT_ID",
  variables={ "movie":"Dune 2" }
)

PROMPT_TEMPLATE = render_response.data

# Making a Call to OpenAI with the Retrieved Prompt

openai = OpenAI(
    api_key = "OPENAI_API_KEY",
    base_url = "https://api.portkey.ai/v1",
    default_headers = {
      'x-portkey-provider': 'openai',
      'x-portkey-api-key': 'PORTKEY_API_KEY',
      'Content-Type': 'application/json',
    }
)

chat_complete = openai.chat.completions.create(**PROMPT_TEMPLATE)

print(chat_complete.choices[0].message.content)

import Portkey from 'portkey-ai';
import OpenAI from 'openai';

// Retrieving the Prompt from Portkey

const portkey = new Portkey({
    apiKey: "PORTKEY_API_KEY"
})

async function getPromptTemplate() {
    const render_response = await portkey.prompts.render({
        promptID: "PROMPT_ID",
        variables: { "movie":"Dune 2" }
    })
    return render_response.data;
}

// Making a Call to OpenAI with the Retrieved Prompt

const openai = new OpenAI({
    apiKey: 'OPENAI_API_KEY',
    baseURL: 'https://api.portkey.ai/v1',
    defaultHeaders: {
      'x-portkey-provider': 'openai',
      'x-portkey-api-key': 'PORTKEY_API_KEY',
      'Content-Type': 'application/json',
    }
});

async function main() {
    const PROMPT_TEMPLATE = await getPromptTemplate();
    const chatCompletion = await openai.chat.completions.create(PROMPT_TEMPLATE);
    console.log(chatCompletion.choices[0]);
}

main();

Authorizations

x-portkey-api-key · string · header · required

Path Parameters

promptId · string · required

The unique identifier of the prompt template to render

Body

application/json

Note: Although hyperparameters are shown grouped here (like messages, max_completion_tokens, temperature, etc.), they should only be passed at the root level, alongside 'variables' and 'stream'. The max_tokens parameter is deprecated — use max_completion_tokens instead.

variables · object · required

Variables to substitute in the prompt template

hyperparameters · Chat Completions · object

Note: All hyperparameters are optional. Pass them at the root level, and not nested under hyperparameters. Their grouping here is for educational purposes only.

Chat Completions

Completions

Show child attributes

Response

200 - application/json

Successful rendered prompt

success · boolean · required

Indicates if the render was successful

data · Chat Completions · object · required

Chat Completions

Completions

Show child attributes