Skip to content

Classification API

Base URL: http://localhost:8001

POST /v1/classify

Classify a single candidate answer.

Request body:

{
  "candidate_id": "string",
  "answer_text": "string (required, non-empty)",
  "processing_run_id": "string | null"
}

Response 201:

{
  "record_id": "uuid",
  "candidate_id": "string",
  "answer_text": "string",
  "primary_horn_type": "fact | concept | procedure | process | principle | reference | troubleshooting | recommendation | open_issue",
  "primary_confidence": 0.0,
  "alternative_types": [
    {"horn_type": "concept", "confidence": 0.42}
  ],
  "assertion_subtype": "capability | existence | configuration | state | constraint | temporal | null",
  "assertion_grammar": {
    "subject": "string | null",
    "predicate": "string | null",
    "object_value": "string | null",
    "scope": "string | null",
    "condition": "string | null",
    "temporal_boundary": "string | null",
    "unknown_fields": ["subject"],
    "completeness_score": 0.67
  },
  "requires_review": false,
  "model_version": "rule-based-v1.0",
  "processing_run_id": "string | null",
  "classified_at": "2026-06-07T12:00:00"
}

Notes: - assertion_subtype and assertion_grammar are only populated when primary_horn_type == "fact". - requires_review is true when primary_confidence < threshold (default 0.75) or primary_horn_type == "open_issue". - alternative_types is populated when confidence is below threshold.

Error 422: Empty answer_text.

POST /v1/classify/batch

Classify up to 100 candidate answers in one request.

Request body:

{
  "candidates": [
    {"candidate_id": "...", "answer_text": "..."},
    {"candidate_id": "...", "answer_text": "..."}
  ],
  "processing_run_id": "string | null"
}

Response 201:

{
  "classified": 2,
  "skipped": 0,
  "records": [...]
}

Records that fail classification (e.g. empty text) are counted in skipped and do not abort the batch.

GET /v1/classifications/{candidate_id}

Retrieve the most recent classification record for a candidate.

Response 200: Same schema as POST /v1/classify response.

Response 404: No classification exists for candidate_id.

Example: Classify a FACT answer

curl -X POST http://localhost:8001/v1/classify \
  -H "Content-Type: application/json" \
  -d '{
    "candidate_id": "abc-123",
    "answer_text": "The platform supports localized help sites when locale-specific branches and configured site targets are available."
  }'

{
  "record_id": "...",
  "candidate_id": "abc-123",
  "primary_horn_type": "fact",
  "primary_confidence": 0.81,
  "assertion_subtype": "capability",
  "assertion_grammar": {
    "subject": "platform",
    "predicate": "supports",
    "object_value": "localized portal builds",
    "scope": "locale-specific branches configured",
    "unknown_fields": [],
    "completeness_score": 1.0
  },
  "requires_review": false,
  "model_version": "rule-based-v1.0"
}