Skip to main content
POST
Grade a knowledge case
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/cases/setGrade with { entryId, grade, reason } sets a case’s grade: provisional, proven, contested or retired. reason is 1–500 characters and is recorded, redacted, with the change. It needs knowledge:manage and answers { entryId, from, to, promotedInto }. An authorized call is a steward decision, as in the Console: any change a person may make is allowed, including restoring a retired case, and the change is recorded with the credential’s attribution: a Personal key as its owner, with the key named on the audit event (via: "personal_key", apiKeyId); an External App as external-app:<id>, with the people who granted its access; a platform key as platform-key:<id>. Setting the grade the case already has answers 400. Grading answers the case’s pending contested and approval review items; retiring it also answers its stale and duplicate items. A retired case is never returned by search. entryId may name a pending revision. Grading a revision proven promotes it into its live case, and promotedInto names that case; it answers 409 conflict while the live case has an undecided contest, or the revision an undecided conflict. The case must be readable by the credential; a malformed, missing, deleted, unreadable or source-restricted case, or an entry that is not a case, answers 404 resource_missing. Send an Idempotency-Key to retry safely; 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

caseId
string
required
Minimum string length: 1

Body

application/json

The case (or pending revision) to grade, its new grade, and why (1–500 characters, recorded with the change).

grade
enum<string>
required
Available options:
provisional,
proven,
contested,
retired
reason
string
required
Required string length: 1 - 500

Response

The grade change

data
object
required

A grade change: from is null for a case that had none; promotedInto is the live case a pending revision graded proven was promoted into (the revision is then deleted), else null.

meta
object
required