Update a retrieval golden set
Replace a retrieval golden set’s name, scope, namespaces and cases, or archive it; a set with runs keeps its namespaces and cases. Requires knowledge:manage.
v2 compatibility notes
POST /api/v2/knowledge/goldenSets/update replaces a golden set. The body is the create body plus goldenSetId, and it is a full replacement of name, scope, namespaces and cases. It needs knowledge:manage and answers 200 with the set as written.
Omitting status keeps the set’s status; archived stops its scheduled runs and active restores them. Every namespace named must be one the credential can read; otherwise 403, recorded.
Once a set has runs, its namespaces and cases are frozen so that its runs stay comparable: changing them answers 409 invalid_state, and the message says the set’s cases and namespaces are frozen. Renaming and archiving still succeed; to measure different cases, create a new set.
A malformed or missing goldenSetId, or a set that searches a namespace the credential cannot read, answers 404 resource_missing. A body that create would refuse, or a missing goldenSetId, answers 400 bad_request.
Send an Idempotency-Key to retry safely. A repeat returns the recorded response only while the credential still holds knowledge:manage and knowledge:read and still reads every namespace the set searches now and every namespace the recorded response names; otherwise it answers 403 for a missing knowledge:read, or 409 idempotency_result_unavailable. See Knowledge curation replay.
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
A golden set's full replacement: name, scope, namespaces and cases. Each case is a query and the golden keys a good retrieval returns for it (a case key, or a synced entry's source id), 1–50 per case; 1–100 cases with distinct caseIds. Omitting status keeps the set's status. Once a set has runs its namespaces and cases are frozen (409): rename or archive it instead.
Response
The golden set as written
One retrieval golden set whose every namespace the caller may read: the golden cases a run measures and the namespaces each is searched in. Each case is a query and the golden keys a good retrieval returns for it (a case key, or a synced entry's source id), 1–50 per case; 1–100 cases with distinct caseIds. lastRunRequestedAt is when a run was last requested on demand (null if never). Never names who created it.

