Prompt Completions

Execute your saved prompt templates on Portkey

Portkey Prompts API completely follows OpenAI’s format for both requests and responses, making it a drop-in replacement existing for your existing Chat or Completions calls.

Features

Send Variables

Create your Propmt Template on Portkey UI, define variables, and pass them with this API:

String Variables

cURL

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": {
      "joke_topic": "elections",
      "humor_level": "10"
    }
  }'

from portkey_ai import Portkey

client = Portkey(
    api_key="PORTKEY_API_KEY"
)

completion = client.prompts.completions.create(
    prompt_id="YOUR_PROMPT_ID",
    variables={
        "joke_topic": "elections",
        "humor_level": "10"
    }
)

import Portkey from 'portkey-ai';

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

const completion = await portkey.prompts.completions.create({
  promptId: "YOUR_PROMPT_ID",
  variables: {
    "joke_topic": "elections",
    "humor_level": "10"
  }
});

JSON Variables

When passing JSON data with variables, stringify the value before sending.

cURL

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_data": "{\"name\":\"John\",\"preferences\":{\"topic\":\"AI\",\"format\":\"brief\"}}"
    }
  }'

import json

user_data = json.dumps({
    "name": "John",
    "preferences": {
        "topic": "AI",
        "format": "brief"
    }
})

completion = client.prompts.completions.create(
    prompt_id="YOUR_PROMPT_ID",
    variables={
        "user_data": user_data
    }
)

const userData = JSON.stringify({
  name: "John",
  preferences: {
    topic: "AI",
    format: "brief"
  }
});

const completion = await portkey.prompts.completions.create({
  promptId: "YOUR_PROMPT_ID",
  variables: {
    user_data: userData
  }
});

Override Prompt Settings

You can override any model hyperparameter saved in the prompt template by sending its new value at the time of making a request:

cURL

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"
    },
    "temperature": 0.7,
    "max_tokens": 250,
    "presence_penalty": 0.2
  }'

completion = client.prompts.completions.create(
    prompt_id="YOUR_PROMPT_ID",
    variables={
        "user_input": "Hello world"
    },
    temperature=0.7,
    max_tokens=250,
    presence_penalty=0.2
)

const completion = await portkey.prompts.completions.create({
  promptId: "YOUR_PROMPT_ID",
  variables: {
    user_input: "Hello world"
  },
  temperature: 0.7,
  max_tokens: 250,
  presence_penalty: 0.2
});

Call Specific Prompt Version

Passing the {promptId} always calls the Published version of your prompt.

But, you can also call a specific template version by appending its version number, like {promptId@12}:

Version Tags:

• @latest: Calls the most recent version
• @{NUMBER} (like @12): Calls the specified version number
• No Suffix: Here, Portkey defaults to the Published version

cURL

curl -X POST "https://api.portkey.ai/v1/prompts/PROMPT_ID@12/completions" \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -d '{
    "variables": {
      "user_input": "Hello world"
    }
  }'

completion = client.prompts.completions.create(
    prompt_id="PROMPT_ID@12", # PROMPT_ID@latest will call the latest version
    variables={
        "user_input": "Hello world"
    }
)

const completion = await portkey.prompts.completions.create({
  promptId: "PROMPT_ID@12", // PROMPT_ID@latest will call the latest version
  variables: {
    user_input: "Hello world"
  }
});

Streaming

Prompts API also supports streaming responses, and completely follows the OpenAI schema.

• Set stream:True explicitly in your request to enable streaming

cURL

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"
    },
    "stream": true
    "max_tokens": 250,
    "presence_penalty": 0.2
  }'

completion = client.prompts.completions.create(
    prompt_id="YOUR_PROMPT_ID",
    variables={"user_input": "Hello"},
    stream=True
)

for chunk in completion:
    print(chunk.choices[0].delta)

const completion = await portkey.prompts.completions.create({
  promptId: "YOUR_PROMPT_ID",
  variables: {
    user_input: "Hello"
  },
  stream: true
});

for await (const chunk of completion) {
  console.log(chunk.choices[0].delta.content);
}