wehub-resource-sync
205 lines
8.6 KiB
Plaintext
205 lines
8.6 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
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| [Search Library](/api-reference/search/search-for-libraries) | `GET /api/v2/libs/search` | Find libraries by name |
|
|
| [Get Context](/api-reference/context/get-documentation-context) | `GET /api/v2/context` | Retrieve documentation snippets for a library |
|
|
| [Refresh Library](/api-reference/refresh/refresh-a-library) | `POST /api/v1/refresh` | Refresh a library's documentation |
|
|
| [Get Policies](/api-reference/policies/get-teamspace-policies) | `GET /api/v2/policies` | Retrieve teamspace policy configuration |
|
|
| [Update Policies](/api-reference/policies/update-teamspace-policies) | `PATCH /api/v2/policies` | Update teamspace policies |
|
|
| [Add Library](/api-reference/add-library/add-a-github-repository) | `POST /api/v2/add/repo/{provider}` | Submit a repository for processing |
|
|
| [Add OpenAPI](/api-reference/add-library/add-an-openapi-specification-by-url) | `POST /api/v2/add/openapi` | Submit an OpenAPI spec |
|
|
| [Upload OpenAPI](/api-reference/add-library/upload-an-openapi-specification-file) | `POST /api/v2/add/openapi-upload` | Upload an OpenAPI spec file |
|
|
| [Add LLMs.txt](/api-reference/add-library/add-an-llmstxt-file) | `POST /api/v2/add/llmstxt` | Submit an llms.txt file |
|
|
| [Add Website](/api-reference/add-library/add-a-website) | `POST /api/v2/add/website` | Submit a website for crawling |
|
|
| [Add Confluence](/api-reference/add-library/add-a-confluence-space) | `POST /api/v2/add/confluence` | Submit a Confluence space |
|
|
|
|
## Library ID format
|
|
|
|
A **library ID** is the URL path of the library on context7.com. If the library page is at `https://context7.com/websites/uploadcare_com`, its ID is `/websites/uploadcare_com`. The same ID works for every endpoint that accepts a `libraryId` or `libraryName` — including [Get Context](/api-reference/context/get-documentation-context) and [Refresh Library](/api-reference/refresh/refresh-a-library).
|
|
|
|
Use `/owner/repo` for GitHub repositories, or `/<source>/<id>` for other sources:
|
|
|
|
| Source | Example library ID |
|
|
|--------|--------------------|
|
|
| GitHub repository | `/vercel/next.js` |
|
|
| GitLab / Bitbucket / generic Git repo | `/<owner>/<repo>` (same shape as GitHub) |
|
|
| Website | `/websites/uploadcare_com` |
|
|
| llms.txt source | `/llmstxt/<source>` |
|
|
| npm / package source | `/packages/<name>` or `/npm/<name>` |
|
|
| Uploaded docs | `/docs/<name>` |
|
|
|
|
You can pin a specific version with either `/owner/repo/<version>` or `/owner/repo@<version>`:
|
|
|
|
```
|
|
/vercel/next.js/v15.1.8
|
|
/vercel/next.js@v15.1.8
|
|
```
|
|
|
|
<Tip>
|
|
Don't know the ID for a library? Find it on [context7.com](https://context7.com) — the URL path of the library page **is** the ID. Or call [Search Library](/api-reference/search/search-for-libraries) and use the `id` from the response.
|
|
</Tip>
|
|
|
|
### Complete Workflow Example
|
|
|
|
```python
|
|
import os
|
|
import requests
|
|
|
|
headers = {"Authorization": f"Bearer {os.environ['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"}
|
|
)
|
|
data = search_response.json()
|
|
best_match = data["results"][0]
|
|
print(f"Found: {best_match['title']} ({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?", "type": "json"}
|
|
)
|
|
docs = context_response.json()
|
|
|
|
for snippet in docs["codeSnippets"]:
|
|
print(f"Title: {snippet['codeTitle']}")
|
|
for code in snippet["codeList"]:
|
|
print(f"Code: {code['code'][:200]}...")
|
|
|
|
for info in docs["infoSnippets"]:
|
|
print(f"Content: {info['content'][:200]}...")
|
|
```
|
|
|
|
<Info>
|
|
For TypeScript SDK usage, 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 with these headers:
|
|
|
|
| Header | Description |
|
|
|--------|-------------|
|
|
| `Retry-After` | Seconds until rate limit resets |
|
|
| `RateLimit-Limit` | Total request limit |
|
|
| `RateLimit-Remaining` | Remaining requests in window |
|
|
| `RateLimit-Reset` | Unix timestamp when limit resets |
|
|
|
|
## 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"
|
|
|
|
# Non-GitHub source (website) - same endpoint, same shape
|
|
curl "https://context7.com/api/v2/context?libraryId=/websites/uploadcare_com&query=image%20transformations" \
|
|
-H "Authorization: Bearer CONTEXT7_API_KEY"
|
|
```
|
|
|
|
### Cache Responses
|
|
|
|
Documentation updates are relatively infrequent, so caching responses for several hours or days reduces API calls and improves performance.
|
|
|
|
### 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:
|
|
retry_after = int(response.headers.get("Retry-After", 2 ** attempt))
|
|
time.sleep(retry_after)
|
|
continue
|
|
|
|
return response
|
|
|
|
raise Exception("Max retries exceeded")
|
|
```
|
|
|
|
### Use Specific Versions
|
|
|
|
Pin to a specific version for consistent results. Both `/` and `@` syntax are supported:
|
|
|
|
```bash
|
|
curl "https://context7.com/api/v2/context?libraryId=/vercel/next.js/v15.1.8&query=app%20router" \
|
|
-H "Authorization: Bearer CONTEXT7_API_KEY"
|
|
|
|
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 or plan |
|
|
| 404 | Not Found - Library doesn't exist | Verify the library ID |
|
|
| 409 | Conflict - Resource already exists | The library has already been added |
|
|
| 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 |
|
|
| 504 | Gateway Timeout - Processing timed out | Retry later |
|
|
|
|
All errors return a JSON object with `error` and `message` fields:
|
|
|
|
```json
|
|
{
|
|
"error": "library_not_found",
|
|
"message": "Library \"/owner/repo\" not found. Please check the library ID or your access permissions."
|
|
}
|
|
```
|
|
|
|
For `301` redirects, the response also includes a `redirectUrl` field pointing to the new library ID.
|
|
|
|
## SDK and Libraries
|
|
|
|
For TypeScript SDK installation and usage, see the [Getting Started guide](/sdks/ts/getting-started).
|