Editing

A knowledge base that came out wrong is nearly always one of three things: an entry the model will never choose because its summary is vague, a page that never transcribed, or a structure that groups things nobody would look for that way. Each has its own repair, and none of them needs a re-crawl. Start by reading what the agent is given.

Read the map the agent gets

GET /v1/knowledge/{kb_id}/prompt returns the table of contents exactly as it is injected into the agent’s system prompt — not a rendering of it, the string itself.

KB_ID=3d1f5a70-8c2b-4e19-9a63-b7f0c4d21e58

curl -sS "https://api.in.talqing.com/v1/knowledge/$KB_ID/prompt" \
  -H "Authorization: Bearer $TALQING_API_KEY" | jq -r '.prompt'

const { prompt, chars, node_count } = await talqing.knowledge.prompt({ kb_id });
console.log(prompt);
console.log(`${node_count} entries, ${chars} characters of system prompt`);

block = talqing.knowledge.prompt(kb_id)
print(block["prompt"])
print(f"{block['node_count']} entries, {block['chars']} characters of system prompt")

What comes back looks like this:

## KNOWLEDGE MAP
When a question relates to the knowledge base, FIRST consult the KNOWLEDGE MAP below,
pick the most relevant node id(s), and call `knowledge_fetch` with them to read the
verbatim content before answering. Ground your answer ONLY in the fetched content. If
nothing in the map is relevant, say you don't have that information — never invent facts.

### Knowledge base: Northwind help centre
Northwind Tools sells power tools and accessories online across the UK and Ireland.
This knowledge covers returns, delivery, warranty and trade accounts. Standard
delivery is 2-3 working days; returns are accepted within 30 days unopened.
Nodes:
- k1 | Returns and refunds — How to return an item, the 30-day window, who pays return postage, and when a refund lands.
  - k2 | Faulty item returns — Returning a tool that arrived damaged or failed within the warranty period; the replacement process.
  - k3 | Change-of-mind returns — Unopened items within 30 days, restocking rules, and the exclusions for special orders.
- k4 | Delivery — Delivery times by region, cut-off for next-day, tracking, and what happens to a missed delivery.
- k5 | Trade accounts — Eligibility, credit terms, the trade discount tiers and how to apply.

Read it as the model will. k1 | Returns and refunds — How to return an item, the 30-day window… tells a model exactly when to fetch it. An entry that read k1 | Information — Details about our policies does not, and the model will not fetch it — there is no similarity search behind this that would find it anyway. See overview for why. chars is how much of the agent’s context this knowledge base occupies. It is the same string on every turn, so it sits in the prompt cache, but it is not free — see using knowledge in agents.

Find what never made it in

GET /v1/knowledge/{kb_id}/pages is the per-URL transcription store behind the table of contents. This is where you look when the agent cannot answer something you know is on the site.

curl -sS "https://api.in.talqing.com/v1/knowledge/$KB_ID/pages?limit=500" \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  | jq '.items[] | select(.status != "done" or .content_len == 0)
        | {url, status, content_len, error}'

const { items } = await talqing.knowledge.pages.list({ kb_id, limit: 500 });

for (const page of items) {
  if (page.status !== "done") console.log("failed:", page.url, page.error);
  else if (page.content_len === 0) console.log("empty:", page.url);
}

pages = talqing.knowledge.pages.list(kb_id, limit=500)

for page in pages["items"]:
    if page["status"] != "done":
        print("failed:", page["url"], page["error"])
    elif page["content_len"] == 0:
        print("empty:", page["url"])

Each row carries url, parent_url, kind (html or pdf), status, error, title, summary, content_len and updated_at. Two readings matter:

A status that is not done means the page never made it in. pending means the build did not reach it. failed means it did not survive the stage, and error always reads the same generic fetch or transcription failed — one string covering both “the page could not be fetched” and “the page rendered but had under 40 characters on it”. A landing page that is one hero image and a button lands here, and so does a page whose text is drawn by a script the render did not wait for.
content_len of 0 means the row holds no text at all, which always accompanies a non-done status. A page that transcribed has content by definition, so a zero here is another way of reading the same failure.

A page that is done with real content but is not in the table of contents is a different problem — see unplaced pages below.

Correct one entry by hand

PATCH /v1/knowledge/{kb_id}/nodes/{node_id} writes an entry’s title, summary and content. Read it first with GET /v1/knowledge/{kb_id}/nodes/{node_id}, which also gives you the version you need for a safe write.

