Skip to content

Context7 Platform -- Up-to-date docs for AI agents

CTX7-989: Update API Docs with v2 (#1333)

Fahreddin Özcaneeddc37b2743
diff --git a/docs/api-guide.mdx b/docs/api-guide.mdx
index 46b67677..c70b277b 100644
--- a/docs/api-guide.mdx
+++ b/docs/api-guide.mdx
@@ -34,13 +34,17 @@ When you exceed rate limits, the API returns a `429` status code:
## Best Practices
-### Specify Topics
+### Be Specific with Queries
-Use the `topic` parameter to get more relevant results and reduce unnecessary content:
+Use detailed, natural language queries for better results:
```bash
-# Focus on routing-specific documentation
-curl "https://context7.com/api/v2/docs/code/vercel/next.js?topic=routing" \
+# 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"
```
@@ -76,56 +80,27 @@ Specify exact versions for consistent results across deployments:
```bash
# Pin to a specific version
-curl "https://context7.com/api/v2/docs/code/vercel/next.js/v15.1.8" \
- -H "Authorization: Bearer CONTEXT7_API_KEY"
-```
-
-### Use Pagination for More Results
-
-When you need more documentation snippets, use the `page` parameter to fetch additional pages. The API supports up to 10 pages (100 snippets total) per topic:
-
-```bash
-# Fetch first page
-curl "https://context7.com/api/v2/docs/code/vercel/next.js?topic=routing&page=1" \
- -H "Authorization: Bearer CONTEXT7_API_KEY"
-
-# Fetch next page if needed
-curl "https://context7.com/api/v2/docs/code/vercel/next.js?topic=routing&page=2" \
+curl "https://context7.com/api/v2/context?libraryId=/vercel/next.js/v15.1.8&query=app%20router" \
-H "Authorization: Bearer CONTEXT7_API_KEY"
```
-The response includes pagination metadata to help you navigate:
-
-```json
-{
- "snippets": [...],
- "pagination": {
- "page": 1,
- "limit": 10,
- "totalPages": 5,
- "hasNext": true,
- "hasPrev": false
- }
-}
-```
-
-**Tips:**
-
-- Use specific topics to reduce the total number of pages needed
-- Check `hasNext` before fetching additional pages
-- Combine with version pinning for consistent pagination
-
## Error Handling
The Context7 API uses standard HTTP status codes:
-| Code | Description | Action |
-| ---- | --------------------------------------------- | ------------------------------------------------------------- |
-| 200 | Success | Process the response normally |
-| 401 | Unauthorized - Invalid or missing API key | Check your API key and authentication header |
-| 404 | Not Found - Library or endpoint doesn't exist | Verify the library ID or endpoint URL |
-| 429 | Too Many Requests - Rate limit exceeded | Implement exponential backoff and retry |
-| 500 | Internal Server Error | Retry with exponential backoff, contact support if persistent |
+| 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
@@ -133,8 +108,8 @@ All errors return a JSON object with these fields:
```json
{
- "error": "Error message describing what went wrong",
- "status": 429
+ "error": "library_not_found",
+ "message": "Library \"/owner/repo\" not found."
}
```
@@ -148,14 +123,11 @@ The Context7 Model Context Protocol (MCP) server provides seamless integration w
npm install @upstash/context7-mcp
```
-**Features:**
-
-- Automatic API key management
-- Built-in caching
-- Type-safe library resolution
-- Optimized for AI workflows
+**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 detailed setup instructions.
+See the [Installation guide](https://github.com/upstash/context7#installation) for setup instructions.
### Direct API Integration
@@ -164,7 +136,7 @@ For custom integrations or non-MCP use cases, use the REST endpoints directly. T
**Example (cURL):**
```bash
-curl "https://context7.com/api/v2/docs/code/vercel/next.js?topic=routing" \
+curl "https://context7.com/api/v2/context?libraryId=/vercel/next.js&query=routing" \
-H "Authorization: Bearer CONTEXT7_API_KEY"
```
@@ -177,22 +149,39 @@ headers = {
"Authorization": "Bearer CONTEXT7_API_KEY"
}
-response = requests.get(
- "https://context7.com/api/v2/docs/code/vercel/next.js",
+# Search for a library
+search = requests.get(
+ "https://context7.com/api/v2/libs/search",
headers=headers,
- params={"topic": "routing"}
+ params={"libraryName": "nextjs", "query": "routing"}
)
+library_id = search.json()["results"][0]["id"]
-docs = response.json()
+# 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 response = await fetch("https://context7.com/api/v2/docs/code/vercel/next.js?topic=routing", {
- headers: {
- Authorization: "Bearer CONTEXT7_API_KEY",
- },
-});
-const docs = await response.json();
+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();
```
diff --git a/docs/howto/api-keys.mdx b/docs/howto/api-keys.mdx
index 6278c530..e85f6056 100644
--- a/docs/howto/api-keys.mdx
+++ b/docs/howto/api-keys.mdx
@@ -23,7 +23,7 @@ Generate a new API key in four simple steps:
4. **Use in your requests or add to your MCP configuration**:
```bash
-curl "https://context7.com/api/v2/docs/code/vercel/next.js" \
+curl "https://context7.com/api/v2/context?libraryId=/vercel/next.js&query=routing" \
-H "Authorization: Bearer YOUR_API_KEY"
```
diff --git a/docs/openapi.json b/docs/openapi.json
index d06c5add..a459a85e 100644
--- a/docs/openapi.json
+++ b/docs/openapi.json
@@ -17,35 +17,48 @@
}
],
"paths": {
- "/v2/docs/code/{owner}/{repo}": {
+ "/v2/libs/search": {
"get": {
- "summary": "Get code snippets for a library",
- "description": "Retrieves paginated code examples and API snippets from a library's documentation. Supports filtering by topic and returns results in JSON or text format.",
- "operationId": "getCodeSnippets",
- "tags": ["Retrieve Documentation"],
+ "summary": "Search for libraries",
+ "description": "Search for libraries by name with intelligent LLM-powered ranking based on your query context.",
+ "operationId": "searchLibraries",
+ "tags": ["Search"],
"parameters": [
{
- "$ref": "#/components/parameters/OwnerParam"
- },
- {
- "$ref": "#/components/parameters/RepoParam"
- },
- {
- "$ref": "#/components/parameters/TopicParam"
- },
- {
- "$ref": "#/components/parameters/TypeParam"
- },
- {
- "$ref": "#/components/parameters/PageParam"
+ "$ref": "#/components/parameters/LibraryNameParam"
},
{
- "$ref": "#/components/parameters/LimitParam"
+ "$ref": "#/components/parameters/QueryParam"
}
],
"responses": {
"200": {
- "$ref": "#/components/responses/CodeSnippetsJsonResponse"
+ "description": "Search results ranked by relevance",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SearchResponse"
+ },
+ "example": {
+ "results": [
+ {
+ "id": "/facebook/react",
+ "title": "React",
+ "description": "A JavaScript library for building user interfaces",
+ "branch": "main",
+ "lastUpdateDate": "2025-01-15T10:30:00.000Z",
+ "state": "finalized",
+ "totalTokens": 500000,
+ "totalSnippets": 2500,
+ "stars": 220000,
+ "trustScore": 10,
+ "benchmarkScore": 95.5,
+ "versions": ["v18.2.0", "v17.0.2"]
+ }
+ ]
+ }
+ }
+ }
},
"400": {
"$ref": "#/components/responses/BadRequestError"
@@ -53,95 +66,14 @@
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
- "404": {
- "$ref": "#/components/responses/NotFoundError"
- },
- "202": {
- "$ref": "#/components/responses/AcceptedError"
- },
- "301": {
- "$ref": "#/components/responses/RedirectError"
- },
- "403": {
- "$ref": "#/components/responses/ForbiddenError"
- },
- "422": {
- "$ref": "#/components/responses/UnprocessableEntityError"
- },
"429": {
"$ref": "#/components/responses/RateLimitError"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
- }
- },
- "security": [
- {},
- {
- "bearerAuth": []
- }
- ]
- }
- },
- "/v2/docs/code/{owner}/{repo}/{version}": {
- "get": {
- "summary": "Get code snippets for a specific library version",
- "description": "Retrieves paginated code examples and API snippets from a specific version (tag or branch) of a library's documentation.",
- "operationId": "getCodeSnippetsByVersion",
- "tags": ["Retrieve Documentation"],
- "parameters": [
- {
- "$ref": "#/components/parameters/OwnerParam"
- },
- {
- "$ref": "#/components/parameters/RepoParam"
- },
- {
- "$ref": "#/components/parameters/VersionParam"
- },
- {
- "$ref": "#/components/parameters/TopicParam"
- },
- {
- "$ref": "#/components/parameters/TypeParam"
- },
- {
- "$ref": "#/components/parameters/PageParam"
},
- {
- "$ref": "#/components/parameters/LimitParam"
- }
- ],
- "responses": {
- "200": {
- "$ref": "#/components/responses/CodeSnippetsJsonResponse"
- },
- "400": {
- "$ref": "#/components/responses/BadRequestError"
- },
- "401": {
- "$ref": "#/components/responses/UnauthorizedError"
- },
- "404": {
- "$ref": "#/components/responses/NotFoundError"
- },
- "202": {
- "$ref": "#/components/responses/AcceptedError"
- },
- "301": {
- "$ref": "#/components/responses/RedirectError"
- },
- "403": {
- "$ref": "#/components/responses/ForbiddenError"
- },
- "422": {
- "$ref": "#/components/responses/UnprocessableEntityError"
- },
- "429": {
- "$ref": "#/components/responses/RateLimitError"
- },
- "500": {
- "$ref": "#/components/responses/InternalServerError"
+ "503": {
+ "$ref": "#/components/responses/ServiceUnavailableError"
}
},
"security": [
@@ -152,111 +84,72 @@
]
}
},
- "/v2/docs/info/{owner}/{repo}": {
+ "/v2/context": {
"get": {
- "summary": "Get documentation content for a library",
- "description": "Retrieves paginated informational documentation snippets from a library. Supports filtering by topic and returns results in JSON or text format.",
- "operationId": "getInfoSnippets",
- "tags": ["Retrieve Documentation"],
+ "summary": "Get documentation context",
+ "description": "Retrieve intelligent, LLM-reranked documentation context for natural language queries. Returns the most relevant code snippets and documentation for your specific question.",
+ "operationId": "getContext",
+ "tags": ["Context"],
"parameters": [
{
- "$ref": "#/components/parameters/OwnerParam"
+ "$ref": "#/components/parameters/LibraryIdParam"
},
{
- "$ref": "#/components/parameters/RepoParam"
- },
- {
- "$ref": "#/components/parameters/TopicParam"
+ "$ref": "#/components/parameters/QueryParam"
},
{
"$ref": "#/components/parameters/TypeParam"
- },
- {
- "$ref": "#/components/parameters/PageParam"
- },
- {
- "$ref": "#/components/parameters/LimitParam"
}
],
"responses": {
"200": {
- "$ref": "#/components/responses/InfoSnippetsJsonResponse"
+ "description": "Documentation context",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ContextResponse"
+ },
+ "example": {
+ "codeSnippets": [
+ {
+ "codeTitle": "Middleware Authentication Example",
+ "codeDescription": "Shows how to implement authentication checks in Next.js middleware",
+ "codeLanguage": "typescript",
+ "codeTokens": 150,
+ "codeId": "https://github.com/vercel/next.js/blob/canary/docs/middleware.mdx#_snippet_0",
+ "pageTitle": "Middleware",
+ "codeList": [
+ {
+ "language": "typescript",
+ "code": "import { NextResponse } from 'next/server'\nimport type { NextRequest } from 'next/server'\n\nexport function middleware(request: NextRequest) {\n const token = request.cookies.get('token')\n if (!token) {\n return NextResponse.redirect(new URL('/login', request.url))\n }\n return NextResponse.next()\n}"
+ }
+ ]
+ }
+ ],
+ "infoSnippets": [
+ {
+ "pageId": "https://github.com/vercel/next.js/blob/canary/docs/middleware.mdx",
+ "breadcrumb": "Routing > Middleware",
+ "content": "Middleware allows you to run code before a request is completed...",
+ "contentTokens": 200
+ }
+ ]
+ }
+ },
+ "text/plain": {
+ "schema": {
+ "type": "string"
+ },
+ "example": "### Middleware Authentication Example\n\nSource: https://github.com/vercel/next.js/blob/canary/docs/middleware.mdx\n\nShows how to implement authentication checks in Next.js middleware\n\n```typescript\nimport { NextResponse } from 'next/server'\n...\n```"
+ }
+ }
},
"400": {
"$ref": "#/components/responses/BadRequestError"
},
- "401": {
- "$ref": "#/components/responses/UnauthorizedError"
- },
- "404": {
- "$ref": "#/components/responses/NotFoundError"
- },
- "202": {
- "$ref": "#/components/responses/AcceptedError"
- },
- "301": {
- "$ref": "#/components/responses/RedirectError"
- },
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
- "422": {
- "$ref": "#/components/responses/UnprocessableEntityError"
- },
- "429": {
- "$ref": "#/components/responses/RateLimitError"
- },
- "500": {
- "$ref": "#/components/responses/InternalServerError"
- }
- },
- "security": [
- {},
- {
- "bearerAuth": []
- }
- ]
- }
- },
- "/v2/docs/info/{owner}/{repo}/{version}": {
- "get": {
- "summary": "Get documentation content for a specific library version",
- "description": "Retrieves paginated informational documentation snippets from a specific version (tag or branch) of a library.",
- "operationId": "getInfoSnippetsByVersion",
- "tags": ["Retrieve Documentation"],
- "parameters": [
- {
- "$ref": "#/components/parameters/OwnerParam"
- },
- {
- "$ref": "#/components/parameters/RepoParam"
- },
- {
- "$ref": "#/components/parameters/VersionParam"
- },
- {
- "$ref": "#/components/parameters/TopicParam"
- },
- {
- "$ref": "#/components/parameters/TypeParam"
- },
- {
- "$ref": "#/components/parameters/PageParam"
- },
- {
- "$ref": "#/components/parameters/LimitParam"
- }
- ],
- "responses": {
- "200": {
- "$ref": "#/components/responses/InfoSnippetsJsonResponse"
- },
- "400": {
- "$ref": "#/components/responses/BadRequestError"
- },
- "401": {
- "$ref": "#/components/responses/UnauthorizedError"
- },
"404": {
"$ref": "#/components/responses/NotFoundError"
},
@@ -266,104 +159,9 @@
"301": {
"$ref": "#/components/responses/RedirectError"
},
- "403": {
- "$ref": "#/components/responses/ForbiddenError"
- },
"422": {
"$ref": "#/components/responses/UnprocessableEntityError"
},
- "429": {
- "$ref": "#/components/responses/RateLimitError"
- },
- "500": {
- "$ref": "#/components/responses/InternalServerError"
- }
- },
- "security": [
- {},
- {
- "bearerAuth": []
- }
- ]
- }
- },
- "/v2/search": {
- "get": {
- "summary": "Search for libraries",
- "description": "Search across available libraries. Returns finalized public libraries and accessible private repositories based on authentication.",
- "operationId": "searchLibraries",
- "tags": ["Search Libraries"],
- "parameters": [
- {
- "name": "query",
- "in": "query",
- "description": "Search query string. Returns empty results if not provided.",
- "required": false,
- "schema": {
- "type": "string",
- "maxLength": 500
- },
- "example": "react hooks"
- }
- ],
- "responses": {
- "200": {
- "description": "Successful search response",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "description": "Search results response",
- "properties": {
- "results": {
- "type": "array",
- "description": "Array of matching libraries",
- "items": {
- "$ref": "#/components/schemas/Library"
- }
- }
- },
- "required": ["results"]
- },
- "examples": {
- "withResults": {
- "summary": "Search with results",
- "value": {
- "results": [
- {
- "id": "/vercel/next.js",
- "title": "Next.js",
- "description": "Next.js enables you to create full-stack web applications by extending the latest React features and integrating powerful Rust-based JavaScript tooling for the fastest builds.",
- "branch": "canary",
- "lastUpdateDate": "2025-11-17T22:20:15.784Z",
- "state": "finalized",
- "totalTokens": 824953,
- "totalSnippets": 3336,
- "stars": 131745,
- "trustScore": 10,
- "benchmarkScore": 91.1,
- "versions": [
- "v14.3.0-canary.87",
- "v13.5.11",
- "v15.1.8",
- "v15.4.0-canary.82",
- "v12.3.7",
- "v11.1.3"
- ]
- }
- ]
- }
- },
- "emptyQuery": {
- "summary": "Empty query returns no results",
- "value": {
- "results": []
- }
- }
- }
- }
- }
- },
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
@@ -392,52 +190,51 @@
}
},
"parameters": {
- "OwnerParam": {
- "name": "owner",
- "in": "path",
- "description": "Repository owner - GitHub username or organization name (case-insensitive)",
+ "LibraryNameParam": {
+ "name": "libraryName",
+ "in": "query",
+ "description": "Library name to search for (e.g., 'react', 'nextjs', 'express')",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
- "example": "vercel"
+ "example": "react"
},
- "RepoParam": {
- "name": "repo",
- "in": "path",
- "description": "Repository name (case-insensitive)",
+ "QueryParam": {
+ "name": "query",
+ "in": "query",
+ "description": "User's original question or task - used for intelligent relevance ranking",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
- "example": "next.js"
+ "example": "How to manage state with hooks"
},
- "VersionParam": {
- "name": "version",
- "in": "path",
- "description": "Specific version (tag or branch) of the library",
+ "LibraryIdParam": {
+ "name": "libraryId",
+ "in": "query",
+ "description": "Context7-compatible library ID in format `/owner/repo` or `/owner/repo/version`",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
- "maxLength": 500
- },
- "example": "v14.0.0"
- },
- "TopicParam": {
- "name": "topic",
- "in": "query",
- "description": "Filter snippets by topic or search term",
- "required": false,
- "schema": {
- "type": "string",
- "maxLength": 500
+ "maxLength": 500,
+ "pattern": "^/[^/]+/[^/]+(/[^/]+)?$"
},
- "example": "authentication"
+ "examples": {
+ "basic": {
+ "summary": "Basic library ID",
+ "value": "/vercel/next.js"
+ },
+ "withVersion": {
+ "summary": "With specific version",
+ "value": "/vercel/next.js/v14.3.0"
+ }
+ }
},
"TypeParam": {
"name": "type",
@@ -450,34 +247,98 @@
"default": "txt"
},
"example": "json"
- },
- "PageParam": {
- "name": "page",
- "in": "query",
- "description": "Page number for pagination (1-indexed). Maximum 10 pages accessible for each topic.",
- "required": false,
- "schema": {
- "type": "integer",
- "minimum": 1,
- "default": 1
- },
- "example": 1
- },
- "LimitParam": {
- "name": "limit",
- "in": "query",
- "description": "Number of items per page",
- "required": false,
- "schema": {
- "type": "integer",
- "minimum": 1,
- "maximum": 10,
- "default": 10
- },
- "example": 10
}
},
"schemas": {
+ "Library": {
+ "type": "object",
+ "description": "Library metadata",
+ "properties": {
+ "id": {
+ "type": "string",
+ "description": "Library ID in format `/owner/repo`",
+ "example": "/vercel/next.js"
+ },
+ "title": {
+ "type": "string",
+ "description": "Display name of the library",
+ "example": "Next.js"
+ },
+ "description": {
+ "type": "string",
+ "description": "Short description",
+ "example": "The React Framework"
+ },
+ "branch": {
+ "type": "string",
+ "description": "Git branch being tracked",
+ "example": "canary"
+ },
+ "lastUpdateDate": {
+ "type": "string",
+ "format": "date-time",
+ "description": "ISO 8601 timestamp of last update",
+ "example": "2025-01-15T10:30:00.000Z"
+ },
+ "state": {
+ "type": "string",
+ "enum": ["finalized", "initial", "processing", "error", "delete"],
+ "description": "Processing state of the library",
+ "example": "finalized"
+ },
+ "totalTokens": {
+ "type": "integer",
+ "description": "Total tokens in documentation",
+ "example": 607822
+ },
+ "totalSnippets": {
+ "type": "integer",
+ "description": "Number of code snippets",
+ "example": 3629
+ },
+ "stars": {
+ "type": "integer",
+ "description": "GitHub stars count",
+ "example": 131745
+ },
+ "trustScore": {
+ "type": "integer",
+ "description": "Source reputation score (0-10)",
+ "minimum": 0,
+ "maximum": 10,
+ "example": 10
+ },
+ "benchmarkScore": {
+ "type": "number",
+ "description": "Quality indicator score (0-100)",
+ "minimum": 0,
+ "maximum": 100,
+ "example": 95.5
+ },
+ "versions": {
+ "type": "array",
+ "description": "Available version tags",
+ "items": {
+ "type": "string"
+ },
+ "example": ["v15.1.8", "v14.3.0"]
+ }
+ }
+ },
+ "SearchResponse": {
+ "type": "object",
+ "description": "Search results response",
+ "properties": {
+ "results": {
+ "type": "array",
+ "description": "Array of matching libraries ranked by relevance",
+ "items": {
+ "$ref": "#/components/schemas/Library"
+ }
+ }
+ },
+ "required": ["results"]
+ },
"CodeSnippet": {
"type": "object",
"description": "A code snippet from library documentation",
@@ -492,7 +353,7 @@
},
"codeLanguage": {
"type": "string",
- "description": "Primary programming language of the snippet"
+ "description": "Primary programming language"
},
"codeTokens": {
"type": "integer",
@@ -500,29 +361,21 @@
},
"codeId": {
"type": "string",
- "description": "Unique identifier for the code snippet"
+ "description": "URL to source location"
},
"pageTitle": {
"type": "string",
- "description": "Title of the documentation page containing this snippet"
+ "description": "Title of the documentation page"
},
"codeList": {
"type": "array",
- "description": "List of code examples in different languages",
+ "description": "Code examples in different languages",
"items": {
"$ref": "#/components/schemas/CodeExample"
}
}
},
- "required": [
- "codeTitle",
- "codeDescription",
- "codeLanguage",
- "codeTokens",
- "codeId",
- "pageTitle",
- "codeList"
- ]
+ "required": ["codeTitle", "codeDescription", "codeLanguage", "codeTokens", "codeId", "pageTitle", "codeList"]
},
"CodeExample": {
"type": "object",
@@ -530,7 +383,7 @@
"properties": {
"language": {
"type": "string",
- "description": "Programming language of this code example"
+ "description": "Programming language"
},
"code": {
"type": "string",
@@ -541,11 +394,11 @@
},
"InfoSnippet": {
"type": "object",
- "description": "A documentation/info snippet from library",
+ "description": "A documentation snippet",
"properties": {
"pageId": {
"type": "string",
- "description": "Unique page identifier"
+ "description": "URL to source page"
},
"breadcrumb": {
"type": "string",
@@ -562,114 +415,34 @@
},
"required": ["content", "contentTokens"]
},
- "Pagination": {
- "type": "object",
- "description": "Pagination metadata",
- "properties": {
- "page": {
- "type": "integer",
- "description": "Current page number (1-indexed)",
- "minimum": 1
- },
- "limit": {
- "type": "integer",
- "description": "Items per page",
- "minimum": 1,
- "maximum": 10
- },
- "totalPages": {
- "type": "integer",
- "description": "Total number of pages available for a topic",
- "minimum": 0
- },
- "hasNext": {
- "type": "boolean",
- "description": "Whether a next page exists"
- },
- "hasPrev": {
- "type": "boolean",
- "description": "Whether a previous page exists"
- }
- },
- "required": ["page", "limit", "totalPages", "hasNext", "hasPrev"]
- },
- "Library": {
+ "ContextResponse": {
"type": "object",
- "description": "Library metadata",
+ "description": "Documentation context response",
"properties": {
- "id": {
- "type": "string",
- "description": "Library ID in format `/owner/repo`",
- "example": "/vercel/next.js"
- },
- "title": {
- "type": "string",
- "description": "Display name of the library",
- "example": "Next.js"
- },
- "description": {
- "type": "string",
- "description": "Short description",
- "example": "The React Framework"
- },
- "branch": {
- "type": "string",
- "description": "Git branch being tracked",
- "example": "canary"
- },
- "lastUpdateDate": {
- "type": "string",
- "format": "date-time",
- "description": "ISO 8601 timestamp of last update",
- "example": "2025-07-27T06:56:26.691Z"
- },
- "state": {
- "type": "string",
- "enum": ["finalized", "initial", "processing", "error", "delete"],
- "description": "Processing state of the library",
- "example": "finalized"
- },
- "totalTokens": {
- "type": "integer",
- "description": "Total tokens in documentation",
- "example": 607822
- },
- "totalSnippets": {
- "type": "integer",
- "description": "Number of code snippets",
- "example": 3629
- },
- "stars": {
- "type": "integer",
- "description": "GitHub stars count",
- "example": 131745
- },
- "trustScore": {
- "type": "integer",
- "description": "Source reputation score (0-10, used internally to determine High/Medium/Low/Unknown reputation)",
- "minimum": 0,
- "maximum": 10,
- "example": 10
- },
- "benchmarkScore": {
- "type": "number",
- "description": "Quality indicator score (0-100, with 100 being the highest quality)",
- "minimum": 0,
- "maximum": 100,
- "example": 95.5
+ "codeSnippets": {
+ "type": "array",
+ "description": "Relevant code snippets",
+ "items": {
+ "$ref": "#/components/schemas/CodeSnippet"
+ }
},
- "versions": {
+ "infoSnippets": {
"type": "array",
- "description": "Available version tags",
+ "description": "Relevant documentation snippets",
"items": {
- "type": "string"
- },
- "example": ["v15.1.8", "v14.3.0-canary.87"]
+ "$ref": "#/components/schemas/InfoSnippet"
+ }
+ },
+ "rules": {
+ "type": "object",
+ "description": "Optional library-specific rules"
}
- }
+ },
+ "required": ["codeSnippets", "infoSnippets"]
},
"Error": {
"type": "object",
+ "description": "Standard error response",
"properties": {
"error": {
"type": "string",
@@ -686,7 +459,7 @@
},
"required": ["error"]
},
- "ValidationError": {
+ "RedirectErrorResponse": {
"allOf": [
{
"$ref": "#/components/schemas/Error"
@@ -694,386 +467,114 @@
{
"type": "object",
"properties": {
- "maxLimit": {
- "type": "integer",
- "description": "Maximum allowed limit value (only present for limit exceeded errors)"
- },
"redirectUrl": {
"type": "string",
- "description": "New location of the library (only present for redirect errors)"
+ "description": "New location of the library"
}
}
}
]
}
},
- "headers": {
- "X-Context7-Page": {
- "description": "Current page number (1-indexed). Only returned for text/plain responses (type=txt).",
- "schema": {
- "type": "integer",
- "minimum": 1
- },
- "example": 1
- },
- "X-Context7-Limit": {
- "description": "Number of items per page. Only returned for text/plain responses (type=txt).",
- "schema": {
- "type": "integer",
- "minimum": 1,
- "maximum": 10
- },
- "example": 10
- },
- "X-Context7-Total-Pages": {
- "description": "Total number of pages available. Only returned for text/plain responses (type=txt).",
- "schema": {
- "type": "integer",
- "minimum": 0
- },
- "example": 10
- },
- "X-Context7-Has-Next": {
- "description": "Whether a next page exists. Only returned for text/plain responses (type=txt).",
- "schema": {
- "type": "string",
- "enum": ["true", "false"]
- },
- "example": "true"
- },
- "X-Context7-Has-Prev": {
- "description": "Whether a previous page exists. Only returned for text/plain responses (type=txt).",
- "schema": {
- "type": "string",
- "enum": ["true", "false"]
- },
- "example": "false"
- },
- "X-Context7-Total-Tokens": {
- "description": "Total token count for the current page. Only returned for text/plain responses (type=txt).",
- "schema": {
- "type": "integer",
- "minimum": 0
- },
- "example": 1500
- }
- },
"responses": {
- "CodeSnippetsJsonResponse": {
- "description": "Successful response with code snippets",
+ "BadRequestError": {
+ "description": "Bad Request - Invalid input parameters",
"content": {
"application/json": {
"schema": {
- "type": "object",
- "description": "Response containing code snippets",
- "properties": {
- "snippets": {
- "type": "array",
- "description": "Array of code snippets",
- "items": {
- "$ref": "#/components/schemas/CodeSnippet"
- }
- },
- "totalTokens": {
- "type": "integer",
- "description": "Total token count for all returned snippets"
- },
- "pagination": {
- "$ref": "#/components/schemas/Pagination"
- }
- },
- "required": ["snippets", "totalTokens", "pagination"]
- },
- "example": {
- "snippets": [
- {
- "codeTitle": "Create and Run Next.js App with create-next-app (Quick Start)",
- "codeDescription": "Quickly set up and start a new Next.js application using `create-next-app` with various package managers. This command creates a new project directory, installs dependencies, and starts the development server. The `--yes` flag skips interactive prompts, enabling a default setup with TypeScript, Tailwind, ESLint, App Router, and Turbopack.",
- "codeLanguage": "bash",
- "codeTokens": 185,
- "codeId": "https://github.com/vercel/next.js/blob/canary/docs/01-app/01-getting-started/01-installation.mdx#_snippet_0",
- "pageTitle": "Installation",
- "codeList": [
- {
- "language": "bash",
- "code": "pnpm create next-app@latest my-app --yes\ncd my-app\npnpm dev"
- },
- {
- "language": "bash",
- "code": "npx create-next-app@latest my-app --yes\ncd my-app\nnpm run dev"
- },
- {
- "language": "bash",
- "code": "yarn create next-app@latest my-app --yes\ncd my-app\nyarn dev"
- },
- {
- "language": "bash",
- "code": "bun create next-app@latest my-app --yes\ncd my-app\nbun dev"
- }
- ]
- }
- ],
- "totalTokens": 185,
- "pagination": {
- "page": 1,
- "limit": 10,
- "totalPages": 10,
- "hasNext": true,
- "hasPrev": false
- }
- }
- },
- "text/plain": {
- "schema": {
- "type": "string",
- "description": "Plain text formatted documentation."
+ "$ref": "#/components/schemas/Error"
},
- "example": "### Create and Run Next.js App with create-next-app (Quick Start)\n\nSource: https://github.com/vercel/next.js/blob/canary/docs/01-app/01-getting-started/01-installation.mdx\n\nQuickly set up and start a new Next.js application using `create-next-app` with various package managers. This command creates a new project directory, installs dependencies, and starts the development server. The `--yes` flag skips interactive prompts, enabling a default setup with TypeScript, Tailwind, ESLint, App Router, and Turbopack.\n\n```bash\npnpm create next-app@latest my-app --yes\ncd my-app\npnpm dev\n```\n\n```bash\nnpx create-next-app@latest my-app --yes\ncd my-app\nnpm run dev\n```\n\n```bash\nyarn create next-app@latest my-app --yes\ncd my-app\nyarn dev\n```\n\n```bash\nbun create next-app@latest my-app --yes\ncd my-app\nbun dev\n```"
- }
- },
- "headers": {
- "X-Context7-Page": {
- "$ref": "#/components/headers/X-Context7-Page"
- },
- "X-Context7-Limit": {
- "$ref": "#/components/headers/X-Context7-Limit"
- },
- "X-Context7-Total-Pages": {
- "$ref": "#/components/headers/X-Context7-Total-Pages"
- },
- "X-Context7-Has-Next": {
- "$ref": "#/components/headers/X-Context7-Has-Next"
- },
- "X-Context7-Has-Prev": {
- "$ref": "#/components/headers/X-Context7-Has-Prev"
- },
- "X-Context7-Total-Tokens": {
- "$ref": "#/components/headers/X-Context7-Total-Tokens"
- }
- }
- },
- "InfoSnippetsJsonResponse": {
- "description": "Successful response with info/documentation snippets",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "description": "Response containing info/documentation snippets",
- "properties": {
- "snippets": {
- "type": "array",
- "description": "Array of info snippets",
- "items": {
- "$ref": "#/components/schemas/InfoSnippet"
- }
- },
- "totalTokens": {
- "type": "integer",
- "description": "Total token count for all returned snippets"
- },
- "pagination": {
- "$ref": "#/components/schemas/Pagination"
+ "examples": {
+ "validationError": {
+ "summary": "Validation error",
+ "value": {
+ "error": "validation_error",
+ "message": "Library name is required"
}
},
- "required": ["snippets", "totalTokens", "pagination"]
- },
- "example": {
- "snippets": [
- {
- "pageId": "https://github.com/vercel/next.js/blob/canary/docs/04-community/01-contribution-guide.mdx",
- "breadcrumb": "How to Contribute > Writing MDX",
- "content": "The docs are written in [MDX](https://mdxjs.com/), a markdown format that supports JSX syntax. This allows us to embed React components in the docs. See the [GitHub Markdown Guide](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) for a quick overview of markdown syntax.",
- "contentTokens": 84
+ "invalidLibraryId": {
+ "summary": "Invalid library ID format",
+ "value": {
+ "error": "invalid_library_id",
+ "message": "Invalid library ID format. Expected: /owner/repo or /owner/repo/version"
}
- ],
- "totalTokens": 84,
- "pagination": {
- "page": 1,
- "limit": 10,
- "totalPages": 10,
- "hasNext": true,
- "hasPrev": false
}
}
- },
- "text/plain": {
- "schema": {
- "type": "string",
- "description": "Plain text formatted documentation."
- },
- "example": "### How to Contribute > Writing MDX\n\nSource: https://github.com/vercel/next.js/blob/canary/docs/04-community/01-contribution-guide.mdx\n\nThe docs are written in [MDX](https://mdxjs.com/), a markdown format that supports JSX syntax. This allows us to embed React components in the docs. See the [GitHub Markdown Guide](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) for a quick overview of markdown syntax."
- }
- },
- "headers": {
- "X-Context7-Page": {
- "$ref": "#/components/headers/X-Context7-Page"
- },
- "X-Context7-Limit": {
- "$ref": "#/components/headers/X-Context7-Limit"
- },
- "X-Context7-Total-Pages": {
- "$ref": "#/components/headers/X-Context7-Total-Pages"
- },
- "X-Context7-Has-Next": {
- "$ref": "#/components/headers/X-Context7-Has-Next"
- },
- "X-Context7-Has-Prev": {
- "$ref": "#/components/headers/X-Context7-Has-Prev"
- },
- "X-Context7-Total-Tokens": {
- "$ref": "#/components/headers/X-Context7-Total-Tokens"
}
}
},
- "BadRequestError": {
- "description": "Bad Request - Invalid input parameters",
+ "ForbiddenError": {
+ "description": "Forbidden - Access denied",
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/ValidationError"
+ "$ref": "#/components/schemas/Error"
},
- "examples": {
- "invalidInput": {
- "summary": "Multiple source parameters provided",
- "value": {
- "error": "invalid_input",
- "message": "Provide exactly one of: docsRepoUrl or llmstxtUrl",
- "status": 400
- }
- },
- "invalidFormat": {
- "summary": "Invalid library format (v2 endpoints)",
- "value": {
- "error": "invalid_format",
- "message": "Invalid library format. Expected: owner/repo[/version]"
- }
- },
- "invalidLength": {
- "summary": "Invalid parameter length",
- "value": {
- "error": "invalid_length",
- "message": "Invalid owner or repo name. Must be 1-500 characters."
- }
- },
- "invalidType": {
- "summary": "Invalid type parameter",
- "value": {
- "error": "invalid_type",
- "message": "Invalid type parameter. Supported values: json, txt"
- }
- },
- "invalidPage": {
- "summary": "Invalid page number",
- "value": {
- "error": "invalid_page",
- "message": "Invalid page number. Must be a positive integer."
- }
- },
- "invalidLimit": {
- "summary": "Limit exceeds maximum",
- "value": {
- "error": "invalid_limit",
- "message": "Items per page exceeds maximum allowed (10)",
- "maxLimit": 10
- }
- },
- "invalidLlmstxtUrl": {
- "summary": "Invalid llms.txt URL",
- "value": {
- "error": "invalid_llmstxt_url",
- "message": "llmstxtUrl must end with llms.txt, llms-full.txt, or llms-small.txt",
- "status": 400
- }
- }
+ "example": {
+ "error": "access_denied",
+ "message": "Access denied: Library /owner/repo is not included in your allowed libraries"
}
}
}
},
- "UnauthorizedError": {
- "description": "Unauthorized - Invalid or missing API key, or access denied",
+ "NotFoundError": {
+ "description": "Not Found - Library or resource doesn't exist",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
- "invalidApiKey": {
- "summary": "Invalid API key",
+ "libraryNotFound": {
+ "summary": "Library not found",
"value": {
- "error": "invalid_api_key",
- "message": "Invalid or expired API key",
- "status": 401
+ "error": "library_not_found",
+ "message": "Library \"/owner/repo\" not found. Please check the library ID or your access permissions."
}
},
- "accessDenied": {
- "summary": "Access denied to library",
+ "tagNotFound": {
+ "summary": "Version tag not found",
"value": {
- "error": "access_denied",
- "message": "Access denied: Library /vercel/next.js is not included in your allowed libraries"
+ "error": "tag_not_found",
+ "message": "Tag \"v1.0.0\" not found for library \"/owner/repo\". Available tags: v2.0.0, v1.5.0"
}
},
- "authenticationFailed": {
- "summary": "Authentication failed",
+ "noSnippetsFound": {
+ "summary": "No snippets found",
"value": {
- "error": "authentication_failed",
- "message": "Failed to authenticate API key",
- "status": 401
+ "error": "no_snippets_found",
+ "message": "Could not fetch documentation snippets from the library."
}
}
}
}
}
},
- "ForbiddenError": {
- "description": "Forbidden - Insufficient permissions or blocked library",
+ "InternalServerError": {
+ "description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
- "examples": {
- "insufficientPermissions": {
- "summary": "Insufficient permissions",
- "value": {
- "error": "insufficient_permissions",
- "message": "Insufficient permissions",
- "status": 403
- }
- },
- "libraryBlocked": {
- "summary": "Library has been blocked",
- "value": {
- "error": "library_blocked",
- "message": "Library /owner/repo has been blocked by system."
- }
- }
+ "example": {
+ "error": "internal_server_error",
+ "message": "An internal error occurred while processing your request.",
+ "status": 500
}
}
}
},
- "NotFoundError": {
- "description": "Not Found - Library, project, or resource doesn't exist",
+ "ServiceUnavailableError": {
+ "description": "Service Unavailable - Search failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
- "examples": {
- "libraryNotFound": {
- "summary": "Library not found",
- "value": {
- "error": "library_not_found",
- "message": "Library /owner/repo not found. You can add it at context7.com/add-library",
- "status": 404
- }
- },
- "tagNotFound": {
- "summary": "Version/tag not found",
- "value": {
- "error": "tag_not_found",
- "message": "Tag 'v1.0.0' not found for library /owner/repo"
- }
- }
+ "example": {
+ "error": "search_failed",
+ "message": "Search failed: Service temporarily unavailable"
}
}
}
@@ -1097,7 +598,7 @@
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/ValidationError"
+ "$ref": "#/components/schemas/RedirectErrorResponse"
},
"example": {
"error": "library_redirected",
@@ -1133,60 +634,56 @@
}
}
},
- "RateLimitError": {
- "description": "Too Many Requests - Rate limit exceeded",
+ "UnauthorizedError": {
+ "description": "Unauthorized - Invalid or missing API key",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
- "error": "Too many requests",
- "status": 429
+ "error": "invalid_api_key",
+ "message": "Invalid API key. Please check your API key. API keys should start with 'ctx7sk' prefix."
}
}
}
},
- "InternalServerError": {
- "description": "Internal Server Error",
+ "RateLimitError": {
+ "description": "Too Many Requests - Rate limit exceeded",
+ "headers": {
+ "Retry-After": {
+ "description": "Seconds until rate limit resets",
+ "schema": {
+ "type": "integer"
+ }
+ },
+ "RateLimit-Limit": {
+ "description": "Request limit",
+ "schema": {
+ "type": "integer"
+ }
+ },
+ "RateLimit-Remaining": {
+ "description": "Remaining requests",
+ "schema": {
+ "type": "integer"
+ }
+ },
+ "RateLimit-Reset": {
+ "description": "Unix timestamp when limit resets",
+ "schema": {
+ "type": "integer"
+ }
+ }
+ },
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
- "examples": {
- "generic": {
- "summary": "Generic internal error",
- "value": {
- "error": "internal_server_error",
- "message": "An internal error occurred while processing your request.",
- "status": 500
- }
- },
- "serverConfiguration": {
- "summary": "Server configuration error",
- "value": {
- "error": "server_configuration",
- "message": "Server configuration error",
- "status": 500
- }
- },
- "databaseError": {
- "summary": "Database operation failed",
- "value": {
- "error": "database_error",
- "message": "Failed to save private repository",
- "status": 500
- }
- },
- "processingFailed": {
- "summary": "Library processing failed",
- "value": {
- "error": "processing_failed",
- "message": "Failed to process library",
- "status": 500
- }
- }
+ "example": {
+ "error": "Too Many Requests",
+ "message": "Rate limit exceeded. Please try again in 60 seconds."
}
}
}
@@ -1195,12 +692,12 @@
},
"tags": [
{
- "name": "Retrieve Documentation",
- "description": "Retrieve library documentation and code examples"
+ "name": "Search",
+ "description": "Search for libraries in the Context7 database"
},
{
- "name": "Search Libraries",
- "description": "Search for libraries in the Context7 database"
+ "name": "Context",
+ "description": "Retrieve documentation context for queries"
}
]
}