openapi: 3.0.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:
ChatCompletionToolChoiceOption:
description: 'Controls which (if any) tool is called by the model.
`none` means the model will not call any tool and instead generates a message.
`auto` means the model can pick between generating a message or calling one or more tools.
`required` means the model must call one or more tools.
Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool.
`none` is the default when no tools are present. `auto` is the default if tools are present.
'
oneOf:
- type: string
description: '`none` means the model will not call any tool and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools.
'
enum:
- none
- auto
- required
- $ref: '#/components/schemas/ChatCompletionNamedToolChoice'
x-oaiExpandable: true
ChatCompletionRequestAssistantMessage:
type: object
title: Assistant message
properties:
content:
nullable: true
type: string
description: 'The contents of the assistant message. Required unless `tool_calls` or `function_call` is specified.
'
role:
type: string
enum:
- assistant
description: The role of the messages author, in this case `assistant`.
name:
type: string
description: An optional name for the participant. Provides the model information to differentiate between participants of the same role.
tool_calls:
$ref: '#/components/schemas/ChatCompletionMessageToolCalls'
function_call:
type: object
deprecated: true
description: Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model.
nullable: true
properties:
arguments:
type: string
description: The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function.
name:
type: string
description: The name of the function to call.
required:
- arguments
- name
required:
- role
ChatCompletionRequestDeveloperMessage:
type: object
title: Developer message
description: New role by OpenAI for select models. Must be explicitly used for models that support it. When used with incompatible models or providers, Portkey automatically converts it to a system role.
properties:
content:
description: The contents of the Developer message.
type: string
role:
type: string
enum:
- developer
description: The role of the messages author, in this case `Developer`.
name:
type: string
description: An optional name for the participant. Provides the model information to differentiate between participants of the same role.
required:
- content
- role
ChatCompletionRequestSystemMessage:
type: object
title: System message
properties:
content:
description: The contents of the system message.
type: string
role:
type: string
enum:
- system
description: The role of the messages author, in this case `system`.
name:
type: string
description: An optional name for the participant. Provides the model information to differentiate between participants of the same role.
required:
- content
- role
ChatCompletionTokenLogprob:
type: object
properties:
token: &id001
description: The token.
type: string
logprob: &id002
description: The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value `-9999.0` is used to signify that the token is very unlikely.
type: number
bytes: &id003
description: A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token.
type: array
items:
type: integer
nullable: true
top_logprobs:
description: List of the most likely tokens and their log probability, at this token position. In rare cases, there may be fewer than the number of requested `top_logprobs` returned.
type: array
items:
type: object
properties:
token: *id001
logprob: *id002
bytes: *id003
required:
- token
- logprob
- bytes
required:
- token
- logprob
- bytes
- top_logprobs
CreateCompletionRequest:
type: object
properties:
model:
description: 'ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models/overview) for descriptions of them.
'
anyOf:
- type: string
- type: string
enum:
- gpt-3.5-turbo-instruct
- davinci-002
- babbage-002
x-oaiTypeLabel: string
prompt:
description: 'The prompt(s) to generate completions for, encoded as a string, array of strings, array of tokens, or array of token arrays.
Note that <|endoftext|> is the document separator that the model sees during training, so if a prompt is not specified the model will generate as if from the beginning of a new document.
'
default: <|endoftext|>
nullable: true
oneOf:
- type: string
default: ''
example: This is a test.
- type:
# --- truncated at 32 KB (92 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/portkey/refs/heads/main/openapi/portkey-prompts-api-openapi.yml