Prompt Completions

Execute your saved prompt templates on Portkey

POST /prompts/{promptId}/completions

cURL

Default

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

200

{
  "status": "<string>",
  "headers": {},
  "body": {
    "id": "<string>",
    "choices": [
      {
        "index": 123,
        "message": {
          "content": "<string>",
          "role": "assistant",
          "tool_calls": [
            {
              "id": "<string>",
              "type": "function",
              "function": {
                "name": "<string>",
                "arguments": "<string>"
              }
            }
          ],
          "function_call": {
            "arguments": "<string>",
            "name": "<string>"
          },
          "content_blocks": [
            {
              "type": "text",
              "text": "<string>"
            }
          ]
        },
        "logprobs": {
          "content": [
            {
              "token": "<string>",
              "logprob": 123,
              "bytes": [
                123
              ],
              "top_logprobs": [
                {
                  "token": "<string>",
                  "logprob": 123,
                  "bytes": [
                    123
                  ]
                }
              ]
            }
          ]
        }
      }
    ],
    "created": 123,
    "model": "<string>",
    "object": "chat.completion",
    "system_fingerprint": "<string>",
    "usage": {
      "completion_tokens": 123,
      "prompt_tokens": 123,
      "total_tokens": 123,
      "completion_tokens_details": {
        "reasoning_tokens": 123,
        "accepted_prediction_tokens": 123,
        "rejected_prediction_tokens": 123
      },
      "prompt_tokens_details": {
        "cached_tokens": 123
      }
    }
  }
}

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);
}

Authorizations

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

Path Parameters

promptId · string · required

The unique identifier of the prompt template to use

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

stream · boolean · default: false

Default: False. Set to True if you want to stream the response

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 completion response

status · string

Response status

headers · object

Response headers

body · Chat Completions · object

Represents a chat completion response returned by model, based on the provided input.

Chat Completions

Completions

Show child attributes