Skip to main content
These eight tools sit under the knowledge:manage scope. They let a coding agent curate the two things your AI answers from: the knowledge entries it retrieves (FAQs, products, promos) and the always-on business profile that shapes every reply. In Sapot Chat this is the same AI Knowledge subsystem the dashboard authors into and the flow-agent runtime retrieves from.
All tools require the knowledge:manage scope. A key without it gets Access token is missing the required scope: knowledge:manage — grant the scope in Settings → API & Agents, or see Authentication & Scopes.

​
The knowledge model

Knowledge is authored as entries, each in exactly one category:
Category is fixed at creation. update_knowledge_entry cannot change an entry’s category — create a new entry (and delete the old one) to move content between categories.
Agent-created entries are created already approved, so the AI can use them immediately — there is no pending step to clear. approve_knowledge_entry exists for entries that arrived pending from another source.

​
Entry tools

​
list_knowledge_entries

List knowledge entries (25 per page) — the content the AI answers from. Returns {data: [entry, …], meta: {total_count, page}}. Each entry carries id, category, question, answer, remarks, status, embedded, price_cents, currency, valid_from, valid_until.

​
search_knowledge

Semantic search over approved knowledge — a preview of what the AI would actually retrieve for a question. Returns {text_context: str, entries: [...]}.
This is the same retrieval the runtime uses, not a separate index. Run it to sanity-check that a new or edited entry is discoverable for the questions customers actually ask, before trusting it in production.

​
create_knowledge_entry

Create a knowledge entry (created already approved, so the AI can use it immediately). Returns the created entry.

​
update_knowledge_entry

Update a knowledge entry. Only the fields you pass are changed. Returns the updated entry. Category cannot be changed here — create a new entry instead.

​
approve_knowledge_entry

Approve a pending knowledge entry so the AI starts using it. Returns the updated (approved) entry.

​
delete_knowledge_entry

Delete a knowledge entry permanently. Returns {} on success.

​
Profile tools

The profile is the always-on business and AI-behaviour layer — one row per account, not retrieved per-question. It is injected into the AI’s system prompt on every reply, so a small change here affects every conversation.

​
get_knowledge_profile

Get the account’s always-on business + AI-behaviour profile. Takes no arguments. Returns business_name, identity, hours, location, contact, tone_preset, formality, emoji_enabled, use_shortform, custom_instructions, content_languages, prohibitions, and a read-only compiled_prompt — a preview of exactly what gets injected into the AI’s system prompt.
compiled_prompt is read-only. It is derived from the other fields; edit the inputs (tone, prohibitions, business info) and read it back to see the result — you cannot set it directly.

​
update_knowledge_profile

Update the business + AI-behaviour profile. Only the fields you pass are changed. Returns the updated profile, with a fresh compiled_prompt preview.

​
What is deliberately not here

This scope is plain CRUD + approve, on purpose. AI-generation, bulk operations, and document import are intentionally not exposed to agent tokens — they carry LLM cost and a large blast radius. An agent authors and curates entries one at a time; generate-from-documents and bulk import stay in the dashboard.

​
Recipe: keep the knowledge base fresh

1

Mine resolved conversations

Read recent resolved threads for questions that keep recurring.
2

Create the entry

create_knowledge_entry(category="faq", question, answer) — it is live immediately (already approved). For a product, use category="product" with price_cents and currency.
3

Verify retrieval

search_knowledge(query="…") with the phrasing a customer would use — confirm your new entry comes back in entries and lands in text_context.

Authentication & Scopes

The default-deny scope model behind knowledge:manage.

The Agent Skill

A companion skill so the agent drives these tools correctly.

REST API

Call the same endpoints directly with a scoped key.