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

# Prompt API

> Learn how to integrate Portkey's prompt templates directly into your applications using the Prompt API

> [!NOTE]
>
> This feature is available on all Portkey [plans](https://portkey.ai/pricing).

The Portkey Prompts API allows you to seamlessly integrate your saved prompts directly into your applications. This powerful feature lets you separate prompt engineering from application code, making both easier to maintain while providing consistent, optimized prompts across your AI applications.

With the Prompt API, you can:

* Use versioned prompts in production applications
* Dynamically populate prompts with variables at runtime
* Override prompt parameters as needed without modifying the original templates
* Retrieve prompt details for use with provider-specific SDKs

## API Endpoints

Portkey offers two primary endpoints for working with saved prompts:

1. **Prompt Completions** (`/prompts/{promptId}/completions`) - Execute your saved prompt templates directly, receiving model completions
2. **Prompt Render** (`/prompts/{promptId}/render`) - Retrieve your prompt template with variables populated, without executing it

## Prompt Completions

The Completions endpoint is the simplest way to use your saved prompts in production. It handles the entire process - retrieving the prompt, applying variables, sending it to the appropriate model, and returning the completion.

### Making a Completion Request

> [tab] Python SDK
>
> ```python theme={"system"}
> from portkey_ai import Portkey
>
> portkey = Portkey(
>   api_key="PORTKEY_API_KEY"
> )
>
> # Execute the prompt with provided variables
> completion = portkey.prompts.completions.create(
>     prompt_id="YOUR_PROMPT_ID",
>     variables={
>         "user_input": "Hello world"
>     },
>     max_tokens=250,
>     presence_penalty=0.2
> )
>
> print(completion)
> ```

> [tab] NodeJS SDK
>
> ```javascript theme={"system"}
> import Portkey from 'portkey-ai';
>
> const portkey = new Portkey({
>     apiKey: "PORTKEY_API_KEY"
> });
>
> // Execute the prompt with provided variables
> const completion = await portkey.prompts.completions.create({
>     promptID: "YOUR_PROMPT_ID",
>     variables: {
>         "user_input": "Hello world"
>     },
>     max_tokens: 250,
>     presence_penalty: 0.2
> });
>
> console.log(completion);
> ```

> [tab] cURL
>
> ```bash theme={"system"}
> curl -X POST "https://api.portkey.ai/v1/prompts/YOUR_PROMPT_ID/completions" \
>   -H "Content-Type: application/json" \
>   -H "x-portkey-api-key: $PORTKEY_API_KEY" \
>   -d '{
>     "variables": {
>       "user_input": "Hello world"
>     },
>     "max_tokens": 250,
>     "presence_penalty": 0.2
>   }'
> ```

### Streaming Support

The completions endpoint also supports streaming responses for real-time interactions:

> [tab] NodeJS SDK
>
> ```javascript theme={"system"}
> import Portkey from 'portkey-ai';
>
> const portkey = new Portkey({
>     apiKey: "PORTKEY_API_KEY"
> });
>
> // Create a streaming completion
> const streamCompletion = await portkey.prompts.completions.create({
>     promptID: "YOUR_PROMPT_ID",
>     variables: {
>         "user_input": "Hello world"
>     },
>     stream: true
> });
>
> // Process the stream
> for await (const chunk of streamCompletion) {
>     console.log(chunk);
> }
> ```

> [tab] Python SDK
>
> ```python theme={"system"}
> from portkey_ai import Portkey
>
> portkey = Portkey(
>   api_key="PORTKEY_API_KEY"
> )
>
> # Create a streaming completion
> completion = portkey.prompts.completions.create(
>     prompt_id="YOUR_PROMPT_ID",
>     variables={
>         "user_input": "Hello world"
>     },
>     stream=True
> )
>
> # Process the stream
> for chunk in completion:
>     print(chunk)
> ```

## Prompt Render

You can retrieve your saved prompts on Portkey using the `/prompts/$PROMPT_ID/render` endpoint. Portkey returns a JSON containing your prompt or messages body along with all the saved parameters that you can directly use in any request.

This is helpful if you are required to use provider SDKs and can not use the Portkey SDK in production. ([Example of how to use Portkey prompt templates with OpenAI SDK](https://docs.portkey.ai/docs/product/prompt-library/retrieve-prompts.md#using-the-render-output-in-a-new-request))

## Using the `Render` Endpoint/Method

1. Make a request to `https://api.portkey.ai/v1/prompts/$PROMPT_ID/render` with your prompt ID
2. Pass your Portkey API key with `x-portkey-api-key` in the header
3. Send up the variables in your payload with `{ "variables": { "VARIABLE_NAME": "VARIABLE_VALUE" } }`

That's it! See it in action:

> [tab] cURL
>
> ```sh theme={"system"}
> curl -X POST "https://api.portkey.ai/v1/prompts/$PROMPT_ID/render" \
> -H "Content-Type: application/json" \
> -H "x-portkey-api-key: $PORTKEY_API_KEY" \
> -d '{
>   "variables": {"movie":"Dune 2"}
> }'
> ```
>
> The Output:
>
> ```JSON theme={"system"}
> {
>     "success": true,
>     "data": {
>         "model": "gpt-4",
>         "n": 1,
>         "top_p": 1,
>         "max_tokens": 256,
>         "temperature": 0,
>         "presence_penalty": 0,
>         "frequency_penalty": 0,
>         "messages": [
>             {
>                 "role": "system",
>                 "content": "You're a helpful assistant."
>             },
>             {
>                 "role": "user",
>                 "content": "Who directed Dune 2?"
>             }
>         ]
>     }
> }
> ```

> [tab] Portkey Python SDK
>
> ```py theme={"system"}
> from portkey_ai import Portkey
>
> portkey = Portkey(
>   api_key="PORTKEY_API_KEY"
> )
>
> render = portkey.prompts.render(
>   prompt_id="PROMPT_ID",
>   variables={ "movie":"Dune 2" }
> )
>
> print(render.data)
> ```
>
> The Output:
>
> ```JSON theme={"system"}
> {
>     "model": "gpt-4",
>     "n": 1,
>     "top_p": 1,
>     "max_tokens": 256,
>     "temperature": 0,
>     "presence_penalty": 0,
>     "frequency_penalty": 0,
>     "messages": [
>         {
>             "role": "system",
>             "content": "You're a helpful assistant."
>         },
>         {
>             "role": "user",
>             "content": "Who directed Dune 2?"
>         }
>     ]
> }
> ```

> [tab] Portkey Node SDK
>
> ```js theme={"system"}
> import Portkey from 'portkey-ai'
>
> const portkey = new Portkey({
>     apiKey: "PORTKEY_API_KEY"
> })
>
> async function getRender(){
>     const render = await portkey.prompts.render({
>         promptID: "PROMPT_ID",
>         variables: { "movie":"Dune 2" }
>     })
>
>     console.log(render.data)
> }
>
> getRender()
> ```
>
> The Output:
>
> ```JSON theme={"system"}
> {
>     "model": "gpt-4",
>     "n": 1,
>     "top_p": 1,
>     "max_tokens": 256,
>     "temperature": 0,
>     "presence_penalty": 0,
>     "frequency_penalty": 0,
>     "messages": [
>         {
>             "role": "system",
>             "content": "You're a helpful assistant."
>         },
>         {
>             "role": "user",
>             "content": "Who directed Dune 2?"
>         }
>     ]
> }
> ```

## Updating Prompt Params While Retrieving the Prompt

If you want to change any model params (like `temperature`, `messages body` etc) while retrieving your prompt from Portkey, you can send the override params in your `render` payload.

Portkey will send back your prompt with overridden params, **without** making any changes to the saved prompt on Portkey.

> [tab] cURL
>
> ```sh theme={"system"}
> curl -X POST "https://api.portkey.ai/v1/prompts/$PROMPT_ID/render" \
> -H "Content-Type: application/json" \
> -H "x-portkey-api-key: $PORTKEY_API_KEY" \
> -d '{
>  "variables": {"movie":"Dune 2"},
>  "model": "gpt-3.5-turbo",
>  "temperature": 2
> }'
> ```
>
> Based on the above snippet, `model` and `temperature` params in the retrieved prompt will be **overridden** with the newly passed values
>
> The New Output:
>
> ```JSON theme={"system"}
> {
>     "success": true,
>     "data": {
>         "model": "gpt-3.5-turbo",
>         "n": 1,
>         "top_p": 1,
>         "max_tokens": 256,
>         "temperature": 2,
>         "presence_penalty": 0,
>         "frequency_penalty": 0,
>         "messages": [
>             {
>                 "role": "system",
>                 "content": "You're a helpful assistant."
>             },
>             {
>                 "role": "user",
>                 "content": "Who directed Dune 2?"
>             }
>         ]
>     }
> }
> ```

> [tab] Python SDK
>
> ```py theme={"system"}
> from portkey_ai import Portkey
>
> portkey = Portkey(
>   api_key="PORTKEY_API_KEY"
> )
>
> render = portkey.prompts.render(
>   prompt_id="PROMPT_ID",
>   variables={ "movie":"Dune 2" },
>   model="gpt-3.5-turbo",
>   temperature=2
> )
>
> print(render.data)
> ```
>
> Based on the above snippet, `model` and `temperature` params in the retrieved prompt will be **overridden** with the newly passed values.
>
> **The New Output:**
>
> ```JSOn theme={"system"}
> {
>     "model": "gpt-3.5-turbo",
>     "n": 1,
>     "top_p": 1,
>     "max_tokens": 256,
>     "temperature": 2,
>     "presence_penalty": 0,
>     "frequency_penalty": 0,
>     "messages": [
>         {
>             "role": "system",
>             "content": "You're a helpful assistant."
>         },
>         {
>             "role": "user",
>             "content": "Who directed Dune 2?"
>         }
>     ]
> }
> ```

> [tab] NodeJS SDK
>
> ```js theme={"system"}
> import Portkey from 'portkey-ai'
>
> const portkey = new Portkey({
>     apiKey: "PORTKEY_API_KEY"
> })
>
> async function getRender(){
>     const render = await portkey.prompts.render({
>         promptID: "PROMPT_ID",
>         variables: { "movie":"Dune 2" },
>         model: "gpt-3.5-turbo",
>         temperature: 2
>     })
>
>     console.log(render.data)
> }
>
> getRender()
> ```
>
> Based on the above snippet, `model` and `temperature` params in the retrieved prompt will be **overridden** with the newly passed values.
>
> **The New Output:**
>
> ```JSON theme={"system"}
> {
>     "model": "gpt-3.5-turbo",
>     "n": 1,
>     "top_p": 1,
>     "max_tokens": 256,
>     "temperature": 2,
>     "presence_penalty": 0,
>     "frequency_penalty": 0,
>     "messages": [
>         {
>             "role": "system",
>             "content": "You're a helpful assistant."
>         },
>         {
>             "role": "user",
>             "content": "Who directed Dune 2?"
>         }
>     ]
> }
> ```

## Using the `render` Output in a New Request

Here's how you can take the output from the `render` API and use it for making a call. We'll take example of OpenAI SDKs, but you can use it simlarly for any other provider SDK as well.

> [tab] OpenAI NodeJS
>
> ```js theme={"system"}
> 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();
> ```

> [tab] OpenAI Python
>
> ```py theme={"system"}
> 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)
> ```

# Create Prompt via API

You can create and manage prompt templates programmatically using the Portkey Admin API. This is the recommended approach when you need structural Mustache templates (section blocks like `{{#var}}...{{/var}}` that conditionally include entire JSON objects), which cannot be created through the UI's Pretty Mode editor.

## The `is_raw_template` field

| Value | Behaviour |
| - | - |
| `0` (default) | Portkey treats the `string` field as structured messages. Variables (`{{var}}`) inside string values work normally. |
| `1` | Portkey runs Mustache rendering on the raw `string` first, then parses the result as JSON. Required when section blocks span JSON structure (e.g. a conditional `image_url` content block). |

## Creating a Prompt

> [tab] cURL
>
> ```bash theme={"system"}
> curl --request POST \
>   --url https://api.portkey.ai/v1/prompts \
>   --header 'Content-Type: application/json' \
>   --header 'x-portkey-api-key: $PORTKEY_API_KEY' \
>   --data '{
>     "collection_id": "YOUR_COLLECTION_ID",
>     "name": "vision-conditional-prompt",
>     "model": "YOUR_MODEL",
>     "parameters": {
>       "max_tokens": 512,
>       "temperature": 0.5,
>       "top_p": 0.9,
>       "n": 1,
>       "stream": true
>     },
>     "string": "[{\"role\":\"user\",\"content\":[{\"type\":\"text\",\"text\":\"{{user_prompt}}\"}{{#has_image}},{\"type\":\"image_url\",\"image_url\":{\"url\":\"{{image_url}}\"}}{{/has_image}},{\"type\":\"text\",\"text\":\"Please analyze accordingly.\"}]}]",
>     "is_raw_template": 1,
>     "virtual_key": "YOUR_VIRTUAL_KEY",
>     "version_description": "Conditional vision prompt with Mustache section",
>     "template_metadata": {
>       "template_type": "chat"
>     }
>   }'
> ```

> [tab] Python SDK
>
> ```python theme={"system"}
> import requests
>
> response = requests.post(
>     "https://api.portkey.ai/v1/prompts",
>     headers={
>         "Content-Type": "application/json",
>         "x-portkey-api-key": "PORTKEY_API_KEY"
>     },
>     json={
>         "collection_id": "YOUR_COLLECTION_ID",
>         "name": "vision-conditional-prompt",
>         "model": "YOUR_MODEL",
>         "parameters": {
>             "max_tokens": 512,
>             "temperature": 0.5,
>             "top_p": 0.9,
>             "n": 1,
>             "stream": True
>         },
>         "string": '[{"role":"user","content":[{"type":"text","text":"{{user_prompt}}"}{{#has_image}},{"type":"image_url","image_url":{"url":"{{image_url}}"}}{{/has_image}},{"type":"text","text":"Please analyze accordingly."}]}]',
>         "is_raw_template": 1,
>         "virtual_key": "YOUR_VIRTUAL_KEY",
>         "version_description": "Conditional vision prompt with Mustache section",
>         "template_metadata": {"template_type": "chat"}
>     }
> )
>
> prompt_id = response.json()["id"]
> print(prompt_id)
> ```

A successful response returns the prompt `id` and `slug`:

```json theme={"system"}
{
  "id": "PROMPT_UUID",
  "slug": "pp-vision-conditional-XXXXXX",
  "version_id": "VERSION_UUID",
  "object": "prompt"
}
```

Use the returned `id` or `slug` to call the prompt via the [Completions](https://docs.portkey.ai/docs/product/prompt-engineering-studio/prompt-api.md#prompt-completions) or [Render](https://docs.portkey.ai/docs/product/prompt-engineering-studio/prompt-api.md#prompt-render) endpoints.

## API Reference

For complete API details, including all available parameters and response formats, refer to the API reference documentation:

* [Prompt Completions API Reference](https://portkey.ai/docs/api-reference/inference-api/prompts/prompt-completion)
* [Prompt Render API Reference](https://portkey.ai/docs/api-reference/inference-api/prompts/render)

## Next Steps

Now that you understand how to integrate prompts into your applications, explore these related features:

* [Prompt Playground](https://docs.portkey.ai/docs/product/prompt-engineering-studio/prompt-playground.md) - Create and test prompts in an interactive environment
* [Prompt Versioning](https://docs.portkey.ai/docs/product/prompt-engineering-studio/prompt-versioning.md) - Track changes to your prompts over time
* [Prompt Observability](https://docs.portkey.ai/docs/product/prompt-engineering-studio/prompt-observability.md) - Monitor prompt performance in production

***

> [card] [Portkey is now PRISMA AIRS AI Gateway. See it in action.](https://www.paloaltonetworks.in/ai-security/ai-gateway?utm_source=portkey\&utm_medium=referral\&utm_campaign=prisma_airs\&utm_content=docs_nav#contact)
>
> Contact Us


## Related topics

- [Prompt Engineering Studio](https://docs.portkey.ai/docs/product/prompt-engineering-studio.md)
- [Prompt Library](https://docs.portkey.ai/docs/product/prompt-engineering-studio/prompt-library.md)
- [Prompt Partials](https://docs.portkey.ai/docs/product/prompt-engineering-studio/prompt-partial.md)
- [Prompt Observability](https://docs.portkey.ai/docs/product/prompt-engineering-studio/prompt-observability.md)
- [Prompt Render](https://docs.portkey.ai/docs/api-reference/inference-api/prompts/render.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.