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

# Classify Response Format

> Confidence scores, per-criterion reasoning, and all response fields

Classify returns a category label, a per-criterion confidence breakdown for every category in your schema, and timing information. This page explains every field in the response.

***

## Response Structure

```json theme={null}
{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "result": {
    "category": "invoice"
  },
  "response_confidence": {
    "categories": [
      {
        "category": "invoice",
        "confidence": 1.0,
        "criteria_confidence": [
          {"criterion": "contains billing information", "confidence": "high"},
          {"criterion": "has itemized charges", "confidence": "high"},
          {"criterion": "includes payment details or amounts due", "confidence": "high"}
        ]
      },
      {
        "category": "contract",
        "confidence": 0.33,
        "criteria_confidence": [
          {"criterion": "contains legal terms and conditions", "confidence": "low"},
          {"criterion": "includes signature lines or parties involved", "confidence": "low"},
          {"criterion": "references obligations or agreements", "confidence": "high"}
        ]
      }
    ]
  },
  "duration": 1.23
}
```

### Top-Level Fields

| Field                 | Type   | Description                                                                                                  |
| --------------------- | ------ | ------------------------------------------------------------------------------------------------------------ |
| `job_id`              | string | Unique identifier for the classification job                                                                 |
| `result.category`     | string | The best-matching category from your `classification_schema`. Always one of the category names you provided. |
| `response_confidence` | object | Per-category and per-criterion confidence breakdown. `null` when no criteria are provided.                   |
| `duration`            | number | Time in seconds the classify request took. May be `null`.                                                    |

### Category Confidence Fields

Each entry in `response_confidence.categories` contains:

| Field                 | Type   | Description                                                                                |
| --------------------- | ------ | ------------------------------------------------------------------------------------------ |
| `category`            | string | The category name from your schema                                                         |
| `confidence`          | number | Float between 0 and 1 representing the fraction of criteria that matched for this category |
| `criteria_confidence` | array  | Per-criterion evaluation results                                                           |

### Criteria Confidence Fields

Each entry in `criteria_confidence` contains:

| Field        | Type   | Description                                                                    |
| ------------ | ------ | ------------------------------------------------------------------------------ |
| `criterion`  | string | The criterion text from your schema                                            |
| `confidence` | string | `"high"` (criterion matched the document) or `"low"` (criterion did not match) |

***

## Structured Confidence: Reasoning You Can Act On

Classify doesn't just return a label. It returns a per-criterion confidence breakdown for **every** category you defined, not just the winner. This gives you structured, interpretable reasoning for why a document was classified the way it was.

Each criterion you define becomes a yes/no evaluation. The `confidence` score for a category is the fraction of its criteria that matched (`high`). In the example above, `"invoice"` scored `1.0` because all 3 criteria matched, while `"contract"` scored `0.33` because only 1 of 3 criteria matched.

This structured output is useful in several ways:

* **Auditability.** You can trace exactly which criteria drove a classification decision. If an invoice was misclassified, inspect the `criteria_confidence` to see which criteria matched or didn't.
* **Threshold-based routing.** Instead of blindly trusting `result.category`, check the confidence score. If the top category scores below a threshold (e.g., `0.6`), flag it for human review rather than routing it automatically.
* **Ambiguity detection.** If two categories score similarly (e.g., `0.67` and `0.55`), the document may be ambiguous. Use this signal to trigger a different workflow or request additional information.
* **Schema refinement.** Low-confidence classifications across your pipeline tell you which criteria need to be more specific. The per-criterion breakdown pinpoints exactly which criteria are too broad or overlapping.

<Tip>
  Think of criteria as a structured checklist. This makes the classification decision transparent and programmatically accessible, not just a black-box label.
</Tip>

***

## Example: Confidence-Based Routing

Use the per-category confidence scores to build routing logic that handles uncertain classifications gracefully.

<CodeGroup>
  ```python Python theme={null}
  import requests

  API_KEY = "YOUR_REDUCTO_API_KEY"
  HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

  # Classify the document
  classify_resp = requests.post(
      "https://platform.reducto.ai/classify",
      headers=HEADERS,
      json={
          "input": "YOUR_FILE_ID",
          "classification_schema": [
              {"category": "invoice", "criteria": ["contains billing information", "has itemized charges"]},
              {"category": "contract", "criteria": ["contains legal terms", "includes signature lines"]},
          ],
      },
  )
  result = classify_resp.json()

  # Extract the winning category and its confidence
  category = result["result"]["category"]
  confidence = next(
      c for c in result["response_confidence"]["categories"]
      if c["category"] == category
  )

  if confidence["confidence"] >= 0.7:
      # High confidence: route automatically
      print(f"Routing {category} automatically (confidence: {confidence['confidence']})")
  else:
      # Low confidence: flag for human review
      print(f"Flagging for review: {category} (confidence: {confidence['confidence']})")
      print("Criteria breakdown:")
      for c in confidence["criteria_confidence"]:
          print(f"  {c['criterion']}: {c['confidence']}")
  ```

  ```bash cURL theme={null}
  # Classify and inspect confidence
  RESPONSE=$(curl -s -X POST https://platform.reducto.ai/classify \
    -H "Authorization: Bearer $REDUCTO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "input": "YOUR_FILE_ID",
      "classification_schema": [
        {"category": "invoice", "criteria": ["contains billing information", "has itemized charges"]},
        {"category": "contract", "criteria": ["contains legal terms", "includes signature lines"]}
      ]
    }')

  # Get the category and confidence
  CATEGORY=$(echo $RESPONSE | jq -r '.result.category')
  CONFIDENCE=$(echo $RESPONSE | jq -r ".response_confidence.categories[] | select(.category == \"$CATEGORY\") | .confidence")

  echo "Category: $CATEGORY (confidence: $CONFIDENCE)"

  # Show per-criterion breakdown
  echo "Criteria breakdown:"
  echo $RESPONSE | jq -r ".response_confidence.categories[] | select(.category == \"$CATEGORY\") | .criteria_confidence[] | \"  \(.criterion): \(.confidence)\""
  ```
</CodeGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Classify Overview" icon="file-lines" href="/classify/overview">
    Quick start, request parameters, and pipeline integration.
  </Card>

  <Card title="Best Practices" icon="gauge-high" href="/classify/best-practices">
    Write better classification schemas for more accurate results.
  </Card>
</CardGroup>