Quickstart

Follow these steps to go from zero to searching your documents.

Start bigRAG

docker compose up -d

Wait for all services to be healthy, then verify:

curl http://localhost:6100/health

Set up authentication (optional)

If you set BIGRAG_API_SECRET, include it in all requests:

export BIGRAG_API_SECRET="your-api-secret"
export BASE="http://localhost:6100"

Create a collection

A collection groups documents that share the same embedding configuration.

curl -X POST $BASE/v1/collections \
  -H "Authorization: Bearer $BIGRAG_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "knowledge_base",
    "description": "Company knowledge base",
    "chunk_size": 512,
    "chunk_overlap": 50
  }'

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

const client = new BigRAG({
  apiSecret: "your-api-secret",
  baseUrl: "http://localhost:6100",
});

const collection = await client.createCollection({
  name: "knowledge_base",
  description: "Company knowledge base",
  chunk_size: 512,
  chunk_overlap: 50,
});

Upload a document

curl -X POST $BASE/v1/collections/knowledge_base/documents \
  -H "Authorization: Bearer $BIGRAG_API_SECRET" \
  -F "file=@handbook.pdf" \
  -F 'metadata={"department": "engineering"}'

const doc = await client.uploadDocument(
  "knowledge_base",
  new File([buffer], "handbook.pdf"),
  { department: "engineering" }
);

The document starts as pending and transitions to processing then ready.

Check document status

curl $BASE/v1/collections/knowledge_base/documents \
  -H "Authorization: Bearer $BIGRAG_API_SECRET"

// Stream real-time progress
for await (const event of client.streamDocumentProgress("knowledge_base", doc.id)) {
  console.log(`${event.step}: ${event.progress}%`);
  if (event.status === "complete") break;
}

Query the collection

Once documents are ready, you can search:

curl -X POST $BASE/v1/collections/knowledge_base/query \
  -H "Authorization: Bearer $BIGRAG_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the PTO policy?",
    "top_k": 5
  }'

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

for (const result of results) {
  console.log(`[${result.score.toFixed(3)}] ${result.text}`);
}

Next Steps

Learn about Collections and how to configure them
Explore Search modes — semantic, keyword, and hybrid
Set up Webhooks for processing notifications
Read the full API Reference