Classify a Candidate Answer

Before you begin

Roles required: Validator, content strategist.

You need a candidate_id for a candidate with available answer text. For Flow A candidates, the answer text is already extracted. For Flow B candidates, a generated draft answer must exist before classification is useful.

Assumed state: Candidates have been extracted and reviewed. See Review Extracted Candidates.

Steps

1. Submit the candidate for classification

Send a POST request to /v1/classify with the candidate_id and the answer text to be classified:

curl -s -X POST http://localhost:8000/v1/classify \
  -H "Content-Type: application/json" \
  -d '{
    "candidate_id": "cand_01j2k3l4m5n6p7q8r9t1",
    "answer_text": "Our platform supports SSO via SAML 2.0 and OIDC. Azure AD is a supported identity provider."
  }'

For Flow A candidates, use the answer_text returned by /v1/candidates/{id}/answers. For Flow B candidates, use the generated draft text.

2. Review the classification response

A successful classification returns HTTP 200 with a ClassificationRecord:

{
  "classification_id": "cls_01j2k3l4m5n6p7q8r9u2",
  "candidate_id": "cand_01j2k3l4m5n6p7q8r9t1",
  "primary_horn_type": "FACT",
  "primary_confidence": 0.94,
  "assertion_subtype": "CAPABILITY",
  "assertion_grammar": {
    "subject": "platform",
    "predicate": "supports",
    "object_value": "SSO via SAML 2.0 and OIDC",
    "scope": "identity and access management"
  },
  "requires_review": false,
  "classified_at": "2026-06-07T14:35:00Z"
}

Key fields to review:

Field	Description
`primary_horn_type`	The assigned Horn information type (e.g., `FACT`, `PROCEDURE`, `OPEN_ISSUE`)
`primary_confidence`	Confidence score for the Horn type assignment, 0.0–1.0
`assertion_subtype`	Subtype for FACT classifications (e.g., `CAPABILITY`, `CONSTRAINT`, `BEHAVIOR`)
`assertion_grammar`	For FACT types: the structured subject/predicate/object/scope decomposition
`requires_review`	`true` if confidence is below threshold or type is `OPEN_ISSUE`

Note: Classification is automated but not infallible. The assigned Horn type represents the model's best interpretation of the answer content. Validators may override the effective Horn type at the REVISED stage of validation if the automated assignment is incorrect.

3. Act on the requires_review flag

The requires_review field is set to true when:

primary_confidence is below 0.75
primary_horn_type is OPEN_ISSUE

In both cases, a human must review the classification before the candidate enters the validation assignment queue.

For low-confidence classifications: review the answer text and the assigned Horn type. If the type is plausible but uncertain, proceed to validation and adjust there if needed. If the type is clearly wrong, you can re-submit to /v1/classify with the same candidate_id and a refined or corrected answer_text.

Note: An OPEN_ISSUE classification means no validated answer exists for this question. The candidate cannot be approved in its current form. It should either trigger a generation work item to produce an answer from internal sources, or be manually answered by a subject-matter expert before re-classification.

4. Classify multiple candidates in batch

For large ingest batches, use the batch classification endpoint to submit up to 100 candidates in a single request:

curl -s -X POST http://localhost:8000/v1/classify/batch \
  -H "Content-Type: application/json" \
  -d '{
    "candidates": [
      {
        "candidate_id": "cand_01j2k3l4m5n6p7q8r9t1",
        "answer_text": "Our platform supports SSO via SAML 2.0 and OIDC."
      },
      {
        "candidate_id": "cand_01j2k3l4m5n6p7q8r9t2",
        "answer_text": "Provisioning a new workspace takes approximately 15 minutes."
      }
    ]
  }'

The batch response returns an array of ClassificationRecord objects in the same order as the input. Each record has the same structure as a single-classification response. Check requires_review on each record individually.

5. Retrieve a stored classification record

Once classified, the record is stored and can be retrieved at any time using the candidate_id:

curl -s "http://localhost:8000/v1/classifications/cand_01j2k3l4m5n6p7q8r9t1"

This is useful when returning to a candidate after a break, when sharing a classification result with a colleague, or when building a validation assignment.

Classification decision flow

Use this diagram to determine whether a candidate is ready for validation after classification:

flowchart TD
    A[POST /v1/classify] --> B{confidence >= 0.75?}
    B -- No --> C[requires_review = true\nHuman review needed]
    B -- Yes --> D{primary_horn_type = OPEN_ISSUE?}
    D -- Yes --> E[requires_review = true\nNo approvable answer exists\nTrigger generation or manual answer]
    D -- No --> F{primary_horn_type = FACT?}
    F -- Yes --> G{assertion_grammar complete?\nsubject + predicate + object + scope}
    G -- No --> H[Review grammar fields\nMay indicate ambiguous answer text]
    G -- Yes --> I[Ready for validation assignment]
    F -- No --> I

Result

Every classified candidate has a ClassificationRecord with an assigned Horn type, a confidence score, and — for FACT types — a full assertion grammar decomposition. Candidates with requires_review: false are ready to enter the validation assignment queue. Candidates with requires_review: true need human review before proceeding.

See also: Claim and Decide a Validation Assignment; Horn Information Types; Review Extracted Candidates