Knowhere Node.js SDK

Official Node.js/TypeScript SDK for the Knowhere document parsing API.

Features

• 🚀 TypeScript-first - Full type safety with comprehensive type definitions
• 📦 Stream-based uploads - Efficient handling of large files
• 🔄 Automatic retries - Exponential backoff for transient failures
• 📊 Adaptive polling - Smart waiting for job completion
• 🎯 Progressive API - High-level convenience methods + low-level control
• ⚡ Modern JavaScript - ESM and CommonJS support

Installation

npm install @ontos-ai/knowhere-sdk

Requirements:

• Node.js >= 22.13.0
• npm >= 10.0.0
• TypeScript >= 5.0 (optional, for type checking)

Quick Start

importKnowherefrom'@ontos-ai/knowhere-sdk';// Initialize clientconstclient=newKnowhere({apiKey: process.env.KNOWHERE_API_KEY,});// Parse a document from URLconstresult=awaitclient.parse({url: 'https://example.com/document.pdf',});// Access parsed contentconsole.log(`Found ${result.textChunks.length} text chunks`);console.log(`Found ${result.imageChunks.length} images`);console.log(`Found ${result.tableChunks.length} tables`);console.log(`Found ${result.pageChunks.length} page chunks`);// Work with chunks — worker metadata is in chunk.metadataresult.textChunks.forEach((chunk)=>{console.log(chunk.content);console.log(chunk.metadata.keywords);console.log(chunk.metadata.summary);});result.pageChunks.forEach((chunk)=>{console.log(chunk.contentSource);// "summary"console.log(chunk.content);// page-level summaryconsole.log(chunk.metadata.pageNums);// citation pages});// Save results to diskawaitresult.save('./output/');

Configuration

Environment Variables

KNOWHERE_API_KEY=sk_... # Required
KNOWHERE_BASE_URL=https://api.knowhereto.ai # Optional

Client Options

