Getting Started (Developer)

Installation

# Node.js
npm install portkey-ai

# Python
pip install portkey-ai

Basic Usage (Node.js)

import Portkey from "portkey-ai";

const portkey = new Portkey();

async function main() {
  const completion = await portkey.chat.completions.create({
    messages: [{ role: "user", content: "What's a Portkey?" }],
    model: "@openai/gpt-4.1"
  });
  console.log(completion.choices[0]);
}

main();

Key Concepts

AI Gateway: A unified API endpoint that routes to 1,600+ LLMs. Drop-in replacement for the OpenAI SDK — change the base URL and add your Portkey API key.
Config Object: JSON-based routing configs define fallback chains, load balancing weights, cache TTLs, and retry logic without touching application code.
Guardrails: Policy rules applied pre/post LLM call to filter inputs and validate outputs (e.g., PII detection, topic blocklists, JSON schema enforcement).
Prompt Management: Store, version, and retrieve prompts via the API — no hard-coded strings in your codebase.
MCP Gateway: Centralized authentication and observability layer for Model Context Protocol servers, enabling secure agent tool access.
Observability API: Every request is logged with latency, token usage, cost, model, and custom metadata; query logs programmatically or via the dashboard.

Authentication

Set your Portkey API key as an environment variable:

export PORTKEY_API_KEY="your-api-key"