Review a run's diff
Read one page of a run’s held changes as its reviewer may see them.
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
Headers
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.
1 - 255Path Parameters
Body
Response
Review a run's diff
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.
- Option 1
- Option 2

