Add a knowledge entry
Ingest content into a namespace the caller can write. Requires permission knowledge:write.
v2 compatibility notes
POST /api/v2/knowledge/addKnowledge writes one entry and says what happened:
De-duplication
An add is de-duplicated only when it sends anexternalRef and an active entry with the same externalRef, the same namespace and the same principal already exists. The principal is the External App for a management JWT; every platform and MCP key has no principal, so all of them share one de-duplication space per namespace. A deleted entry never de-duplicates a new add. Two adds racing past the check can both write: send an Idempotency-Key to make a retry safe, see Knowledge write replay.
Errors
403 permission_denied or forbidden
403 permission_denied or forbidden
permission_denied: the credential lacks knowledge:write, or it writes company (the default target) without knowledge:manage; the error names the permission as error.requiredPermission. forbidden: the target namespace is outside the caller’s writable set, and no grant opens it. global is never writable through the API.413 payload_too_large
413 payload_too_large
content is over 1,000,000 characters. Split the document.Authorizations
Headers
1–255 printable ASCII characters. A repeat with the same key and request never runs the write again, a 5xx included. It returns the first response (Idempotency-Replayed: true) only when the route's current authorization policy permits disclosure; otherwise 409 idempotency_result_unavailable. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.
1 - 255Body
Response
Deduplicated: an active entry already held this externalRef in this namespace for this principal, so nothing was added. deduplicated is true.

