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

# Judge a ticket

> POST /api/judge with an API key and a published pack.

`POST /api/judge` judges one ticket against the pack's published version and stores the evaluation. The route accepts an API key only, with `judgments:run`.

```bash theme={null}
curl https://judged.systems/api/judge \
  -H "x-api-key: $JUDGED_API_KEY" \
  -H "content-type: application/json" \
  -H "idempotency-key: ticket-48213-rev1" \
  -d '{
    "packId": "PACK_ID",
    "ticket": {
      "externalId": "48213",
      "subject": "Charged twice for May",
      "customerMessage": "I was billed twice and want one refunded.",
      "messages": [
        { "role": "agent", "text": "I can see two charges on 2 May.", "at": "2026-05-02T15:04:00Z" }
      ],
      "metadata": { "plan": "pro", "priority": null }
    }
  }'
```

## Response

`200` returns the stored judgment. `result` is the full object from [Results](/docs/guides/results).

```json theme={null}
{
  "evaluationId": "cm7evaluation",
  "packVersionId": "cm7version",
  "result": {
    "status": "accept",
    "answers": {
      "department": {
        "type": "choice",
        "choice": "billing",
        "probabilities": {
          "billing": 0.91,
          "technical": 0.04,
          "account": 0.03,
          "other": 0.02
        }
      }
    },
    "reviewReasons": [],
    "modelId": "typesafe-ai/jev",
    "latencyMs": 840
  }
}
```

The evaluation model is `typesafe-ai/jev`, called once per ticket. `modelId` is the identifier the gateway returned. Pin checks to that field.

A gateway or output failure is also `200`. `result.status` is `review` and `reviewReasons` contains the error kind. The evaluation is still stored.

## Idempotency

`Idempotency-Key` is optional, 1 to 128 characters. The same user and the same key on this route returns the stored evaluation and does not call the model again.

The key is stored per surface. A key used on `POST /api/judge` does not collide with the same string on the inbound webhook.

A `gateway_auth` or `gateway_unavailable` result does not store the key. Send the same key again to retry.

`externalId` is your ticket id. It is not the idempotency key.

## Errors

| Status | Body | When |
| - | - | - |
| 400 | `{ "error": "invalid request", "issues": [] }` | The body failed schema validation, including a bad idempotency key |
| 401 | `{ "error": "API key required" }` | No key |
| 401 | `{ "error": "invalid API key" }` | Unknown or revoked key |
| 403 | `{ "error": "missing permission judgments:run" }` | The key cannot run judgments |
| 404 | `{ "error": "pack not found" }` | The pack is not yours |
| 409 | `{ "error": "pack has no published version" }` | Publish the draft first |
| 429 | `{ "error": "rate limit exceeded" }` | Slow down and retry |

Field reference: `POST /api/judge` in the API reference tab.


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