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 (every Omni session without an agent-specific binding grounds against these):
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.

​
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 (or to no grounding if none are set).

​
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.