getContext - Context7

The getContext method retrieves documentation snippets from a specific library, ranked by relevance to your query. This is the core method for getting contextual documentation to feed to LLMs or display to users.

Method Signature

// Returns JSON array (default)
await client.getContext(
  query: string,
  libraryId: string,
  options?: GetContextOptions
): Promise<Documentation[]>

// Returns formatted text
await client.getContext(
  query: string,
  libraryId: string,
  options: GetContextOptions & { type: 'txt' }
): Promise<string>

Parameters

query

string

required

The user’s question or task. Used to rank documentation snippets by relevance.Examples:

"How do I use the useState hook?"
"How to handle form validation?"
"Setting up middleware in Express"

libraryId

string

required

Context7 library ID in the format /owner/repository.Examples:

"/facebook/react"
"/vuejs/core"
"/expressjs/express"
"/microsoft/typescript"

Get library IDs from the searchLibrary method’s results.

options

GetContextOptions

Configuration options for the request

Show properties

type

'json' | 'txt'

default:"'json'"

Response format:

"json": Returns Documentation[] array (default)
"txt": Returns formatted string ready for LLM consumption

Return Types

JSON Format (Default)

Returns an array of Documentation objects:

Documentation[]

array

Array of documentation snippets, ordered by relevance to the query

Show Documentation object

title

string

required

Title or heading of the documentation snippetExample: "Using the useState Hook"

content

string

required

The documentation content. May include markdown-formatted code blocks.Example: "The useState Hook lets you add state to function components..."

source

string

required

Source URL or identifier for the documentation snippetExample: "https://react.dev/reference/react/useState"

Text Format

Returns a pre-formatted string with all documentation snippets, ready to be inserted into an LLM prompt or displayed to users.

Examples

Basic Usage (JSON)

Get structured documentation for a specific query:

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

const client = new Context7({ apiKey: 'ctx7sk-...' });

const docs = await client.getContext(
  'How do I use React hooks?',
  '/facebook/react'
);

console.log(`Found ${docs.length} relevant documentation snippets`);

docs.forEach(doc => {
  console.log(`\nTitle: ${doc.title}`);
  console.log(`Content: ${doc.content}`);
  console.log(`Source: ${doc.source}`);
});

Explicit JSON Format

const docs = await client.getContext(
  'How to create components in Vue?',
  '/vuejs/core',
  { type: 'json' }
);

// TypeScript knows this is Documentation[]
const firstDoc = docs[0];
console.log(firstDoc.title);
console.log(firstDoc.content);

Text Format for LLMs

Get pre-formatted documentation for language model prompts:

const context = await client.getContext(
  'How do I handle errors in Express middleware?',
  '/expressjs/express',
  { type: 'txt' }
);

// Use directly in your LLM prompt
const prompt = `
Relevant documentation:
${context}

Based on the documentation above, answer this question:
${userQuestion}
`;

// Send to your LLM
const response = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [
    { role: 'system', content: prompt },
    { role: 'user', content: userQuestion }
  ]
});

Building a Documentation Chatbot

async function answerQuestion(question: string, framework: string) {
  // First, find the library
  const libraries = await client.searchLibrary(question, framework);
  
  if (libraries.length === 0) {
    return { error: 'Library not found' };
  }
  
  // Get relevant documentation
  const docs = await client.getContext(question, libraries[0].id);
  
  if (docs.length === 0) {
    return { error: 'No relevant documentation found' };
  }
  
  // Format response
  return {
    answer: docs.map(doc => ({
      title: doc.title,
      content: doc.content,
      source: doc.source
    })),
    library: libraries[0].name
  };
}

// Usage
const result = await answerQuestion(
  'How do I use computed properties?',
  'vue'
);

RAG (Retrieval-Augmented Generation) Pattern

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

const context7 = new Context7({ apiKey: process.env.CONTEXT7_API_KEY });
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

async function ragAnswer(question: string, libraryId: string) {
  // Retrieve relevant documentation
  const context = await context7.getContext(question, libraryId, {
    type: 'txt'
  });
  
  // Generate answer using the context
  const completion = await openai.chat.completions.create({
    model: 'gpt-4-turbo',
    messages: [
      {
        role: 'system',
        content: `You are a helpful assistant. Use the following documentation to answer questions accurately.\n\n${context}`
      },
      {
        role: 'user',
        content: question
      }
    ]
  });
  
  return completion.choices[0].message.content;
}

// Usage
const answer = await ragAnswer(
  'How do I optimize React performance?',
  '/facebook/react'
);

Displaying Documentation in UI

async function fetchDocs(topic: string, libraryId: string) {
  const docs = await client.getContext(topic, libraryId);
  
  return docs.map(doc => ({
    id: crypto.randomUUID(),
    title: doc.title,
    content: doc.content,
    sourceUrl: doc.source,
    // Parse markdown content for rendering
    html: markdownToHtml(doc.content)
  }));
}

// In your React component
function DocsPanel({ topic, libraryId }) {
  const [docs, setDocs] = useState([]);
  
  useEffect(() => {
    fetchDocs(topic, libraryId).then(setDocs);
  }, [topic, libraryId]);
  
  return (
    <div>
      {docs.map(doc => (
        <article key={doc.id}>
          <h3>{doc.title}</h3>
          <div dangerouslySetInnerHTML={{ __html: doc.html }} />
          <a href={doc.sourceUrl}>View source</a>
        </article>
      ))}
    </div>
  );
}

Combining Search and Context

