Skip to Content
Baseera Docs

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 console

The 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.results

Item status

An item's status in the result is one of:

StatusMeaning
queuedA new version is being processed. It becomes searchable when it is ready.
unchangedThe content, title and metadata match what is already indexed. Nothing was written.
rejectedThe 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.
  • text up 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:

app/api/baseera/upload-token/route.ts
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.

Next steps

On this page