/api/v2/judges/*) are the Console’s Judges page, its judge panels and the re-judge buttons on the skill, agent, procedure and workflow pages, for machines: they read and write the same rows. How judges are dispatched and calibrated is described in Judges.
A judge is named by its id, the agent id its verdicts carry. Times are epoch milliseconds.
Authority
Judges, verdicts, drift alerts and admissions belong to no org unit, so every operation is decided at the platform scope, as the Console decides it. A grant that covers only some org units receives
403 permission_denied, which names the first permission missing. The three governance reads are required together because the Console requires all three. Each write keeps the permission of the Console action it mirrors.
- A Personal key acts as its owner: the owner’s grants must hold the permissions at the platform scope, and the key’s scopes must reach the same permissions.
- An External App or a platform API key needs a role grant at the platform scope whose role carries the permissions.
- A Forge agent can never hold
synthesis:approve,procedures:approveorworkflows:manage, so it can never resolve an admission or re-judge. The read permissions,judges:useandjudges:managefollow an agent’s own role grants.
Subjects
The three subject reads takesubjectKind and subjectId:
A subject read filters, so a subject with no verdicts, or one that does not exist, is an empty list or
null, never 404. A PERSONAL agent is never a readable subject: its verdicts and activity read as empty, and a judge’s verdict list leaves them out. An agent that no longer exists is treated the same way, because its leftover verdicts can no longer be shown not to be a PERSONAL agent’s.
What never leaves
The responses are allowlists. They never carry a rubric’s calibration examples or a criterion’s per-score examples, a failed dispatch’s raw error text (only itserrorKind and governance decisionId), who resolved an admission, or who overrode a verdict, why, or with what alternate verdict. Keyed maps are sent as {key, value} or {criterion, score, rationale} entries.
Lists
Every list answers{<items>, count} for one page. List judges is served in pages from one read of the whole judge set; each judge’s drift count is counted to 100. The other four lists page at the database: limit sets the page size, and while meta.hasMore is true, meta.nextCursor passed as cursor reads the next page. A cursor is bound to its route, its other parameters and the credential; any other cursor is 400. A page may hold fewer rows than limit while more remain, and no judge list answers meta.partial.
Writes
Every write takes a strict JSON body: an unknown field is400. An override rationale and a demote reason must be at least 20 characters after trimming. A write names its subject, and a subject that does not exist is 404; so is a PERSONAL agent. A promotion the thresholds refuse and an admission already resolved are 409 conflict, with a message naming why.
A re-judge changes nothing on its subject: it schedules a judge and answers {scheduled, skippedReason?, subjectKind, subjectId}. A subject the judge would skip (deprecated or archived, a rubric skill, a platform-shipped agent, a built-in procedure, or a procedure version with no recorded synthesis test run) answers scheduled: false with skippedReason, and nothing is scheduled. Read the verdict back through the subject reads with the returned subjectKind and subjectId.
Every write accepts an Idempotency-Key (see Idempotency): a same-key retry returns the recorded 200 only while you still hold the write’s permission at the platform scope, and the write never runs twice.
Who acted
A Personal key acts as its owner: an override, an admission resolution and an audit event record the owner, as the Console records a person. A pending admission is a group human task that asks everyone who holdssynthesis:approve at the platform scope now (see Review queues); a Personal key resolves it through that task, and an External App or a platform API key resolves it as before and closes the task. An External App or a platform API key is recorded as itself (external-app:<id> or platform-key:<id>), and the audit event names who gave the grants that let it act. Every Platform API write records an audit event: judge.verdict_overridden, judge.promoted, judge.demoted, judge.admission_resolved or, when a judge was scheduled, judge.rejudge_requested. No response names who acted.
The Forge MCP server exposes these eighteen operations in the judges tool group.
