Skip to main content
POST
Decide a knowledge review item
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/decideReview with { id, decision, note } decides one pending item in the knowledge review queue, as a steward decides it in the Console review queue. It needs knowledge:manage and answers 200 with { itemId, status }: approved for a grade, merge or verification, rejected for a dismissal. A holder of knowledge:manage decides an item with this route (MCP forge_decide_knowledge_review), or a person in Console through the item’s handoff link. An authorized call is a steward decision: it 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>. The stamp is never returned. The item must be pending and in a namespace the credential can read, read as no one: a source-restricted item or case is never decided. The item’s case, and every case the decision writes, must be readable now.
An unknown field, action or grade; a decision missing a case id; a blank note or one over 500 characters; a decision the item’s kind does not allow, or a grade the case already has (the message says which); or an invalid Idempotency-Key.
permission_denied: the credential lacks knowledge:manage. forbidden: the item’s case, or a case the decision writes, moved out of the credential’s readable namespaces; or a verify where the credential lacks knowledge:manage at the case’s home. Each refusal is recorded.
The item is malformed, missing, outside the credential’s readable namespaces or source-restricted; or a case the decision writes is malformed, missing, deleted or source-restricted. A caller cannot tell these apart.
invalid_state: the item is already resolved. conflict: the merge was refused (the message gives the reason, and nothing is written); the verification occurrence the item named has changed; or a proven grade would promote a pending revision whose conflict item, or whose live case’s contest, is still undecided (decide that item first). The Idempotency-Key answers idempotency_key_in_flight, idempotency_outcome_unknown and idempotency_result_unavailable are also 409.
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 can still see the item; otherwise it answers 403 for a missing knowledge:read, or the non-disclosing 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

reviewId
string
required
Minimum string length: 1

Body

application/json

A steward's decision on one pending review item, and why (1–500 characters, recorded with it). Each kind allows its own decisions: approval — grade proven or dismiss; contested — grade proven, provisional or retired, or dismiss; conflict — grade the case or a related case provisional or retired, or dismiss; duplicate — merge the loser into the survivor, or dismiss; stale — grade retired, or dismiss; verification_due — verify the case, or dismiss.

decision
object
required
note
string
required
Required string length: 1 - 500

Response

The item decided

data
object
required

The decided item and its new status: approved (a grade, merge or verification) or rejected (dismissed). The decider and note are recorded, never returned.

meta
object
required