Skip to content

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

docs(enterprise): add on-premise API reference (#2810)

Fahreddin Özcan8a6c029f659a
diff --git a/docs/docs.json b/docs/docs.json
index bf5e7dfb..8201afc2 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -87,7 +87,32 @@
]
},
"enterprise/backup-restore",
- "enterprise/library-import"
+ "enterprise/library-import",
+ {
+ "group": "API Reference",
+ "pages": [
+ "enterprise/api/authentication",
+ {
+ "group": "Search",
+ "pages": ["enterprise/api/search/search-for-libraries"]
+ },
+ {
+ "group": "Context",
+ "pages": ["enterprise/api/context/get-documentation-context"]
+ },
+ {
+ "group": "Parse",
+ "pages": [
+ "enterprise/api/parse/parse-a-git-repository",
+ "enterprise/api/parse/parse-an-openapi-spec-by-url",
+ "enterprise/api/parse/upload-an-openapi-spec-file",
+ "enterprise/api/parse/parse-a-website",
+ "enterprise/api/parse/refresh-a-library",
+ "enterprise/api/parse/get-parse-status"
+ ]
+ }
+ ]
+ }
]
}
]
diff --git a/docs/enterprise/api/authentication.mdx b/docs/enterprise/api/authentication.mdx
new file mode 100644
index 00000000..4a5c8730
--- /dev/null
+++ b/docs/enterprise/api/authentication.mdx
@@ -0,0 +1,64 @@
+---
+title: "Authentication"
+description: "How to authenticate requests to your on-premise Context7 instance"
+---
+
+The on-premise API supports API keys for server-to-server and MCP access. Pass the key in the `Authorization` header:
+
+```bash
+Authorization: Bearer ctx7op-xxxxxxxx_xxxxxxxxxxxxxxxx
+```
+
+Keys are scoped to the user account that created them and inherit that user's role (`admin` or `member`). There are no per-key scopes or expiry - revoke a key to invalidate it.
+
+## Creating an API Key
+
+<Steps>
+ <Step title="Open Settings">
+ Go to **Personal Settings > API Keys** in the admin dashboard and click **Create API Key**.
+
+ <Frame>
+ ![API Keys settings page](/images/enterprise/api-keys/api-keys-empty.png)
+ </Frame>
+ </Step>
+ <Step title="Name the key">
+ Give the key a descriptive name so you know which client or service is using it (e.g. `CI pipeline`, `Cursor`).
+
+ <Frame>
+ ![Create API Key dialog](/images/enterprise/api-keys/api-keys-create-dialog.png)
+ </Frame>
+ </Step>
+ <Step title="Copy the key">
+ Copy the full key value before closing the dialog. It is only shown once.
+
+ <Frame>
+ ![API Key Created dialog showing the key value](/images/enterprise/api-keys/api-keys-created.png)
+ </Frame>
+ </Step>
+</Steps>
+
+<Warning>API keys are shown only once at creation. Store yours securely before closing the dialog.</Warning>
+
+## Revoking a Key
+
+Go to **Settings > API Keys** and click the delete icon next to the key. Revocation is immediate and cannot be undone. Update any integrations using the key before revoking.
+
+## Roles
+
+| Role | Access |
+|---|---|
+| `admin` | Full access to all endpoints including settings, user management, and delete operations |
+| `member` | Can trigger parsing and search. Cannot access admin endpoints |
+
+Default credentials on a fresh install are `admin` / `admin`. Change them immediately from **Settings > Change Credentials**.
+
+## Anonymous Access
+
+Certain operations can be allowed without authentication. Configure them from **Settings > Permissions**:
+
+| Permission | Default |
+|---|---|
+| Anonymous parse / refresh | Off |
+| Anonymous delete | Off |
+
+The search (`GET /v2/libs/search`) and context (`GET /v2/context`) endpoints are always publicly accessible unless a global `API_KEY` environment variable is set, in which case every endpoint requires a bearer token.
diff --git a/docs/enterprise/api/context/get-documentation-context.mdx b/docs/enterprise/api/context/get-documentation-context.mdx
new file mode 100644
index 00000000..dd5c56ad
--- /dev/null
+++ b/docs/enterprise/api/context/get-documentation-context.mdx
@@ -0,0 +1,5 @@
+---
+title: "Get documentation context"
+description: "Retrieve documentation snippets for a library ranked by relevance to your query"
+openapi: "openapi-enterprise.json GET /v2/context"
+---
diff --git a/docs/enterprise/api/parse/get-parse-status.mdx b/docs/enterprise/api/parse/get-parse-status.mdx
new file mode 100644
index 00000000..f77affd9
--- /dev/null
+++ b/docs/enterprise/api/parse/get-parse-status.mdx
@@ -0,0 +1,5 @@
+---
+title: "Get parse status"
+description: "Returns the status of all active and queued parse jobs"
+openapi: "openapi-enterprise.json GET /parse-status"
+---
diff --git a/docs/enterprise/api/parse/parse-a-git-repository.mdx b/docs/enterprise/api/parse/parse-a-git-repository.mdx
new file mode 100644
index 00000000..962258f8
--- /dev/null
+++ b/docs/enterprise/api/parse/parse-a-git-repository.mdx
@@ -0,0 +1,5 @@
+---
+title: "Parse a Git repository"
+description: "Queue a GitHub or GitLab repository for parsing and indexing"
+openapi: "openapi-enterprise.json POST /parse"
+---
diff --git a/docs/enterprise/api/parse/parse-a-website.mdx b/docs/enterprise/api/parse/parse-a-website.mdx
new file mode 100644
index 00000000..200f9f3d
--- /dev/null
+++ b/docs/enterprise/api/parse/parse-a-website.mdx
@@ -0,0 +1,5 @@
+---
+title: "Parse a website"
+description: "Crawl and index a public website starting from the given URL"
+openapi: "openapi-enterprise.json POST /parse-website"
+---
diff --git a/docs/enterprise/api/parse/parse-an-openapi-spec-by-url.mdx b/docs/enterprise/api/parse/parse-an-openapi-spec-by-url.mdx
new file mode 100644
index 00000000..1eb0a3f3
--- /dev/null
+++ b/docs/enterprise/api/parse/parse-an-openapi-spec-by-url.mdx
@@ -0,0 +1,5 @@
+---
+title: "Parse an OpenAPI spec by URL"
+description: "Queue a remote OpenAPI specification (JSON or YAML) for parsing and indexing"
+openapi: "openapi-enterprise.json POST /parse-openapi"
+---
diff --git a/docs/enterprise/api/parse/refresh-a-library.mdx b/docs/enterprise/api/parse/refresh-a-library.mdx
new file mode 100644
index 00000000..ac79d2f2
--- /dev/null
+++ b/docs/enterprise/api/parse/refresh-a-library.mdx
@@ -0,0 +1,5 @@
+---
+title: "Refresh a library"
+description: "Re-parse an existing library using its stored settings"
+openapi: "openapi-enterprise.json POST /projects/{projectId}/refresh"
+---
diff --git a/docs/enterprise/api/parse/upload-an-openapi-spec-file.mdx b/docs/enterprise/api/parse/upload-an-openapi-spec-file.mdx
new file mode 100644
index 00000000..a4c7efe3
--- /dev/null
+++ b/docs/enterprise/api/parse/upload-an-openapi-spec-file.mdx
@@ -0,0 +1,5 @@
+---
+title: "Upload an OpenAPI spec file"
+description: "Upload an OpenAPI specification file directly for parsing and indexing"
+openapi: "openapi-enterprise.json POST /parse-openapi-upload"
+---
diff --git a/docs/enterprise/api/search/search-for-libraries.mdx b/docs/enterprise/api/search/search-for-libraries.mdx
new file mode 100644
index 00000000..daffa005
--- /dev/null
+++ b/docs/enterprise/api/search/search-for-libraries.mdx
@@ -0,0 +1,5 @@
+---
+title: "Search for libraries"
+description: "Search locally indexed libraries by name"
+openapi: "openapi-enterprise.json GET /v2/libs/search"
+---
diff --git a/docs/images/enterprise/api-keys/api-keys-create-dialog.png b/docs/images/enterprise/api-keys/api-keys-create-dialog.png
new file mode 100644
index 00000000..91bc1b21
Binary files /dev/null and b/docs/images/enterprise/api-keys/api-keys-create-dialog.png differ
diff --git a/docs/images/enterprise/api-keys/api-keys-created.png b/docs/images/enterprise/api-keys/api-keys-created.png
new file mode 100644
index 00000000..6a52f824
Binary files /dev/null and b/docs/images/enterprise/api-keys/api-keys-created.png differ
diff --git a/docs/images/enterprise/api-keys/api-keys-empty.png b/docs/images/enterprise/api-keys/api-keys-empty.png
new file mode 100644
index 00000000..55c15e83
Binary files /dev/null and b/docs/images/enterprise/api-keys/api-keys-empty.png differ
diff --git a/docs/openapi-enterprise.json b/docs/openapi-enterprise.json
new file mode 100644
index 00000000..d2a6293e
--- /dev/null
+++ b/docs/openapi-enterprise.json
@@ -0,0 +1,739 @@
+{
+ "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 <html><body>{children}</body></html>\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": [] }
+ ]
+ }
+ },
+ "/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"]
+ },
+ "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"
+ }
+ }
+ }
+ },
+ "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"
+ }
+ ]
+}