TypeScript SDK

npm install @bigrag/client

import { APIError, type Document } from "@bigrag/client/browser";

import { BigRAG } from "@bigrag/client";

const client = new BigRAG({
  apiKey: process.env.BIGRAG_API_KEY!, // bigrag_sk_... minted via /v1/admin/api-keys
  baseUrl: "http://localhost:4000",
});

// Create a collection
const collection = await client.collections.create({
  name: "knowledge_base",
  description: "Company docs",
  chunk_size: 512,
});

// Upload a document
const doc = await client.documents.upload("knowledge_base", file);

// Poll processing status
let current = doc;
while (current.status === "pending" || current.status === "processing") {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  current = await client.documents.get("knowledge_base", doc.id);
  console.log(current.progress?.message ?? current.status);
}

// Query
const { results } = await client.queries.query("knowledge_base", {
  query: "What is the PTO policy?",
  top_k: 5,
});

client.collections.list({ name?, limit?, offset? })
client.collections.listAll({ name?, limit? })  // AsyncGenerator that pages through every collection
client.collections.create({
  name,
  description?,
  embedding_preset_id?,
  embedding_provider?,      // "openai" | "cohere" | "voyage" | "openai_compatible"
  embedding_model?,
  embedding_api_key?,
  embedding_base_url?,
  dimension?,
  chunk_size?, chunk_overlap?, chunk_strategy?,    // "paragraph" | "recursive"
  tenant_field?,            // metadata key required for tenant filtering
  metadata_schema?,         // JSON Schema
  reranking_enabled?, reranking_model?, reranking_api_key?,
  multimodal_enabled?, multimodal_enrichment_enabled?,
  default_top_k?, default_min_score?, default_search_mode?,
  metadata?,
})
client.collections.get(name)
client.collections.stats(name)
client.collections.update(name, {
  description?, metadata?, embedding_api_key?,
  chunk_strategy?, metadata_schema?,
  reranking_enabled?, reranking_model?, reranking_api_key?,
  multimodal_enabled?, multimodal_enrichment_enabled?,
  default_top_k?, default_min_score?, default_search_mode?,
})
client.collections.delete(name)
client.collections.truncate(name)        // delete all documents, keep the collection
client.collections.analytics(name)

client.documents.upload(collection, file, metadata?)
client.documents.batchUpload(collection, files, metadata?)
client.documents.list(collection, { q?, status?, sort?, order?, limit?, offset? })
client.documents.listAll(collection, { q?, status?, sort?, order?, limit? })  // AsyncGenerator
client.documents.get(collection, documentId)
client.documents.delete(collection, documentId)
client.documents.getChunks(collection, documentId, { limit?, offset? }?)
client.documents.getElements(collection, documentId, { limit?, offset? }?)

const answer = await client.chat.create({
  collection: "docs",
  message: "What is the PTO policy?",
  top_k: 8,
  search_mode: "hybrid",
});
console.log(answer.assistant_message.content);

const suggestions = await client.chat.getQuestionSuggestions("docs");
const fresh = await client.chat.generateQuestionSuggestions({ collection: "docs" });

for await (const event of client.chat.stream({
  collection: "docs",
  message: "Answer with citations",
})) {
  if (event.event === "delta") process.stdout.write(event.data.delta);
}

client.queries.query(collection, {
  query,
  top_k?, filters?, min_score?,
  search_mode?,             // "semantic" | "keyword" | "hybrid"
  rerank?,
  skip_cache?,
  multimodal?,
})
// Response exposes: results, query, collection, total, timings
// Multimodal collections include result.multimodal_elements

client.queries.multiQuery({
  query, collections, top_k?, filters?, min_score?, search_mode?, rerank?, skip_cache?, multimodal?
})
client.queries.batchQuery({
  queries: [{ collection, query, top_k?, search_mode?, skip_cache? }, ...]
})

client.vectors.upsert(collection, vectors)
client.vectors.delete(collection, ids)

client.webhooks.create({ url, events, collections? })
client.webhooks.list({ limit?, offset? })
client.webhooks.get(id)
client.webhooks.update(id, { url?, events?, collections?, active? })
client.webhooks.delete(id)
client.webhooks.listDeliveries(id, { limit?, offset? })
client.webhooks.test(id)
client.webhooks.replayDelivery(id, deliveryId)