async function smartSearch(userQuery: string, searchTerm: string) {
  // Find relevant libraries
  const libraries = await client.searchLibrary(userQuery, searchTerm);
  
  if (libraries.length === 0) {
    return { error: 'No libraries found' };
  }
  
  // Get documentation from the most relevant library
  const topLibrary = libraries[0];
  const docs = await client.getContext(userQuery, topLibrary.id);
  
  return {
    library: topLibrary,
    documentation: docs,
    alternatives: libraries.slice(1, 4) // Next 3 alternatives
  };
}

// Usage
const result = await smartSearch(
  'I need to validate form inputs',
  'react'
);

console.log(`Using: ${result.library.name}`);
console.log(`Found ${result.documentation.length} relevant docs`);

Error Handling

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

try {
  const docs = await client.getContext(
    'How to use components?',
    '/facebook/react'
  );
  
  if (docs.length === 0) {
    console.log('No relevant documentation found for this query');
  }
} catch (error) {
  if (error instanceof Context7Error) {
    console.error('Context7 error:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

Handling Invalid Library IDs

try {
  const docs = await client.getContext(
    'How to use this?',
    '/nonexistent/library'
  );
} catch (error) {
  if (error instanceof Context7Error) {
    console.error('Library not found or access denied');
  }
}

Caching Documentation

class CachedContext7 {
  private cache = new Map<string, Documentation[]>();
  private client: Context7;
  
  constructor(apiKey: string) {
    this.client = new Context7({ apiKey });
  }
  
  async getContext(query: string, libraryId: string): Promise<Documentation[]> {
    const key = `${libraryId}:${query}`;
    
    if (this.cache.has(key)) {
      return this.cache.get(key)!;
    }
    
    const docs = await this.client.getContext(query, libraryId);
    this.cache.set(key, docs);
    
    // Auto-expire after 1 hour
    setTimeout(() => this.cache.delete(key), 60 * 60 * 1000);
    
    return docs;
  }
}

Server-Side API Route (Next.js)

// app/api/docs/route.ts
import { Context7 } from '@upstash/context7-sdk';
import { NextResponse } from 'next/server';

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

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const query = searchParams.get('query');
  const libraryId = searchParams.get('libraryId');
  
  if (!query || !libraryId) {
    return NextResponse.json(
      { error: 'Missing query or libraryId' },
      { status: 400 }
    );
  }
  
  try {
    const docs = await client.getContext(query, libraryId);
    return NextResponse.json({ docs });
  } catch (error) {
    return NextResponse.json(
      { error: 'Failed to fetch documentation' },
      { status: 500 }
    );
  }
}

Type Definitions

GetContextOptions

interface GetContextOptions {
  /**
   * Response format
   * - "json": Returns Documentation[] array (default)
   * - "txt": Returns formatted text string
   */
  type?: 'json' | 'txt';
}

Documentation

interface Documentation {
  /** Title of the documentation snippet */
  title: string;
  
  /** The documentation content (may include code blocks in markdown format) */
  content: string;
  
  /** Source URL or identifier for the snippet */
  source: string;
}

Best Practices

Write Specific Queries

More specific queries return more targeted documentation:

// Less effective - too vague
await client.getContext('React', '/facebook/react');

// More effective - specific question
await client.getContext(
  'How do I use useEffect for data fetching?',
  '/facebook/react'
);

Choose the Right Format

Use JSON when you need to process or display documentation:

const docs = await client.getContext(query, libraryId); // JSON by default

// Process each snippet individually
const titles = docs.map(doc => doc.title);

Use text format when feeding directly to LLMs:

const context = await client.getContext(query, libraryId, { type: 'txt' });

// Ready for LLM prompt
const prompt = `Context: ${context}\n\nQuestion: ${question}`;

Handle Empty Results

const docs = await client.getContext(query, libraryId);

if (docs.length === 0) {
  // Try a broader query or different library
  const alternativeDocs = await client.getContext(
    'general introduction',
    libraryId
  );
}

Process Markdown Content

Documentation content may include markdown. Process it for display:

import { marked } from 'marked';

const docs = await client.getContext(query, libraryId);

const processedDocs = docs.map(doc => ({
  ...doc,
  html: marked(doc.content)
}));

Common Library IDs

Here are some frequently used library IDs:

React: /facebook/react
Vue: /vuejs/core
Express: /expressjs/express
TypeScript: /microsoft/typescript
Next.js: /vercel/next.js
Svelte: /sveltejs/svelte

Use the searchLibrary method to discover library IDs programmatically.

Next Steps

Search Libraries

Learn how to find library IDs using searchLibrary

Client Configuration

Advanced client configuration options

​Method Signature

​Parameters

​Return Types

​JSON Format (Default)

​Text Format

​Examples

​Basic Usage (JSON)

​Explicit JSON Format

​Text Format for LLMs

​Building a Documentation Chatbot

​RAG (Retrieval-Augmented Generation) Pattern

​Displaying Documentation in UI

​Combining Search and Context

​Error Handling

​Handling Invalid Library IDs

​Caching Documentation

​Server-Side API Route (Next.js)

​Type Definitions

​GetContextOptions

​Documentation

​Best Practices

​Write Specific Queries

​Choose the Right Format

​Handle Empty Results

​Process Markdown Content

​Common Library IDs

​Next Steps

Search Libraries

Client Configuration

Method Signature

Parameters

Return Types

JSON Format (Default)

Text Format

Examples

Basic Usage (JSON)

Explicit JSON Format

Text Format for LLMs

Building a Documentation Chatbot

RAG (Retrieval-Augmented Generation) Pattern

Displaying Documentation in UI

Combining Search and Context

Error Handling

Handling Invalid Library IDs

Caching Documentation

Server-Side API Route (Next.js)

Type Definitions

GetContextOptions

Documentation

Best Practices

Write Specific Queries

Choose the Right Format

Handle Empty Results

Process Markdown Content

Common Library IDs

Next Steps