Pushing knowledge
Keep a knowledge base in step with your own data, set access rules, and let tenants upload their own documents.
createBaseera().kb pushes documents and records from your system into a knowledge base. Each item has an externalId you choose. Pushing the same id again replaces the old version, and content that has not changed is not embedded again.
import { createBaseera } from "@baseera/node";
const baseera = createBaseera({
agentId: process.env.BASEERA_AGENT_ID!,
secretKey: process.env.BASEERA_SECRET_KEY!, // server only
baseUrl: process.env.BASEERA_RUNTIME_URL!,
});
const knowledgeBase = process.env.BASEERA_KNOWLEDGE_BASE_ID!; // from the consoleThe knowledge base must belong to the agent's organization. The token the SDK signs has the purpose kb_write, so it cannot be used for anything else.
Push one item
Send exactly one of text, url or file.
const one = await baseera.kb.upsert({
knowledgeBase,
externalId: "policy-7",
title: "Refund policy",
text: policy.markdown,
metadata: { lang: "en", tags: ["policy"], version: 3 },
});
// { ok: true, item: { externalId: "policy-7", status: "queued" | "unchanged" | "rejected", error? } }Prop
Type
await baseera.kb.upsert({ knowledgeBase, externalId: "faq", title: "FAQ", url: "https://example.com/faq" });
await baseera.kb.upsert({ knowledgeBase, externalId: "manual", title: "User manual", file: { name: "manual.pdf", data: bytes } });Files are hashed, reserved and uploaded straight to private storage for you. They never travel through Baseera's JSON API.
Push many
upsertMany makes batches of up to 100 for you, and returns results in input order.
const many = await baseera.kb.upsertMany(
records.map((r) => ({ knowledgeBase, externalId: r.id, title: r.title, text: r.body })),
);
if (!many.ok) retryLater(many.retryAfter); // the items decided before the failure are in many.resultsItem status
An item's status in the result is one of:
| Status | Meaning |
|---|---|
queued | A new version is being processed. It becomes searchable when it is ready. |
unchanged | The content, title and metadata match what is already indexed. Nothing was written. |
rejected | The item was refused, with error: { code, message }. It never fails its neighbours. |
Ask where an item stands, or delete it:
await baseera.kb.status({ knowledgeBase, externalId: "policy-7" });
// { ok: true, status: { status: "ready", version, searchableVersion, chunkCount, errorCode } }
await baseera.kb.delete({ knowledgeBase, externalId: "policy-7", tenantId: org.id });
// { ok: true, deleted: true }The processing status is pending_upload, queued, parsing, embedding, ready or failed. searchableVersion says which version is answering: the previous version keeps answering until the new one is ready, and if it fails. To be told when an item is ready, use a webhook instead of polling.
Access rules
Give an item access rules and only the users whose token satisfies them find it.
await baseera.kb.upsert({
knowledgeBase,
externalId: "salary-bands",
title: "Salary bands",
text: doc.markdown,
tenantId: org.id,
access: { roles: ["staff"], plan: "pro" },
});A user's token carries role and claims. See Signing user tokens. The rules fail closed: a user without the claim sees nothing of the item, in a search, a citation or a source link. roles is also matched against the token's role.
Limits
- 1,000 items a minute per secret key.
textup to 1,000,000 characters. Files up to 50 MB.- Metadata up to 20 keys.
- 20,000 pushed items per knowledge base, or the organization's storage.
Tenant uploads
Let an admin of one of your tenants add documents that only that tenant's users get answers from. In the console, turn on "Let tenants add their own documents" on the agent's Knowledge page, which is off by default, and attach the knowledge base.
Your server signs a token after it has checked that the user may manage that tenant's documents:
import { createBaseera } from "@baseera/node";
const baseera = createBaseera({
agentId: process.env.BASEERA_AGENT_ID!,
secretKey: process.env.BASEERA_SECRET_KEY!,
baseUrl: process.env.BASEERA_RUNTIME_URL!,
});
export async function POST() {
const admin = await requireTenantAdmin(); // YOUR authorization
const result = await baseera.kb.createTenantUploadToken({
knowledgeBase: process.env.BASEERA_KNOWLEDGE_BASE_ID!,
tenantId: admin.organizationId, // the same id you put in this tenant's users' tokens
userId: admin.id,
ttlSeconds: 300, // default 300, at most 600
});
if (!result.ok) return new Response(null, { status: 500 });
return Response.json({ token: result.token });
}Then show the component in your app:
import { BaseeraKnowledgeUpload } from "@baseera/ui/connected";
<BaseeraKnowledgeUpload
tenant="Acme Ltd"
getUploadToken={() => fetch("/api/baseera/upload-token", { method: "POST" }).then((r) => r.json()).then((b) => b.token)}
/>The token names the knowledge base, the tenant and the user. Baseera reads them from the token and nowhere else, so the browser cannot upload for another tenant. It works only with your agent's publishable key from your allowed domains, and it expires in minutes: the component asks for a new one.
signTenantUploadToken({ agentId, secretKey, knowledgeBase, tenantId, userId, ttlSeconds? }) is the lower-level function behind createTenantUploadToken. It throws on a missing field. Limits per tenant and knowledge base: 200 files, 200 MB in all, 25 MB a file.
Forget a tenant
When a customer leaves, delete everything they have with purgeTenantKnowledge.