constclient=newKnowhere({apiKey: 'sk_...',// API authentication keybaseURL: 'https://...',// API base URLtimeout: 60000,// Request timeout (ms)uploadTimeout: 600000,// Upload timeout (ms)maxRetries: 5,// Max retry attempts});

Usage Examples

Parse from File

// From file path (recommended)constresult=awaitclient.parse({file: './document.pdf',});// From Bufferconstbuffer=awaitfs.readFile('./document.pdf');constresult=awaitclient.parse({file: buffer,fileName: 'document.pdf',});// From Streamconststream=fs.createReadStream('./document.pdf');constresult=awaitclient.parse({file: stream,fileName: 'document.pdf',});

fileName is inferred automatically when file is a local file path. When file is a Buffer, Uint8Array, or a stream without path metadata, provide fileName explicitly.

Advanced Options

constresult=awaitclient.parse({url: 'https://example.com/doc.pdf',model: 'advanced',// 'base' | 'advanced'ocr: true,// Enable OCRdocType: 'pdf',// Document type hintsmartTitleParse: true,// Smart title detectionsummaryImage: true,// Generate image summariessummaryTable: true,// Generate table summariessummaryText: true,// Generate text summariesaddFragDesc: 'Custom context',// Additional fragment descriptionkbDir: 'project_docs',// Knowledge base directorypollInterval: 10000,// Polling interval (ms)pollTimeout: 1800000,// Max wait time (ms)verifyChecksum: true,// Verify ZIP checksum (default: true)webhook: {// Webhook for completionurl: 'https://...',},onUploadProgress: (progress)=>{console.log(`Upload: ${progress.percent}%`);},onPollProgress: (status)=>{console.log(`Status: ${status.status}`);},});

Bring Your Own Key (BYOK)

Pass per-request LLM credentials via llmConfig on parse/job create and retrieval queries. Flat root applies to both channels; use models for different model ids on the same endpoint, or text / vision for different provider endpoints. Use camelCase in TypeScript; the HTTP client serializes to snake_case on the wire.

// Multimodal shorthand — one model for text + visionconstllmConfig={apiKey: process.env.OPENAI_API_KEY,model: 'gpt-4o',baseUrl: 'https://api.openai.com/v1',};// Same endpoint, different models per channelconstmodelsConfig={apiKey: process.env.OPENAI_API_KEY,baseUrl: 'https://api.openai.com/v1',models: {text: 'gpt-4o-mini',vision: 'gpt-4o'},};// Or two different endpointsconstsplitLlmConfig={text: {apiKey: process.env.OPENAI_API_KEY,model: 'gpt-4o-mini',baseUrl: 'https://api.openai.com/v1',},vision: {apiKey: process.env.DASHSCOPE_API_KEY,model: 'qwen-vl-max',baseUrl: 'https://dashscope.aliyuncs.com/compatible-mode/v1',},};constresult=awaitclient.parse({url: 'https://example.com/doc.pdf',llmConfig: modelsConfig,});constresponse=awaitclient.retrieval.query({namespace: 'support-center',query: 'What is the refund policy?',useAgentic: true,llmConfig: splitLlmConfig,});

Page Citation Assets

Page citation assets are generated by Knowhere during page-memory parsing. The SDK does not render PDF pages locally; it preserves the page image descriptors returned by the server on page chunks and retrieval metadata.

importKnowherefrom'@ontos-ai/knowhere-sdk';constclient=newKnowhere({apiKey: process.env.KNOWHERE_API_KEY});constresult=awaitclient.parse({file: './manual.pdf',});for(constchunkofresult.pageChunks){console.log(chunk.metadata.pageAssets);}

metadata.pageAssets entries point at concrete page images stored with the Knowhere result. artifactRef is the durable result artifact path; assetUrl is an optional server-generated access URL.

typePageCitationAsset={pageNum: number;artifactRef: string;assetUrl?: string;contentType: 'image/png'|'image/jpeg';width?: number;height?: number;source: 'knowhere-rendered-page-citation-source';};

Document chunk APIs can include signed page image URLs when requested:

constchunks=awaitclient.documents.listChunks('doc_123',{chunkType: 'page',includeAssetUrls: true,});console.log(chunks.chunks[0]?.metadata.pageAssets?.[0]?.assetUrl);

Low-Level API

For granular control over the job lifecycle:

// 1. Create jobconstjob=awaitclient.jobs.create({sourceType: 'file',fileName: 'document.pdf',documentMetadata: {createdByClient: 'cli',sourceFileName: 'document.pdf',},parsingParams: {model: 'advanced',ocrEnabled: true},});// 2. Upload fileawaitclient.jobs.upload(job,{file: './document.pdf',onProgress: ({ percent })=>console.log(`${percent}%`),});// 3. Wait for completionconstjobResult=awaitclient.jobs.wait(job.jobId,{pollInterval: 10000,});// 4. Load resultsconstresult=awaitclient.jobs.load(jobResult);

Retrieval and Document Lifecycle

Published documents are queryable through the retrieval API after a job finishes. client.jobs.create(...) may return a planned documentId; persist jobResult.documentId after publication as the canonical value if you need to update or archive the same document later.

constjob=awaitclient.jobs.create({sourceType: 'url',sourceUrl: 'https://example.com/manual.pdf',namespace: 'support-center',documentMetadata: {createdByClient: 'notebook',title: 'Support manual',},});constjobResult=awaitclient.jobs.wait(job.jobId);constdocumentId=jobResult.documentId??job.documentId;if(!documentId){thrownewError('Expected documentId after successful publication.');}console.log(documentId);// Agentic mode (LLM navigation + answer synthesis)constresponse=awaitclient.retrieval.query({namespace: 'support-center',query: 'How do I reset Bluetooth pairing?',chunkTypes: ['page'],topK: 5,useAgentic: true,});console.log(response.answerText);// LLM-generated answerconsole.log(response.referencedChunks);// cited evidence chunksconsole.log(response.evidenceText);// rendered evidence context, when returnedconsole.log(response.stopReason);// agentic termination reason, when returnedconsole.log(response.failureReason);// no-answer reason, when returnedfor(constresultofresponse.results){console.log(result.content);console.log(result.contentSource);console.log(result.score);console.log(result.metadata?.pageNums);console.log(result.source.sourceFileName,result.source.sectionPath);}

Retrieval results use one canonical source object:

result.content;result.chunkId;result.chunkType;result.contentSource;result.score;result.assetUrl;result.metadata;result.source.documentId;result.source.sourceFileName;result.source.sectionPath;

Agentic references expose the current retrieval citation fields:

constreference=response.referencedChunks[0];reference.chunkId;reference.documentId;reference.chunkType;reference.contentSource;reference.sectionPath;reference.filePath;reference.jobId;reference.assetUrl;reference.metadata;

Use documentId to update or archive a document:

constupdateJob=awaitclient.jobs.create({sourceType: 'url',sourceUrl: 'https://example.com/manual-v2.pdf',
documentId,});constdocuments=awaitclient.documents.list({namespace: 'support-center',page: 1,pageSize: 50,});constdocument=awaitclient.documents.get(documentId);constchunks=awaitclient.documents.listChunks(documentId,{page: 1,pageSize: 50,chunkType: 'page',includeAssetUrls: true,});constarchived=awaitclient.documents.archive(documentId);console.log(documents.documents.length);console.log(documents.pagination.totalPages);console.log(document.status);console.log(chunks.pagination.total);if(chunks.chunks[0]){constchunk=awaitclient.documents.getChunk(documentId,chunks.chunks[0].id,{includeAssetUrls: true,});console.log(chunk.chunk.content);console.log(chunk.chunk.contentSource);console.log(chunk.chunk.metadata.pageNums);console.log(chunk.chunk.assetUrl);}console.log(archived.status);

Local Knowledge Tools

The SDK can also run exact inspection tools over parsed results. Local import helpers still write under the SDK cache directory by design, while published documentId reads use configured parsed storage first and fall back to Knowhere's remote chunk API without importing the result ZIP into local disk. Server workflows can configure parsed storage with client.knowledge.withParsedStorage(...) so Notebook, MCP, and CLI surfaces share the same committed result-layout model.

constparsed=awaitclient.knowledge.parseToLocalCache({file: './manual.pdf',localDocumentId: 'manual',});constoutline=awaitclient.knowledge.getDocumentOutline(parsed.document.localDocumentId);constread=awaitclient.knowledge.readChunks({localDocumentId: parsed.document.localDocumentId,sectionPath: outline.sections[0]?.sectionPath,limit: 5,});constgrep=awaitclient.knowledge.grepChunks({localDocumentId: parsed.document.localDocumentId,pattern: 'warranty',maxResults: 10,});// grep.matches include pageNumbers when the source chunk has them.constserverSearch=awaitclient.knowledge.search({query: 'battery warranty',localDocumentIds: [parsed.document.localDocumentId],topK: 5,});console.log(read.chunks);console.log(grep.matches);console.log(serverSearch.references);

Local grep and reads use the cached parse result. Published documentId grep streams documents.listChunks(...) page by page when parsed storage is missing or stale. Search uses the Knowhere API retrieval query; local document IDs only help map returned server document IDs back to local cache IDs when available. When knowledge.parseToLocalCache(...), knowledge.importJobResult(...), or knowledge.loadJobResult(...) runs with configured parsed storage, the SDK writes the expanded Knowhere result layout (manifest.json, chunks.json, sidecars, and assets), sync progress, and a final .knowhere-sdk/commit.json before returning. Partial storage writes are ignored until the commit marker is present.

constknowledge=client.knowledge.withParsedStorage({storage: myParsedDocumentStorage,scheduler: myBackgroundScheduler,limits: {remotePageSize: 100,maxPagesPerSync: 10},});

If a search result only has a published documentId, read-oriented helpers can accept that remote identifier directly. readChunks supports display paging; remote fallback requests asset URLs from the Knowhere API, and storage hits use stored object URLs when the configured storage can resolve them:

constremoteRead=awaitknowledge.readChunks({documentId: 'doc_123',page: 1,pageSize: 20,chunkType: 'page',});constremoteOutline=awaitknowledge.getDocumentOutline({documentId: 'doc_123',});constgrep=awaitknowledge.grepChunks({documentId: 'doc_123',pattern: 'warranty',maxResults: 10,});constjobRead=awaitknowledge.readChunks({jobId: jobResult.jobId,localDocumentId: 'manual',limit: 5,});

The MCP package is a wrapper over this SDK interface; install it only when an agent host needs an MCP server. See the MCP package README for Codex, Claude Code, Claude Desktop, and generic stdio MCP host configuration examples.

For longer parses, use the non-blocking SDK flow and cache the result after the job completes:

conststarted=awaitclient.knowledge.startParse({file: './manual.pdf',localDocumentId: 'manual',});conststatus=awaitclient.knowledge.getJobStatus(started.job.jobId);if(status.job.isDone&&status.cache.document){console.log(status.cache.document.localDocumentId);}

When the job was started through client.knowledge.startParse(...), getJobStatus(...) automatically caches the completed result locally the first time it observes status.job.isDone. Use importJobResult(...) to recover a completed job into the local cache when it was not started through the local knowledge helper, or to retry a local import step explicitly. Use loadJobResult(...) for server workflows that should load a completed result without creating SDK local-disk cache state. Use syncParsedDocument(...) to explicitly resume or retry parsed-storage sync for an existing documentId, jobId, or local parsed result.

Follow-up queries can exclude documents or sections for one request:

constfollowUp=awaitclient.retrieval.query({namespace: 'support-center',query: 'battery charging',excludeDocumentIds: ['doc_old'],excludeSections: [{documentId: 'doc_123',sectionPath: 'Appendix / Legal'}],});

Error Handling

import{BadRequestError,AuthenticationError,RateLimitError,PollingTimeoutError,JobFailedError,ValidationError,InvalidStateError,}from'@ontos-ai/knowhere-sdk';try{constresult=awaitclient.parse({url: '...'});}catch(error){if(errorinstanceofValidationError){console.error('Invalid parameters:',error.message);}elseif(errorinstanceofRateLimitError){// Wait and retryawaitsleep(error.retryAfter*1000);}elseif(errorinstanceofAuthenticationError){console.error('Invalid API key');}elseif(errorinstanceofPollingTimeoutError){console.error('Processing timeout');}elseif(errorinstanceofJobFailedError){console.error('Job failed:',error.jobResult.error);}elseif(errorinstanceofInvalidStateError){console.error('Invalid state:',error.message);}}

Documentation

For complete documentation, visit https://docs.knowhereto.ai

Examples

Check out the examples directory for more usage examples:

• Basic Usage
• File Upload
• Error Handling
• Low-Level API

Development

# Install dependencies
npm ci
# Run tests
npm test# Run tests with coverage
npm run test:ci
# Lint code
npm run lint
# Format code
npm run format
# Type check
npm run typecheck
# Build
npm run build

Release Workflow

See docs/release-workflow.md for the Changesets-based stable and beta release process.

Community

• Contributing guide: CONTRIBUTING.md
• Security policy: SECURITY.md
• Code of conduct: CODE_OF_CONDUCT.md

License

MIT

Support

• 📧 Email: team@knowhereto.ai
• 🐛 Issues: GitHub Issues
• 📚 Documentation: https://docs.knowhereto.ai

Changelog

See CHANGELOG.md for release history.