Skip to content

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

docs: convert the handwritten api docs to use openapi file

enesgulesfc2a2a6dd322
diff --git a/docs/api-guide.mdx b/docs/api-guide.mdx
new file mode 100644
index 00000000..524ee61a
--- /dev/null
+++ b/docs/api-guide.mdx
@@ -0,0 +1,176 @@
+---
+title: API Guide
+description: Authentication, rate limits, best practices, and integration guides for the Context7 API
+---
+
+## Authentication
+
+All API requests require authentication using an API key. Include your API key in the `Authorization` header:
+
+```bash
+Authorization: Bearer CONTEXT7_API_KEY
+```
+
+Get your API key at [context7.com/dashboard](https://context7.com/dashboard).
+
+<Warning>
+ Treat your API key like a password. Store it in an environment variable or secret manager and
+ rotate it immediately if you suspect it has leaked.
+</Warning>
+
+## Rate Limits
+
+- **Without API key**: Low rate limits and no custom configuration
+- **With API key**: Higher limits based on your plan
+- View current usage and reset windows in the [dashboard](https://context7.com/dashboard).
+
+When you exceed rate limits, the API returns a `429` status code with a `retryAfterSeconds` field indicating when you can retry:
+
+```json
+{
+ "error": "Too many requests",
+ "status": 429,
+ "retryAfterSeconds": 60
+}
+```
+
+## Best Practices
+
+### 1. Use Appropriate Token Limits
+
+Request only the amount of documentation you need to minimize token usage and response times:
+
+```bash
+# Request only 2000 tokens for quick lookups
+curl "https://context7.com/api/v1/vercel/next.js?tokens=2000" \
+ -H "Authorization: Bearer CONTEXT7_API_KEY"
+```
+
+### 2. Specify Topics
+
+Use 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" \
+ -H "Authorization: Bearer CONTEXT7_API_KEY"
+```
+
+### 3. Cache Responses
+
+Store documentation locally to reduce API calls and improve performance. Documentation updates are relatively infrequent, so caching for several hours or days is usually appropriate.
+
+### 4. Handle Rate Limits
+
+Implement exponential backoff for rate limit errors:
+
+```python
+import time
+import requests
+
+def fetch_with_retry(url, headers, max_retries=3):
+ for attempt in range(max_retries):
+ response = requests.get(url, headers=headers)
+
+ if response.status_code == 429:
+ retry_after = response.json().get('retryAfterSeconds', 60)
+ time.sleep(retry_after)
+ continue
+
+ return response
+
+ raise Exception("Max retries exceeded")
+```
+
+### 5. Use Specific Versions
+
+When possible, 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" \
+ -H "Authorization: Bearer CONTEXT7_API_KEY"
+```
+
+## Error Handling
+
+The Context7 API uses standard HTTP status codes:
+
+| Code | Description | Action |
+| ---- | --------------------------------------------- | --------------------------------------------- |
+| 200 | Success | Process the response normally |
+| 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 |
+
+### Error Response Format
+
+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
+}
+```
+
+## SDK and Libraries
+
+### MCP Server (Recommended)
+
+The Context7 Model Context Protocol (MCP) server provides seamless integration with Claude and other AI tools:
+
+```bash
+npm install @upstash/context7-mcp
+```
+
+**Features:**
+- Automatic API key management
+- Built-in caching
+- Type-safe library resolution
+- Optimized for AI workflows
+
+See the [Installation guide](/installation) for detailed setup instructions.
+
+### Direct API Integration
+
+For custom integrations or non-MCP use cases, use the REST endpoints directly. The API is language-agnostic and works with any HTTP client.
+
+**Example (cURL):**
+```bash
+curl "https://context7.com/api/v1/vercel/next.js?topic=routing" \
+ -H "Authorization: Bearer CONTEXT7_API_KEY"
+```
+
+**Example (Python):**
+```python
+import requests
+
+headers = {
+ "Authorization": "Bearer CONTEXT7_API_KEY"
+}
+
+response = requests.get(
+ "https://context7.com/api/v1/vercel/next.js",
+ headers=headers,
+ params={"topic": "routing", "tokens": 5000}
+)
+
+docs = response.json()
+```
+
+**Example (JavaScript/Node.js):**
+```javascript
+const response = await fetch(
+ "https://context7.com/api/v1/vercel/next.js?topic=routing&tokens=5000",
+ {
+ headers: {
+ "Authorization": "Bearer CONTEXT7_API_KEY"
+ }
+ }
+);
+
+const docs = await response.json();
+```
diff --git a/docs/api.mdx b/docs/api.mdx
deleted file mode 100644
index 1a92eab6..00000000
--- a/docs/api.mdx
+++ /dev/null
@@ -1,350 +0,0 @@
----
-title: Public API
----
-
-The Context7 Public API provides programmatic access to library documentation and search functionality.
-
-## Base URL
-
-```
-https://context7.com/api
-```
-
-## Authentication
-
-All API requests require authentication using an API key. Include your API key in the `Authorization` header:
-
-```
-Authorization: Bearer CONTEXT7_API_KEY
-```
-
-Get your API key at [context7.com/dashboard](https://context7.com/dashboard).
-
-<Warning>
- Treat your API key like a password. Store it in an environment variable or secret manager and
- rotate it immediately if you suspect it has leaked.
-</Warning>
-
-## Endpoints
-
-### Get Context
-
-Retrieve documentation and code examples for a specific library.
-
-#### Request
-
-**HTTP Method**: `GET`
-
-**Endpoint**: `/v1/[library]`
-
-**URL Format**:
-
-- `/v1/{owner}/{repo}` - Get latest version
-- `/v1/{owner}/{repo}/{version}` - Get specific version
-
-**Examples**:
-
-- `/v1/vercel/next.js`
-- `/v1/vercel/next.js/v15.1.8`
-- `/v1/upstash/docs`
-
-#### Query Parameters
-
-| Parameter | Type | Required | Default | Description |
-| --------- | ------ | -------- | ------- | ------------------------------------------------ |
-| `type` | string | No | `txt` | Format of the response: `txt` or `json` |
-| `topic` | string | No | - | Topic to search/rerank the results |
-| `tokens` | number | No | `10000` | Maximum token count to be included in the result |
-
-#### Examples
-
-<AccordionGroup>
- <Accordion title="Basic usage (default txt format)">
- ```bash
- curl "https://context7.com/api/v1/vercel/next.js" \
- -H "Authorization: Bearer CONTEXT7_API_KEY"
- ```
- </Accordion>
-
-<Accordion title="Using JSON format">
- ```bash curl "https://context7.com/api/v1/vercel/next.js?type=json" \ -H "Authorization: Bearer
- CONTEXT7_API_KEY" ```
-</Accordion>
-
-<Accordion title="Specifying a topic">
- ```bash curl "https://context7.com/api/v1/vercel/next.js?topic=routing" \ -H "Authorization:
- Bearer CONTEXT7_API_KEY" ```
-</Accordion>
-
-<Accordion title="Limiting token count">
- ```bash curl "https://context7.com/api/v1/vercel/next.js?tokens=2000" \ -H "Authorization: Bearer
- CONTEXT7_API_KEY" ```
-</Accordion>
-
- <Accordion title="Multiple parameters">
- ```bash
- curl "https://context7.com/api/v1/vercel/next.js?topic=authentication&tokens=3000&type=txt" \
- -H "Authorization: Bearer CONTEXT7_API_KEY"
- ```
- </Accordion>
-</AccordionGroup>
-
-#### Response
-
-Returns documentation content in the specified format (`txt` or `json`).
-
-- `txt` (default) delivers a plain-text block optimised for feeding into LLM contexts.
-- `json` provides a structured payload with metadata, snippets, and sections.
-
-```json
-{
- "library": "/vercel/next.js",
- "version": "v15.1.8",
- "topic": "routing",
- "tokens": 2950,
- "chunks": [
- {
- "title": "Middleware overview",
- "content": "Next.js middleware runs before a request is completed...",
- "source": "docs/app/building-your-application/routing/middleware.mdx",
- "url": "https://nextjs.org/docs/app/building-your-application/routing/middleware"
- }
- ]
-}
-```
-
----
-
-### Search Libraries
-
-Search for libraries in the Context7 database.
-
-#### Request
-
-**HTTP Method**: `GET`
-
-**Endpoint**: `/v1/search`
-
-#### Query Parameters
-
-| Parameter | Type | Required | Description |
-| --------- | ------ | -------- | -------------------------- |
-| `query` | string | Yes | Library name to search for |
-
-#### Example
-
-```bash
-curl "https://context7.com/api/v1/search?query=next.js" \
- -H "Authorization: Bearer CONTEXT7_API_KEY"
-```
-
-#### Response
-
-Returns up to 50 matching libraries.
-
-```json
-{
- "results": [
- {
- "id": "/vercel/next.js",
- "title": "Next.js",
- "description": "The React Framework",
- "branch": "canary",
- "lastUpdateDate": "2025-07-27T06:56:26.691Z",
- "state": "finalized",
- "totalTokens": 607822,
- "totalSnippets": 3629,
- "totalPages": 1156,
- "stars": 131745,
- "trustScore": 10,
- "versions": [
- "v14.3.0-canary.87",
- "v13.5.11",
- "v15.1.8",
- "v15.4.0-canary.82",
- "v12.3.7",
- "v11.1.3"
- ]
- }
- ],
- "metadata": {
- "authentication": "paid"
- }
-}
-```
-
-#### Response Fields
-
-| Field | Type | Description |
-| ---------------- | ------ | -------------------------------------------------------------- |
-| `id` | string | Library ID in format `/owner/repo` |
-| `title` | string | Display name of the library |
-| `description` | string | Short description |
-| `branch` | string | Git branch being tracked |
-| `lastUpdateDate` | string | ISO 8601 timestamp of last update |
-| `state` | string | Processing state: `finalized`, `initial`, `error`, or `delete` |
-| `totalTokens` | number | Total tokens in documentation |
-| `totalSnippets` | number | Number of code snippets |
-| `totalPages` | number | Number of documentation pages |
-| `stars` | number | GitHub stars count |
-| `trustScore` | number | Authority score (0-10) |
-| `versions` | array | Available version tags |
-
----
-
-### Add a Library
-
-Submit a new library to Context7 for indexing.
-
-#### Request
-
-**HTTP Method**: `POST`
-
-**Endpoint**: `/v1/add`
-
-**Content-Type**: `application/json`
-
-#### Request Body
-
-| Field | Type | Required | Description |
-| ---------------- | ------ | -------- | ---------------------------------------------------------- |
-| `docsRepoUrl` | string | Yes | GitHub repository URL |
-| `projectTitle` | string | No | Display name for the project |
-| `branch` | string | No | Git branch to parse (default: repository's default branch) |
-| `folders` | array | No | Specific folders to include for documentation |
-| `excludeFolders` | array | No | Folders to exclude from parsing |
-| `excludeFiles` | array | No | Files to exclude from parsing |
-
-#### Examples
-
-<AccordionGroup>
- <Accordion title="Basic example">
- ```bash
- curl -X POST "https://context7.com/api/v1/add" \
- -H "Authorization: Bearer CONTEXT7_API_KEY" \
- -H "Content-Type: application/json" \
- -d '{
- "docsRepoUrl": "https://github.com/okken/pytest-check",
- "projectTitle": "PyTest Check",
- "branch": "main"
- }'
- ```
- </Accordion>
-
- <Accordion title="With specific branch">
- ```bash
- curl -X POST "https://context7.com/api/v1/add" \
- -H "Authorization: Bearer CONTEXT7_API_KEY" \
- -H "Content-Type: application/json" \
- -d '{
- "docsRepoUrl": "https://github.com/pallets/flask",
- "projectTitle": "Flask",
- "branch": "2.0.x"
- }'
- ```
- </Accordion>
-
- <Accordion title="With included folders">
- ```bash
- curl -X POST "https://context7.com/api/v1/add" \
- -H "Authorization: Bearer CONTEXT7_API_KEY" \
- -H "Content-Type: application/json" \
- -d '{
- "docsRepoUrl": "https://github.com/okken/pytest-check",
- "branch": "main",
- "folders": ["docs", "examples"]
- }'
- ```
- </Accordion>
-
- <Accordion title="With excluded folders">
- ```bash
- curl -X POST "https://context7.com/api/v1/add" \
- -H "Authorization: Bearer CONTEXT7_API_KEY" \
- -H "Content-Type: application/json" \
- -d '{
- "docsRepoUrl": "https://github.com/psf/requests",
- "projectTitle": "Requests",
- "branch": "main",
- "excludeFolders": ["tests", "examples"]
- }'
- ```
- </Accordion>
-</AccordionGroup>
-
-#### Response
-
-```json
-{
- "message": "Parsing process started for https://github.com/okken/pytest-check",
- "status": "processing",
- "docsRepoUrl": "https://github.com/okken/pytest-check",
- "projectName": "/okken/pytest-check",
- "description": "A pytest plugin that allows multiple failures per test.",
- "projectTitle": "auto-detected",
- "folders": ["docs", "examples"],
- "excludeFolders": ["archive"],
- "excludeFiles": [
- "CHANGELOG.md",
- "changelog.md",
- "CHANGELOG.mdx",
- "changelog.mdx",
- "LICENSE.md",
- "license.md",
- "CODE_OF_CONDUCT.md",
- "code_of_conduct.md"
- ],
- "metadata": {
- "authentication": "paid"
- }
-}
-```
-
-The `status` field transitions through `processing → finalized`. Poll the library detail view or call the `/v1/search` endpoint to confirm when parsing completes.
-
-## Rate Limits
-
-- **Without API key**: Limited requests per IP
-- **With API key**: Higher limits based on your plan
-- View current usage and reset windows in the [dashboard](https://context7.com/dashboard).
-
-## Error Codes
-
-| Code | Description |
-| ---- | --------------------------------------------- |
-| 200 | Success |
-| 401 | Unauthorized - Invalid or missing API key |
-| 404 | Not Found - Library or endpoint doesn't exist |
-| 429 | Too Many Requests - Rate limit exceeded |
-| 500 | Internal Server Error |
-
-```json
-{
- "error": "Too many requests",
- "status": 429,
- "retryAfterSeconds": 60
-}
-```
-
-## Best Practices
-
-1. **Use appropriate token limits**: Request only the amount of documentation you need
-2. **Specify topics**: Use the `topic` parameter to get more relevant results
-3. **Cache responses**: Store documentation locally to reduce API calls
-4. **Handle rate limits**: Implement exponential backoff for rate limit errors
-5. **Use specific versions**: When possible, specify exact versions for consistent results
-
-## SDK and Libraries
-
-For easier integration, consider using:
-
-- **MCP Server**: `@upstash/context7-mcp` - Model Context Protocol integration
-- **Direct API**: Use the REST endpoints documented above
-
-## Support
-
-For API support and questions:
-
-- Documentation: [docs.context7.com](https://docs.context7.com)
-- GitHub Issues: [github.com/upstash/context7/issues](https://github.com/upstash/context7/issues)
-- Discord: [upstash.com/discord](https://upstash.com/discord)
diff --git a/docs/docs.json b/docs/docs.json
index 99d2a8c1..8ffa094d 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -9,18 +9,35 @@
"dark": "#0F172A"
},
"navigation": {
- "pages": [
- "overview",
- "installation",
- "usage",
- "adding-libraries",
- "plans-pricing",
- "api",
- "security",
- "troubleshooting",
- "contact"
+ "groups": [
+ {
+ "group": "Overview",
+ "pages": [
+ "overview",
+ "installation",
+ "usage",
+ "adding-libraries",
+ "plans-pricing",
+ "api-guide"
+ ]
+ },
+ {
+ "group": "API Reference",
+ "openapi": "openapi.json"
+ },
+ {
+ "group": "Resources",
+ "pages": [
+ "security",
+ "troubleshooting",
+ "contact"
+ ]
+ }
]
},
+ "api": {
+ "playground": {"display": "simple"}
+ },
"logo": {
"light": "/logo/logo.svg",
"dark": "/logo/logo-dark.svg",
diff --git a/docs/openapi.json b/docs/openapi.json
new file mode 100644
index 00000000..3c0b1ac1
--- /dev/null
+++ b/docs/openapi.json
@@ -0,0 +1,756 @@
+{
+ "openapi": "3.0.0",
+ "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",
+ "contact": {
+ "name": "Context7 Support",
+ "url": "https://context7.com",
+ "email": "[email protected]"
+ }
+ },
+ "servers": [
+ {
+ "url": "https://context7.com/api",
+ "description": "Production server"
+ }
+ ],
+ "security": [
+ {
+ "bearerAuth": []
+ }
+ ],
+ "paths": {
+ "/v1/{owner}/{repo}": {
+ "get": {
+ "summary": "Get Context",
+ "description": "Retrieve documentation and code examples for the latest version of a specific library.",
+ "operationId": "getContext",
+ "tags": ["Documentation"],
+ "parameters": [
+ {
+ "name": "owner",
+ "in": "path",
+ "required": true,
+ "description": "Repository owner (e.g., 'vercel', 'upstash')",
+ "schema": {
+ "type": "string"
+ },
+ "example": "vercel"
+ },
+ {
+ "name": "repo",
+ "in": "path",
+ "required": true,
+ "description": "Repository name (e.g., 'next.js', 'docs')",
+ "schema": {
+ "type": "string"
+ },
+ "example": "next.js"
+ },
+ {
+ "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"
+ }
+ },
+ {
+ "name": "topic",
+ "in": "query",
+ "required": false,
+ "description": "Topic to search/rerank the results (e.g., 'routing', 'authentication', 'hooks')",
+ "schema": {
+ "type": "string"
+ },
+ "example": "routing"
+ },
+ {
+ "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
+ }
+ }
+ ],
+ "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"
+ }
+ }
+ }
+ },
+ "401": {
+ "$ref": "#/components/responses/UnauthorizedError"
+ },
+ "404": {
+ "$ref": "#/components/responses/NotFoundError"
+ },
+ "429": {
+ "$ref": "#/components/responses/RateLimitError"
+ },
+ "500": {
+ "$ref": "#/components/responses/InternalServerError"
+ }
+ }
+ }
+ },
+ "/v1/{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"],
+ "parameters": [
+ {
+ "name": "owner",
+ "in": "path",
+ "required": true,
+ "description": "Repository owner (e.g., 'vercel', 'upstash')",
+ "schema": {
+ "type": "string"
+ },
+ "example": "vercel"
+ },
+ {
+ "name": "repo",
+ "in": "path",
+ "required": true,
+ "description": "Repository name (e.g., 'next.js', 'docs')",
+ "schema": {
+ "type": "string"
+ },
+ "example": "next.js"
+ },
+ {
+ "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"
+ },
+ {
+ "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"
+ }
+ },
+ {
+ "name": "topic",
+ "in": "query",
+ "required": false,
+ "description": "Topic to search/rerank the results (e.g., 'routing', 'authentication', 'hooks')",
+ "schema": {
+ "type": "string"
+ },
+ "example": "routing"
+ },
+ {
+ "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
+ }
+ }
+ ],
+ "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"
+ }
+ }
+ }
+ },
+ "401": {
+ "$ref": "#/components/responses/UnauthorizedError"
+ },
+ "404": {
+ "$ref": "#/components/responses/NotFoundError"
+ },
+ "429": {
+ "$ref": "#/components/responses/RateLimitError"
+ },
+ "500": {
+ "$ref": "#/components/responses/InternalServerError"
+ }
+ }
+ }
+ },
+ "/v1/search": {
+ "get": {
+ "summary": "Search Libraries",
+ "description": "Search for libraries in the Context7 database. Returns up to 50 matching libraries with metadata.",
+ "operationId": "searchLibraries",
+ "tags": ["Search"],
+ "parameters": [
+ {
+ "name": "query",
+ "in": "query",
+ "required": true,
+ "description": "Library name to search for",
+ "schema": {
+ "type": "string"
+ },
+ "example": "next.js"
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Successful search with up to 50 matching libraries",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SearchResponse"
+ }
+ }
+ }
+ },
+ "401": {
+ "$ref": "#/components/responses/UnauthorizedError"
+ },
+ "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. The parsing process starts immediately and the status transitions from `processing` to `finalized`.",
+ "operationId": "addLibrary",
+ "tags": ["Library Management"],
+ "requestBody": {
+ "required": true,
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AddLibraryRequest"
+ },
+ "examples": {
+ "basic": {
+ "summary": "Basic example",
+ "value": {
+ "docsRepoUrl": "https://github.com/okken/pytest-check",
+ "projectTitle": "PyTest Check",
+ "branch": "main"
+ }
+ },
+ "withFolders": {
+ "summary": "With included folders",
+ "value": {
+ "docsRepoUrl": "https://github.com/okken/pytest-check",
+ "branch": "main",
+ "folders": ["docs", "examples"]
+ }
+ },
+ "withExclusions": {
+ "summary": "With excluded folders",
+ "value": {
+ "docsRepoUrl": "https://github.com/psf/requests",
+ "projectTitle": "Requests",
+ "branch": "main",
+ "excludeFolders": ["tests", "examples"]
+ }
+ }
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Library parsing process started successfully",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AddLibraryResponse"
+ }
+ }
+ }
+ },
+ "401": {
+ "$ref": "#/components/responses/UnauthorizedError"
+ },
+ "429": {
+ "$ref": "#/components/responses/RateLimitError"
+ },
+ "500": {
+ "$ref": "#/components/responses/InternalServerError"
+ }
+ }
+ }
+ }
+ },
+ "components": {
+ "securitySchemes": {
+ "bearerAuth": {
+ "type": "http",
+ "scheme": "bearer",
+ "description": "Get your API key at [context7.com/dashboard](https://context7.com/dashboard). Treat your API key like a password and store it securely."
+ }
+ },
+ "schemas": {
+ "ContextResponse": {
+ "type": "object",
+ "description": "Documentation content response with metadata and chunks",
+ "properties": {
+ "library": {
+ "type": "string",
+ "description": "Library ID in format `/owner/repo`",
+ "example": "/vercel/next.js"
+ },
+ "version": {
+ "type": "string",
+ "description": "Version of the library",
+ "example": "v15.1.8"
+ },
+ "topic": {
+ "type": "string",
+ "description": "Requested topic (if specified)",
+ "example": "routing"
+ },
+ "tokens": {
+ "type": "integer",
+ "description": "Actual token count in the response",
+ "example": 2950
+ },
+ "chunks": {
+ "type": "array",
+ "description": "Documentation chunks with content and metadata",
+ "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"
+ }
+ }
+ }
+ }
+ }
+ },
+ "SearchResponse": {
+ "type": "object",
+ "description": "Search results with library metadata",
+ "properties": {
+ "results": {
+ "type": "array",
+ "description": "Array of matching libraries (up to 50 results)",
+ "items": {
+ "$ref": "#/components/schemas/Library"
+ }
+ },
+ "metadata": {
+ "type": "object",
+ "properties": {
+ "authentication": {
+ "type": "string",
+ "description": "Authentication status",
+ "example": "paid"
+ }
+ }
+ }
+ },
+ "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,
+ "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"
+ }
+ }
+ },
+ "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-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
+ },
+ "totalPages": {
+ "type": "integer",
+ "description": "Number of documentation pages",
+ "example": 1156
+ },
+ "stars": {
+ "type": "integer",
+ "description": "GitHub stars count",
+ "example": 131745
+ },
+ "trustScore": {
+ "type": "integer",
+ "description": "Authority score (0-10)",
+ "minimum": 0,
+ "maximum": 10,
+ "example": 10
+ },
+ "versions": {
+ "type": "array",
+ "description": "Available version tags",
+ "items": {
+ "type": "string"
+ },
+ "example": ["v15.1.8", "v14.3.0-canary.87"]
+ }
+ }
+ },
+ "AddLibraryRequest": {
+ "type": "object",
+ "required": ["docsRepoUrl"],
+ "properties": {
+ "docsRepoUrl": {
+ "type": "string",
+ "description": "GitHub repository URL",
+ "example": "https://github.com/okken/pytest-check"
+ },
+ "projectTitle": {
+ "type": "string",
+ "description": "Display name for the project (auto-detected if not provided)",
+ "example": "PyTest Check"
+ },
+ "branch": {
+ "type": "string",
+ "description": "Git branch to parse (defaults to repository's default branch)",
+ "example": "main"
+ },
+ "folders": {
+ "type": "array",
+ "description": "Specific folders to include for documentation",
+ "items": {
+ "type": "string"
+ },
+ "example": ["docs", "examples"]
+ },
+ "excludeFolders": {
+ "type": "array",
+ "description": "Folders to exclude from parsing",
+ "items": {
+ "type": "string"
+ },
+ "example": ["tests", "archive"]
+ },
+ "excludeFiles": {
+ "type": "array",
+ "description": "Files to exclude from parsing",
+ "items": {
+ "type": "string"
+ },
+ "example": ["CHANGELOG.md", "LICENSE.md"]
+ }
+ }
+ },
+ "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."
+ },
+ "projectTitle": {
+ "type": "string",
+ "description": "Project title (auto-detected or provided)",
+ "example": "auto-detected"
+ },
+ "folders": {
+ "type": "array",
+ "description": "Folders included in parsing",
+ "items": {
+ "type": "string"
+ },
+ "example": ["docs", "examples"]
+ },
+ "excludeFolders": {
+ "type": "array",
+ "description": "Folders excluded from parsing",
+ "items": {
+ "type": "string"
+ },
+ "example": ["archive"]
+ },
+ "excludeFiles": {
+ "type": "array",
+ "description": "Files excluded from parsing (default excludes common files)",
+ "items": {
+ "type": "string"
+ },
+ "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"
+ }
+ }
+ }
+ },
+ "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.",
+ "projectTitle": "auto-detected",
+ "folders": ["docs", "examples"],
+ "excludeFolders": ["archive"],
+ "excludeFiles": [
+ "CHANGELOG.md",
+ "changelog.md",
+ "CHANGELOG.mdx",
+ "changelog.mdx",
+ "LICENSE.md",
+ "license.md",
+ "CODE_OF_CONDUCT.md",
+ "code_of_conduct.md"
+ ],
+ "metadata": {
+ "authentication": "paid"
+ }
+ }
+ },
+ "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)"
+ }
+ }
+ }
+ },
+ "responses": {
+ "UnauthorizedError": {
+ "description": "Unauthorized - Invalid or missing API key",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ },
+ "example": {
+ "error": "Unauthorized - Invalid or missing API key",
+ "status": 401
+ }
+ }
+ }
+ },
+ "NotFoundError": {
+ "description": "Not Found - Library or endpoint doesn't exist",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ },
+ "example": {
+ "error": "Library not found",
+ "status": 404
+ }
+ }
+ }
+ },
+ "RateLimitError": {
+ "description": "Too Many Requests - Rate limit exceeded",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ },
+ "example": {
+ "error": "Too many requests",
+ "status": 429,
+ "retryAfterSeconds": 60
+ }
+ }
+ }
+ },
+ "InternalServerError": {
+ "description": "Internal Server Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ },
+ "example": {
+ "error": "Internal server error",
+ "status": 500
+ }
+ }
+ }
+ }
+ }
+ },
+ "tags": [
+ {
+ "name": "Documentation",
+ "description": "Retrieve library documentation and code examples"
+ },
+ {
+ "name": "Search",
+ "description": "Search for libraries in the Context7 database"
+ },
+ {
+ "name": "Library Management",
+ "description": "Add and manage libraries in Context7"
+ }
+ ]
+}