Skip to main content
POST
Add a knowledge entry
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

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 an externalRef 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

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.
content is over 1,000,000 characters. Split the document.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

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.

Required string length: 1 - 255

Body

application/json
content
string
required

The text. Over 1,000,000 characters answers 413; split the document.

Required string length: 1 - 1000000
contentType
enum<string>
required
Available options:
document,
note,
snippet
artifactKind
enum<string>

Optional authored kind; omit when unclassified. Independent of contentType.

Available options:
lesson,
policy,
how_to,
reference,
faq,
note
title
string
Maximum string length: 500
tags
string[]

Labels stored on the entry, trimmed and de-duplicated, and returned by get and getChunks.

Maximum array length: 20
Required string length: 1 - 64
scopeType
string

Knowledge scope type to target. The resulting namespace must be in the caller's readable (reads) or writable (writes) set, or the request answers 403.

scopeId
string

Entity id for a scope that carries one. Requires scopeType.

externalRef
string

The caller's own record id, stored for provenance and returned as a chunk's source.ref. The add's de-duplication key within a namespace.

Maximum string length: 500

Response

Deduplicated: an active entry already held this externalRef in this namespace for this principal, so nothing was added. deduplicated is true.

data
object
required

A knowledge add's outcome. 201: the entry was created. 200 with deduplicated: true: an active entry with the same externalRef in the same namespace, added by the same principal, already existed and nothing was written.

meta
object
required