{ "openapi": "3.0.0", "info": { "title": "Context7 On-Premise API", "description": "REST API for the Context7 On-Premise server. Covers library parsing and documentation search.", "version": "1.0.0" }, "servers": [ { "url": "https://your-instance.example.com/api", "description": "Your on-premise deployment (replace with your actual host)" }, { "url": "http://localhost:3000/api", "description": "Local development" } ], "paths": { "/v2/libs/search": { "get": { "summary": "Search for libraries", "description": "Search locally indexed libraries by name. Results may also include public libraries from Context7 Cloud depending on your policy settings.", "operationId": "searchLibraries", "tags": [ "Search" ], "parameters": [ { "name": "libraryName", "in": "query", "description": "Library name to search for (e.g., `react`, `nextjs`)", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 500 }, "example": "react" }, { "name": "query", "in": "query", "description": "User's original question or task - used for relevance ranking", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 500 }, "example": "How to manage state with hooks" } ], "responses": { "200": { "description": "Search results ranked by relevance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" }, "example": { "results": [ { "id": "/your-org/your-repo", "title": "Your Repo", "description": "Internal tooling docs", "totalSnippets": 150, "source": "Local (Private)", "trustScore": 10 } ] } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ {}, { "bearerAuth": [] } ] } }, "/v2/context": { "get": { "summary": "Get documentation context", "description": "Retrieve documentation snippets for a library ranked by relevance to your query, formatted as plain text ready to inject into an LLM prompt. This is the endpoint MCP tools call internally.", "operationId": "getContext", "tags": [ "Context" ], "parameters": [ { "name": "libraryId", "in": "query", "description": "Library ID returned by `GET /v2/libs/search` (e.g., `/your-org/your-repo`)", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 500 }, "example": "/vercel/next.js" }, { "name": "query", "in": "query", "description": "Natural language question or topic to retrieve context for", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 500 }, "example": "How do I use the app router?" } ], "responses": { "200": { "description": "Relevant documentation snippets as plain text", "content": { "text/plain": { "schema": { "type": "string" }, "example": "### useRouter()\n\nSource: https://github.com/vercel/next.js/...\n\nThe `useRouter` hook allows you to programmatically change routes inside Client Components.\n\n--------------------------------\n\n### app/layout.tsx\n\n```tsx\nexport default function Layout({ children }) {\n return {children}\n}\n```" } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ {}, { "bearerAuth": [] } ] } }, "/parse": { "post": { "summary": "Parse a Git repository", "description": "Queue a GitHub or GitLab repository for parsing and indexing. Returns immediately with a queue position. Monitor progress with `GET /parse-status`.", "operationId": "parseRepo", "tags": [ "Parse" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParseRepoRequest" }, "examples": { "minimal": { "summary": "Minimal - index the whole repo", "value": { "repoUrl": "https://github.com/your-org/your-repo" } }, "withOptions": { "summary": "With folder and branch filters", "value": { "repoUrl": "https://github.com/your-org/your-repo", "branch": "main", "folders": [ "docs" ], "excludeFolders": [ "node_modules" ], "force": false } } } } } }, "responses": { "202": { "$ref": "#/components/responses/ParseQueued" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ {}, { "bearerAuth": [] } ] } }, "/parse-openapi": { "post": { "summary": "Parse an OpenAPI spec by URL", "description": "Queue a remote OpenAPI specification (JSON or YAML) for parsing and indexing.", "operationId": "parseOpenApi", "tags": [ "Parse" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "openApiUrl" ], "properties": { "openApiUrl": { "type": "string", "format": "uri", "description": "URL of a JSON or YAML OpenAPI specification" }, "projectTitle": { "type": "string", "description": "Display name for the project" }, "description": { "type": "string", "description": "Short description shown in the library list" }, "force": { "type": "boolean", "description": "Re-parse even if already indexed", "default": false } } }, "example": { "openApiUrl": "https://example.com/openapi.json", "projectTitle": "My API" } } } }, "responses": { "202": { "$ref": "#/components/responses/ParseQueued" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ {}, { "bearerAuth": [] } ] } }, "/parse-openapi-upload": { "post": { "summary": "Upload an OpenAPI spec file", "description": "Upload an OpenAPI specification file directly for parsing and indexing.", "operationId": "parseOpenApiUpload", "tags": [ "Parse" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "openapiFile" ], "properties": { "openapiFile": { "type": "string", "format": "binary", "description": "A `.json` or `.yaml` OpenAPI specification file" } } } } } }, "responses": { "202": { "$ref": "#/components/responses/ParseQueued" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ {}, { "bearerAuth": [] } ] } }, "/import-libraries": { "post": { "summary": "Import a library bundle", "description": "Import pre-parsed libraries into an airgapped on-premise install. Accepts either a Context7 Cloud export `.zip` (`multipart/form-data`) or a JSON body (`application/json`) for programmatic clients. Requires a personal API key (or an admin session). Each library is queued as its own job and its snippets are re-embedded locally with this install's configured provider. Available only on installs running an **offline (airgapped) license**.", "operationId": "importLibraries", "tags": [ "Parse" ], "parameters": [ { "name": "force", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Overwrite libraries that already exist. Handy when posting a piped export body, which carries no `force` field. Without it, existing libraries are skipped." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportLibrariesRequest" } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "bundleFile" ], "properties": { "bundleFile": { "type": "string", "format": "binary", "description": "A Context7 Cloud `context7-libraries.zip` export (up to 100 MB)" }, "force": { "type": "boolean", "description": "Overwrite libraries that already exist on this install", "default": false } } } } } }, "responses": { "202": { "$ref": "#/components/responses/LibrariesImported" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] } ] } }, "/parse-website": { "post": { "summary": "Parse a website", "description": "Crawl and index a public website starting from the given URL.", "operationId": "parseWebsite", "tags": [ "Parse" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "websiteUrl" ], "properties": { "websiteUrl": { "type": "string", "format": "uri", "description": "Root URL to start crawling from" }, "projectTitle": { "type": "string", "description": "Display name for the project" }, "description": { "type": "string", "description": "Short description shown in the library list" }, "maxPages": { "type": "integer", "description": "Maximum number of pages to crawl", "default": 100 }, "maxDepth": { "type": "integer", "description": "Maximum link depth from the root URL", "default": 3 }, "excludePatterns": { "type": "array", "items": { "type": "string" }, "description": "URL path patterns to skip (e.g., `/blog/*`)" }, "force": { "type": "boolean", "description": "Re-crawl even if already indexed", "default": false } } }, "example": { "websiteUrl": "https://docs.example.com", "maxPages": 50 } } } }, "responses": { "202": { "$ref": "#/components/responses/ParseQueued" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ {}, { "bearerAuth": [] } ] } }, "/projects/{projectId}/refresh": { "post": { "summary": "Refresh a library", "description": "Re-parse an existing library using its stored settings. Returns immediately with a queue position.\n\nNot available for:\n- Libraries imported from Context7 Cloud (re-import an updated bundle instead)\n- Uploaded OpenAPI files (re-upload the file instead)", "operationId": "refreshProject", "tags": [ "Parse" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "Project identifier without the leading slash. For repositories use `owner/repo` (e.g. `upstash/ratelimit-js`). For websites use `websites/hostname` (e.g. `websites/upstash`). For OpenAPI specs use `openapi/derived-name`.", "schema": { "type": "string" }, "example": "upstash/ratelimit-js" } ], "responses": { "202": { "$ref": "#/components/responses/ParseQueued" }, "400": { "description": "Bad Request - refresh not available for this project type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "imported": { "summary": "Imported library", "value": { "error": "Refresh isn't available for imported libraries. Re-import an updated export from Context7 Cloud to update it." } }, "uploadedFile": { "summary": "Uploaded OpenAPI file", "value": { "error": "Refresh not available for uploaded OpenAPI files. Re-upload the same file to update." } }, "noToken": { "summary": "No git token configured", "value": { "error": "No git token configured for GitHub. Configure a GitHub App or set a personal access token." } } } } } }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "Conflict - a parse job is already active or queued for this project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "This project is already queued", "project": "/upstash/ratelimit-js", "status": "queued" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ {}, { "bearerAuth": [] } ] } }, "/parse-status": { "get": { "summary": "Get parse status", "description": "Returns the current status of all active and queued parse jobs.", "operationId": "getParseStatus", "tags": [ "Parse" ], "responses": { "200": { "description": "Active parse jobs and their status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParseStatusResponse" }, "example": { "activeParses": { "/your-org/your-repo": { "status": "parsing", "startedAt": "2025-01-01T12:00:00.000Z", "duration": 8.6, "statusMessage": "Scanning 16 files" }, "/other-org/other-repo": { "status": "queued", "position": 1, "createdAt": "2025-01-01T12:00:01.000Z" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ {}, { "bearerAuth": [] } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key generated from Personal Settings. See [Authentication](/enterprise/api/authentication#creating-an-api-key)." } }, "schemas": { "Library": { "type": "object", "description": "An indexed library", "properties": { "id": { "type": "string", "description": "Library ID to pass to `GET /v2/context`", "example": "/your-org/your-repo" }, "title": { "type": "string", "description": "Display name", "example": "Your Repo" }, "description": { "type": "string", "description": "Short description", "example": "Internal tooling docs" }, "totalSnippets": { "type": "integer", "description": "Number of indexed snippets", "example": 150 }, "source": { "type": "string", "description": "Where the library was indexed from", "example": "Local (Private)" }, "trustScore": { "type": "integer", "description": "Source reputation score (0–10)", "example": 10 } } }, "SearchResponse": { "type": "object", "properties": { "results": { "type": "array", "description": "Matching libraries ranked by relevance", "items": { "$ref": "#/components/schemas/Library" } } }, "required": [ "results" ] }, "ParseQueuedResponse": { "type": "object", "properties": { "message": { "type": "string", "example": "Parse queued" }, "project": { "type": "string", "description": "Project identifier assigned to this library (e.g. `/your-org/your-repo`)", "example": "/your-org/your-repo" }, "queueId": { "type": "integer", "description": "Numeric ID for this parse job", "example": 5 }, "position": { "type": "integer", "nullable": true, "description": "Position in the queue. `null` if the job started immediately", "example": 1 } }, "required": [ "message", "project", "queueId" ] }, "ImportLibrariesRequest": { "type": "object", "required": [ "libraries" ], "properties": { "libraries": { "type": "array", "description": "The libraries to import. Each carries its full snippet content; embeddings are recomputed on this install.", "items": { "$ref": "#/components/schemas/ImportLibrary" } }, "force": { "type": "boolean", "description": "Overwrite libraries that already exist on this install", "default": false } } }, "ImportLibrary": { "type": "object", "required": [ "project", "codeSnippets", "infoSnippets" ], "properties": { "project": { "type": "string", "description": "Library identifier, e.g. `/your-org/your-repo`", "example": "/vercel/next.js" }, "title": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string", "description": "Source type of the library (e.g. `repo`, `website`, `openapi`)" }, "language": { "type": "string", "example": "English" }, "branch": { "type": "string" }, "docsRepoUrl": { "type": "string" }, "docsSiteUrl": { "type": "string" }, "totalTokens": { "type": "integer" }, "codeSnippets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "language": { "type": "string" }, "codeList": { "type": "array", "items": { "type": "object", "properties": { "language": { "type": "string" }, "code": { "type": "string" } } } }, "tokens": { "type": "integer" } } } }, "infoSnippets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": "string" }, "breadcrumb": { "type": "string" }, "tokens": { "type": "integer" } } } } } }, "LibrariesImportedResponse": { "type": "object", "properties": { "message": { "type": "string", "example": "Queued 2 libraries for import" }, "queued": { "type": "array", "description": "Library identifiers queued for import", "items": { "type": "string" }, "example": [ "/vercel/next.js", "/facebook/react" ] }, "skipped": { "type": "array", "description": "Libraries that were not imported, with a reason", "items": { "type": "object", "properties": { "project": { "type": "string" }, "reason": { "type": "string", "example": "already exists" } } } } }, "required": [ "message", "queued", "skipped" ] }, "ParseRepoRequest": { "type": "object", "required": [ "repoUrl" ], "properties": { "repoUrl": { "type": "string", "format": "uri", "description": "HTTPS URL of the GitHub or GitLab repository" }, "branch": { "type": "string", "description": "Branch to parse. Defaults to the repository's default branch" }, "folders": { "type": "array", "items": { "type": "string" }, "description": "Only index files under these paths. Empty means the entire repository" }, "excludeFolders": { "type": "array", "items": { "type": "string" }, "description": "Paths to skip during indexing" }, "excludeFiles": { "type": "array", "items": { "type": "string" }, "description": "Glob patterns for files to exclude" }, "force": { "type": "boolean", "description": "Re-parse even if the current commit is already indexed", "default": false } } }, "ParseJobStatus": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "queued", "parsing", "finalizing" ], "description": "Current job status" }, "position": { "type": "integer", "description": "Queue position. Only present when `status` is `queued`" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the job was queued. Only present when `status` is `queued`" }, "startedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the job began running. Only present when `status` is `parsing` or `finalizing`" }, "duration": { "type": "number", "description": "Elapsed seconds since the job started. Only present when `status` is `parsing` or `finalizing`" }, "statusMessage": { "type": "string", "description": "Human-readable progress detail (e.g. `Scanning 16 files`). Only present when `status` is `parsing`" } }, "required": [ "status" ] }, "ParseStatusResponse": { "type": "object", "properties": { "activeParses": { "type": "object", "description": "Map of project name to its current parse job status", "additionalProperties": { "$ref": "#/components/schemas/ParseJobStatus" } } }, "required": [ "activeParses" ] }, "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error description" } }, "required": [ "error" ] } }, "responses": { "ParseQueued": { "description": "Parse job accepted and queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParseQueuedResponse" } } } }, "LibrariesImported": { "description": "Libraries accepted and queued for import", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibrariesImportedResponse" } } } }, "ForbiddenError": { "description": "Forbidden - the action is not permitted for this install or user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Library import is available only with an offline license." } } } }, "BadRequestError": { "description": "Bad Request - invalid or missing parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "repoUrl is required" } } } }, "UnauthorizedError": { "description": "Unauthorized - authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Authentication required" } } } }, "NotFoundError": { "description": "Not Found - library does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Project not found" } } } }, "InternalServerError": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "An unexpected error occurred" } } } } } }, "tags": [ { "name": "Search", "description": "Search indexed libraries" }, { "name": "Context", "description": "Retrieve documentation context for queries" }, { "name": "Parse", "description": "Parse and index new libraries" } ] }