188 lines
5.7 KiB
Plaintext
188 lines
5.7 KiB
Plaintext
---
|
|
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();
|
|
```
|