Context7 Platform -- Up-to-date docs for AI agents
docs: update for api v2 (#1052)
Enes Gulesf35c002beead
diff --git a/docs/api-guide.mdx b/docs/api-guide.mdxindex 718f50a3..80e78e06 100644--- a/docs/api-guide.mdx+++ b/docs/api-guide.mdx@@ -23,35 +23,24 @@ Get your API key at [context7.com/dashboard](https://context7.com/dashboard). Le- **With API key**: Higher limits based on your plan- View current usage and reset windows in the [dashboard](https://context7.com/dashboard).-When you exceed rate limits, the API returns a `429` status code with a `retryAfterSeconds` field indicating when you can retry:+When you exceed rate limits, the API returns a `429` status code:```json{"error": "Too many requests",- "status": 429,- "retryAfterSeconds": 60+ "status": 429}```## Best Practices-### Use Appropriate Token Limits--Request only the amount of documentation you need to minimize token usage and response times:--```bash-# Fetches 2000 tokens of documentation-curl "https://context7.com/api/v1/vercel/next.js?tokens=2000" \- -H "Authorization: Bearer CONTEXT7_API_KEY"-```-### Specify TopicsUse the `topic` parameter to get more relevant results and reduce unnecessary content:```bash# Focus on routing-specific documentation-curl "https://context7.com/api/v1/vercel/next.js?topic=routing" \+curl "https://context7.com/api/v2/docs/code/vercel/next.js?topic=routing" \-H "Authorization: Bearer CONTEXT7_API_KEY"```@@ -72,8 +61,8 @@ def fetch_with_retry(url, headers, max_retries=3):response = requests.get(url, headers=headers)if response.status_code == 429:- retry_after = response.json().get('retryAfterSeconds', 60)- time.sleep(retry_after)+ # Wait before retrying with exponential backoff+ time.sleep(2 ** attempt)continuereturn response@@ -87,10 +76,44 @@ Specify exact versions for consistent results across deployments:```bash# Pin to a specific version-curl "https://context7.com/api/v1/vercel/next.js/v15.1.8" \+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" \-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:@@ -110,8 +133,7 @@ All errors return a JSON object with these fields:```json{"error": "Error message describing what went wrong",- "status": 429,- "retryAfterSeconds": 60 // Only present for rate limit errors+ "status": 429}```@@ -141,7 +163,7 @@ For custom integrations or non-MCP use cases, use the REST endpoints directly. T**Example (cURL):**```bash-curl "https://context7.com/api/v1/vercel/next.js?topic=routing" \+curl "https://context7.com/api/v2/docs/code/vercel/next.js?topic=routing" \-H "Authorization: Bearer CONTEXT7_API_KEY"```@@ -155,9 +177,9 @@ headers = {}response = requests.get(- "https://context7.com/api/v1/vercel/next.js",+ "https://context7.com/api/v2/docs/code/vercel/next.js",headers=headers,- params={"topic": "routing", "tokens": 5000}+ params={"topic": "routing"})docs = response.json()@@ -167,7 +189,7 @@ docs = response.json()```javascriptconst response = await fetch(- "https://context7.com/api/v1/vercel/next.js?topic=routing&tokens=5000",+ "https://context7.com/api/v2/docs/code/vercel/next.js?topic=routing",{headers: {Authorization: "Bearer CONTEXT7_API_KEY",diff --git a/docs/dashboard/api-keys.mdx b/docs/dashboard/api-keys.mdxindex 56dd7f3f..5c429fd8 100644--- a/docs/dashboard/api-keys.mdx+++ b/docs/dashboard/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/v1/vercel/next.js" \+curl "https://context7.com/api/v2/docs/code/vercel/next.js" \-H "Authorization: Bearer YOUR_API_KEY"```diff --git a/docs/dashboard/libraries.mdx b/docs/dashboard/libraries.mdxindex 95432d33..c73bf2b7 100644--- a/docs/dashboard/libraries.mdx+++ b/docs/dashboard/libraries.mdx@@ -1,9 +1,9 @@---title: Library Access-description: Configure which libraries your team can access and set token limits+description: Configure which libraries your team can access----Control which public libraries your team can access and configure maximum token limits for API requests from the [libraries tab](https://context7.com/dashboard?tab=libraries).+Control which public libraries your team can access from the [libraries tab](https://context7.com/dashboard?tab=libraries).## Public Library Access@@ -21,12 +21,6 @@ Configure which public libraries your team can access:<Note>Only owners and admins can change these settings.</Note>-## Token Limits----Set the maximum tokens per API request (**1,000 to 100,000**) to control the amount of documentation retrieved in each response. This helps prevent overwhelming the context window of LLMs with excessive documentation.-<Note>For private repositories, see the [Private Repositories](/dashboard/private-repositories) page.</Note>diff --git a/docs/images/dashboard/token-limit-card.png b/docs/images/dashboard/token-limit-card.pngdeleted file mode 100644index 7ad4cf2e..00000000Binary files a/docs/images/dashboard/token-limit-card.png and /dev/null differdiff --git a/docs/openapi.json b/docs/openapi.jsonindex 8b36e9a6..30e5ae95 100644--- a/docs/openapi.json+++ b/docs/openapi.json@@ -3,7 +3,7 @@"info": {"title": "Context7 Public API","description": "The Context7 Public API provides programmatic access to library documentation and search functionality. Get up-to-date documentation and code examples for any library.",- "version": "1.0.0",+ "version": "2.0.0","contact": {"name": "Context7 Support","url": "https://context7.com",@@ -17,83 +17,35 @@}],"paths": {- "/v1/{owner}/{repo}": {+ "/v2/docs/code/{owner}/{repo}": {"get": {- "summary": "Get Context",- "description": "Retrieve documentation and code examples for the latest version of a specific library.",- "operationId": "getContext",- "tags": ["Documentation"],+ "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"],"parameters": [{- "name": "owner",- "in": "path",- "required": true,- "description": "Repository owner (e.g., 'vercel', 'upstash')",- "schema": {- "type": "string"- },- "example": "vercel"+ "$ref": "#/components/parameters/OwnerParam"},{- "name": "repo",- "in": "path",- "required": true,- "description": "Repository name (e.g., 'next.js', 'docs')",- "schema": {- "type": "string"- },- "example": "next.js"+ "$ref": "#/components/parameters/RepoParam"},{- "name": "type",- "in": "query",- "required": false,- "description": "Format of the response: `txt` for plain text optimized for LLM contexts, or `json` for structured payload with metadata",- "schema": {- "type": "string",- "enum": ["txt", "json"],- "default": "txt"- }+ "$ref": "#/components/parameters/TopicParam"},{- "name": "topic",- "in": "query",- "required": false,- "description": "Topic to search/rerank the results (e.g., 'routing', 'authentication', 'hooks')",- "schema": {- "type": "string"- },- "example": "routing"+ "$ref": "#/components/parameters/TypeParam"},{- "name": "tokens",- "in": "query",- "required": false,- "description": "Maximum token count to be included in the result",- "schema": {- "type": "integer",- "default": 10000,- "minimum": 100,- "maximum": 100000- }+ "$ref": "#/components/parameters/PageParam"+ },+ {+ "$ref": "#/components/parameters/LimitParam"}],"responses": {"200": {- "description": "Successful response with documentation content",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/ContextResponse"- }- },- "text/plain": {- "schema": {- "type": "string",- "description": "Plain text documentation optimized for LLM contexts"- }- }- }+ "$ref": "#/components/responses/CodeSnippetsJsonResponse"},"400": {"$ref": "#/components/responses/BadRequestError"@@ -104,102 +56,65 @@"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": []+ }+ ]}},- "/v1/{owner}/{repo}/{version}": {+ "/v2/docs/code/{owner}/{repo}/{version}": {"get": {- "summary": "Get Context (Specific Version)",- "description": "Retrieve documentation and code examples for a specific version of a library.",- "operationId": "getContextVersion",- "tags": ["Documentation"],+ "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": [{- "name": "owner",- "in": "path",- "required": true,- "description": "Repository owner (e.g., 'vercel', 'upstash')",- "schema": {- "type": "string"- },- "example": "vercel"+ "$ref": "#/components/parameters/OwnerParam"},{- "name": "repo",- "in": "path",- "required": true,- "description": "Repository name (e.g., 'next.js', 'docs')",- "schema": {- "type": "string"- },- "example": "next.js"+ "$ref": "#/components/parameters/RepoParam"},{- "name": "version",- "in": "path",- "required": true,- "description": "Specific version tag (e.g., 'v15.1.8', 'v14.3.0-canary.87')",- "schema": {- "type": "string"- },- "example": "v15.1.8"+ "$ref": "#/components/parameters/VersionParam"},{- "name": "type",- "in": "query",- "required": false,- "description": "Format of the response: `txt` for plain text optimized for LLM contexts, or `json` for structured payload with metadata",- "schema": {- "type": "string",- "enum": ["txt", "json"],- "default": "txt"- }+ "$ref": "#/components/parameters/TopicParam"},{- "name": "topic",- "in": "query",- "required": false,- "description": "Topic to search/rerank the results (e.g., 'routing', 'authentication', 'hooks')",- "schema": {- "type": "string"- },- "example": "routing"+ "$ref": "#/components/parameters/TypeParam"},{- "name": "tokens",- "in": "query",- "required": false,- "description": "Maximum token count to be included in the result",- "schema": {- "type": "integer",- "default": 10000,- "minimum": 100,- "maximum": 100000- }+ "$ref": "#/components/parameters/PageParam"+ },+ {+ "$ref": "#/components/parameters/LimitParam"}],"responses": {"200": {- "description": "Successful response with documentation content",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/ContextResponse"- }- },- "text/plain": {- "schema": {- "type": "string",- "description": "Plain text documentation optimized for LLM contexts"- }- }- }+ "$ref": "#/components/responses/CodeSnippetsJsonResponse"},"400": {"$ref": "#/components/responses/BadRequestError"@@ -210,130 +125,270 @@"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": []+ }+ ]}},- "/v1/search": {+ "/v2/docs/info/{owner}/{repo}": {"get": {- "summary": "Search Libraries",- "description": "Search for libraries in the Context7 database. Returns up to 50 matching libraries with metadata.",- "operationId": "searchLibraries",- "tags": ["Search"],+ "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"],"parameters": [{- "name": "query",- "in": "query",- "required": true,- "description": "Library name to search for",- "schema": {- "type": "string"- },- "example": "next.js"+ "$ref": "#/components/parameters/OwnerParam"+ },+ {+ "$ref": "#/components/parameters/RepoParam"+ },+ {+ "$ref": "#/components/parameters/TopicParam"+ },+ {+ "$ref": "#/components/parameters/TypeParam"+ },+ {+ "$ref": "#/components/parameters/PageParam"+ },+ {+ "$ref": "#/components/parameters/LimitParam"}],"responses": {"200": {- "description": "Successful search with up to 50 matching libraries",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/SearchResponse"- }- }- }+ "$ref": "#/components/responses/InfoSnippetsJsonResponse"+ },+ "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"}- }- }- },- "/v1/add": {- "post": {- "summary": "Add a Library",- "description": "Submit a new library to Context7 for indexing. Supports GitHub/GitLab repositories, llms.txt files, and tag-based library versions. The parsing process starts immediately and the status transitions from `processing` to `finalized`.",- "operationId": "addLibrary",- "tags": ["Library Management"],+ },"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"+ }],- "requestBody": {- "required": true,- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/AddLibraryRequest"- },- "examples": {- "github": {- "summary": "GitHub repository",- "value": {- "docsRepoUrl": "https://github.com/okken/pytest-check",- "branch": "main",- "folders": ["docs"]- }- },- "llmstxt": {- "summary": "llms.txt file",- "value": {- "llmstxtUrl": "https://example.com/llms.txt"- }- },- "tag": {- "summary": "Tag-based version",- "value": {- "libraryName": "/vercel/next.js",- "libraryTagCode": "v15.1.8"- }- }- }- }+ "responses": {+ "200": {+ "$ref": "#/components/responses/InfoSnippetsJsonResponse"+ },+ "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/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": "Library parsing process started successfully",+ "description": "Successful search response","content": {"application/json": {"schema": {- "$ref": "#/components/schemas/AddLibraryResponse"+ "type": "object",+ "description": "Search results response",+ "properties": {+ "results": {+ "type": "array",+ "description": "Array of matching libraries",+ "items": {+ "$ref": "#/components/schemas/Library"+ }+ },+ "metadata": {+ "$ref": "#/components/schemas/APIResponseMetadata"+ }+ },+ "required": ["results", "metadata"]+ },+ "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"+ ]+ }+ ],+ "metadata": {+ "authentication": "none"+ }+ }+ },+ "emptyQuery": {+ "summary": "Empty query returns no results",+ "value": {+ "results": [],+ "metadata": {+ "authentication": "none"+ }+ }+ }}}}},- "400": {- "$ref": "#/components/responses/BadRequestError"- },"401": {"$ref": "#/components/responses/UnauthorizedError"},- "403": {- "$ref": "#/components/responses/ForbiddenError"- },- "404": {- "$ref": "#/components/responses/NotFoundError"- },"429": {"$ref": "#/components/responses/RateLimitError"},"500": {"$ref": "#/components/responses/InternalServerError"}- }+ },+ "security": [+ {},+ {+ "bearerAuth": []+ }+ ]}}},@@ -345,124 +400,211 @@"description": "Get your API key at [context7.com/dashboard](https://context7.com/dashboard). Treat your API key like a password and store it securely."}},+ "parameters": {+ "OwnerParam": {+ "name": "owner",+ "in": "path",+ "description": "Repository owner - GitHub username or organization name (case-insensitive)",+ "required": true,+ "schema": {+ "type": "string",+ "minLength": 1,+ "maxLength": 500+ },+ "example": "vercel"+ },+ "RepoParam": {+ "name": "repo",+ "in": "path",+ "description": "Repository name (case-insensitive)",+ "required": true,+ "schema": {+ "type": "string",+ "minLength": 1,+ "maxLength": 500+ },+ "example": "next.js"+ },+ "VersionParam": {+ "name": "version",+ "in": "path",+ "description": "Specific version (tag or branch) of the library",+ "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+ },+ "example": "authentication"+ },+ "TypeParam": {+ "name": "type",+ "in": "query",+ "description": "Response format type",+ "required": false,+ "schema": {+ "type": "string",+ "enum": ["json", "txt"],+ "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": {- "ContextResponse": {+ "CodeSnippet": {"type": "object",- "description": "Documentation content response with metadata and chunks",+ "description": "A code snippet from library documentation","properties": {- "library": {+ "codeTitle": {"type": "string",- "description": "Library ID in format `/owner/repo`",- "example": "/vercel/next.js"+ "description": "Title of the code snippet"},- "version": {+ "codeDescription": {"type": "string",- "description": "Version of the library",- "example": "v15.1.8"+ "description": "Description of what the code does"},- "topic": {+ "codeLanguage": {"type": "string",- "description": "Requested topic (if specified)",- "example": "routing"+ "description": "Primary programming language of the snippet"},- "tokens": {+ "codeTokens": {"type": "integer",- "description": "Actual token count in the response",- "example": 2950+ "description": "Token count for the snippet"+ },+ "codeId": {+ "type": "string",+ "description": "Unique identifier for the code snippet"+ },+ "pageTitle": {+ "type": "string",+ "description": "Title of the documentation page containing this snippet"},- "chunks": {+ "codeList": {"type": "array",- "description": "Documentation chunks with content and metadata",+ "description": "List of code examples in different languages","items": {- "type": "object",- "properties": {- "title": {- "type": "string",- "description": "Title of the documentation section",- "example": "Middleware overview"- },- "content": {- "type": "string",- "description": "Documentation content",- "example": "Next.js middleware runs before a request is completed..."- },- "source": {- "type": "string",- "description": "Source file path in the repository",- "example": "docs/app/building-your-application/routing/middleware.mdx"- },- "url": {- "type": "string",- "description": "URL to the original documentation",- "example": "https://nextjs.org/docs/app/building-your-application/routing/middleware"- }- }+ "$ref": "#/components/schemas/CodeExample"}+ }+ },+ "required": ["codeTitle", "codeDescription", "codeLanguage", "codeTokens", "codeId", "pageTitle", "codeList"]+ },+ "CodeExample": {+ "type": "object",+ "description": "A single code example",+ "properties": {+ "language": {+ "type": "string",+ "description": "Programming language of this code example"},- "metadata": {- "type": "object",- "description": "API request metadata",- "properties": {- "authentication": {- "type": "string",- "description": "Authentication status",- "example": "paid"- }- }+ "code": {+ "type": "string",+ "description": "The actual code content"}- }+ },+ "required": ["language", "code"]},- "SearchResponse": {+ "InfoSnippet": {"type": "object",- "description": "Search results with library metadata",+ "description": "A documentation/info snippet from library","properties": {- "results": {- "type": "array",- "description": "Array of matching libraries (up to 50 results)",- "items": {- "$ref": "#/components/schemas/Library"- }+ "pageId": {+ "type": "string",+ "description": "Unique page identifier"},- "metadata": {- "type": "object",- "properties": {- "authentication": {- "type": "string",- "description": "Authentication status",- "example": "paid"- }- }+ "breadcrumb": {+ "type": "string",+ "description": "Navigation breadcrumb path"+ },+ "content": {+ "type": "string",+ "description": "The documentation content"+ },+ "contentTokens": {+ "type": "integer",+ "description": "Token count for the content"}},- "example": {- "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,- "benchmarkScore": 95.5,- "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"+ "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"]+ },+ "APIResponseMetadata": {+ "type": "object",+ "description": "Response metadata",+ "properties": {+ "authentication": {+ "type": "string",+ "enum": ["none", "personal", "team"],+ "description": "Authentication type used for this request"+ }+ },+ "required": ["authentication"]},"Library": {"type": "object",@@ -510,11 +652,6 @@"description": "Number of code snippets","example": 3629},- "totalPages": {- "type": "integer",- "description": "Number of documentation pages",- "example": 1156- },"stars": {"type": "integer","description": "GitHub stars count",@@ -544,228 +681,386 @@}}},- "AddLibraryRequest": {+ "Error": {"type": "object",- "description": "Request to add a library. Provide exactly one of: docsRepoUrl, llmstxtUrl, or both libraryName and libraryTagCode.","properties": {- "docsRepoUrl": {- "type": "string",- "description": "GitHub or GitLab repository URL",- "example": "https://github.com/okken/pytest-check"- },- "llmstxtUrl": {- "type": "string",- "description": "URL to llms.txt, llms-full.txt, or llms-small.txt file",- "example": "https://example.com/llms.txt"- },- "libraryName": {- "type": "string",- "description": "Library identifier for tag-based sources (use with libraryTagCode)",- "example": "/vercel/next.js"- },- "libraryTagCode": {+ "error": {"type": "string",- "description": "Version tag for tag-based sources (use with libraryName)",- "example": "v15.1.8"+ "description": "Error code identifier"},- "branch": {+ "message": {"type": "string",- "description": "Git branch to parse (defaults to repository's default branch)",- "example": "main"+ "description": "Human-readable error message"},- "folders": {- "type": "array",- "description": "Specific folders to include for documentation",- "items": {- "type": "string"- },- "example": ["docs", "examples"]+ "status": {+ "type": "integer",+ "description": "HTTP status code"+ }+ },+ "required": ["error"]+ },+ "ValidationError": {+ "allOf": [+ {+ "$ref": "#/components/schemas/Error"},- "excludeFolders": {- "type": "array",- "description": "Folders to exclude from parsing",- "items": {- "type": "string"+ {+ "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)"+ }+ }+ }+ ]+ }+ },+ "responses": {+ "CodeSnippetsJsonResponse": {+ "description": "Successful response with code snippets",+ "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"+ },+ "metadata": {+ "$ref": "#/components/schemas/APIResponseMetadata"+ }+ },+ "required": ["snippets", "totalTokens", "pagination", "metadata"]},- "example": ["tests", "archive"]+ "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+ },+ "metadata": {+ "authentication": "none"+ }+ }},- "excludeFiles": {- "type": "array",- "description": "Files to exclude from parsing",- "items": {+ "text/plain": {+ "schema": {"type": "string"},- "example": ["CHANGELOG.md", "LICENSE.md"]+ "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```"}}},- "AddLibraryResponse": {- "type": "object",- "description": "Response after submitting a library for indexing",- "properties": {- "message": {- "type": "string",- "description": "Status message",- "example": "Parsing process started for https://github.com/okken/pytest-check"- },- "status": {- "type": "string",- "description": "Current processing status (transitions from processing to finalized)",- "enum": ["processing", "finalized"],- "example": "processing"- },- "docsRepoUrl": {- "type": "string",- "description": "GitHub repository URL",- "example": "https://github.com/okken/pytest-check"- },- "projectName": {- "type": "string",- "description": "Project name in format `/owner/repo`",- "example": "/okken/pytest-check"- },- "description": {- "type": "string",- "description": "Auto-detected project description",- "example": "A pytest plugin that allows multiple failures per test."- },- "folders": {- "type": "array",- "description": "Folders included in parsing",- "items": {- "type": "string"+ "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"+ },+ "metadata": {+ "$ref": "#/components/schemas/APIResponseMetadata"+ }+ },+ "required": ["snippets", "totalTokens", "pagination", "metadata"]},- "example": ["docs", "examples"]+ "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+ }+ ],+ "totalTokens": 84,+ "pagination": {+ "page": 1,+ "limit": 10,+ "totalPages": 10,+ "hasNext": true,+ "hasPrev": false+ },+ "metadata": {+ "authentication": "none"+ }+ }},- "excludeFolders": {- "type": "array",- "description": "Folders excluded from parsing",- "items": {+ "text/plain": {+ "schema": {"type": "string"},- "example": ["archive"]- },- "excludeFiles": {- "type": "array",- "description": "Files excluded from parsing (default excludes common files)",- "items": {- "type": "string"+ "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."+ }+ }+ },+ "BadRequestError": {+ "description": "Bad Request - Invalid input parameters",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ValidationError"},- "example": [- "CHANGELOG.md",- "changelog.md",- "CHANGELOG.mdx",- "changelog.mdx",- "LICENSE.md",- "license.md",- "CODE_OF_CONDUCT.md",- "code_of_conduct.md"- ]- },- "metadata": {- "type": "object",- "properties": {- "authentication": {- "type": "string",- "example": "paid"+ "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": {- "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.",- "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"+ }+ },+ "UnauthorizedError": {+ "description": "Unauthorized - Invalid or missing API key, or access denied",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ },+ "examples": {+ "invalidApiKey": {+ "summary": "Invalid API key",+ "value": {+ "error": "invalid_api_key",+ "message": "Invalid or expired API key",+ "status": 401+ }+ },+ "accessDenied": {+ "summary": "Access denied to library",+ "value": {+ "error": "access_denied",+ "message": "Access denied: Library /vercel/next.js is not included in your allowed libraries"+ }+ },+ "authenticationFailed": {+ "summary": "Authentication failed",+ "value": {+ "error": "authentication_failed",+ "message": "Failed to authenticate API key",+ "status": 401+ }+ }+ }}}},- "Error": {- "type": "object",- "properties": {- "error": {- "type": "string",- "description": "Error message"- },- "status": {- "type": "integer",- "description": "HTTP status code"- },- "retryAfterSeconds": {- "type": "integer",- "description": "Seconds to wait before retrying (for rate limit errors)"+ "ForbiddenError": {+ "description": "Forbidden - Insufficient permissions or blocked library",+ "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."+ }+ }+ }}}- }- },- "responses": {- "BadRequestError": {- "description": "Bad Request - Invalid input parameters",+ },+ "NotFoundError": {+ "description": "Not Found - Library, project, or resource doesn't exist","content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"},- "example": {- "error": "Invalid input",- "status": 400+ "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"+ }+ }}}}},- "UnauthorizedError": {- "description": "Unauthorized - Invalid or missing API key",+ "AcceptedError": {+ "description": "Accepted - Library not yet finalized","content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"},"example": {- "error": "Unauthorized - Invalid or missing API key",- "status": 401+ "error": "library_not_finalized",+ "message": "Library /owner/repo not finalized yet."}}}},- "ForbiddenError": {- "description": "Forbidden - Insufficient permissions",+ "RedirectError": {+ "description": "Moved Permanently - Library has been redirected","content": {"application/json": {"schema": {- "$ref": "#/components/schemas/Error"+ "$ref": "#/components/schemas/ValidationError"},"example": {- "error": "Insufficient permissions",- "status": 403+ "error": "library_redirected",+ "message": "Library /owner/repo has been redirected to this library: /new-owner/new-repo.",+ "redirectUrl": "/new-owner/new-repo"}}}},- "NotFoundError": {- "description": "Not Found - Library or endpoint doesn't exist",+ "UnprocessableEntityError": {+ "description": "Unprocessable Entity - Library is too large or has no code","content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"},- "example": {- "error": "Library not found",- "status": 404+ "examples": {+ "tooLarge": {+ "summary": "Library too large",+ "value": {+ "error": "library_too_large",+ "message": "Library /owner/repo is too large to process."+ }+ },+ "noCode": {+ "summary": "No code found",+ "value": {+ "error": "no_code_found",+ "message": "Library /owner/repo has no or too few snippets found in documentation files."+ }+ }}}}@@ -779,8 +1074,7 @@},"example": {"error": "Too many requests",- "status": 429,- "retryAfterSeconds": 60+ "status": 429}}}@@ -792,9 +1086,39 @@"schema": {"$ref": "#/components/schemas/Error"},- "example": {- "error": "Internal server error",- "status": 500+ "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+ }+ }}}}@@ -803,16 +1127,12 @@},"tags": [{- "name": "Documentation",+ "name": "Retrieve Documentation","description": "Retrieve library documentation and code examples"},{- "name": "Search",+ "name": "Search Libraries","description": "Search for libraries in the Context7 database"- },- {- "name": "Library Management",- "description": "Add and manage libraries in Context7"}]}diff --git a/docs/usage.mdx b/docs/usage.mdxindex 4ff0ca10..38b99863 100644--- a/docs/usage.mdx+++ b/docs/usage.mdx@@ -9,7 +9,6 @@ Practical techniques for using Context7 effectively.- [Auto-invoke Context7](#auto-invoke-context7) so you never forget to pull fresh docs- [Target the exact library ID](#use-specific-library-ids) to skip search steps- [Tune networking and proxies](#configure-https-proxy) for locked-down environments-- [Control token usage](#control-token-usage) to keep responses snappy- [Bring in private repositories](#work-with-private-repositories) for internal docs## Auto-Invoke Context7@@ -153,37 +152,6 @@ Both lowercase and uppercase environment variables are supported.connectivity before restarting your IDE.</Tip>-## Control Token Usage--Manage documentation size to control costs and response times.--### Set Token Limits in Dashboard--1. Go to [Dashboard → Libraries](https://context7.com/dashboard)-2. Set "Maximum tokens per request"-3. Default is 10,000, adjust based on your needs--### Use Topic Filtering--Focus documentation on specific topics:--```txt-Explain Next.js middleware authentication patterns. use context7-```--Context7 automatically extracts "authentication" as a topic and ranks relevant docs higher.--### Direct API Usage--When using the API directly, specify tokens:--```bash-curl "https://context7.com/api/v1/vercel/next.js?tokens=3000&topic=routing" \- -H "Authorization: Bearer YOUR_API_KEY"-```--Lower token counts result in faster responses and lower costs.-## Work with Private RepositoriesAdd your private GitHub, GitLab, or Bitbucket repositories to make internal documentation available through Context7. Requires a Pro or Enterprise plan.@@ -250,8 +218,8 @@ See [Security](/security) for comprehensive security guidelines.### Performance- Use specific library IDs such as `/vercel/next.js` instead of general phrases like "next.js docs" when possible.-- Set appropriate token limits -- use lower values for quick lookups, and higher values for comprehensive docs.- Focus results using topic filtering. Try adding specific topics like "authentication" or "routing".+- Use pagination when you need more context — the API supports up to 10 pages per topic. Check the `hasNext` field in responses to know when more pages are available.- Cache frequently used documentation locally for 6-24 hours to reduce API calls.### Library Managementdiff --git a/src/lib/types.ts b/src/lib/types.tsindex 05bd154a..89afe11c 100644--- a/src/lib/types.ts+++ b/src/lib/types.ts@@ -7,7 +7,6 @@ export interface SearchResult {state: DocumentState;totalTokens: number;totalSnippets: number;- totalPages: number;stars?: number;trustScore?: number;benchmarkScore?: number;