Skip to main content

Classify Event

Classify a quality event and map it to applicable CFR regulations using the Knowledge Graph Entity Resolver.

Endpoint​

POST /v1/kg/classify

Base URL: https://api.ctwise.ai

Authorization Tier: Starter+

Request​

Headers​

HeaderRequiredDescription
X-Api-KeyYesYour CTWise API key (format: ctw_<32hex>)
Content-TypeYesapplication/json

Body Parameters​

ParameterTypeRequiredDescription
eventstringYesNatural-language description of the quality event
product_typestringNoFilter by product type: drug, food, device, api

Example Request​

curl -X POST "https://api.ctwise.ai/v1/kg/classify" \
  -H "X-Api-Key: ctw_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Spider found in manufacturing area during production",
    "product_type": "drug"
  }'

Response​

Success (200)​

{
  "classification": {
    "event_type": "pest_control",
    "confidence": 0.97,
    "category": "sanitation",
    "severity": "major"
  },
  "applicable_regulations": [
    {
      "cfr_section": "21 CFR 211.56",
      "title": "Sanitation",
      "relevance": "direct",
      "summary": "Buildings used in manufacture, processing, packing, or holding of drug products shall be maintained in a clean and sanitary condition.",
      "product_type": "drug"
    },
    {
      "cfr_section": "21 CFR 211.25",
      "title": "Personnel qualifications",
      "relevance": "indirect",
      "summary": "Each person engaged in the manufacture, processing, packing, or holding of a drug product shall have education, training, and experience.",
      "product_type": "drug"
    }
  ],
  "evidence_sources": [
    {
      "source_type": "event_taxonomy",
      "source_id": "event-taxonomy-v2.0.jsonl",
      "retrieval_method": "keyword_match",
      "confidence": 0.97,
      "matched_terms": ["spider", "manufacturing area", "pest"]
    }
  ],
  "evidence_chain": {
    "chain_integrity": "verified",
    "evidence_coverage": 0.97,
    "provenance_complete": true
  },
  "response_metadata": {
    "taxonomy_version": "v2.0",
    "processing_timestamp": "2026-03-03T12:00:00Z",
    "resolver_version": "1.0.0",
    "lambda_request_id": "abc123-def456"
  }
}

Response Fields​

FieldTypeDescription
classification.event_typestringClassified event type from taxonomy (e.g., pest_control, contamination, equipment_failure)
classification.confidencenumberClassification confidence score (0-1); threshold is 0.60
classification.categorystringHigh-level event category (sanitation, equipment, documentation, personnel, etc.)
classification.severitystringDefault severity classification: critical, major, minor
applicable_regulationsarrayArray of applicable CFR sections for the event + product type combination
applicable_regulations[].cfr_sectionstringCFR citation (e.g., "21 CFR 211.56")
applicable_regulations[].titlestringOfficial CFR section title
applicable_regulations[].relevancestringRelevance level: direct or indirect
applicable_regulations[].summarystringBrief summary of the regulation
applicable_regulations[].product_typestringProduct type this regulation applies to
evidence_sourcesarraySource provenance for each classification assertion
evidence_sources[].source_typestringType of evidence source (event_taxonomy, cfr_mapping, etc.)
evidence_sources[].source_idstringUnique identifier for the source document
evidence_sources[].retrieval_methodstringMethod used for retrieval (keyword_match, semantic_search, etc.)
evidence_sources[].confidencenumberConfidence score for this evidence source (0-1)
evidence_chainobjectEvidence integrity and coverage metrics
evidence_chain.chain_integritystringIntegrity status: verified, partial, unverified
evidence_chain.evidence_coveragenumberPercentage of response covered by evidence (0-1)
evidence_chain.provenance_completebooleanWhether full provenance chain is available
response_metadataobjectProcessing metadata and versioning information
response_metadata.taxonomy_versionstringVersion of event taxonomy used
response_metadata.processing_timestampstringISO 8601 timestamp of processing
response_metadata.resolver_versionstringVersion of Entity Resolver service

Error Responses​

StatusCauseResponse ExampleResolution
400Missing event field{"error": "Missing required field: event"}Include event description in request body
400Invalid product_type{"error": "Invalid product_type. Must be one of: drug, food, device, api"}Use valid product type values
500Classification failure{"error": "Internal classification error"}Retry request; check Lambda logs if persists
503Service unavailable{"error": "Entity Resolver unavailable"}Retry with exponential backoff

Classification Confidence Levels​

The Entity Resolver uses the following confidence thresholds:

Confidence RangeClassificationAction
0.85 - 1.0High confidenceReturn classification with full detail
0.60 - 0.84Medium confidenceReturn classification with lower confidence flag
0.0 - 0.59Low confidenceReturn event_type: "unknown" with suggested manual review

Event Taxonomy Categories​

The Knowledge Graph supports 30 event types across these categories:

  • Sanitation: Pest control, cleaning validation, facility maintenance
  • Equipment: Calibration failures, equipment breakdowns, maintenance issues
  • Documentation: Record-keeping errors, missing documentation, signature issues
  • Personnel: Training deficiencies, hygiene violations, unauthorized access
  • Process Control: Deviation management, out-of-specification results, process validation
  • Materials Management: Supplier issues, raw material quality, labeling errors
  • Laboratory: Testing failures, method validation, laboratory controls
  • Quality Systems: CAPA deficiencies, change control, internal audits

Usage Examples​

Basic Classification​

curl -X POST "https://api.ctwise.ai/v1/kg/classify" \
  -H "X-Api-Key: ctw_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Equipment was not calibrated according to written procedures"
  }'

Product-Specific Classification​

curl -X POST "https://api.ctwise.ai/v1/kg/classify" \
  -H "X-Api-Key: ctw_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Temperature monitoring records for refrigerated storage were incomplete",
    "product_type": "drug"
  }'

Notes​

  • The Entity Resolver uses a curated Event Taxonomy with 30 event types mapped to CFR regulations
  • Classification confidence threshold is 0.60 — events below this return event_type: "unknown"
  • Each event type maps to specific CFR sections per product type (drug, food, device, API)
  • All responses include evidence provenance (P0 non-negotiable requirement)
  • Product type filtering returns only regulations applicable to specified product types
  • The service uses both keyword matching and semantic analysis for classification
  • Response times typically range from 200-500ms depending on text complexity

483 Intelligence (Cross-Domain)​