mirror of
https://github.com/upstash/context7.git
synced 2026-02-06 07:08:31 +00:00
351 lines
10 KiB
Plaintext
351 lines
10 KiB
Plaintext
---
|
|
title: Public API
|
|
---
|
|
|
|
The Context7 Public API provides programmatic access to library documentation and search functionality.
|
|
|
|
## Base URL
|
|
|
|
```
|
|
https://context7.com/api
|
|
```
|
|
|
|
## Authentication
|
|
|
|
All API requests require authentication using an API key. Include your API key in the `Authorization` header:
|
|
|
|
```
|
|
Authorization: Bearer CONTEXT7_API_KEY
|
|
```
|
|
|
|
Get your API key at [context7.com/dashboard](https://context7.com/dashboard).
|
|
|
|
<Warning>
|
|
Treat your API key like a password. Store it in an environment variable or secret manager and
|
|
rotate it immediately if you suspect it has leaked.
|
|
</Warning>
|
|
|
|
## Endpoints
|
|
|
|
### Get Context
|
|
|
|
Retrieve documentation and code examples for a specific library.
|
|
|
|
#### Request
|
|
|
|
**HTTP Method**: `GET`
|
|
|
|
**Endpoint**: `/v1/[library]`
|
|
|
|
**URL Format**:
|
|
|
|
- `/v1/{owner}/{repo}` - Get latest version
|
|
- `/v1/{owner}/{repo}/{version}` - Get specific version
|
|
|
|
**Examples**:
|
|
|
|
- `/v1/vercel/next.js`
|
|
- `/v1/vercel/next.js/v15.1.8`
|
|
- `/v1/upstash/docs`
|
|
|
|
#### Query Parameters
|
|
|
|
| Parameter | Type | Required | Default | Description |
|
|
| --------- | ------ | -------- | ------- | ------------------------------------------------ |
|
|
| `type` | string | No | `txt` | Format of the response: `txt` or `json` |
|
|
| `topic` | string | No | - | Topic to search/rerank the results |
|
|
| `tokens` | number | No | `10000` | Maximum token count to be included in the result |
|
|
|
|
#### Examples
|
|
|
|
<AccordionGroup>
|
|
<Accordion title="Basic usage (default txt format)">
|
|
```bash
|
|
curl "https://context7.com/api/v1/vercel/next.js" \
|
|
-H "Authorization: Bearer CONTEXT7_API_KEY"
|
|
```
|
|
</Accordion>
|
|
|
|
<Accordion title="Using JSON format">
|
|
```bash curl "https://context7.com/api/v1/vercel/next.js?type=json" \ -H "Authorization: Bearer
|
|
CONTEXT7_API_KEY" ```
|
|
</Accordion>
|
|
|
|
<Accordion title="Specifying a topic">
|
|
```bash curl "https://context7.com/api/v1/vercel/next.js?topic=routing" \ -H "Authorization:
|
|
Bearer CONTEXT7_API_KEY" ```
|
|
</Accordion>
|
|
|
|
<Accordion title="Limiting token count">
|
|
```bash curl "https://context7.com/api/v1/vercel/next.js?tokens=2000" \ -H "Authorization: Bearer
|
|
CONTEXT7_API_KEY" ```
|
|
</Accordion>
|
|
|
|
<Accordion title="Multiple parameters">
|
|
```bash
|
|
curl "https://context7.com/api/v1/vercel/next.js?topic=authentication&tokens=3000&type=txt" \
|
|
-H "Authorization: Bearer CONTEXT7_API_KEY"
|
|
```
|
|
</Accordion>
|
|
</AccordionGroup>
|
|
|
|
#### Response
|
|
|
|
Returns documentation content in the specified format (`txt` or `json`).
|
|
|
|
- `txt` (default) delivers a plain-text block optimised for feeding into LLM contexts.
|
|
- `json` provides a structured payload with metadata, snippets, and sections.
|
|
|
|
```json
|
|
{
|
|
"library": "/vercel/next.js",
|
|
"version": "v15.1.8",
|
|
"topic": "routing",
|
|
"tokens": 2950,
|
|
"chunks": [
|
|
{
|
|
"title": "Middleware overview",
|
|
"content": "Next.js middleware runs before a request is completed...",
|
|
"source": "docs/app/building-your-application/routing/middleware.mdx",
|
|
"url": "https://nextjs.org/docs/app/building-your-application/routing/middleware"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Search Libraries
|
|
|
|
Search for libraries in the Context7 database.
|
|
|
|
#### Request
|
|
|
|
**HTTP Method**: `GET`
|
|
|
|
**Endpoint**: `/v1/search`
|
|
|
|
#### Query Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
| --------- | ------ | -------- | -------------------------- |
|
|
| `query` | string | Yes | Library name to search for |
|
|
|
|
#### Example
|
|
|
|
```bash
|
|
curl "https://context7.com/api/v1/search?query=next.js" \
|
|
-H "Authorization: Bearer CONTEXT7_API_KEY"
|
|
```
|
|
|
|
#### Response
|
|
|
|
Returns up to 50 matching libraries.
|
|
|
|
```json
|
|
{
|
|
"results": [
|
|
{
|
|
"id": "/vercel/next.js",
|
|
"title": "Next.js",
|
|
"description": "The React Framework",
|
|
"branch": "canary",
|
|
"lastUpdateDate": "2025-07-27T06:56:26.691Z",
|
|
"state": "finalized",
|
|
"totalTokens": 607822,
|
|
"totalSnippets": 3629,
|
|
"totalPages": 1156,
|
|
"stars": 131745,
|
|
"trustScore": 10,
|
|
"versions": [
|
|
"v14.3.0-canary.87",
|
|
"v13.5.11",
|
|
"v15.1.8",
|
|
"v15.4.0-canary.82",
|
|
"v12.3.7",
|
|
"v11.1.3"
|
|
]
|
|
}
|
|
],
|
|
"metadata": {
|
|
"authentication": "paid"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Response Fields
|
|
|
|
| Field | Type | Description |
|
|
| ---------------- | ------ | -------------------------------------------------------------- |
|
|
| `id` | string | Library ID in format `/owner/repo` |
|
|
| `title` | string | Display name of the library |
|
|
| `description` | string | Short description |
|
|
| `branch` | string | Git branch being tracked |
|
|
| `lastUpdateDate` | string | ISO 8601 timestamp of last update |
|
|
| `state` | string | Processing state: `finalized`, `initial`, `error`, or `delete` |
|
|
| `totalTokens` | number | Total tokens in documentation |
|
|
| `totalSnippets` | number | Number of code snippets |
|
|
| `totalPages` | number | Number of documentation pages |
|
|
| `stars` | number | GitHub stars count |
|
|
| `trustScore` | number | Authority score (0-10) |
|
|
| `versions` | array | Available version tags |
|
|
|
|
---
|
|
|
|
### Add a Library
|
|
|
|
Submit a new library to Context7 for indexing.
|
|
|
|
#### Request
|
|
|
|
**HTTP Method**: `POST`
|
|
|
|
**Endpoint**: `/v1/add`
|
|
|
|
**Content-Type**: `application/json`
|
|
|
|
#### Request Body
|
|
|
|
| Field | Type | Required | Description |
|
|
| ---------------- | ------ | -------- | ---------------------------------------------------------- |
|
|
| `docsRepoUrl` | string | Yes | GitHub repository URL |
|
|
| `projectTitle` | string | No | Display name for the project |
|
|
| `branch` | string | No | Git branch to parse (default: repository's default branch) |
|
|
| `folders` | array | No | Specific folders to include for documentation |
|
|
| `excludeFolders` | array | No | Folders to exclude from parsing |
|
|
| `excludeFiles` | array | No | Files to exclude from parsing |
|
|
|
|
#### Examples
|
|
|
|
<AccordionGroup>
|
|
<Accordion title="Basic example">
|
|
```bash
|
|
curl -X POST "https://context7.com/api/v1/add" \
|
|
-H "Authorization: Bearer CONTEXT7_API_KEY" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"docsRepoUrl": "https://github.com/okken/pytest-check",
|
|
"projectTitle": "PyTest Check",
|
|
"branch": "main"
|
|
}'
|
|
```
|
|
</Accordion>
|
|
|
|
<Accordion title="With specific branch">
|
|
```bash
|
|
curl -X POST "https://context7.com/api/v1/add" \
|
|
-H "Authorization: Bearer CONTEXT7_API_KEY" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"docsRepoUrl": "https://github.com/pallets/flask",
|
|
"projectTitle": "Flask",
|
|
"branch": "2.0.x"
|
|
}'
|
|
```
|
|
</Accordion>
|
|
|
|
<Accordion title="With included folders">
|
|
```bash
|
|
curl -X POST "https://context7.com/api/v1/add" \
|
|
-H "Authorization: Bearer CONTEXT7_API_KEY" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"docsRepoUrl": "https://github.com/okken/pytest-check",
|
|
"branch": "main",
|
|
"folders": ["docs", "examples"]
|
|
}'
|
|
```
|
|
</Accordion>
|
|
|
|
<Accordion title="With excluded folders">
|
|
```bash
|
|
curl -X POST "https://context7.com/api/v1/add" \
|
|
-H "Authorization: Bearer CONTEXT7_API_KEY" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"docsRepoUrl": "https://github.com/psf/requests",
|
|
"projectTitle": "Requests",
|
|
"branch": "main",
|
|
"excludeFolders": ["tests", "examples"]
|
|
}'
|
|
```
|
|
</Accordion>
|
|
</AccordionGroup>
|
|
|
|
#### Response
|
|
|
|
```json
|
|
{
|
|
"message": "Parsing process started for https://github.com/okken/pytest-check",
|
|
"status": "processing",
|
|
"docsRepoUrl": "https://github.com/okken/pytest-check",
|
|
"projectName": "/okken/pytest-check",
|
|
"description": "A pytest plugin that allows multiple failures per test.",
|
|
"projectTitle": "auto-detected",
|
|
"folders": ["docs", "examples"],
|
|
"excludeFolders": ["archive"],
|
|
"excludeFiles": [
|
|
"CHANGELOG.md",
|
|
"changelog.md",
|
|
"CHANGELOG.mdx",
|
|
"changelog.mdx",
|
|
"LICENSE.md",
|
|
"license.md",
|
|
"CODE_OF_CONDUCT.md",
|
|
"code_of_conduct.md"
|
|
],
|
|
"metadata": {
|
|
"authentication": "paid"
|
|
}
|
|
}
|
|
```
|
|
|
|
The `status` field transitions through `processing → finalized`. Poll the library detail view or call the `/v1/search` endpoint to confirm when parsing completes.
|
|
|
|
## Rate Limits
|
|
|
|
- **Without API key**: Limited requests per IP
|
|
- **With API key**: Higher limits based on your plan
|
|
- View current usage and reset windows in the [dashboard](https://context7.com/dashboard).
|
|
|
|
## Error Codes
|
|
|
|
| Code | Description |
|
|
| ---- | --------------------------------------------- |
|
|
| 200 | Success |
|
|
| 401 | Unauthorized - Invalid or missing API key |
|
|
| 404 | Not Found - Library or endpoint doesn't exist |
|
|
| 429 | Too Many Requests - Rate limit exceeded |
|
|
| 500 | Internal Server Error |
|
|
|
|
```json
|
|
{
|
|
"error": "Too many requests",
|
|
"status": 429,
|
|
"retryAfterSeconds": 60
|
|
}
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
1. **Use appropriate token limits**: Request only the amount of documentation you need
|
|
2. **Specify topics**: Use the `topic` parameter to get more relevant results
|
|
3. **Cache responses**: Store documentation locally to reduce API calls
|
|
4. **Handle rate limits**: Implement exponential backoff for rate limit errors
|
|
5. **Use specific versions**: When possible, specify exact versions for consistent results
|
|
|
|
## SDK and Libraries
|
|
|
|
For easier integration, consider using:
|
|
|
|
- **MCP Server**: `@upstash/context7-mcp` - Model Context Protocol integration
|
|
- **Direct API**: Use the REST endpoints documented above
|
|
|
|
## Support
|
|
|
|
For API support and questions:
|
|
|
|
- Documentation: [docs.context7.com](https://docs.context7.com)
|
|
- GitHub Issues: [github.com/upstash/context7/issues](https://github.com/upstash/context7/issues)
|
|
- Discord: [upstash.com/discord](https://upstash.com/discord)
|