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

# Extract

> Classify one conversational turn and pull its entity spans

Label a single conversational turn with an intent and an operation, and pull the values out of it with their exact positions.

This is the understanding layer between speech-to-text and a reply — what did the speaker just ask for, and what values did they give me.

<Info>
  Billed per input token. A failed run is refunded automatically — you are never charged for an answer you did not get. See [Judge pricing](/api-reference/judge/pricing).
</Info>

<Note>
  **Your existing 60db API key already works.** Judge wraps the 60db Jev model behind the same platform credential as TTS, STT and Memory — you do not need a separate key, and you do not need to reissue the one you have. Keys created from now on carry a `judge` scope; keys issued earlier are accepted on their `slm` scope.
</Note>

## Request

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token — **your standard 60db API key** (`sk_…`), or a user JWT. There is no separate Judge credential.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  application/json
</ParamField>

### Body

<ParamField body="text" type="string" required>
  The turn to classify. Maximum **2,048 Unicode code points**.
</ParamField>

<ParamField body="schema" type="object" required>
  The label sets the model may choose from. Every entry is a map of **label name → description**, and the description is what the model actually reads.

  <ParamField body="schema.intents" type="object" required>
    What the speaker wants.
  </ParamField>

  <ParamField body="schema.operations" type="object" required>
    What to do about it.
  </ParamField>

  <ParamField body="schema.entities" type="object">
    Values to pull out of the text.
  </ParamField>

  <ParamField body="schema.responsePaths" type="object">
    How the agent should reply. **Supplying this selects the v2 model**, which also returns a `response_path` and tracks conversation state.
  </ParamField>

  The required `unknown` label is **added for you** if you omit it from a classification map, so you cannot fail on a detail you did not write.
</ParamField>

<ParamField body="profile" type="string" default="generic">
  `generic` or `medical`. v2 only.
</ParamField>

<ParamField body="budget_ms" type="integer" default="8000">
  Total request budget in milliseconds, 1–30000. Covers queuing and inference.
</ParamField>

<ParamField body="request_id" type="string">
  Your own correlation id, echoed back. Generated for you if omitted.
</ParamField>

<ParamField body="save" type="boolean" default="true">
  `false` bills the run but keeps it out of history.
</ParamField>

## Response

<ResponseField name="data.intent" type="object">
  `label` (one of your intents) and `confidence`.
</ResponseField>

<ResponseField name="data.operation" type="object">
  `label` (one of your operations) and `confidence`.
</ResponseField>

<ResponseField name="data.response_path" type="object | null">
  Present only on v2 — i.e. when you supplied `schema.responsePaths`.
</ResponseField>

<ResponseField name="data.entities" type="array">
  Each entity carries `label`, `text`, `start`, `end` and `confidence`.
</ResponseField>

<ResponseField name="data.offset_unit" type="string">
  Always `unicode_code_points` — see the warning below.
</ResponseField>

<ResponseField name="data.timings" type="object">
  `queueMs`, `inferenceMs` and `totalMs` from the model service itself.
</ResponseField>

<ResponseField name="data.min_confidence" type="number | null">
  Lowest confidence across the classifications. Entity confidences are excluded — one uncertain span should not flag the whole turn.
</ResponseField>

## Entity offsets

<Warning>
  `start` and `end` are **Unicode code point** offsets — not bytes, and not UTF-16 indices.

  In JavaScript slice with `Array.from(text).slice(start, end).join('')`; in Python with `"".join(list(text)[start:end])`. A plain `text.slice()` or `text[start:end]` lands in the wrong place as soon as the turn contains an emoji or any astral character.
</Warning>

## Errors

| Status | Meaning                                                                                    |
| ------ | ------------------------------------------------------------------------------------------ |
| `400`  | Text over 2,048 code points, a missing label map, or `version: 2` without `responsePaths`. |
| `402`  | Insufficient credits.                                                                      |
| `403`  | Your role cannot run the judge, or the API key lacks the `judge` scope.                    |
| `429`  | Inference queue full.                                                                      |
| `504`  | The request budget expired — shorten the text or raise `budget_ms`.                        |

## Example

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.60db.ai/judge/extract \
    -H "Authorization: Bearer your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
        "text": "can you move my 10am appointment to friday",
        "schema": {
            "intents": {
                "booking": "Wants to arrange or change a booking"
            },
            "operations": {
                "reschedule": "Move an existing booking"
            },
            "entities": {
                "date": "A calendar date",
                "time": "A clock time"
            }
        }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.60db.ai/judge/extract', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your-api-key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      "text": "can you move my 10am appointment to friday",
      "schema": {
        "intents": {
          "booking": "Wants to arrange or change a booking"
        },
        "operations": {
          "reschedule": "Move an existing booking"
        },
        "entities": {
          "date": "A calendar date",
          "time": "A clock time"
        }
      }
    }),
  });
  const data = await response.json();
  ```

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

  response = requests.post(
      "https://api.60db.ai/judge/extract",
      headers={
          "Authorization": "Bearer your-api-key",
          "Content-Type": "application/json",
      },
      json={
          "text": "can you move my 10am appointment to friday",
          "schema": {
              "intents": {
                  "booking": "Wants to arrange or change a booking"
              },
              "operations": {
                  "reschedule": "Move an existing booking"
              },
              "entities": {
                  "date": "A calendar date",
                  "time": "A clock time"
              }
          }
      },
  )
  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "a1b2c3d4-e5f6-4789-abcd-ef0123456789",
      "saved": true,
      "version": 1,
      "request_id": "b2c3d4e5-f6a7-4890-bcde-f01234567890",
      "intent": {
        "label": "booking",
        "confidence": 0.94
      },
      "operation": {
        "label": "reschedule",
        "confidence": 0.61
      },
      "response_path": null,
      "entities": [
        {
          "label": "date",
          "text": "friday",
          "start": 36,
          "end": 42,
          "confidence": 0.8
        },
        {
          "label": "time",
          "text": "10am",
          "start": 16,
          "end": 20,
          "confidence": 0.8
        }
      ],
      "offset_unit": "unicode_code_points",
      "model_revision": "a221b77a8baf4a613b8f8652661d41fa10a5641e",
      "summary": {
        "intent": "booking",
        "operation": "reschedule",
        "entities": 2
      },
      "min_confidence": 0.61,
      "timings": {
        "queueMs": 1.2,
        "inferenceMs": 18.7,
        "totalMs": 19.9
      },
      "latency_ms": 2,
      "credits_charged": 5.6e-07
    }
  }
  ```
</ResponseExample>