Skip to main content
An Omni knowledge base is hosted grounding: you add content once, and every bound agent retrieves from it per turn while it talks. Paste text, upload a file, add a URL, or crawl a public website. No vector database, no retrieval server, no kb_endpoint to host. (If you already run your own retrieval, the kb_endpoint configure knob stays supported; this guide is the hosted path.) You need a key with the kb:manage scope (create one in the console; sandbox keys don’t carry it).

​
Step 1, create a knowledge base

Names are unique per organization (case-insensitive), so the console picker stays unambiguous.

​
Step 2, add content

Four ways. File, URL, and pasted text share /documents. A public website uses /crawls, which discovers same-origin pages and registers each one as a normal URL document. Content registers as pending and is chunked and embedded asynchronously; poll status until it reads indexed. Do not treat the site as ready while pages are still pending. Paste text (policies, FAQs, snippets):
Fetch a URL (one help-center page):
Crawl a public website (sitemap, then a shallow same-origin walk; default 25 pages, hard cap 40). Private, loopback, and metadata addresses are rejected. Already-ingested URLs in this base are reused:
Upload a file (pdf, docx, xlsx, txt, md, csv, html, json; 25MB max):
Verify what the agent will actually retrieve with GET /v1/knowledgebases/{id}/documents/{docId}/content, which returns the extracted text and indexed chunks. Pasted-text documents can be edited in place (PATCH .../documents/{docId}); re-add files or URLs to replace them. A failed document can be re-queued with POST .../documents/{docId}/retry.

​
Step 3, bind it to your agents

Per agent profile (sessions opened with session_label=<agent_id> ground against these):
Or org-wide defaults (agents without an explicit binding inherit these unless inheritance is disabled):
weight tunes retrieval priority when several bases are bound. The binding route needs omni:session (it rides the agent profile surface); everything under /v1/knowledgebases needs kb:manage. For an integration that must use only its own attached knowledge, set inherit_org_knowledgebases: false when creating or updating the agent:
Explicit bindings still work. With an empty binding list, the agent does no hosted knowledge retrieval. Removing the last binding does not reactivate organization defaults. The setting defaults to true for existing behavior; check the returned agent resource to confirm it was saved. It applies to new sessions and does not rewrite an active call’s configuration.

​
Step 4, talk

Nothing about the session changes. Open Omni as usual and the agent answers from the bound bases:

​
FAQ

​
Hosted knowledge base or my own kb_endpoint?

Use a hosted knowledge base when you want PyAI to store, chunk, embed, and retrieve your content with zero infrastructure. Use kb_endpoint when the content already lives in your systems, changes too fast to sync, or needs per-request logic (the session_label is echoed to your endpoint so you can branch per caller).

​
When is content visible to agents?

After the document reaches indexed. Ingestion is asynchronous; poll the document or list documents and check status.

​
What happens when I delete a knowledge base?

DELETE /v1/knowledgebases/{id} removes the base and its chunks. Agents bound to it fall back to the org defaults only when inheritance is enabled; otherwise they use their remaining explicit bindings or no grounding.

​
Next steps

Omni tools

Hosted, server, and client tools, including knowledge search.

Create agents via API

Bind a hosted base to a stored profile.

API reference

Every /v1/knowledgebases endpoint, with schemas.

Quickstart

Mint a key and open your first Omni session.