Kyro API

Self-hosted RAG API. Upload documents, embed them locally, and ask questions grounded in your own files — no data leaves your server.

How to use Kyro

Kyro gives you three ways to interact with your documents — pick whichever fits your workflow. All three talk to the same backend running on your server.

Dashboard

Kyro ships with a built-in web dashboard available at the root of your instance (e.g. http://localhost:3000). It's the fastest way to get started — no API calls required.

read   — list files, search, ask questions
write  — upload, delete, embed files
admin  — full access including key management

TypeScript SDK

kyro-sdk is the official client library for Node.js and the browser. It wraps every HTTP endpoint with typed methods, handles streaming SSE responses, and throws structured errors you can catch and branch on.

npm i @kyroinfra/kyro

import { KyroClient } from "kyro-sdk";

const kyro = new KyroClient({ 
  baseURL: "http://localhost:3000/api/v2",
  apiKey:  "kyro_live_...",
});

// Upload a file
const file = await kyro.files.upload(blob, "report.pdf");

// Ask a question (non-streaming)
const { answer, sources } = await kyro.files.ask({ 
  question: "What are the key findings?",
  stream:   false,
});

Typical workflow

End-to-end: upload → tag → embed → ask.

// 1. Upload
const file = await kyro.files.upload(pdfBlob, "agreement.pdf");

// 2. Tag with metadata
await kyro.files.setMetadata(file.id, { 
  document_type: "contract",
  matter_number: "M-2024-001",
});

// 3. Add to a collection
await kyro.collections.addFiles(collectionId, { fileIds: [file.id] });

// 4. Poll until embedded
let status = (await kyro.files.getText(file.id)).extractionStatus;
while (status !== "completed") { 
  await new Promise(r => setTimeout(r, 2000));
  status = (await kyro.files.getText(file.id)).extractionStatus;
}
await kyro.files.embed(file.id);

// 5. Ask questions
const { answer } = await kyro.files.ask({ 
  question:     "What are the termination conditions?",
  collectionId: collectionId,
  stream:       false,
});

SDK · Files

All file operations live on kyro.files.

const file = await kyro.files.upload(blob, "contract.pdf");
// file.id, file.extractionStatus

const { data, pagination } = await kyro.files.list(50);
if (pagination.hasMore) {
  const next = await kyro.files.list(50, pagination.nextCursor);
}

const blob = await kyro.files.download(fileId);

await kyro.files.delete(fileId);

const { extractionStatus, extractedText } = await kyro.files.getText(fileId);
// extractionStatus: "pending" | "processing" | "completed" | "failed" | "skipped"

await kyro.files.triggerExtraction(fileId);

const { chunksCreated } = await kyro.files.embed(fileId);

await kyro.files.setMetadata(fileId, {
  matter_number: "M-2024-001",
  document_type: "contract",
});

const meta = await kyro.files.getMetadata(fileId);

await kyro.files.deleteMetadataKey(fileId, "counterparty");

const { data } = await kyro.files.search("indemnification clause");
// data[i].headline — snippet with <mark> highlights

const { data } = await kyro.files.semanticSearch({
  query:        "force majeure clause",
  collectionId: collectionId,
  limit:        10,
});
// data[i]: { fileId, fileName, chunkIndex, content, rrfScore }

SDK · Collections

All collection operations live on kyro.collections. A collection is a named group of files — scope search and /ask to it by passing its ID.

const col = await kyro.collections.create({
  name:        "Q4 Contracts",
  description: "All contracts signed in Q4 2024",
});

const collections = await kyro.collections.list();

const col = await kyro.collections.get(collectionId);
// col.queryReady — true when ready to search

await kyro.collections.update(collectionId, { name: "Q4 Agreements" });

await kyro.collections.delete(collectionId);

await kyro.collections.addFiles(collectionId, {
  fileIds: [fileId1, fileId2],
});

const { data } = await kyro.collections.listFiles(collectionId);
// data[i].embeddingStatus

await kyro.collections.removeFile(collectionId, fileId);

SDK · Ask & Search

const { answer, sources } = await kyro.files.ask({ 
  question:     "What is the total contract value?",
  collectionId: collectionId,
  stream:       false,
});

// sources[i]: { fileId, fileName, chunkIndex, content, rrfScore }

for await (const event of kyro.files.askStream({ question: "Summarise the risks." })) { 
  switch (event.type) { 
    case "sources": console.log(event.sources); break;
    case "chunk":   process.stdout.write(event.text); break;
    case "done":    console.log("\nDone"); break;
    case "error":   console.error(event.message); break;
  }
}

SDK · Error Handling

All SDK methods throw typed errors. Import the specific class you want to catch — each maps to a distinct HTTP status code.

import {
  KyroApiError, KyroAuthError, KyroNotFoundError,
  KyroRateLimitError, KyroQuotaError, KyroValidationError,
} from "kyro-sdk";

try { 
  await kyro.files.upload(blob, "file.pdf");
} catch (err) { 
  if (err instanceof KyroAuthError)       { /* 401 — invalid or missing API key */ }
  if (err instanceof KyroQuotaError)      { /* 403 — storage quota exceeded */ }
  if (err instanceof KyroNotFoundError)   { /* 404 — resource not found */ }
  if (err instanceof KyroRateLimitError)  { /* 429 — check err.retryAfter */
    setTimeout(retry, err.retryAfter * 1000); }
  if (err instanceof KyroValidationError) { /* 400 — err.details has field errors */ }
  if (err instanceof KyroApiError)        { /* catch-all */ }
}

Self-hosting

Kyro runs entirely on your own infrastructure. Postgres stores files and metadata, Redis queues background jobs, and Ollama runs your embedding and chat models locally. Nothing leaves your network.

docker compose up -d

ollama pull nomic-embed-text
ollama pull llama3.2

read   — list files, search, ask questions
write  — upload, delete, embed files
admin  — full access including key management

Authentication

File and search endpoints use API keys. Dashboard and key-management endpoints use a short-lived JWT obtained from /auth/login.

X-Api-Key: kyro_live_your_key_here

Authorization: Bearer <token from /auth/login>

RAG Pipeline

Every document goes through three stages before it can be queried. All processing runs on your server — no external API calls are made at any stage.

/ask — grounded answers

Send a question, get a cited answer. Kyro retrieves the most relevant chunks via hybrid search, builds a grounded prompt, and streams the response from your local LLM. The LLM only sees what is in your documents — it cannot fabricate facts from outside them.

const res = await fetch('/api/v2/files/ask', {
  method: 'POST',
  headers: { 'X-Api-Key': process.env.KYRO_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ 
    question: 'What are the payment terms?',
    collectionId: 'c_xyz',  // or fileIds: [...], or omit for org-wide
    topK: 8,
    stream: true,
  }),
});

