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.mdxindex 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 HandlingThe 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 wnpm 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.mdxindex 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.jsonindex 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"}]}