Context7 Platform -- Up-to-date docs for AI agents
docs(enterprise): document programmatic library import/export API (#2887)
Fahreddin Özcanea82d5585aca
diff --git a/docs/docs.json b/docs/docs.jsonindex f63cc06d..46566198 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -120,6 +120,7 @@"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/import-libraries","enterprise/api/parse/parse-a-website","enterprise/api/parse/refresh-a-library","enterprise/api/parse/get-parse-status"diff --git a/docs/enterprise/api/parse/import-libraries.mdx b/docs/enterprise/api/parse/import-libraries.mdxnew file mode 100644index 00000000..c51bbe98--- /dev/null+++ b/docs/enterprise/api/parse/import-libraries.mdx@@ -0,0 +1,5 @@+---+title: "Import a library bundle"+description: "Import pre-parsed libraries into an airgapped on-premise install, as a JSON body or a Context7 Cloud export file"+openapi: "openapi-enterprise.json POST /import-libraries"+---diff --git a/docs/enterprise/library-import.mdx b/docs/enterprise/library-import.mdxindex 7d68a389..0c4169fe 100644--- a/docs/enterprise/library-import.mdx+++ b/docs/enterprise/library-import.mdx@@ -121,6 +121,61 @@ Because your install didn't parse these libraries from source, it can't refreshRe-importing a library you already have does nothing unless **Overwrite existing libraries** is checked. The import skips libraries that already exist and tells you which ones it skipped.</Note>+## Automating with the API++Besides the dashboard flow, both sides expose an API so you can script imports. For example, you can sync a fixed set of libraries into on-premise on a schedule from a bridge host that can reach both networks.++<Steps>++<Step title="Export from Context7 Cloud">++Call the cloud export endpoint with your **enterprise license key** in the `Authorization` header. It returns one library's full content (every code and info snippet, without embeddings), already shaped for the import endpoint.++```bash+curl -X POST https://context7.com/api/v1/enterprise/export \+ -H "Authorization: Bearer YOUR_LICENSE_KEY" \+ -H "Content-Type: application/json" \+ -d '{"library":"vercel/next.js"}'+```++Only public libraries can be exported this way.++</Step>++<Step title="Import into your on-premise install">++Post that JSON to your install's [import endpoint](/enterprise/api/parse/import-libraries), authenticated with a [personal API key](/enterprise/api/authentication#creating-an-api-key). The body is `{ "libraries": [...], "force": false }`, which is exactly the export response shape.++```bash+curl -X POST https://your-instance.example.com/api/import-libraries \+ -H "Authorization: Bearer YOUR_API_KEY" \+ -H "Content-Type: application/json" \+ --data @library.json+```++</Step>++</Steps>++From a host that can reach both networks, such as a bridge or import gateway, the two calls chain directly:++```bash+curl -sf -X POST https://context7.com/api/v1/enterprise/export \+ -H "Authorization: Bearer YOUR_LICENSE_KEY" \+ -H "Content-Type: application/json" \+ -d '{"library":"vercel/next.js"}' \+| curl -X POST https://your-instance.example.com/api/import-libraries \+ -H "Authorization: Bearer YOUR_API_KEY" \+ -H "Content-Type: application/json" \+ --data-binary @-+```++For a strictly airgapped install, save the export response to a file, transfer it the same way you would the `.zip`, then import it. The import endpoint also accepts the dashboard `.zip` bundle as a `multipart/form-data` upload (field `bundleFile`). See the [endpoint reference](/enterprise/api/parse/import-libraries) for details.++<Note>+The import endpoint is available only on offline-license installs, the same gate as the dashboard flow. A library that already exists is skipped unless you overwrite it with `force`, either as a `?force=true` query param (handy when piping the export straight through) or a `"force": true` field in a JSON body. The response lists what it queued and skipped.+</Note>+## Limits- Up to 50 libraries per export.diff --git a/docs/openapi-enterprise.json b/docs/openapi-enterprise.jsonindex d2a6293e..0c1d116f 100644--- a/docs/openapi-enterprise.json+++ b/docs/openapi-enterprise.json@@ -309,6 +309,69 @@]}},+ "/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",@@ -581,6 +644,111 @@},"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"],@@ -684,6 +852,25 @@}}},+ "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": {