Skip to main content
PATCH
Change a knowledge learning setting
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/settings/set with { key, value } stores one learning setting, as Save does on the Console Knowledge › Settings page. It needs platform:manage and answers 200 with the settings in force after the write, the same view as Read the knowledge learning settings. MCP hosts call it through forge_call_operation with operationId setKnowledgeSetting. key is one of the editable knowledge.* keys (knowledge.gradeRankWeights, knowledge.evidenceLogCap, knowledge.provenThresholds, knowledge.signalPrecedence, knowledge.ratingSignal, knowledge.failedRunSignal, knowledge.distillationMinClusterSize, knowledge.distillationMinScore, knowledge.distillationScopes, knowledge.staleAfterDays, knowledge.memoryPromotionRetrievalThreshold, knowledge.federatedDefaultTrustWeight) or chat.ltmPromotionThreshold. value is required and may be any JSON value the key’s rule accepts. Settings are deployment-wide: the write changes how knowledge learns for every tenant. Changing a proven threshold, the signal precedence, the rating bands or the failed-run setting re-derives every case’s outcome state under the new value. The write is stamped with the credential and recorded as a platform_setting_set audit event naming platform_setting:<key> and the value before and after. A change made in the Console is recorded the same way. platform:manage is an approve-and-administer scope: it is in no default scope set, a Personal key carrying it expires sooner, and a Forge agent’s key is never granted it. Send an Idempotency-Key to retry safely: a repeat writes and audits nothing again. The settings have no home to recheck, so a repeat returns the recorded response while the credential still holds platform:manage, and 403 once it does not. The same key with a different body answers 422 idempotency_key_reuse. See Knowledge settings and re-embed replay.

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

Path Parameters

settingKey
string
required
Minimum string length: 1

Body

application/json

One knowledge learning setting: its key (one of the editable knowledge.* keys or chat.ltmPromotionThreshold) and the value its rule accepts. A value outside the rule, or another key, answers 400 and writes nothing.

value
any
required

Response

The learning settings in force after the write

data
object
required

The knowledge learning settings in force, deployment-wide: every value resolved to a valid one, the chat message to long-term memory threshold, which keys carry a stored override (overriddenKeys), a stored value its rule keeps only part of (partlyApplied) or none of (ignoredKeys), and when each stored key was last written.

meta
object
required