client.auth.setupStatus()
client.auth.setup({ email, password, display_name? })
client.auth.login({ email, password })
client.auth.logout()
client.auth.logoutAll()
client.auth.me()
client.auth.whoami()
client.auth.changePassword({ current_password, new_password })
client.auth.getPreferences()
client.auth.updatePreferences({ theme: "dark" })

client.admin.users.list({ limit?, offset? })
client.admin.users.create({ email, password, display_name?, role? })
client.admin.users.update(userId, { email?, display_name?, role?, password? })
client.admin.users.delete(userId)

client.admin.apiKeys.list({ limit?, offset? })
client.admin.apiKeys.create({ name, expires_at?, scopes?, collection? })
client.admin.apiKeys.update(keyId, { name?, active?, expires_at?, scopes?, collection? })
client.admin.apiKeys.rotate(keyId)
client.admin.apiKeys.delete(keyId)

client.admin.access.logs({ action?, actorId?, collection?, statusFamily?, success?, limit?, offset? })
client.admin.access.overview({ windowDays? })
client.admin.audit.list({ action?, actorId?, resourceType?, limit?, offset? })

client.admin.settings.list()
client.admin.settings.test({ values })
client.admin.settings.update({ values })
client.admin.settings.reset({ keys })
client.admin.settings.purgeEmbeddingCache()

client.admin.vectorStorage.overview()

client.admin.embeddingPresets.list({ limit?, offset? })
client.admin.embeddingPresets.create({ name, provider, model, api_key, base_url?, dimension })
client.admin.embeddingPresets.update(presetId, { name?, provider?, model?, api_key?, base_url?, dimension? })
client.admin.embeddingPresets.test({ provider, model, api_key?, base_url? })
client.admin.embeddingPresets.testSaved(presetId)
client.admin.embeddingPresets.delete(presetId)

client.admin.mcpServers.list()
client.admin.mcpServers.create({ title, server_name, collection? })
client.admin.mcpServers.update(serverId, { title?, server_name?, collection? })
client.admin.mcpServers.rotate(serverId)
client.admin.mcpServers.delete(serverId)

client.connectors.s3.sources({ collection? })
client.connectors.s3.createSource({
  collection_name,
  bucket,
  prefix?,
  region?,
  endpoint_url?,
  force_path_style?,
  access_key_id,
  secret_access_key,
  session_token?,
  metadata?,
  schedule_enabled?,
  sync_interval_hours?,
})
client.connectors.s3.updateSource(sourceId, {
  bucket?,
  prefix?,
  region?,
  endpoint_url?,
  force_path_style?,
  access_key_id?,
  secret_access_key?,
  session_token?,
  metadata?,
  schedule_enabled?,
  sync_interval_hours?,
})
client.connectors.s3.deleteSource(sourceId)
client.connectors.s3.syncSource(sourceId)
client.connectors.s3.syncJobs({ collection?, sourceId?, limit? })

client.evaluations.run({
  collection: "docs",
  cases: [{ query: "What is RAG?", relevant_ids: ["doc-id"] }],
  top_k: 10,
  search_mode: "hybrid",
})

client.health()                          // GET /health
client.readiness()                       // GET /health/ready
client.getStats()                        // GET /v1/stats
client.listEmbeddingModels()             // GET /v1/embeddings/models
client.getUsage({ windowDays? })          // GET /v1/usage
client.getOverviewStatus()               // GET /v1/status/overview
client.getCollectionsStatus()            // GET /v1/status/collections
client.getUsageStatus({ windowDays? })    // GET /v1/status/usage
client.getAccessStatus({ windowDays? })   // GET /v1/admin/status/access
client.collections.analytics(collection) // GET /v1/collections/{name}/analytics

import {
  BigRAG,
  AuthenticationError,
  NotFoundError,
  APIError,
} from "@bigrag/client";

try {
  await client.collections.get("missing");
} catch (err) {
  if (err instanceof NotFoundError) {
    // 404
  } else if (err instanceof AuthenticationError) {
    // 401
  } else if (err instanceof APIError) {
    // any other API error — check err.status
  }
}