Skip to main content
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

{
  "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

FieldTypeDescription
job_idstringUnique identifier for the classification job
result.categorystringThe best-matching category from your classification_schema. Always one of the category names you provided.
response_confidenceobjectPer-category and per-criterion confidence breakdown. null when no criteria are provided.
durationnumberTime in seconds the classify request took. May be null.

​
Category Confidence Fields

Each entry in response_confidence.categories contains:
FieldTypeDescription
categorystringThe category name from your schema
confidencenumberFloat between 0 and 1 representing the fraction of criteria that matched for this category
criteria_confidencearrayPer-criterion evaluation results

​
Criteria Confidence Fields

Each entry in criteria_confidence contains:
FieldTypeDescription
criterionstringThe criterion text from your schema
confidencestring"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.
Think of criteria as a structured checklist. This makes the classification decision transparent and programmatically accessible, not just a black-box label.

​
Example: Confidence-Based Routing

Use the per-category confidence scores to build routing logic that handles uncertain classifications gracefully. 
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']}")

Classify Overview

Quick start, request parameters, and pipeline integration.

Best Practices

Write better classification schemas for more accurate results.