Portkey Admin API enables programmatic management of Portkey organizations and workspaces, including resource management for configs, virtual keys, and API keys, analytics and monitoring for usage statistics and performance trends, and user and workspace administration for managing accounts, permissions, and team membership. Includes audit logging of all administrative operations.
openapi: 3.0.0
info:
title: Portkey 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
x-server-groups:
ControlPlaneServers: &ControlPlaneServers
- url: https://api.portkey.ai/v1
description: Portkey API Public Endpoint
- url: SELF_HOSTED_CONTROL_PLANE_URL
description: Self-Hosted Control Plane URL
DataPlaneServers: &DataPlaneServers
- url: https://api.portkey.ai/v1
description: Portkey API Public Endpoint
- url: SELF_HOSTED_GATEWAY_URL
description: Self-Hosted Gateway URL
PublicServers: &PublicServers
- url: https://api.portkey.ai
description: Portkey Public API (no auth required)
x-mint:
mcp:
enabled: true
name: Portkey MCP
description: Official MCP Server for Portkey Docs & APIs
servers:
- url: https://api.portkey.ai/v1
description: Portkey API Public Endpoint
tags:
- name: Assistants
description: Build Assistants that can call models and use tools.
- name: Audio
description: Turn audio into text or text into audio.
- name: Chat
description: Given a list of messages comprising a conversation, the model will return a response.
- name: Realtime
description: WebSocket proxy for provider Realtime APIs
- name: Collections
description: Create, List, Retrieve, Update, and Delete collections of prompts.
- name: Labels
description: Create, List, Retrieve, Update, and Delete labels.
- name: Prompt Collections
description: Create, List, Retrieve, Update, and Delete prompt collections.
- name: PromptPartials
description: Create, List, Retrieve, Update, and Delete prompt partials.
- name: Prompts
description: Given a prompt template ID and variables, will run the saved prompt template and return a response.
- name: Guardrails
description: Create, List, Retrieve, Update, and Delete prompt Guardrails.
- name: Completions
description: Given a prompt, the model will return one or more predicted completions, and can also return the probabilities of alternative tokens at each position.
- name: Embeddings
description: Get a vector representation of a given input that can be easily consumed by machine learning models and algorithms.
- name: Rerank
description: Rerank a list of documents based on their relevance to a query. Supported providers include Cohere, Voyage, Jina, Pinecone, Bedrock, and Azure AI.
- name: Fine-tuning
description: Manage fine-tuning jobs to tailor a model to your specific training data.
- name: Batch
description: Create large batches of API requests to run asynchronously.
- name: Files
description: Files are used to upload documents that can be used with features like Assistants and Fine-tuning.
- name: Images
description: Given a prompt and/or an input image, the model will generate a new image.
- name: Models
description: List and describe the various models available in the API.
- name: Moderations
description: Given a input text, outputs if the model classifies it as potentially harmful.
- name: Configs
description: Create, List, Retrieve, and Update your Portkey Configs.
- name: Feedback
description: Send and Update any feedback.
- name: Logs
description: Custom Logger to add external logs to Portkey.
- name: Integrations
description: Create, List, Retrieve, Update, and Delete your Portkey Integrations.
- name: Integrations > Workspaces
description: Manage workspace access for your Portkey Integrations.
- name: Integrations > Models
description: Manage model access for your Portkey Integrations.
- name: Providers
description: Create, List, Retrieve, Update, and Delete your Portkey Providers.
- name: Virtual-keys
description: Create, List, Retrieve, Update, and Delete your Portkey Virtual keys.
- name: Users
description: Create and manage users.
- name: User-invites
description: Create and manage user invites.
- name: Workspaces
description: Create and manage workspaces.
- name: Workspaces > Members
description: Create and manage workspace members.
- name: MCP Integrations
description: Create, List, Retrieve, Update, and Delete MCP Integrations.
- name: MCP Integrations > Workspaces
description: Manage workspace access for MCP Integrations.
- name: MCP Integrations > Capabilities
description: List and manage capabilities for MCP Integrations.
- name: MCP Integrations > Metadata
description: Get MCP Integration metadata and sync info.
- name: MCP Servers
description: Create, List, Retrieve, Update, and Delete MCP Servers (workspace instances of MCP Integrations).
- name: MCP Servers > Capabilities
description: List and manage capabilities for MCP Servers.
- name: MCP Servers > User Access
description: List and manage user access for MCP Servers.
- name: MCP Servers > Connections
description: List and manage user connections for MCP Servers.
- name: Api-Keys
description: Create, List, Retrieve, Update, and Delete your Portkey API keys.
- name: Logs Export
description: Exports logs service.
- name: Audit Logs
description: Get audit logs for your Portkey account.
- name: Analytics
description: Get analytics over different data points like requests, costs, tokens, etc.
- name: Analytics > Graphs
description: Get data points for graphical representation.
- name: Analytics > Summary
description: Get overall summary for the selected time bucket.
- name: Analytics > Groups
description: Get grouped metrics for the selected time bucket.
- name: Usage Limits Policies
description: Manage usage limits policies to control total usage over time
- name: Rate Limits Policies
description: Manage rate limits policies to control request or token rates
- name: Model Pricing
description: Model pricing configurations for 2300+ LLMs across 40+ providers
- name: Secret-References
description: Create, List, Retrieve, Update, and Delete secret references to external secret managers.
paths:
# Note: When adding an endpoint, make sure you also add it in the `groups` section, in the end of this file,
# under the appropriate group
/chat/completions:
servers: *DataPlaneServers
post:
operationId: createChatCompletion
tags:
- Chat
summary: Chat
parameters:
- $ref: "#/components/parameters/PortkeyTraceId"
- $ref: "#/components/parameters/PortkeySpanId"
- $ref: "#/components/parameters/PortkeyParentSpanId"
- $ref: "#/components/parameters/PortkeySpanName"
- $ref: "#/components/parameters/PortkeyMetadata"
- $ref: "#/components/parameters/PortkeyCacheNamespace"
- $ref: "#/components/parameters/PortkeyCacheForceRefresh"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateChatCompletionRequest"
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/CreateChatCompletionResponse"
security:
- Portkey-Key: []
Virtual-Key: []
- Portkey-Key: []
Provider-Auth: []
Provider-Name: []
- Portkey-Key: []
Config: []
- Portkey-Key: []
Provider-Auth: []
Provider-Name: []
Custom-Host: []
x-code-samples:
- lang: cURL
label: Default
source: |
curl https://api.portkey.ai/v1/chat/completions \
-H "Content-Type: application/json" \
-H "x-portkey-api-key: $PORTKEY_API_KEY" \
-H "x-portkey-virtual-key: $PORTKEY_PROVIDER_VIRTUAL_KEY" \
-d '{
"model": "gpt-5",
"messages": [
{
"role": "system",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "Hello!"
}
],
"max_completion_tokens": 250
}'
- lang: cURL
label: Self-Hosted
source: |
curl SELF_HOSTED_GATEWAY_URL/chat/completions \
-H "Content-Type: application/json" \
-H "x-portkey-api-key: $PORTKEY_API_KEY" \
-H "x-portkey-virtual-key: $PORTKEY_PROVIDER_VIRTUAL_KEY" \
-d '{
"model": "gpt-5",
"messages": [
{
"role": "system",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "Hello!"
}
],
"max_completion_tokens": 250
}'
- lang: python
label: Default
source: |
from portkey_ai import Portkey
portkey = Portkey(
api_key = "PORTKEY_API_KEY",
virtual_key = "PROVIDER_VIRTUAL_KEY"
)
response = portkey.chat.completions.create(
model="gpt-5",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello!"}
],
max_completion_tokens=250
)
print(response.choices[0].message)
- lang: python
label: Self-Hosted
source: |
from portkey_ai import Portkey
portkey = Portkey(
api_key = "PORTKEY_API_KEY",
base_url = "SELF_HOSTED_GATEWAY_URL",
virtual_key = "PROVIDER_VIRTUAL_KEY"
)
response = portkey.chat.completions.create(
model="gpt-5",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello!"}
],
max_completion_tokens=250
)
print(response.choices[0].message)
- lang: javascript
label: Default
source: |
import Portkey from 'portkey-ai';
const portkey = new Portkey({
apiKey: 'PORTKEY_API_KEY',
virtualKey: 'PROVIDER_VIRTUAL_KEY'
});
async function main() {
const response = await portkey.chat.completions.create({
messages: [{ role: "system", content: "You are a helpful assistant." }],
model: "gpt-5",
max_completion_tokens: 250,
});
console.log(response.choices[0]);
}
main();
- lang: javascript
label: Self-Hosted
source: |
import Portkey from 'portkey-ai';
const portkey = new Portkey({
apiKey: 'PORTKEY_API_KEY',
virtualKey: 'PROVIDER_VIRTUAL_KEY',
baseUrl: 'SELF_HOSTED_GATEWAY_URL'
});
async function main() {
const response = await portkey.chat.completions.create({
messages: [{ role: "system", content: "You are a helpful assistant." }],
model: "gpt-5",
max_completion_tokens: 250,
});
console.log(response.choices[0]);
}
main();
/realtime:
servers: *DataPlaneServers
get:
operationId: connectRealtime
tags:
- Realtime
summary: Realtime
description: "Connect to the Realtime API endpoint."
parameters:
- $ref: "#/components/parameters/PortkeyTraceId"
- $ref: "#/components/parameters/PortkeySpanId"
- $ref: "#/components/parameters/PortkeyParentSpanId"
- $ref: "#/components/parameters/PortkeySpanName"
- $ref: "#/components/parameters/PortkeyMetadata"
- $ref: "#/components/parameters/PortkeyCacheNamespace"
- $ref: "#/components/parameters/PortkeyCacheForceRefresh"
- name: model
in: query
required: false
schema:
type: string
description: Often required for OpenAI-style realtime; other query params pass through unchanged.
responses:
"101":
description: WebSocket upgrade.
default:
description: Error
security:
- Portkey-Key: []
Virtual-Key: []
- Portkey-Key: []
Provider-Auth: []
Provider-Name: []
- Portkey-Key: []
Config: []
- Portkey-Key: []
Provider-Auth: []
Provider-Name: []
Custom-Host: []
x-code-samples:
- lang: cURL
label: Default
source: |
curl -sS -D - -o /dev/null \
-H "x-portkey-api-key: $PORTKEY_API_KEY" \
-H "x-portkey-virtual-key: $PORTKEY_PROVIDER_VIRTUAL_KEY" \
"https://api.portkey.ai/v1/realtime?model=gpt-4o-realtime-preview"
- lang: cURL
label: Self-Hosted
source: |
curl -sS -D - -o /dev/null \
-H "x-portkey-api-key: $PORTKEY_API_KEY" \
-H "x-portkey-virtual-key: $PORTKEY_PROVIDER_VIRTUAL_KEY" \
"SELF_HOSTED_GATEWAY_URL/realtime?model=gpt-4o-realtime-preview"
- lang: javascript
label: Default
source: |
import WebSocket from 'ws';
const ws = new WebSocket(
'wss://api.portkey.ai/v1/realtime?model=gpt-4o-realtime-preview',
{
headers: {
'x-portkey-api-key': process.env.PORTKEY_API_KEY,
'x-portkey-virtual-key': process.env.PORTKEY_PROVIDER_VIRTUAL_KEY,
},
}
);
- lang: javascript
label: Self-Hosted
source: |
import WebSocket from 'ws';
const u = new URL(process.env.SELF_HOSTED_GATEWAY_URL);
u.protocol = u.protocol === 'https:' ? 'wss:' : 'ws:';
u.pathname = `${u.pathname.replace(/\/$/, '')}/realtime`;
u.searchParams.set('model', 'gpt-4o-realtime-preview');
new WebSocket(u.toString(), {
headers: {
'x-portkey-api-key': process.env.PORTKEY_API_KEY,
'x-portkey-virtual-key': process.env.PORTKEY_PROVIDER_VIRTUAL_KEY,
},
});
- lang: python
label: Default
source: |
import os
import asyncio
import websockets
async def main():
uri = "wss://api.portkey.ai/v1/realtime?model=gpt-4o-realtime-preview"
headers = {
"x-portkey-api-key": os.environ["PORTKEY_API_KEY"],
"x-portkey-virtual-key": os.environ["PORTKEY_PROVIDER_VIRTUAL_KEY"],
}
async with websockets.connect(uri, extra_headers=headers):
pass
asyncio.run(main())
- lang: python
label: Self-Hosted
source: |
import os
import asyncio
from urllib.parse import urlparse, urlunparse
import websockets
async def main():
p = urlparse(os.environ["SELF_HOSTED_GATEWAY_URL"])
scheme = "wss" if p.scheme == "https" else "ws"
path = p.path.rstrip("/") + "/realtime"
uri = urlunparse((scheme, p.netloc, path, "", "model=gpt-4o-realtime-preview", ""))
headers = {
"x-portkey-api-key": os.environ["PORTKEY_API_KEY"],
"x-portkey-virtual-key": os.environ["PORTKEY_PROVIDER_VIRTUAL_KEY"],
}
async with websockets.connect(uri, extra_headers=headers):
pass
asyncio.run(main())
/completions:
servers: *DataPlaneServers
post:
operationId: createCompletion
tags:
- Completions
summary: Completions
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateCompletionRequest"
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/CreateCompletionResponse"
security:
- Portkey-Key: []
Virtual-Key: []
- Portkey-Key: []
Provider-Auth: []
Provider-Name: []
- Portkey-Key: []
Config: []
- Portkey-Key: []
Provider-Auth: []
Provider-Name: []
Custom-Host: []
x-code-samples:
- lang: curl
label: Default
source: |
curl https://api.portkey.ai/v1/completions \
-H "Content-Type: application/json" \
-H "x-portkey-api-key: $PORTKEY_API_KEY" \
-H "x-portkey-virtual-key: $PORTKEY_PROVIDER_VIRTUAL_KEY" \
-d '{
"model": "gpt-3.5-turbo-instruct",
"prompt": "Say this is a test",
"max_tokens": 7,
"temperature": 0
}'
- lang: python
label: Default
source: |
from portkey_ai import Portkey
portkey = Portkey(
api_key = "PORTKEY_API_KEY",
virtual_key = "PROVIDER_VIRTUAL_KEY"
)
response = portkey.completions.create(
model="gpt-3.5-turbo-instruct",
prompt="Say this is a test",
max_tokens=7,
temperature=0
)
print(response)
- lang: javascript
label: Default
source: |
import Portkey from 'portkey-ai';
const portkey = new Portkey({
apiKey: 'PORTKEY_API_KEY',
virtualKey: 'PROVIDER_VIRTUAL_KEY'
});
async function main() {
const response = await portkey.completions.create({
model: "gpt-3.5-turbo-instruct",
prompt: "Say this is a test.",
max_tokens: 7,
temperature: 0,
});
console.log(response);
}
main();
- lang: javascript
label: Self-Hosted
source: |
import Portkey from 'portkey-ai';
const portkey = new Portkey({
apiKey: 'PORTKEY_API_KEY',
virtualKey: 'PROVIDER_VIRTUAL_KEY',
baseUrl: 'SELF_HOSTED_GATEWAY_URL'
});
async function main() {
const response = await client.completions.create({
model: "gpt-3.5-turbo-instruct",
prompt: "Say this is a test.",
max_tokens: 7,
temperature: 0,
});
console.log(response);
}
main();
- lang: python
label: Self-Hosted
source: |
from portkey_ai import Portkey
portkey = Portkey(
api_key = "PORTKEY_API_KEY",
virtual_key = "PROVIDER_VIRTUAL_KEY",
base_url = "SELF_HOSTED_GATEWAY_URL"
)
response = portkey.completions.create(
model="gpt-3.5-turbo-instruct",
prompt="Say this is a test",
max_tokens=7,
temperature=0
)
print(response)
- lang: curl
label: Self-Hosted
source: |
curl https://SELF_HOSTED_GATEWAY_URL/completions \
-H "Content-Type: application/json" \
-H "x-portkey-api-key: $PORTKEY_API_KEY" \
-H "x-portkey-virtual-key: $PORTKEY_PROVIDER_VIRTUAL_KEY" \
-d '{
"model": "gpt-3.5-turbo-instruct",
"prompt": "Say this is a test",
"max_tokens": 7,
"temperature": 0
}'
/collections:
servers: *ControlPlaneServers
post:
summary: Create a new collection
description: Creates a new collection in the specified workspace
tags:
- Collections
security:
- Portkey-Key: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
workspace_id:
type: string
description: ID or slug of the workspace
name:
type: string
description: Name of the collection
parent_collection_id:
type: string
description: ID or slug of the parent collection (optional)
required:
- name
responses:
'200':
description: Collection created successfully
content:
application/json:
schema:
type: object
properties:
id:
type: string
format: uuid
description: ID of the created collection
slug:
type: string
description: Slug of the created collection
'400':
description: Bad request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Workspace or parent collection not found
'500':
description: Server error
get:
summary: List collections
description: Lists all collections in the specified workspace
tags:
- Collections
security:
- Portkey-Key: []
parameters:
- name: workspace_id
in: query
required: true
schema:
type: string
description: ID or slug of the workspace
- name: current_page
in: query
required: false
schema:
type: integer
minimum: 0
description: Page number for pagination (0-indexed)
- name: page_size
in: query
required: false
schema:
type: integer
minimum: 1
description: Number of items per page
- name: search
in: query
required: false
schema:
type: string
description: Search query to filter collections by name
responses:
'200':
description: List of collections
content:
application/json:
schema:
type: object
properties:
total:
type: integer
description: Total number of collections matching the criteria
data:
type: array
items:
$ref: '#/components/schemas/CollectionWithDetails'
'400':
description: Bad request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Workspace not found
'500':
description: Server error
/collections/{collectionId}:
servers: *ControlPlaneServers
parameters:
- name: collectionId
in: path
required: true
schema:
type: string
description: ID or slug of the collection
get:
summary: Get collection details
description: Retrieves details of a specific collection
tags:
- Collections
security:
- Portkey-Key: []
responses:
'200':
description: Collection details
content:
application/json:
schema:
$ref: '#/components/schemas/CollectionWithChildCollections'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Collection not found
'500':
description: Server error
put:
summary: Update collection
description: Updates a collection's details
security:
- Portkey-Key: []
tags:
- Collections
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: New name for the collection
required:
- name
responses:
'200':
description: OK
headers:
Content-Type:
schema:
type: string
example: application/json
content:
application/json:
schema:
type: object
example: {}
'400':
description: Bad request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Collection not found
'500':
description: Server error
delete:
summary: Delete collection
description: Deletes a collection
security:
- Portkey-Key: []
tags:
- Collections
responses:
'200':
description: OK
headers:
Content-Type:
schema:
type: string
example: application/json
content:
application/json:
schema:
type: object
example: {}
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Collection not found or trying to delete default collection
'500':
description: Server error
/labels:
servers: *ControlPlaneServers
post:
summary: Create a new label
description: Creates a new label in the system
operationId: createLabel
security:
- Portkey-Key: []
tags:
- Labels
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateLabelRequest'
responses:
'200':
description: Label created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CreateLabelResponse'
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
'403':
description: Forbidden
'500':
description: Server error
get:
summary: List labels
description: Returns a list of labels based on filters
operationId: listLabels
security:
- Portkey-Key: []
tags:
- Labels
parameters:
- name: organisation_id
in: query
schema:
type: string
format: uuid
description: ID of the organisation
- name: workspace_id
in: query
schema:
type: string
description: ID or slug of the workspace
- name: search
in: query
schema:
type: string
description: Search query to filter labels by name
- name: current_page
in: query
schema:
type: integer
minimum: 0
description: Page number for pagination
- name: page_size
in: query
schema:
type: integer
minimum: 1
description: Number of items per page
responses:
'200':
description: List of labels
content:
application/json:
schema:
$ref: '#/components/schemas/ListLabelsResponse'
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
'403':
description: Forbidden
'500':
description: Server error
/labels/{labelId}:
servers: *ControlPlaneServers
get:
summary: Get a label by ID
description: Returns a specific label by its ID
operationId: getLabel
security:
- Portkey-Key: []
tags:
- Labels
parameters:
- name: labelId
in: path
required: true
schema:
type: string
format: uuid
description: ID of the label to retrieve
- name: organisation_id
in: query
schema:
type: string
format: uuid
description: ID of the organisation
- name: workspace_id
in: query
schema:
type: string
description: ID or slug of the workspace
responses:
'200':
description: Label details
content:
application/json:
schema:
$ref: '#/components/schemas/Label'
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Label not found
'500':
description: Server error
put:
summary: Update a label
description: Updates an existing label
operationId: updateLabel
security:
- Portkey-Key: []
tags:
- Labels
parameters:
- name: labelId
in: path
required: true
schema:
type: string
format: uuid
description: ID of the label to update
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateLabelRequest'
responses:
'200':
description: OK
headers:
Content-Type:
schema:
type: string
example: application/json
content:
application/json:
schema:
type: object
example: {}
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Label not found
'500':
description: Server error
delete:
summary: Delete a label
description: Deletes a label
operationId: deleteLabel
security:
- Portkey-Key: []
tags:
- Labels
parameters:
- name: labelId
in: path
required: true
schema:
type: string
format: uuid
description: ID of the label to delete
responses:
'200':
description: OK
headers:
Content-Type:
schema:
type: string
example: application/json
content:
application/json:
schema:
type: object
example: {}
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Label not
# --- truncated at 32 KB (1194 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/portkey/refs/heads/main/openapi/portkey-openapi.yml