Skip to main content
POST
Review a run's diff
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/synchronized-sources/reviewDiff requires knowledge:read. The body names sourceId and runId; start a review with reviewId and cursor null (or absent), and continue it with the page’s view.reviewId and view.continueCursor. The answer is {sourceId, outcome, view}: reviewing has more pages, ready completed the review. Counts are only the changes this person may see (scope: "visible"); hasRestrictedChanges says whether others exist, without counting them. Sample titles are redacted, and no reviewer or decider is named. It is a POST because a review is recorded: approveDiff must cite a review this same person completed on the diff’s current revision, and starting a new review replaces an unfinished one. stale, expired and replaced answer {sourceId, outcome, revision}: read the diff state and review again. The decide flags (canApprove, canApproveShrink, canReject, canResume) are true only where the key holds knowledge:manage where the source lives. Only a Personal key is admitted, acting as its owner: the owner must hold the permission where the source lives, and is recorded as the reviewer, with the key named in the audit. An External App or platform key answers 403 forbidden, recorded: a person reviews and decides a source’s held changes. A review page is never replayed: it shows the changes this person could see when it was read, and that access can narrow since. A repeat under the same Idempotency-Key answers 409 idempotency_result_unavailable; review again with a new key. A new review replaces an unfinished one, so a retry is harmless.

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

synchronizedSourceId
string
required
Minimum string length: 1
runId
string
required
Minimum string length: 1

Body

application/json

Start a review with reviewId and cursor null (or absent); continue it with the previous page's view.reviewId and view.continueCursor.

reviewId
integer | null
Required range: x >= 0
cursor
string | null
Minimum string length: 1

Response

Review a run's diff

data
object
required

One page of a run's diff as its reviewer may see it. reviewing has more pages (view.continueCursor); ready completed the review, and its view.reviewId and view.revision are what approveDiff takes. Counts are only the changes the reviewer may see (scope: "visible"); hasRestrictedChanges says whether others exist without counting them. Sample titles are redacted. stale, expired and replaced answer the diff's current revision instead: read its state and review again. A review never names a reviewer or decider.

meta
object
required