Quickstart

uv tool install kscli
kscli --version

pip install ksapi
# or: uv add ksapi

npm install @knowledge-stack/ksapi
# or: pnpm add @knowledge-stack/ksapi

# nothing to install — just curl + an API key

kscli folders create --name "Quickstart"
kscli folders list --format yaml   # grab the path_part_id

folder = ks.folders.create(name="Quickstart")
print(folder.id, folder.path_part_id)

const folder = await ks.folders.create({ name: "Quickstart" });
console.log(folder.id, folder.pathPartId);

curl -X POST $KS_BASE_URL/v1/folders \
  -H "Authorization: Bearer $KS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Quickstart"}'

kscli documents ingest \
  --file ./report.pdf \
  --path-part-id <folder-path-part-id> \
  --name "Q4 Report"

with open("report.pdf", "rb") as f:
    doc = ks.documents.ingest(
        file=f,
        parent_path_part_id="<folder-path-part-id>",
        name="Q4 Report",
    )
print(doc.id, doc.workflow_id)

import fs from "node:fs";

const doc = await ks.documents.ingest({
  file: fs.createReadStream("report.pdf"),
  parentPathPartId: "<folder-path-part-id>",
  name: "Q4 Report",
});
console.log(doc.id, doc.workflowId);

curl -X POST $KS_BASE_URL/v1/documents/ingest \
  -H "Authorization: Bearer $KS_API_KEY" \
  -F "file=@report.pdf" \
  -F "parent_path_part_id=<folder-path-part-id>" \
  -F "name=Q4 Report"

kscli workflows list --limit 5
kscli workflows describe <workflow-id>

wf = ks.workflows.describe(workflow_id=doc.workflow_id)
print(wf.status)  # RUNNING → COMPLETED

kscli chunks search \
  --query "what drove revenue growth" \
  --parent-path-ids <folder-path-part-id> \
  --limit 5

hits = ks.chunks.search(
    query="what drove revenue growth",
    parent_path_ids=["<folder-path-part-id>"],
    top_k=5,
)
for h in hits:
    print(f"[{h.score:.2f}] {h.content[:160]}")

const hits = await ks.chunks.search({
  query: "what drove revenue growth",
  parentPathIds: ["<folder-path-part-id>"],
  topK: 5,
});
hits.forEach((h) => console.log(`[${h.score.toFixed(2)}] ${h.content.slice(0, 160)}`));

curl -X POST $KS_BASE_URL/v1/chunks/search \
  -H "Authorization: Bearer $KS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "what drove revenue growth",
    "parent_path_ids": ["<folder-path-part-id>"],
    "top_k": 5
  }'

kscli threads create --title "Earnings deep-dive"
kscli threads chat <thread-id> --message "Summarize the report" --stream

thread = ks.threads.create(title="Earnings deep-dive")
for event in ks.threads.stream(
    thread_id=thread.id,
    message="Summarize the report",
):
    if event.type == "message_delta":
        print(event.text, end="", flush=True)
    elif event.type == "citation":
        print(f"\n  ↳ {event.chunk_id}")

const thread = await ks.threads.create({ title: "Earnings deep-dive" });
for await (const ev of ks.threads.stream({
  threadId: thread.id,
  message: "Summarize the report",
})) {
  if (ev.type === "message_delta") process.stdout.write(ev.text);
  if (ev.type === "citation") console.log(`\n  ↳ ${ev.chunkId}`);
}

THREAD=$(curl -s -X POST $KS_BASE_URL/v1/threads \
  -H "Authorization: Bearer $KS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Earnings deep-dive"}' | jq -r .id)

curl -N -X POST $KS_BASE_URL/v1/threads/$THREAD/stream \
  -H "Authorization: Bearer $KS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Summarize the report"}'