NODE_ID=9c4b1e02-6f7a-4d38-b512-0a3e8c6f1d94

curl -sS "https://api.in.talqing.com/v1/knowledge/$KB_ID/nodes/$NODE_ID" \
  -H "Authorization: Bearer $TALQING_API_KEY" | jq '{title, summary, version, source_url}'

curl -sS -X PATCH "https://api.in.talqing.com/v1/knowledge/$KB_ID/nodes/$NODE_ID" \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Returns and refunds",
    "summary": "How to return an item, the 30-day window, who pays return postage, and when a refund lands.",
    "version": 0
  }'

const node = await talqing.knowledge.nodes.get({ kb_id, node_id });

await talqing.knowledge.nodes.update({
  kb_id,
  node_id,
  patchNodeRequest: {
    title: "Returns and refunds",
    summary:
      "How to return an item, the 30-day window, who pays return postage, and when a refund lands.",
    version: node.version,
  },
});

node = talqing.knowledge.nodes.get(kb_id, node_id)

talqing.knowledge.nodes.update(
    kb_id,
    node_id,
    title="Returns and refunds",
    summary="How to return an item, the 30-day window, who pays return postage, and when a refund lands.",
    version=node["version"],
)

Omitted fields are left alone. Every successful write bumps version by one, whether or not you sent it.

Optimistic concurrency

Send the version you read. If the entry changed underneath you — somebody else edited it, or the CoPilot rewrote the tree — the write is refused with a 409: this node was edited elsewhere — reload and retry. Re-read and re-apply. Omitting version force-writes. That is a deliberate escape hatch for a script that owns the knowledge base outright, not a convenience. In an editor, send it.

Content lives on the page, not on the entry

content is a special case. A table-of-contents entry is pure structure; the text lives on the transcribed page, keyed by the entry’s source_url. So:

Sending content on an entry with a source_url rewrites that page’s text. Every entry pointing at that URL sees the change, and so does the agent’s next fetch.
Sending content on a category, or on any entry with no source_url, does nothing. There is no page to write to. The request succeeds and the content is discarded — title and summary in the same request still apply.

The node model

Field	Where	What it is
`id`	tree, `get_node`	The entry’s id, a UUID
`title`	both	What the agent sees in the map. Editable
`summary`	both	What the agent sees in the map. Editable, and the field that decides whether the entry is ever fetched
`kind`	both	`page`, `pdf` or `category`. Set by the build, not editable
`source_url`	both	The transcribed page this entry’s content comes from. `null` on a category. Not editable
`has_content`	tree	Whether a transcribed page backs this entry
`content`	`get_node`	The verbatim text an agent gets when it fetches this entry. Editable through `source_url`
`version`	`get_node`	The concurrency counter. Starts at `0`, increments on every write
`children`	tree	Nested entries

Structure is expressed by nesting and sibling order in the tree GET /v1/knowledge/{kb_id} returns. patch_node cannot move an entry to a different parent or reorder siblings — restructuring is regenerate_toc or the CoPilot.

Deleting an entry

DELETE /v1/knowledge/{kb_id}/nodes/{node_id} drops an entry permanently, and its entire subtree with it. Agents can no longer retrieve any of it. The transcribed pages survive — only the table-of-contents entries are removed — so a regenerate_toc afterwards may put them back. Delete an entry to hide a page from the agent right now; delete the URL from the selection and rebuild to remove it for good.

Rebuild the structure without re-crawling

POST /v1/knowledge/{kb_id}/toc re-runs only the last stage: one model pass over the pages already transcribed, producing a fresh table of contents and a fresh overview. Nothing is crawled and nothing is transcribed again.

curl -sS -X POST "https://api.in.talqing.com/v1/knowledge/$KB_ID/toc" \
  -H "Authorization: Bearer $TALQING_API_KEY"

const { pages } = await talqing.knowledge.regenerateToc({ kb_id });
console.log(`reorganizing ${pages} pages`);

result = talqing.knowledge.regenerate_toc(kb_id)
print(f"reorganizing {result['pages']} pages")

This is the specific repair for “the structure came out wrong”, and for a build that failed at the generating stage — the pages are already there, so there is nothing to redo but the organizing. It moves the knowledge base to generating and back to ready.

It replaces the tree. Hand edits to titles and summaries are written over, entries you deleted come back, and every entry gets a new id with its version reset to 0. A script holding node ids must re-read the tree afterwards.If you have curated the map, use the CoPilot to adjust it instead — that also replaces the tree and re-issues ids, but it starts from the current one rather than from scratch.

