Skip to main content
PATCH
Update a retrieval golden set
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/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

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

goldenSetId
string
required
Minimum string length: 1

Body

application/json

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.

name
string
required
Minimum string length: 1
scope
string
required
Minimum string length: 1
namespaces
string[]
required
Required array length: 1 - 50 elements
Minimum string length: 1
cases
object[]
required
Required array length: 1 - 100 elements
status
enum<string>
Available options:
active,
archived

Response

The golden set as written

data
object
required

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.

meta
object
required