API Guide

Authentication, rate limits, best practices, and integration guides for the Context7 API

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer CONTEXT7_API_KEY

Get your API key at context7.com/dashboard. Learn more about creating and managing API keys.

Store your API key in an environment variable or secret manager. Rotate it if compromised.

Rate Limits

• Without API key: Low rate limits and no custom configuration
• With API key: Higher limits based on your plan
• View current usage and reset windows in the dashboard.

When you exceed rate limits, the API returns a 429 status code:

{
  "error": "Too many requests",
  "status": 429
}

Best Practices

Specify Topics

Use the topic parameter to get more relevant results and reduce unnecessary content:

# Focus on routing-specific documentation
curl "https://context7.com/api/v2/docs/code/vercel/next.js?topic=routing" \
  -H "Authorization: Bearer CONTEXT7_API_KEY"

Cache Responses

Store documentation locally to reduce API calls and improve performance. Documentation updates are relatively infrequent, so caching for several hours or days is usually appropriate.

Handle Rate Limits

Implement exponential backoff for rate limit errors:

import time
import requests

def fetch_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code == 429:
            # Wait before retrying with exponential backoff
            time.sleep(2 ** attempt)
            continue

        return response

    raise Exception("Max retries exceeded")

Use Specific Versions

Specify exact versions for consistent results across deployments:

# Pin to a specific version
curl "https://context7.com/api/v2/docs/code/vercel/next.js/v15.1.8" \
  -H "Authorization: Bearer CONTEXT7_API_KEY"

Use Pagination for More Results

When you need more documentation snippets, use the page parameter to fetch additional pages. The API supports up to 10 pages (100 snippets total) per topic:

# Fetch first page
curl "https://context7.com/api/v2/docs/code/vercel/next.js?topic=routing&page=1" \
  -H "Authorization: Bearer CONTEXT7_API_KEY"

# Fetch next page if needed
curl "https://context7.com/api/v2/docs/code/vercel/next.js?topic=routing&page=2" \
  -H "Authorization: Bearer CONTEXT7_API_KEY"

The response includes pagination metadata to help you navigate:

{
  "snippets": [...],
  "pagination": {
    "page": 1,
    "limit": 10,
    "totalPages": 5,
    "hasNext": true,
    "hasPrev": false
  }
}

Tips:

• Use specific topics to reduce the total number of pages needed
• Check hasNext before fetching additional pages
• Combine with version pinning for consistent pagination

Error Handling

The Context7 API uses standard HTTP status codes:

Code	Description	Action
200	Success	Process the response normally
401	Unauthorized - Invalid or missing API key	Check your API key and authentication header
404	Not Found - Library or endpoint doesn’t exist	Verify the library ID or endpoint URL
429	Too Many Requests - Rate limit exceeded	Implement exponential backoff and retry
500	Internal Server Error	Retry with exponential backoff, contact support if persistent

Error Response Format

All errors return a JSON object with these fields:

{
  "error": "Error message describing what went wrong",
  "status": 429
}

SDK and Libraries

MCP Server (Recommended)

The Context7 Model Context Protocol (MCP) server provides seamless integration with Claude and other AI tools:

npm install @upstash/context7-mcp

Features:

• Automatic API key management
• Built-in caching
• Type-safe library resolution
• Optimized for AI workflows

See the Installation guide for detailed setup instructions.

Direct API Integration

For custom integrations or non-MCP use cases, use the REST endpoints directly. The API is language-agnostic and works with any HTTP client.

Example (cURL):

curl "https://context7.com/api/v2/docs/code/vercel/next.js?topic=routing" \
  -H "Authorization: Bearer CONTEXT7_API_KEY"

Example (Python):

import requests

headers = {
    "Authorization": "Bearer CONTEXT7_API_KEY"
}

response = requests.get(
    "https://context7.com/api/v2/docs/code/vercel/next.js",
    headers=headers,
    params={"topic": "routing"}
)

docs = response.json()

Example (JavaScript/Node.js):

const response = await fetch("https://context7.com/api/v2/docs/code/vercel/next.js?topic=routing", {
  headers: {
    Authorization: "Bearer CONTEXT7_API_KEY",
  },
});
const docs = await response.json();