Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Portkey Analytics > Graphs Prompts API
description: The Portkey REST API. Please see https://portkey.ai/docs/api-reference for more details.
version: 2.0.0
termsOfService: https://portkey.ai/terms
contact:
name: Portkey Developer Forum
url: https://portkey.wiki/community
license:
name: MIT
url: https://github.com/Portkey-AI/portkey-openapi/blob/master/LICENSE
servers:
- url: https://api.portkey.ai/v1
description: Portkey API Public Endpoint
security:
- Portkey-Key: []
tags:
- name: Prompts
description: Given a prompt template ID and variables, will run the saved prompt template and return a response.
paths:
/prompts:
servers:
- url: https://api.portkey.ai/v1
description: Portkey API Public Endpoint
- url: SELF_HOSTED_CONTROL_PLANE_URL
description: Self-Hosted Control Plane URL
post:
summary: Create a new prompt
operationId: createPrompt
tags:
- Prompts
security:
- Portkey-Key: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
- collection_id
- string
- parameters
- virtual_key
properties:
name:
type: string
collection_id:
type: string
description: UUID or slug of the collection
string:
type: string
description: Prompt template in string format
parameters:
type: object
description: Parameters for the prompt
functions:
type: array
description: Functions for the prompt
items:
type: object
tools:
type: array
description: Tools for the prompt
items:
type: object
tool_choice:
type: object
description: Tool Choice for the prompt
model:
type: string
description: The model to use for the prompt
virtual_key:
type: string
description: The virtual key to use for the prompt
version_description:
type: string
description: The description of the prompt version
template_metadata:
type: object
description: Metadata for the prompt
responses:
'200':
description: Prompt created successfully
content:
application/json:
schema:
type: object
properties:
id:
type: string
format: uuid
slug:
type: string
version_id:
type: string
format: uuid
object:
type: string
enum:
- prompt
'400':
description: Bad request
'401':
description: Unauthorized
'403':
description: Forbidden
'500':
description: Server error
get:
summary: List prompts
operationId: listPrompts
tags:
- Prompts
security:
- Portkey-Key: []
parameters:
- name: collection_id
in: query
schema:
type: string
- name: workspace_id
in: query
schema:
type: string
- name: current_page
in: query
schema:
type: integer
- name: page_size
in: query
schema:
type: integer
- name: search
in: query
schema:
type: string
responses:
'200':
description: List of prompts
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/PromptSummary'
total:
type: integer
'400':
description: Bad request
'401':
description: Unauthorized
'403':
description: Forbidden
'500':
description: Server error
/prompts/{promptId}:
servers:
- url: https://api.portkey.ai/v1
description: Portkey API Public Endpoint
- url: SELF_HOSTED_CONTROL_PLANE_URL
description: Self-Hosted Control Plane URL
get:
summary: Get a prompt by ID or slug
operationId: getPrompt
tags:
- Prompts
security:
- Portkey-Key: []
parameters:
- name: promptId
in: path
required: true
schema:
type: string
responses:
'200':
description: Prompt details
content:
application/json:
schema:
$ref: '#/components/schemas/Prompt'
'400':
description: Bad request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Prompt not found
'500':
description: Server error
put:
summary: Update a prompt
description: 'Update a prompt''s metadata and/or create a new version with updated template content.
**Partial version updates:** Set `patch: true` to perform a partial update of version fields (`string`, `parameters`, `model`, `virtual_key`, `version_description`, `functions`, `tools`, `tool_choice`, `is_raw_template`, `prompt_metadata`). When enabled, any version fields omitted from the request are backfilled from the current latest version, allowing you to update only the fields you need. When `patch` is omitted or `false`, all version fields must be provided together (original strict validation).
**Metadata-only updates:** Fields like `name`, `collection_id`, `version_description`, and `virtual_key` can always be updated independently without affecting versioning.
'
operationId: updatePrompt
tags:
- Prompts
security:
- Portkey-Key: []
parameters:
- name: promptId
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
patch:
type: boolean
description: 'When `true`, enables partial version updates. Missing version fields (`string`, `parameters`, `model`) are backfilled from the current latest version, so you only need to provide the fields you want to change. When `false` or omitted, the original strict validation is preserved for backward compatibility.
'
name:
type: string
collection_id:
type: string
string:
type: string
description: The prompt template string. When `patch` is `true`, this field is optional and will be inherited from the current latest version if omitted.
parameters:
type: object
description: Model parameters (e.g. temperature, max_tokens). When `patch` is `true`, this field is optional and will be inherited from the current latest version if omitted.
model:
type: string
description: The model identifier. When `patch` is `true`, this field is optional and will be inherited from the current latest version if omitted.
virtual_key:
type: string
description: The virtual key to associate with this version. When `patch` is `true`, this field is optional and will be inherited from the current latest version if omitted.
version_description:
type: string
description: A human-readable description for this version. When `patch` is `true`, this field is optional and will be inherited from the current latest version if omitted.
functions:
type: array
items:
type: object
description: Function definitions available to the model. When `patch` is `true`, this field is optional and will be inherited from the current latest version if omitted.
tools:
type: array
items:
type: object
description: Tool definitions available to the model. When `patch` is `true`, this field is optional and will be inherited from the current latest version if omitted.
tool_choice:
type: object
description: Controls which tool the model uses. When `patch` is `true`, this field is optional and will be inherited from the current latest version if omitted.
is_raw_template:
type: integer
enum:
- 0
- 1
description: Whether the template string is raw (1) or processed (0). When `patch` is `true`, this field is optional and will be inherited from the current latest version if omitted.
prompt_metadata:
type: object
description: Additional metadata for the prompt version. When `patch` is `true`, this field is optional and will be inherited from the current latest version if omitted.
responses:
'200':
description: Prompt updated successfully
content:
application/json:
schema:
type: object
properties:
id:
type: string
format: uuid
slug:
type: string
prompt_version_id:
type: string
format: uuid
'400':
description: Bad request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Prompt not found
'500':
description: Server error
delete:
summary: Delete a prompt
operationId: deletePrompt
tags:
- Prompts
security:
- Portkey-Key: []
parameters:
- name: promptId
in: path
required: true
schema:
type: string
responses:
'200':
description: Prompt deleted successfully
content:
application/json:
schema:
type: object
properties: {}
'400':
description: Bad request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Prompt not found
'500':
description: Server error
/prompts/{promptId}/versions:
servers:
- url: https://api.portkey.ai/v1
description: Portkey API Public Endpoint
- url: SELF_HOSTED_CONTROL_PLANE_URL
description: Self-Hosted Control Plane URL
get:
summary: Get all versions of a prompt
operationId: getPromptVersions
tags:
- Prompts
security:
- Portkey-Key: []
parameters:
- name: promptId
in: path
required: true
schema:
type: string
responses:
'200':
description: List of prompt versions
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PromptVersionSummary'
'400':
description: Bad request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Prompt not found
'500':
description: Server error
/prompts/{promptId}/versions/{versionId}:
servers:
- url: https://api.portkey.ai/v1
description: Portkey API Public Endpoint
- url: SELF_HOSTED_CONTROL_PLANE_URL
description: Self-Hosted Control Plane URL
get:
summary: Get a specific version of a prompt
operationId: getPromptByVersion
tags:
- Prompts
security:
- Portkey-Key: []
parameters:
- name: promptId
in: path
required: true
schema:
type: string
- name: versionId
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Prompt version details
content:
application/json:
schema:
$ref: '#/components/schemas/Prompt'
'400':
description: Bad request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Prompt version not found
'500':
description: Server error
put:
summary: Update a specific version of a prompt
description: 'Updates metadata for a specific prompt version. **This endpoint only supports updating the `label_id` field.**
Prompt versions are immutable — their `string`, `parameters`, and `model` content cannot be changed after creation. To update prompt content, use `PUT /prompts/{promptId}` which creates a new version with the updated content.
'
operationId: updatePromptVersion
tags:
- Prompts
security:
- Portkey-Key: []
parameters:
- name: promptId
in: path
required: true
schema:
type: string
- name: versionId
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
label_id:
type: string
format: uuid
description: The label to assign to this version.
responses:
'200':
description: Prompt version updated successfully
content:
application/json:
schema:
type: object
properties: {}
'400':
description: Bad request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Prompt version not found
'500':
description: Server error
/prompts/{promptId}/makeDefault:
servers:
- url: https://api.portkey.ai/v1
description: Portkey API Public Endpoint
- url: SELF_HOSTED_CONTROL_PLANE_URL
description: Self-Hosted Control Plane URL
put:
summary: Set a version as the default for a prompt
operationId: updatePromptDefault
tags:
- Prompts
security:
- Portkey-Key: []
parameters:
- name: promptId
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- version
properties:
version:
type: number
description: Version Number to set as default
responses:
'200':
description: Default version set successfully
content:
application/json:
schema:
type: object
properties: {}
'400':
description: Bad request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Prompt or version not found
'500':
description: Server error
/prompts/{promptId}/completions:
servers:
- url: https://api.portkey.ai/v1
description: Portkey API Public Endpoint
- url: SELF_HOSTED_GATEWAY_URL
description: Self-Hosted Gateway URL
post:
operationId: createPromptCompletion
tags:
- Prompts
summary: Prompts Completions
description: 'Execute your saved prompt templates on Portkey
'
parameters:
- in: path
name: promptId
required: true
schema:
type: string
description: The unique identifier of the prompt template to use
requestBody:
required: true
content:
application/json:
schema:
allOf:
- type: object
required:
- variables
description: '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.
'
properties:
variables:
type: object
description: Variables to substitute in the prompt template
stream:
type: boolean
default: false
description: 'Default: False. Set to True if you want to stream the response'
hyperparameters:
oneOf:
- title: Chat Completions
$ref: '#/components/schemas/CreateChatCompletionRequest'
- title: Completions
$ref: '#/components/schemas/CreateCompletionRequest'
description: '**Note**: All hyperparameters are optional. Pass them at the root level, and not nested under `hyperparameters`. Their grouping here is for educational purposes only.
'
responses:
'200':
description: Successful completion response
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: Response status
headers:
type: object
description: Response headers
body:
oneOf:
- title: Chat Completions
$ref: '#/components/schemas/CreateChatCompletionResponse'
- title: Completions
$ref: '#/components/schemas/CreateCompletionResponse'
x-code-samples:
- lang: cURL
label: Default
source: "curl -X POST \"https://api.portkey.ai/v1/prompts/YOUR_PROMPT_ID/completions\" \\\n -H \"Content-Type: application/json\" \\\n -H \"x-portkey-api-key: $PORTKEY_API_KEY\" \\\n -d '{\n \"variables\": {\n \"user_input\": \"Hello world\"\n },\n \"max_completion_tokens\": 250,\n \"presence_penalty\": 0.2\n }'\n"
- lang: Python
label: Default
source: "from portkey_ai import Portkey\n\nclient = Portkey(\n api_key=\"PORTKEY_API_KEY\"\n)\n\ncompletion = client.prompts.completions.create(\n prompt_id=\"YOUR_PROMPT_ID\",\n variables={\n \"user_input\": \"Hello world\"\n },\n max_completion_tokens=250,\n presence_penalty=0.2\n)\n\nprint(completion)\n"
- lang: JavaScript
label: Default
source: "import Portkey from 'portkey-ai';\n\nconst portkey = new Portkey({\n apiKey: 'PORTKEY_API_KEY'\n});\n\nconst completion = await portkey.prompts.completions.create({\n promptId: \"YOUR_PROMPT_ID\",\n variables: {\n user_input: \"Hello world\"\n },\n max_completion_tokens: 250,\n presence_penalty: 0.2\n});\n\nconsole.log(completion);\n"
- lang: curl
label: Self-Hosted
source: "curl -X POST \"SELF_HOSTED_GATEWAY_URL/prompts/YOUR_PROMPT_ID/completions\" \\\n -H \"Content-Type: application/json\" \\\n -H \"x-portkey-api-key: $PORTKEY_API_KEY\" \\\n -d '{\n \"variables\": {\n \"user_input\": \"Hello world\"\n },\n \"max_completion_tokens\": 250,\n \"presence_penalty\": 0.2\n }'\n"
- lang: python
label: Self-Hosted
source: "from portkey_ai import Portkey\n\nclient = Portkey(\n api_key=\"PORTKEY_API_KEY\",\n base_url=\"SELF_HOSTED_GATEWAY_URL\"\n)\n\ncompletion = client.prompts.completions.create(\n prompt_id=\"YOUR_PROMPT_ID\",\n variables={\n \"user_input\": \"Hello world\"\n },\n max_completion_tokens=250,\n presence_penalty=0.2\n)\n\nprint(completion)\n"
- lang: javascript
label: Self-Hosted
source: "import Portkey from 'portkey-ai';\n\nconst portkey = new Portkey({\n apiKey: 'PORTKEY_API_KEY',\n baseURL: 'SELF_HOSTED_GATEWAY_URL'\n});\n\nconst completion = await portkey.prompts.completions.create({\n promptId: \"YOUR_PROMPT_ID\",\n variables: {\n user_input: \"Hello world\"\n },\n max_completion_tokens: 250,\n presence_penalty: 0.2\n});\n\nconsole.log(completion);\n"
/prompts/{promptId}/render:
servers:
- url: https://api.portkey.ai/v1
description: Portkey API Public Endpoint
- url: SELF_HOSTED_GATEWAY_URL
description: Self-Hosted Gateway URL
post:
operationId: createPromptRender
tags:
- Prompts
summary: Prompts Render
description: 'Renders a prompt template with its variable values filled in
'
parameters:
- in: path
name: promptId
required: true
schema:
type: string
description: The unique identifier of the prompt template to render
requestBody:
required: true
content:
application/json:
schema:
allOf:
- type: object
required:
- variables
description: '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.
'
properties:
variables:
type: object
description: Variables to substitute in the prompt template
hyperparameters:
oneOf:
- title: Chat Completions
$ref: '#/components/schemas/CreateChatCompletionRequest'
- title: Completions
$ref: '#/components/schemas/CreateCompletionRequest'
description: '**Note**: All hyperparameters are optional. Pass them at the root level, and not nested under `hyperparameters`. Their grouping here is for educational purposes only.
'
responses:
'200':
description: Successful rendered prompt
content:
application/json:
schema:
$ref: '#/components/schemas/PromptRenderResponse'
x-code-samples:
- lang: cURL
label: Default
source: "curl -X POST \"https://api.portkey.ai/v1/prompts/YOUR_PROMPT_ID/render\" \\\n -H \"Content-Type: application/json\" \\\n -H \"x-portkey-api-key: $PORTKEY_API_KEY\" \\\n -d '{\n \"variables\": {\n \"user_input\": \"Hello world\"\n },\n \"max_completion_tokens\": 250,\n \"presence_penalty\": 0.2\n }'\n"
- lang: Python
label: Default
source: "from portkey_ai import Portkey\n\nclient = Portkey(\n api_key=\"PORTKEY_API_KEY\"\n)\n\ncompletion = client.prompts.render(\n prompt_id=\"YOUR_PROMPT_ID\",\n variables={\n \"user_input\": \"Hello world\"\n },\n max_completion_tokens=250,\n presence_penalty=0.2\n)\n\nprint(completion)\n"
- lang: JavaScript
label: Default
source: "import Portkey from 'portkey-ai';\n\nconst portkey = new Portkey({\n apiKey: 'PORTKEY_API_KEY'\n});\n\nconst completion = await portkey.prompts.render({\n promptId: \"YOUR_PROMPT_ID\",\n variables: {\n user_input: \"Hello world\"\n },\n max_completion_tokens: 250,\n presence_penalty: 0.2\n});\n\nconsole.log(completion);\n"
- lang: cURL
label: Self-Hosted
source: "curl -X POST \"SELF_HOSTED_GATEWAY_URL/prompts/YOUR_PROMPT_ID/render\" \\\n -H \"Content-Type: application/json\" \\\n -H \"x-portkey-api-key: $PORTKEY_API_KEY\" \\\n -d '{\n \"variables\": {\n \"user_input\": \"Hello world\"\n },\n \"max_completion_tokens\": 250,\n \"presence_penalty\": 0.2\n }'\n"
- lang: Python
label: Self-Hosted
source: "from portkey_ai import Portkey\n\nclient = Portkey(\n api_key=\"PORTKEY_API_KEY\",\n base_url=\"SELF_HOSTED_GATEWAY_URL\"\n)\n\ncompletion = client.prompts.render(\n prompt_id=\"YOUR_PROMPT_ID\",\n variables={\n \"user_input\": \"Hello world\"\n },\n max_completion_tokens=250,\n presence_penalty=0.2\n)\n\nprint(completion)\n"
- lang: JavaScript
label: Self-Hosted
source: "import Portkey from 'portkey-ai';\n\nconst portkey = new Portkey({\n apiKey: 'PORTKEY_API_KEY',\n baseUrl: 'SELF_HOSTED_GATEWAY_URL'\n});\n\nconst completion = await portkey.prompts.render({\n promptId: \"YOUR_PROMPT_ID\",\n variables: {\n user_input: \"Hello world\"\n },\n max_completion_tokens: 250,\n presence_penalty: 0.2\n});\n\nconsole.log(completion);\n"
components:
schemas:
CreateChatCompletionRequest:
type: object
properties:
messages:
description: A list of messages comprising the conversation so far. [Example Python code](https://cookbook.openai.com/examples/how_to_format_inputs_to_chatgpt_models).
type: array
minItems: 1
items:
$ref: '#/components/schemas/ChatCompletionRequestMessage'
model:
description: ID of the model to use. See the [model endpoint compatibility](https://platform.openai.com/docs/models/model-endpoint-compatibility) table for details on which models work with the Chat API.
example: gpt-5
anyOf:
- type: string
- type: string
enum:
- gpt-5
- gpt-5-mini
- gpt-5-nano
- o4-mini
- o3
- o3-mini
- o1
- o1-mini
- gpt-4o
- gpt-4o-mini
- gpt-4o-2024-05-13
- gpt-4-turbo
- gpt-4-turbo-2024-04-09
- gpt-4-0125-preview
- gpt-4-turbo-preview
- gpt-4-1106-preview
- gpt-4-vision-preview
- gpt-4
- gpt-4-0314
- gpt-4-0613
- gpt-4-32k
- gpt-4-32k-0314
- gpt-4-32k-0613
- gpt-3.5-turbo
- gpt-3.5-turbo-16k
- gpt-3.5-turbo-0301
- gpt-3.5-turbo-0613
- gpt-3.5-turbo-1106
- gpt-3.5-turbo-0125
- gpt-3.5-turbo-16k-0613
x-oaiTypeLabel: string
frequency_penalty:
type:
- number
- 'null'
default: 0
minimum: -2
maximum: 2
description: 'Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model''s likelihood to repeat the same line verbatim.
[See more information about frequency and presence penalties.](https://platform.openai.com/docs/guides/text-generation/parameter-details)
'
logit_bias:
type:
- object
- 'null'
x-oaiTypeLabel: map
default: null
additionalProperties:
type: integer
description: 'Modify the likelihood of specified tokens appearing in the completion.
Accepts a JSON object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from -100 to 100. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token.
'
logprobs:
description: Whether to return log probabilities of the output tokens or not. If true, returns the log probabilities of each output token returned in the `content` of `message`.
type:
- boolean
- 'null'
default: false
top_logprobs:
description: An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability. `logprobs` must be set to `true` if this parameter is used.
type:
- integer
- 'null'
minimum: 0
maximum: 20
max_tokens:
description: 'Deprecated in favor of `max_completion_tokens`.
The maximum number of [tokens](https://platform.openai.com/tokenizer?view=bpe) that can be generated in the chat completion. This value can be used to control [costs](https://openai.com/api/pricing/) for text generated via API.
**Supported models:** GPT-4o, GPT-4o-mini, GPT-4, GPT-4 Turbo, GPT-3.5 Turbo.
**Not supported:** o-series reasoning models (o1, o3, o3-mini, o4-mini) and GPT-5 series — use `max_completion_tokens` instead.
'
type:
- integer
- 'null'
deprecated: true
max_completion_tokens:
description: 'An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning).
**Supported models:** GPT-5 series, o-series reasoning models (o1, o3, o3-mini, o4-mini) — required. Also supported on GPT-4o, GPT-4o-mini, GPT-4, GPT-4 Turbo, GPT-3.5 Turbo as a replacement for `max_tokens`.
'
type:
- integer
- 'null'
n:
type:
- integer
- 'null'
minimum: 1
maximum: 128
default: 1
example: 1
description: How many chat completion choices to generate for each input message. Note that you will be charged based on the number of generated tokens across all of the choices. Keep `n` as `1` to minimize costs.
presence_penalty:
type:
- number
- 'null'
default: 0
minimum: -2
maximum: 2
description: 'Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model''s likelihood to talk about new topics.
[See more information about frequency and presence penalties.](https://platform.openai.com/docs/guides/text-generation/parameter-details)
'
response_format:
type: object
description: 'An object specifying the format that the model must output.
Setting to `{ "type": "json_schema", "json_schema": {...} }`enables Structured Outputs which ensures the model will match your
supplied JSON schema. Works across all the providers that support this functionality. [OpenAI & Azure OpenAI](/integrations/llms/openai/structured-outputs), [Gemini & Vertex AI](/integrations/llms/vertex-ai/controlled-generations).
Setting to `{ "type": "json_object" }` enables the older JSON mode, which ensures the message the model generates is valid JSON.
Using `json_schema` is preferred for models that support it.
'
oneOf:
- $ref: '#/components/schemas/ResponseFormatText'
- $ref: '#/components/schemas/ResponseFormatJsonSchema'
- $ref: '#/components/schemas/ResponseFormatJsonObject'
# --- truncated at 32 KB (93 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/portkey/refs/heads/main/openapi/portkey-prompts-api-openapi.yml