> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Judges

> Read machine judges, their rubrics, drift alerts and verdicts; override, promote or demote a judgment; and re-judge a skill, agent, procedure or workflow.

Judges are Forge's machine evaluators: system agents that score a skill, an agent, a procedure, a workflow draft or a run against a rubric and record a verdict. The routes on this page (at v2, under `/api/v2/judges/*`) are the Console's [Judges](https://docs.gloo.com/forge/console/platform/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](https://docs.gloo.com/forge/concepts/trust-fabric.md#judges).

A judge is named by its `id`, the agent id its verdicts carry. Times are epoch milliseconds.

## Authority

| Operations | Permissions |
| - | - |
| [List judges](https://docs.gloo.com/forge/reference/http-api/judges/list.md), [Get judge](https://docs.gloo.com/forge/reference/http-api/judges/get.md), [List judge drift alerts](https://docs.gloo.com/forge/reference/http-api/judges/listDriftAlerts.md), [List judge verdicts](https://docs.gloo.com/forge/reference/http-api/judges/listVerdicts.md), [List judge admissions](https://docs.gloo.com/forge/reference/http-api/judges/listAdmissions.md), [Get judge admission](https://docs.gloo.com/forge/reference/http-api/judges/getAdmission.md) | `platform:read` |
| [Get judge rubric](https://docs.gloo.com/forge/reference/http-api/judges/getRubric.md), [List subject judge verdicts](https://docs.gloo.com/forge/reference/http-api/judges/listSubjectVerdicts.md), [Get subject judge activity](https://docs.gloo.com/forge/reference/http-api/judges/getSubjectActivity.md) | `grants:read`, `policies:read` and `audit:read` |
| [Get latest judge verdict](https://docs.gloo.com/forge/reference/http-api/judges/getLatestVerdict.md) | `workflows:read` |
| [Override judge verdict](https://docs.gloo.com/forge/reference/http-api/judges/overrideVerdict.md) | `judges:use` |
| [Promote judge](https://docs.gloo.com/forge/reference/http-api/judges/promote.md), [Demote judge](https://docs.gloo.com/forge/reference/http-api/judges/demote.md) | `judges:manage` |
| [Resolve judge admission](https://docs.gloo.com/forge/reference/http-api/judges/resolveAdmission.md), [Re-judge skill](https://docs.gloo.com/forge/reference/http-api/judges/rejudgeSkill.md), [Re-judge agent](https://docs.gloo.com/forge/reference/http-api/judges/rejudgeAgent.md) | `synthesis:approve` |
| [Re-judge procedure](https://docs.gloo.com/forge/reference/http-api/judges/rejudgeProcedure.md) | `procedures:approve` |
| [Re-judge workflow](https://docs.gloo.com/forge/reference/http-api/judges/rejudgeWorkflow.md) | `workflows:manage` |

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:approve` or `workflows:manage`, so it can never resolve an admission or re-judge. The read permissions, `judges:use` and `judges:manage` follow an agent's own role grants.

## Subjects

The three subject reads take `subjectKind` and `subjectId`:

| `subjectKind` | `subjectId` |
| - | - |
| `skill` | The skill's `id` |
| `agent` | The agent's `id`, as [Agents](https://docs.gloo.com/forge/reference/http-api/agents) returns it |
| `procedure` | The procedure version's id |
| `workflow_graph` | The workflow draft's `draftId`, from `GET /api/v3/workflows/{workflowId}/draft` |
| `workflow_run` | The run's id |

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 its `errorKind` 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](https://docs.gloo.com/forge/reference/http-api/judges/list.md) 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 is `400`. 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](https://docs.gloo.com/forge/reference/idempotency.md#judge-writes)): 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 holds `synthesis:approve` at the platform scope now (see [Review queues](https://docs.gloo.com/forge/reference/http-api/governance#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](https://docs.gloo.com/forge/reference/mcp-server.md) exposes these eighteen operations in the `judges` tool group.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.