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.

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 with a retryAfterSeconds field indicating when you can retry:

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

Best Practices

Use Appropriate Token Limits

Request only the amount of documentation you need to minimize token usage and response times:

# Fetches 2000 tokens of documentation
curl "https://context7.com/api/v1/vercel/next.js?tokens=2000" \
  -H "Authorization: Bearer CONTEXT7_API_KEY"

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/v1/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:
            retry_after = response.json().get('retryAfterSeconds', 60)
            time.sleep(retry_after)
            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/v1/vercel/next.js/v15.1.8" \
  -H "Authorization: Bearer CONTEXT7_API_KEY"

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,
  "retryAfterSeconds": 60  // Only present for rate limit errors
}

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/v1/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/v1/vercel/next.js",
    headers=headers,
    params={"topic": "routing", "tokens": 5000}
)

docs = response.json()

Example (JavaScript/Node.js):

const response = await fetch(
  "https://context7.com/api/v1/vercel/next.js?topic=routing&tokens=5000",
  {
    headers: {
      "Authorization": "Bearer CONTEXT7_API_KEY"
    }
  }
);

const docs = await response.json();