mirror of
https://github.com/upstash/context7.git
synced 2026-09-14 19:09:34 +08:00
enesakar
226 lines
6.9 KiB
Plaintext
226 lines
6.9 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](/howto/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](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
|
|
|
|
For TypeScript SDK installation and usage, see the [Getting Started guide](/sdks/ts/getting-started).
|