Skip to main content

​
Constructor

Create a new Context7 client instance: 
import { Context7 } from '@upstash/context7-sdk';

const client = new Context7(config);

​
Parameters

​
config
Context7Config
default:"{}"
Configuration object for the client

​
Returns

A configured Context7 client instance.

​
Throws

  • Context7Error: If no API key is provided and CONTEXT7_API_KEY environment variable is not set

​
Configuration Options

​
Using Environment Variables

The recommended approach for production applications: 
// Set environment variable
process.env.CONTEXT7_API_KEY = 'ctx7sk-your-api-key';

// Initialize without config
const client = new Context7();

​
Using Direct Configuration

Useful for testing or when you need multiple clients: 
const client = new Context7({
  apiKey: 'ctx7sk-your-api-key'
});

​
Priority Order

When both methods are used, the constructor parameter takes precedence: 
process.env.CONTEXT7_API_KEY = 'ctx7sk-env-key';

const client = new Context7({
  apiKey: 'ctx7sk-config-key' // This one will be used
});

​
Built-in Features

The client automatically configures several features:

​
Automatic Retries

Failed requests are retried up to 5 times with exponential backoff:
  • Retry 1: ~50ms delay
  • Retry 2: ~135ms delay
  • Retry 3: ~403ms delay
  • Retry 4: ~1.1s delay
  • Retry 5: ~3s delay

​
Authentication

API key is automatically included in all requests as a Bearer token in the Authorization header.

​
Cache Control

Requests are configured with cache: "no-store" to ensure fresh results.

​
Error Handling

​
Missing API Key

try {
  const client = new Context7(); // No API key provided
} catch (error) {
  if (error instanceof Context7Error) {
    console.error(error.message);
    // "API key is required. Pass it in the config or set CONTEXT7_API_KEY environment variable."
  }
}

​
Invalid API Key Format

If your API key doesn’t start with ctx7sk, you’ll see a warning: 
const client = new Context7({ apiKey: 'invalid-key' });
// Console warning: "API key should start with 'ctx7sk'"

​
Usage Examples

​
Basic Setup

import { Context7 } from '@upstash/context7-sdk';

const client = new Context7({
  apiKey: process.env.CONTEXT7_API_KEY
});

// Client is ready to use
const libraries = await client.searchLibrary('query', 'react');

​
Multiple Clients

Create separate clients for different API keys or use cases: 
const productionClient = new Context7({
  apiKey: process.env.CONTEXT7_PRODUCTION_KEY
});

const testClient = new Context7({
  apiKey: process.env.CONTEXT7_TEST_KEY
});

​
Singleton Pattern

Reuse a single client instance across your application: 
// lib/context7.ts
import { Context7 } from '@upstash/context7-sdk';

export const context7Client = new Context7({
  apiKey: process.env.CONTEXT7_API_KEY
});

// app/api/search/route.ts
import { context7Client } from '@/lib/context7';

export async function GET(request: Request) {
  const libraries = await context7Client.searchLibrary('query', 'react');
  return Response.json(libraries);
}

​
Edge Runtime (Next.js, Cloudflare Workers)

The SDK works in edge runtimes: 
// app/api/docs/route.ts
import { Context7 } from '@upstash/context7-sdk';

export const runtime = 'edge';

export async function GET(request: Request) {
  const client = new Context7({
    apiKey: process.env.CONTEXT7_API_KEY
  });
  
  const docs = await client.getContext('hooks', '/facebook/react');
  return Response.json(docs);
}

​
Type Definitions

​
Context7Config

interface Context7Config {
  apiKey?: string;
}

​
Context7Error

class Context7Error extends Error {
  name: 'Context7Error';
  message: string;
}

​
Available Methods

Once initialized, the client provides two main methods:

searchLibrary

Search for libraries by name and query

getContext

Retrieve documentation snippets for a library

Build docs developers (and LLMs) love

Get started for freeTalk to us