Skip to main content
POST
Create 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/create creates a golden set, as a person does on the Console Knowledge Quality page. A run of the set measures how well retrieval finds each case’s golden keys. It needs knowledge:manage and answers 201 with the KnowledgeGoldenSet. The response is { id, name, scope, namespaces, cases, status, createdAt, lastRunRequestedAt }; lastRunRequestedAt is when a run was last requested on demand, or null. The set is recorded as created by the credential, which is never returned. Namespaces resolve from the credential, never the request; a Personal key acts as its owner. An unknown field, a blank name or scope, a count outside its range, a repeated or blank caseId, a blank query or an unknown status answers 400 bad_request. Send an Idempotency-Key to retry safely. A repeat returns the recorded 201 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

Body

application/json

A new golden set: its name, the scope it measures, the namespaces to search (1–50, each one the caller may read) and its 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. status defaults to active.

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 created

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