Guides

Knowledge from a server

Ask the account's Knowledge Base for a cited answer, search it, and read Your numbers, from your own server or an n8n workflow.

The account's Knowledge Base answers from the business's own content, with sources. From a browser, a signed-in person asks with app.ask() (see Ask by text). From your own server, use db.knowledge.

It needs the account's token with knowledge:read (never an app key), Knowledge active on the account, and the owner's Use your content for Knowledge switch on in Settings, Features. When that switch is off, a call answers consent_blocked; only the owner can switch it on. Every plan. These calls share the hub's limit of 30 a minute, and each answer counts towards the account's Knowledge answers.

#A cited answer

const a = await db.knowledge.ask('What is our refund policy?');
if (a.grounded) {
  console.log(a.answer); // with [1], [2] markers
  for (const s of a.sources) console.log(s.ref, s.title, s.locator, s.url);
} else {
  console.log(a.noAnswerMessage ?? 'The content does not cover this.');
}

const next = await db.knowledge.ask('And for gift cards?', { session: a.session ?? undefined });

grounded is true only for an answer that came with sources. An answer with none came from the model, not from the business's content: never present it as the business's. status is ok, no_results (the content has no answer) or error (the service failed, not the content).

Narrow it to part of the library with filters: { topic: ['refunds'], year: [2026] }, or doc_ids from a search hit.

#Search

const found = await db.knowledge.search({ q: 'hot water', topic: ['plumbing', 'gas'], limit: 10 });
for (const hit of found.hits) console.log(hit.title, hit.locator, hit.snippet);
console.log(found.facets.topic); // counts under the current filters

A facet given several values matches any of them. The matched words in snippet sit between highlight.pre and highlight.post. With includeMedia: true, audio and video hits carry addresses that expire in minutes: use them at once, never store them.

#Your numbers

The business's own figures (imported tables, Google Analytics, Search Console) are datasets in Your numbers. Built-in ones are ds-builtin-<name>:

const visits = await db.knowledge.data({
  dataset: 'ds-builtin-google-analytics-daily',
  measures: [{ column: 'sessions', agg: 'sum' }],
  dimensions: ['site'],
});

The answer is the platform's own shape: columns and rows, plus what it assumed. The Data tab under Knowledge in the hub lists each dataset and its columns.