Add knowledge to an agent

1. Prepare the source. Use content the organization is authorized to store and expose to callers. Remove secrets and unrelated personal data. Prefer clear headings, canonical facts, and one maintained source per fact.
2. Choose a container. Use POST /v1/knowledge-bases to group related material. Use flat POST /v1/knowledge/documents for a standalone upload or text document. Use POST /v1/knowledge/documents/import-url for a permitted URL.
3. Submit the content. For files, send multipart form data and retain the returned document ID. For URL imports, record the canonical source URL and refresh policy.

Canonical JSON request for importing a permitted web page:

{
  "url": "https://example.com/pricing",
  "name": "Pricing"
}

curl --fail-with-body -X POST https://api.thunderphone.com/v1/knowledge/documents \
  -H "Authorization: Bearer $THUNDERPHONE_API_KEY" \
  -H "X-ThunderPhone-Client: skills/add-knowledge@1.0" \
  -F "file=@$DOCUMENT_PATH"

import os, requests

with open(os.environ["DOCUMENT_PATH"], "rb") as document:
    r = requests.post("https://api.thunderphone.com/v1/knowledge/documents",
        files={"file": document},
        headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}",
                 "X-ThunderPhone-Client": "skills/add-knowledge@1.0"}, timeout=120)
r.raise_for_status()
print(r.json())

import { openAsBlob } from "node:fs";
const form = new FormData();
form.set("file", await openAsBlob(process.env.DOCUMENT_PATH!));
const response = await fetch("https://api.thunderphone.com/v1/knowledge/documents", {
  method: "POST", headers: { Authorization: `Bearer ${process.env.THUNDERPHONE_API_KEY}`,
    "X-ThunderPhone-Client": "skills/add-knowledge@1.0" }, body: form,
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

4. Wait for readiness. Poll GET /v1/knowledge/documents/{document_id} or the knowledge-base document list. Do not attach or test content still marked pending/processing. Investigate failed indexing before retrying.
5. Search directly. Use POST /v1/knowledge/search or POST /v1/knowledge-bases/{knowledge_base_id}/search with representative caller questions. Check that the retrieved passage supports the intended answer and excludes unrelated content.
6. Attach to the agent. Patch knowledge_base_ids and/or knowledge_document_ids, review the draft, deploy it, and run spoken test scenarios.
7. Verify. Test exact facts, paraphrases, conflicts, missing information, and content the agent should refuse to invent. Confirm source updates are reindexed before relying on them.

Errors

Source and safety rules

• Follow knowledge base and the knowledge API reference.
• Do not upload content without rights or expose secrets and unnecessary personal data.
• Direct search quality is evidence for retrieval, not proof of spoken answer quality.
• Preserve source provenance and remove stale copies rather than relying on ordering.

See references/knowledge-lifecycle.md.