The official Node.js SDK makes it easy to integrate Portkey’s AI gateway into any Node.js or TypeScript application. Enjoy unified access to 250+ LLMs, advanced observability, routing, governance, and enterprise features with just a few lines of code.

Official

Github Repo

​
Installation

Install the Portkey SDK from npm:

npm install portkey-ai
# or
yarn add portkey-ai
# or
pnpm add portkey-ai

​
API Key Setup

  1. Create a Portkey API key in your dashboard.
  2. Store your API key securely as an environment variable:
export PORTKEY_API_KEY="your_api_key_here"
The SDK automatically detects your API key from the environment.

​
Quickstart

Here’s a minimal example to get you started:

import Portkey from 'portkey-ai';

const portkey = new Portkey({
  apiKey: process.env.PORTKEY_API_KEY,
  virtualKey: 'your_virtual_key_here' // Or use config: 'cf-***'
});

const response = await portkey.chat.completions.create({
  messages: [{ role: 'user', content: 'Hello, world!' }],
  model: 'openai/gpt-3.5-turbo'
});

console.log(response.choices[0].message.content);
You can use either a Virtual Key or a Config object to select your AI provider. Find more info on different authentication mechanisms here.

​
Authentication & Configuration

The SDK requires:

  • Portkey API Key: Your Portkey API key (env var PORTKEY_API_KEY recommended)
  • Provider Authentication:
    • Virtual Key: The Virtual Key of your chosen AI provider
    • Config: The Config object or config slug for advanced routing
    • Provider Slug + Auth Headers: Useful if you do not want to save your API keys to Portkey and make direct requests.
// With Virtual Key
const portkey = new Portkey({ apiKey: '...', virtualKey: '...' });

// With Config
const portkey = new Portkey({ apiKey: '...', config: 'cf-***' });

// With Provider Slug + Auth Headers
const portkey = new Portkey({ apiKey: '...', provider: 'openai', Authorization: 'Bearer OPENAI_API_KEY' });

​
Adding Trace ID & Metadata

const chatCompletion = await portkey.chat.completions.create({
  messages: [{ role: 'user', content: 'Say this is a test' }],
  model: 'gpt-4o',
}, {
  traceId: '39e2a60c-b47c-45d8',
  metadata: { _user: '432erf6' }
});

console.log(chatCompletion.choices);

​
TypeScript Support

Portkey’s Node.js SDK is fully typed and works seamlessly with TypeScript:

import Portkey, { ChatCompletionResponse } from 'portkey-ai';
// ...
const response: ChatCompletionResponse = await portkey.chat.completions.create(/* ... */);

​
Parameters

List of All Headers

View the complete list of headers that can be used with Portkey API requests, including authentication, configuration, and custom headers.

Here’s how you can use these headers with the Node.js SDK:

const portkey = new Portkey({
    apiKey: "PORTKEY_API_KEY",
    virtualKey: "VIRTUAL_KEY",
    // Add any other headers from the reference
});

// Or at runtime
const chatCompletion = await portkey.chat.completions.create(
    {
        messages: [{ role: "user", content: "Hello!" }],
        model: "gpt-4o"
    },
    {
        traceId: "your_trace_id",
        metadata: { _user: "user_id" },
        // Add any other headers as needed
    }
);

​
Troubleshooting & Support

​
FAQ