Skip to Content
Baseera Docs
Knowledge

Push via API

Send documents from your own server, see them in the dashboard, and get a webhook when each one is ready.

When your content lives in your own system (a product catalog, tickets, policies per customer), your server can push it to a knowledge base instead of uploading files by hand. Each pushed document is an item with an id you choose, so pushing the same id again updates it.

This guide covers what you do in the dashboard. The requests themselves are in the Knowledge API reference.

What the API does

  • Your server pushes 1 to 100 items per request, reads or deletes one by its id, and reserves a signed upload for files.
  • Requests are signed with one of the agent's secret keys, so only your server can write knowledge. A publishable key or a user token cannot.
  • A document whose content did not change is not embedded again, so a nightly push of a whole catalog costs nothing for what stayed the same.
  • Pushes count against a limit of 1,000 items a minute per secret key.

Set it up

Create or choose a knowledge base. See Knowledge.

Create a secret key for the agent on Deploy & access, under Secret keys. Copy it when it is shown: it appears only once. Store it in your server's environment, never in browser code. See Embed.

Push items from your server with the Node SDK or the HTTP API. See the Knowledge API reference.

Open the knowledge base. Pushed items appear in Sources with the kind Via API, their ID (the external id you chose) and a status.

Get told when a document is ready

Open the Webhook section of the knowledge base and enter an https Address. Choose Events: A document is ready and A document failed. Press Save webhook.

Copy the Signing secret when it is shown. It is shown once. Your server uses it to confirm a call came from Baseera. The call carries ids and a status, never document text. Recent deliveries shows each delivery with its status (Waiting, Delivered, Gave up), Tries and the reason a delivery failed. See Webhooks and the Webhooks API reference.

Who can read pushed documents

A pushed item can be platform-wide (every tenant) or belong to one tenant, and it can carry access rules. See Knowledge access.

What can go wrong

  • Nothing appears in Sources. Check that the knowledge base id in your request belongs to the same organization as the agent whose secret key you used. Otherwise the answer is "knowledge base not found".
  • The item stays in a processing state or shows Failed. The row shows the same reasons as uploaded files. See Upload documents.
  • A request is rejected as too large. Send fewer items per request, or use a URL or a file upload for large documents.
  • The webhook shows "Address not allowed". The address must be public https. Private, local and internal addresses are refused.
  • The webhook shows "Gave up". Baseera tries a delivery up to six times, spread over roughly 50 minutes, then stops. Check that your server answers with a 2xx quickly.
  • "Enter your two-factor code before changing the webhook." Your organization requires two-factor. Sign in with your code first.

Next steps

On this page