---
title: API Guide
description: 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:
```bash
Authorization: Bearer CONTEXT7_API_KEY
```
Get your API key at [context7.com/dashboard](https://context7.com/dashboard). Learn more about [creating and managing API keys](/dashboard/api-keys).
<Warning>
Store your API key in an environment variable or secret manager. Rotate it if compromised.
</Warning>
## 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](https://context7.com/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
### MCP Server (Recommended)
The Context7 Model Context Protocol (MCP) server provides seamless integration with Claude and other AI tools:
```bash
npm install @upstash/context7-mcp
```
**Tools provided:**
- `resolve-library-id`: Search for libraries and get their Context7 IDs
- `query-docs`: Get documentation context for your questions
See the [Installation guide](https://github.com/upstash/context7#installation) for 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):**
```bash
curl "https://context7.com/api/v2/context?libraryId=/vercel/next.js&query=routing" \
-H "Authorization: Bearer CONTEXT7_API_KEY"
```
**Example (Python):**
```python
import requests
headers = {
"Authorization": "Bearer CONTEXT7_API_KEY"
}
# Search for a library
search = requests.get(
"https://context7.com/api/v2/libs/search",
headers=headers,
params={"libraryName": "nextjs", "query": "routing"}
)
library_id = search.json()["results"][0]["id"]
# Get documentation context
response = requests.get(
"https://context7.com/api/v2/context",
headers=headers,
params={"libraryId": library_id, "query": "How to setup dynamic routes"}
)
print(response.text)
```
**Example (JavaScript/Node.js):**
```javascript
const headers = { Authorization: "Bearer CONTEXT7_API_KEY" };
// Search for a library
const search = await fetch(
"https://context7.com/api/v2/libs/search?libraryName=react&query=state",
{ headers }
);
const { results } = await search.json();
// Get documentation context
const docs = await fetch(
`https://context7.com/api/v2/context?libraryId=${results[0].id}&query=useState hook`,
{ headers }
);
const context = await docs.text();
```
