> ## 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.

# Quickstart

> Publish a pack, create an API key, and judge one ticket.

Judge one ticket against a published pack. You need an account, a pack with a published version, and an API key.

<Steps>
  <Step title="Create a pack">
    In the app, open Packs and create a pack. A new pack starts from the triage draft: department, urgency, refund requested, policy risk, and escalation.

    To create one over the API, send a key with `packs:write`:

    ```bash theme={null}
    curl https://judged.systems/api/packs \
      -H "x-api-key: $JUDGED_API_KEY" \
      -H "content-type: application/json" \
      -d '{ "name": "Triage" }'
    ```

    The response includes `id`. That is the `packId` you judge with. The body of a new pack is the starter draft. Replace it with `PATCH /api/packs/{packId}` when you want your own questions. See [Packs](/docs/guides/packs) and [Questions](/docs/guides/questions).
  </Step>

  <Step title="Publish the draft">
    REST, MCP, webhooks, and simulations judge the published version. The playground can judge the draft before you publish.

    ```bash theme={null}
    curl https://judged.systems/api/packs/PACK_ID/publish \
      -X POST \
      -H "x-api-key: $JUDGED_API_KEY" \
      -H "content-type: application/json" \
      -d '{ "notes": "first triage version" }'
    ```

    The response is `{ "versionId": "..." }`. A published version does not change. The next publish creates a new version and makes it live.
  </Step>

  <Step title="Create an API key">
    In the app, open Integrations and create a key. The secret is shown once. Copy it into `JUDGED_API_KEY`.

    `POST /api/judge` accepts an API key and does not fall back to a browser session. Send the key as `x-api-key` or `Authorization: Bearer`.
  </Step>

  <Step title="Judge a ticket">
    <CodeGroup>
      ```bash curl theme={null}
      curl https://judged.systems/api/judge \
        -H "x-api-key: $JUDGED_API_KEY" \
        -H "content-type: application/json" \
        -d '{
          "packId": "PACK_ID",
          "ticket": {
            "externalId": "48213",
            "subject": "Charged twice for May",
            "customerMessage": "I was billed twice and want one refunded."
          }
        }'
      ```

      ```javascript Node theme={null}
      const response = await fetch("https://judged.systems/api/judge", {
        method: "POST",
        headers: {
          "x-api-key": process.env.JUDGED_API_KEY,
          "content-type": "application/json",
        },
        body: JSON.stringify({
          packId: "PACK_ID",
          ticket: {
            externalId: "48213",
            subject: "Charged twice for May",
            customerMessage: "I was billed twice and want one refunded.",
          },
        }),
      });

      if (!response.ok) {
        throw new Error(await response.text());
      }

      const judgment = await response.json();
      ```

      ```python Python theme={null}
      import os
      import requests

      response = requests.post(
          "https://judged.systems/api/judge",
          headers={"x-api-key": os.environ["JUDGED_API_KEY"]},
          json={
              "packId": "PACK_ID",
              "ticket": {
                  "externalId": "48213",
                  "subject": "Charged twice for May",
                  "customerMessage": "I was billed twice and want one refunded.",
              },
          },
          timeout=60,
      )
      response.raise_for_status()
      judgment = response.json()
      ```
    </CodeGroup>

    A `200` body is `{ evaluationId, result, packVersionId }`. `result.status` is `accept` or `review`. A gateway failure is still `200`, with `status: "review"` and a reason such as `gateway_unavailable`. See [Errors](/docs/guides/errors).
  </Step>

  <Step title="Read the stored evaluation">
    ```bash theme={null}
    curl https://judged.systems/api/evaluations/EVALUATION_ID \
      -H "x-api-key: $JUDGED_API_KEY"
    ```

    The row includes the redacted ticket, the answers, and any labels added later. List recent rows with `GET /api/evaluations`.
  </Step>
</Steps>

<Tip>
  Send `Idempotency-Key` (1–128 characters) when a retry must not judge the ticket twice. The same key on `POST /api/judge` returns the stored evaluation. A gateway failure does not store the key, so a retry can run again.
</Tip>

## Next

<Columns cols={2}>
  <Card title="Write questions" icon="list-checks" href="/docs/guides/questions">
    Choice, score, and boolean, and what to leave out of the instructions.
  </Card>

  <Card title="Set thresholds" icon="sliders-horizontal" href="/docs/guides/results">
    When a probability or a score becomes review.
  </Card>

  <Card title="Receive a completion" icon="webhook" href="/docs/guides/webhooks">
    Accept a ticket with 202, then verify the signed POST.
  </Card>

  <Card title="Connect an agent" icon="bot" href="/docs/guides/mcp">
    OAuth into `{origin}/mcp` and call `judge_ticket`.
  </Card>
</Columns>


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