for await (const event of parseSSE(res)) {
  if (event.type === 'sources')  console.log(event.sources);
  if (event.type === 'chunk')    process.stdout.write(event.text);
  if (event.type === 'done')     break;
}

/semantic-search — chunk retrieval

Returns ranked chunks without generating an answer. Useful for building your own UI, debugging retrieval quality, or feeding results into your own pipeline. Uses the same two-phase hybrid retrieval as /ask: BM25 keyword matching fused with pgvector cosine similarity via Reciprocal Rank Fusion, optionally followed by cross-encoder reranking.

curl "http://localhost:3000/api/v2/files/semantic-search?q=payment+terms&collection_id=c_xyz&limit=5" \
  -H "X-Api-Key: $API_KEY"

Metadata Filters

Every file can carry arbitrary key/value metadata — useful for tagging documents with vertical-specific fields like matter_number, document_type, product, or version. Set metadata with PUT /files/:id/metadata, then pass a filters object to /ask to scope retrieval.

curl -X PUT http://localhost:3000/api/v2/files/f_abc123/metadata \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{\"matter_number\": \"M-2024-001\", \"document_type\": \"contract\"}'

{
  "question": "What are the termination clauses?",
  "filters": {
    "matter_number": "M-2024-001",
    "document_type": ["contract", "amendment"]
  }
}

Filters are AND across keys and OR across values. The example above matches files where matter_number is M-2024-001 and document_type is either contract or amendment.

Rate Limiting

The default limit is 100 requests per minute per API key, enforced in Redis (falls back to in-process memory if Redis is unavailable). Both limits are configurable in the server source — adjust to match your infrastructure capacity.

Error Codes

All errors return a consistent JSON body. Check error.message for a human-readable description.

{
  "error": "API key does not have write scope"
}

HTTP API Reference

All endpoints documented below. Authenticate file and search operations with your API key in the X-Api-Key header. Base URL defaults to http://localhost:3000/api/v2 — replace with whatever host you deployed Kyro on.

X-Api-Key: kyro_live_your_key_here