API Guide - Context7

Authentication

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

bash

Authorization: Bearer CONTEXT7_API_KEY

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

API Methods

Context7 provides two core API methods for retrieving documentation context.

Search Library

Search for available libraries by name. Use this to find the correct library ID before fetching documentation.

Endpoint: GET /api/v2/libs/search

Parameter	Type	Required	Description
`query`	string	Yes	Your question or task (used for relevance ranking)
`libraryName`	string	Yes	Library name to search for (e.g., "react", "nextjs")

Response: Returns an array of matching libraries:

json

[
  {
    "id": "/facebook/react",
    "name": "React",
    "description": "A JavaScript library for building user interfaces",
    "totalSnippets": 1250,
    "trustScore": 95,
    "benchmarkScore": 88,
    "versions": ["v18.2.0", "v17.0.2"]
  }
]

Example:

bash

curl "https://context7.com/api/v2/libs/search?libraryName=react&query=hooks" \
  -H "Authorization: Bearer CONTEXT7_API_KEY"

Get Context

Retrieve documentation context for a specific library. Returns relevant documentation snippets based on your query.

Endpoint: GET /api/v2/context

Parameter	Type	Required	Description
`query`	string	Yes	Your question or task (used for relevance ranking)
`libraryId`	string	Yes	Library identifier from search (e.g., `/facebook/react`)
`type`	string	No	Response format: `json` (default) or `txt`

Response (JSON format): Returns an array of documentation snippets:

json

[
  {
    "title": "Using the Effect Hook",
    "content": "The Effect Hook lets you perform side effects...",
    "source": "react.dev/reference/react/useEffect"
  }
]

Response (Text format): Returns plain text ready for LLM prompts.

Example:

bash

# JSON format (default)
curl "https://context7.com/api/v2/context?libraryId=/facebook/react&query=useEffect" \
  -H "Authorization: Bearer CONTEXT7_API_KEY"

# Text format
curl "https://context7.com/api/v2/context?libraryId=/facebook/react&query=useEffect&type=txt" \
  -H "Authorization: Bearer CONTEXT7_API_KEY"

Complete Workflow Example

python

import requests

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

# Step 1: Search for the library
search_response = requests.get(
    "https://context7.com/api/v2/libs/search",
    headers=headers,
    params={"libraryName": "react", "query": "I need to manage state"}
)
libraries = search_response.json()
best_match = libraries[0]
print(f"Found: {best_match['name']} ({best_match['id']})")

# Step 2: Get documentation context
context_response = requests.get(
    "https://context7.com/api/v2/context",
    headers=headers,
    params={"libraryId": best_match["id"], "query": "How do I use useState?"}
)
docs = context_response.json()

for doc in docs:
    print(f"Title: {doc['title']}")
    print(f"Content: {doc['content'][:200]}...")

<Info> For TypeScript SDK usage with additional features, see [Search Library](/sdks/ts/commands/search-library) and [Get Context](/sdks/ts/commands/get-context). </Info>

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:

json

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

Best Practices

Be Specific with Queries

Use detailed, natural language queries for better results:

bash

# Good - specific question
curl "https://context7.com/api/v2/context?libraryId=/vercel/next.js&query=How%20to%20implement%20authentication%20with%20middleware" \
  -H "Authorization: Bearer CONTEXT7_API_KEY"

# Less optimal - vague query
curl "https://context7.com/api/v2/context?libraryId=/vercel/next.js&query=auth" \
  -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:

python

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:

bash

# Pin to a specific version
curl "https://context7.com/api/v2/context?libraryId=/vercel/next.js/v15.1.8&query=app%20router" \
  -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
202	Accepted - Library not finalized	Wait and retry later
301	Moved - Library redirected	Use the new library ID from `redirectUrl`
400	Bad Request - Invalid parameters	Check query parameters
401	Unauthorized - Invalid API key	Check your API key format (starts with `ctx7sk`)
403	Forbidden - Access denied	Check library access permissions
404	Not Found - Library doesn't exist	Verify the library ID
422	Unprocessable - Library too large/no code	Try a different library
429	Too Many Requests - Rate limit exceeded	Wait for `Retry-After` header, then retry
500	Internal Server Error	Retry with backoff
503	Service Unavailable - Search failed	Retry later

Error Response Format

All errors return a JSON object with these fields:

json

{
  "error": "library_not_found",
  "message": "Library \"/owner/repo\" not found."
}

SDK and Libraries

For TypeScript SDK installation and usage, see the Getting Started guide.