Skip to main content
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,
  provider: '@openai-prod' // Provider slug from Model Catalog
});

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

console.log(response.choices[0].message.content);
Add providers in the Model Catalog to get a provider slug (e.g., @openai-prod). You can also use a Config for advanced routing.

​
Authentication & Configuration

The SDK requires:
  • Portkey API Key: Your Portkey API key (env var PORTKEY_API_KEY recommended)
  • Provider Authentication:
    • Provider Slug: Add a provider in Model Catalog and use its slug (recommended)
    • 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 Provider Slug
const portkey = new Portkey({ apiKey: '...', provider: 'openai' });

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


---

## Adding Trace ID & Metadata

```ts
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
    }
);

​
Changelog

View Changelog

Stay updated with the latest features, improvements, and bug fixes in the Portkey Node.js SDK by checking the release tags on GitHub.

​
Troubleshooting & Support

​
FAQ

Yes! Portkey’s APIs are OpenAI-compatible. You can use any OpenAI-compatible library by pointing it to the Portkey API endpoint and using your Portkey API key.
Check out our integration docs here.