Skip to main content
POST
Re-judge an agent
Schedules the agent-quality judge on one agent, named by its id as Get agent returns it. The answer is 200 with {scheduled, skippedReason?, subjectKind: "agent", subjectId}. A deprecated or archived agent (status_deprecated, status_archived) and a platform-shipped agent (system_agent) are skipped: scheduled: false with skippedReason, and nothing is scheduled. Read the verdict back through Get latest judge verdict, List subject judge verdicts or Get subject judge activity with the returned subjectKind and subjectId. The body is strict: an unknown field is 400. An id that names no agent answers 404 resource_missing “Agent not found”. A PERSONAL agent answers the same 404: it is never a machine subject. Needs synthesis:approve at the platform scope: a grant that covers only some org units receives 403, and nothing is written. A Personal key acts as its owner; an External App or platform key is recorded as itself, with who gave its grant (see Who acted). A Forge agent can never hold synthesis:approve. Without a key, a repeat schedules the judge again. Send an Idempotency-Key to make a retry safe: the same key and body within 24 hours returns the recorded 200 only while you still hold synthesis:approve at the platform scope; otherwise 409 idempotency_result_unavailable, and the write never runs twice. The same key with a different body is 422. If an outcome is unknown, repeat with the same key or read the subject with Get subject judge activity; never retry under a new key.

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

Optional logical intent key. A same-key retry within 24 hours returns the recorded result without writing again.

Required string length: 1 - 255

Body

application/json
id
string
required

The agent's id, as GET /api/v2/agents/get returns it.

Response

Whether a judge was scheduled, and the subject to read its verdict on

data
object
required
meta
object
required