Skip to main content
POST
Run a golden set now
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/run with { goldenSetId, k } schedules one manual retrieval eval run of an active golden set, as Run now does on the Console Knowledge Quality page. k is the hits each case retrieves, an integer 1–20, default 8. It needs knowledge:manage and answers 200 with { goldenSetId, k, scheduled: true }. The run happens in the background: it embeds each case’s query, searches the set’s namespaces and records its embedding model, chunker version and k. Read its result with List golden set runs. Send an Idempotency-Key to retry safely: a repeat schedules nothing again. It returns the recorded response only while the credential still holds knowledge:manage and knowledge:read and still reads every namespace of the set; 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

The active golden set to run now, and k, the hits each case retrieves (an integer 1–20; 8 when omitted).

k
integer
Required range: 1 <= x <= 20

Response

The run was scheduled

data
object
required

A manual run was scheduled at k. It runs in the background: read its result with GET /api/v2/knowledge/goldenSets/listRuns.

meta
object
required