Knowledge bases: upload & search

Knowledge bases ingest documents asynchronously (parse → chunk → embed) and let you search the result:

Upload — POST /v1/knowledge-bases/{kb_id}/upload_train (multipart). Returns run ids you can poll.
Search — POST /v1/knowledge-bases/{kb_id}/search.

Replace kb_id and your_api_key. Use the prefix parameter to organise and scope documents into folders.

Upload documents and wait for ingestion

Upload returns immediately with run ids; ingestion runs in the background. Poll the training runs (SDK get_runs, or the running jobs endpoint) until they complete before searching. Don’t set Content-Type yourself on the upload — let your HTTP client set the multipart boundary.

# pip install noxus-sdk
from pathlib import Path
import time
from noxus_sdk.client import Client

client = Client(api_key="your_api_key")
kb = client.knowledge_bases.get(knowledge_base_id="kb_id")

run_ids = kb.upload_document(files=[Path("path/to/document.pdf")], prefix="/")
print(f"ingestion started: {run_ids}")

# Wait for ingestion to finish
while any(
    r.status not in ("completed", "failed")
    for r in kb.get_runs(run_ids=",".join(run_ids))
):
    time.sleep(3)
print("ingestion done")

import requests

base = "https://backend.noxus.ai"

files = [("files", ("document.txt", open("path/to/document.txt", "rb"), "text/plain"))]
resp = requests.post(
    f"{base}/v1/knowledge-bases/kb_id/upload_train",
    headers={"X-API-KEY": "your_api_key"},  # no Content-Type — requests sets multipart
    files=files,
    params={"prefix": "/"},
)
print(resp.json())  # run ids to poll for ingestion status

import fs from "fs";

const base = "https://backend.noxus.ai";

const form = new FormData();
form.append("files", new Blob([fs.readFileSync("path/to/document.txt")]), "document.txt");

const resp = await fetch(`${base}/v1/knowledge-bases/kb_id/upload_train?prefix=/`, {
  method: "POST",
  headers: { "X-API-KEY": "your_api_key" }, // fetch sets the multipart boundary
  body: form,
});
console.log(await resp.json()); // run ids

curl -X POST "https://backend.noxus.ai/v1/knowledge-bases/kb_id/upload_train?prefix=/" \
  -H "X-API-KEY: your_api_key" \
  -F "files=@path/to/document.txt"

Search the knowledge base

Runs a semantic / hybrid query (depending on the KB’s retrieval settings) over the ingested content and returns the matching chunks with their source documents. Scope the search with prefix.

from noxus_sdk.client import Client

client = Client(api_key="your_api_key")
kb = client.knowledge_bases.get(knowledge_base_id="kb_id")

for result in kb.search(query="Your search query", prefix="/"):
    print(result.document_source.name)
    print(result.content)

import requests

resp = requests.post(
    "https://backend.noxus.ai/v1/knowledge-bases/kb_id/search",
    params={"query": "Your search query", "prefix": "/"},
    headers={"X-API-KEY": "your_api_key", "Content-Type": "application/json"},
)
for result in resp.json():
    print(result["document_source"]["name"])
    print(result["content"])

const params = new URLSearchParams({ query: "Your search query", prefix: "/" });
const resp = await fetch(
  `https://backend.noxus.ai/v1/knowledge-bases/kb_id/search?${params}`,
  {
    method: "POST",
    headers: { "X-API-KEY": "your_api_key", "Content-Type": "application/json" },
  }
);
for (const result of await resp.json()) {
  console.log(result.document_source.name);
  console.log(result.content);
}

curl -X POST "https://backend.noxus.ai/v1/knowledge-bases/kb_id/search?query=Your%20search%20query&prefix=/" \
  -H "X-API-KEY: your_api_key" \
  -H "Content-Type: application/json"

Async / await with the SDK

Use the a-prefixed coroutines (aget, aupload_document, aget_runs, asearch) from async code so the event loop stays responsive.

Python SDK

import asyncio
from pathlib import Path
from noxus_sdk.client import Client


async def main():
    client = Client(api_key="your_api_key")
    kb = await client.knowledge_bases.aget(knowledge_base_id="kb_id")

    await kb.aupload_document(files=[Path("path/to/document.pdf")], prefix="/")

    results = await kb.asearch(query="Your search query", prefix="/")
    for r in results:
        print(r.document_source.name, r.content)


asyncio.run(main())

⌘I

Introduction

Cookbook

Workflows

Runs

Knowledge Bases

Conversations

Agents (Co-workers)

Triggers

Deployments

Platform

Sandboxes

Tables

Variables

Insights

System keys

Roles

Admin

Upload

Inboxes

Analytics

Upload documents and wait for ingestion

Search the knowledge base

Async / await with the SDK

​Upload documents and wait for ingestion

​Search the knowledge base

​Async / await with the SDK

Upload documents and wait for ingestion

Search the knowledge base

Async / await with the SDK