A knowledge base with no transcribed pages is a 400: no transcribed pages — run a build first. A build already in flight is a 409.

Pages the table of contents left out

On a ready knowledge base, GET /v1/knowledge/{kb_id} returns unplaced: URLs that transcribed successfully but that the table-of-contents pass did not put anywhere. The model drops a page when it judges it redundant — a duplicate, an empty stub — and it is told to be conservative, but it does drop some.

An unplaced page is not reachable by the agent. It has no entry in the map, so there is no id to fetch and nothing will surface it. Its content is stored and paid for and never used.

Treat a non-empty unplaced as a signal, not an error. Look at what is in it:

If they really are redundant, leave them.
If something important is there, ask the CoPilot to place it — that is what it is for, and it is the only way to add an entry to the tree.
If a lot is there, the build probably selected too many near-identical pages. Narrow the selection and build again.

curl -sS "https://api.in.talqing.com/v1/knowledge/$KB_ID" \
  -H "Authorization: Bearer $TALQING_API_KEY" | jq '.unplaced'

const detail = await talqing.knowledge.get({ kb_id });
console.log(detail.unplaced); // null unless the KB is ready

detail = talqing.knowledge.get(kb_id)
print(detail["unplaced"])  # None unless the KB is ready

unplaced is computed on read and is null on a knowledge base that is not ready. discovered and parents work the same way in reverse — they are populated only at review.

Troubleshooting

Symptom	Cause	Fix
The agent says it does not have information that is on the site	The page is not in the knowledge base at all	`list_pages`: a non-`done` status means it never transcribed; absence means it was never selected. Add the URL to the selection and build again
The agent does not fetch an entry that clearly holds the answer	The title and summary do not describe what callers ask	`patch_node` the summary to name the concrete things the page answers. Check the result with `get_kb_prompt`
The agent fetches the wrong entry	Two summaries read alike	Rewrite both so they distinguish themselves, or merge the pages
A page is `done` but not in the tree	The table-of-contents pass judged it redundant	It is in `unplaced`. Ask the CoPilot to place it
A page is `failed`, `content_len` 0	Either the fetch did not work — a site blocking automation, a timeout, a PDF with no extractable text — or the page had under 40 characters on it. The error string does not distinguish them	Open the URL yourself. If there is text on it, re-select it and build again; if it fails a second time, index a different URL that carries the same content
The agent’s answer is right but out of date	A knowledge base is a snapshot; nothing re-crawls	Build again, or `patch_node` the content for a single correction
The structure groups things nobody would look for that way	The table-of-contents pass organized on what the site’s links suggested	`regenerate_toc`, or describe the grouping you want to the CoPilot
A build failed at `generating`	The organizing pass errored	`regenerate_toc` — the pages are already transcribed
Any write returns 409 `knowledge base is …`	A build is running	Wait — only one runs per knowledge base. If it has been stuck for an hour it is wedged and nothing will move it; delete the knowledge base and build it again
`patch_node` returns 409	Somebody or something edited the entry after you read it	Re-read the node and re-apply your change

KnowledgeCoPilot

Restructure the tree, rewrite summaries in bulk and place dropped pages by describing what you want.

Using it in an agent

What the agent does with the map at runtime, and how to prompt it so it uses one.

Get started

Agents

Tools

Knowledge

Agent teams

Agent tasks

Telephony

Web & chat

Integrations

Email outbound

Observability

Guides

Platform

Read the map the agent gets

Find what never made it in

Correct one entry by hand

Optimistic concurrency

Content lives on the page, not on the entry

The node model

Deleting an entry

Rebuild the structure without re-crawling

Pages the table of contents left out

Troubleshooting

Next

KnowledgeCoPilot

Using it in an agent

​Read the map the agent gets

​Find what never made it in

​Correct one entry by hand

​Optimistic concurrency

​Content lives on the page, not on the entry

​The node model

​Deleting an entry

​Rebuild the structure without re-crawling

​Pages the table of contents left out

​Troubleshooting

​Next

KnowledgeCoPilot

Using it in an agent

Read the map the agent gets

Find what never made it in

Correct one entry by hand

Optimistic concurrency

Content lives on the page, not on the entry

The node model

Deleting an entry

Rebuild the structure without re-crawling

Pages the table of contents left out

Troubleshooting

Next