Knowledge
Your organisation's documents (policies, handbooks, syllabuses, FAQs, web pages) that AI Teammates answer from. Documents marked policy are also what they check discussions against. Each project has its own knowledge base, and each room can have its own documents too (a syllabus, a meeting agenda): an AI in a room uses the organisation's documents plus that room's.
How it's stored
Every source ends up in the same shape, so the AI uses them all the same way:
- Read: uploads (PDF, Word, PowerPoint, text, Markdown, photos), typed text, Google Docs links and public web pages are turned into clean text. Headings, numbered clauses and lists are kept; menus, scripts and page clutter are dropped. PDFs and photos are read by Claude, which marks parts it can't read instead of guessing.
- Review: Claude writes a preview: a summary, suggested tags and anything to check (unreadable parts, pages skipped, text cut short). The document waits as
"review"until someone approves it, and can be corrected first. The AI doesn't use it before that. - Use: on approval the text is split into passages at its headings, and each passage keeps its document's title, section ("Fees › Term fees"), tags, source and date. Those are what the AI sees, so it can say where an answer comes from.
New versions replace old ones: a corrected text, a new upload with replaces, or a changed web page goes up for review, and once approved it supersedes the previous version (no second copy). Until then the AI keeps using the approved version.
For best results: use headings, keep one subject per document, give documents clear titles, and mark rules as policy. Scanned pages and photos work, but typed text is read most reliably.
Add documents
# Typed or pasted text
curl -X POST https://api.appsocom.dev/knowledge -H "Authorization: Bearer $APPSOCOM_API_KEY" \
-H "Content-Type: application/json" -d '{"title":"Phones policy","kind":"policy","text":"# Phones policy\n\nStaff must never…"}'
# A file
curl -X POST https://api.appsocom.dev/knowledge/upload -H "Authorization: Bearer $APPSOCOM_API_KEY" \
-F file=@handbook.pdf -F kind=reference
# A web page, or up to 25 pages of a site, re-checked weekly
curl -X POST https://api.appsocom.dev/knowledge -H "Authorization: Bearer $APPSOCOM_API_KEY" \
-H "Content-Type: application/json" -d '{"url":"https://school.example/policies/","crawl":10,"recheck":"weekly"}'Each answers with the document, status: "review" and its preview. Then:
curl -X POST https://api.appsocom.dev/knowledge/kb_…/approve -H "Authorization: Bearer $APPSOCOM_API_KEY" \
-H "Content-Type: application/json" -d '{"tags":["safeguarding"]}' # optional: title, kind, text, tags| Field | |
|---|---|
kind |
"reference" (default) or "policy" |
room |
the room it belongs to; leave out for the whole organisation |
review |
false adds it straight away (for automation) |
replaces |
a document id: this is that document's new version |
crawl |
web: pages to read on the same site, under the starting page (1–25, default 1). robots.txt is respected. |
recheck |
web: "daily" or "weekly"; changes wait for review |
Only public pages can be imported: no sign-ins, no private or local addresses.
Whole websites
For a site with many pages (a shop, a help centre), add the site instead of a crawl. Appsocom reads it in the background, its sitemap first and then the links on each page, keeps each page as its own document, and reads it again every week. Changed pages are updated, pages that are gone are removed, and pages go into use at once, without review (you chose the site).
curl -X POST https://api.appsocom.dev/knowledge/sites -H "Authorization: Bearer $APPSOCOM_API_KEY" \
-H "Content-Type: application/json" -d '{"url":"shop.example","exclude":["/blog","/tag*"],"maxPages":500}'| Field | |
|---|---|
url |
the site; https:// is assumed. The whole site is read (with or without www.); robots.txt is respected |
exclude |
paths to leave out: "/blog" (and everything under it), "/tag*" (anything starting with it), or full addresses (at most 50) |
maxPages |
at most this many pages (1–2,000, default 2,000) |
recheck |
"weekly" (default), "daily" or null (only when asked) |
kind |
"reference" (default) or "policy", for every page |
suggest |
false: no suggested questions and answers (below) |
GET /knowledge/sites |
the sites, with status (crawling, ready, failed with error), pages, checkedAt and issues (pages skipped and why) |
GET /knowledge/sites/:siteId |
the site, its pages in use (url, title, docId) and the pages turned off |
PATCH /knowledge/sites/:siteId |
title, exclude, maxPages, recheck, kind, suggest; a change to what it covers reads it again now |
POST /knowledge/sites/:siteId/recrawl |
read it again now |
POST /knowledge/sites/:siteId/pages |
{ url, off: true } removes one page and skips it from then on; off: false brings it back at once |
DELETE /knowledge/sites/:siteId |
the site and every page of it |
Suggested questions and answers: after each crawl, Claude drafts the questions customers most often ask that the changed pages answer (up to 8 per page, from the 5 changed pages most likely to answer customers: FAQ, help, pricing, delivery, returns, contact). They wait for an admin: GET /knowledge/suggestions, then POST /knowledge/suggestions/:id/approve (optionally with an edited question and answer; it becomes a short document in use at once) or DELETE /knowledge/suggestions/:id.
Collections: one knowledge base per customer
An app that serves many organisations from one Appsocom project can keep each one's knowledge apart: add ?collection=<name> (1–64 letters, numbers, _ or -; or "collection" in a JSON body or form) to any knowledge call. A collection has its own documents, sites, suggestions, search and limits, and is never found from the project's own knowledge base or another collection. For the AI assistant, mint the person's token with knowledge: "<name>" so its search_knowledge uses that collection. DELETE /knowledge?collection=<name> deletes a whole collection (for example when a customer leaves).
Other calls
GET /knowledge |
the organisation's documents (?room= one room's, ?all=true everything) |
GET /knowledge/:docId |
the document, its passages and sections, and draft (text waiting for review) |
PATCH /knowledge/:docId |
title, kind, tags, recheck; text puts a new version up for review |
POST /knowledge/:docId/discard-update |
drop a new version waiting for review |
POST /knowledge/:docId/recheck |
re-read a web document now |
DELETE /knowledge/:docId |
delete it; the AI stops using it at once |
POST /knowledge/search |
{ query, room?, collection? } → the passages the AI in that room would get |
In the console: project → Knowledge base. In a space: Admin → Knowledge base (admins), and Rooms → Documents for the AI (hosts, per room).
Limits and cost
500 documents per project (or per collection), 50 per room, 400,000 characters per document; and, not counted in those, 20 sites and 2,000 site pages per project or collection. Reading a PDF or photo and each preview use Claude Haiku 5.5 (about $0.01 for a 10-page document); embeddings use Workers AI (a fraction of a cent per document). A full read of a 2,000-page site embeds about 3 million tokens on Workers AI (a few cents); later reads embed only the pages that changed. Suggestions read at most 5 changed pages per crawl with Haiku 5.5.
Self-hosting
Needs the STORAGE (R2) and AI bindings and ANTHROPIC_API_KEY for previews and PDFs. For larger knowledge bases add a Vectorize index (npx wrangler vectorize create appsocom-knowledge --dimensions=1024 --metric=cosine) as binding KNOWLEDGE_INDEX; without it vectors are kept in R2 and searched in the Worker. Web re-checks and site crawls run from the TENANTS Durable Object's alarm (a few pages per step).