Investigate Event

Perform a comprehensive investigation of a quality event including classification, similar historical observations, ICH guideline mapping, and AI-powered risk assessment.

Endpoint

POST /v1/kg/investigate

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

Authorization Tier: Pro+

Request

Headers

Header	Required	Description
Content-Type	Yes	application/json

Body Parameters

Parameter	Type	Required	Description
event	string	Yes	Natural-language description of the quality event to investigate
product_type	string	No	Product type: drug, food, device, api
include_similar	boolean	No	Include similar 483 observations via semantic search (default: true)
include_ich	boolean	No	Include relevant ICH guideline sections (default: true)
include_risk_assessment	boolean	No	Include AI-powered risk assessment (default: true)
similarity_threshold	number	No	Minimum similarity score for related observations (0-1, default: 0.75)

Example Request

curl -X POST "https://api.ctwise.ai/v1/kg/investigate" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Opened containers of raw materials were left uncovered in the production area",
    "product_type": "drug",
    "include_similar": true,
    "include_ich": true,
    "include_risk_assessment": true,
    "similarity_threshold": 0.75
  }'

Response

Success (200)

{
  "event_classification": {
    "event_type": "materials_handling",
    "confidence": 0.92,
    "category": "materials_management",
    "severity": "major",
    "keywords_extracted": ["uncovered containers", "raw materials", "production area"]
  },
  "applicable_regulations": [
    {
      "cfr_section": "21 CFR 211.86",
      "title": "Protection of components, drug product containers, and closures",
      "relevance": "direct",
      "summary": "Containers of components, drug product containers, and closures shall be protected from contamination and deterioration.",
      "product_types": ["drug"],
      "subsections": [
        {
          "subsection": "(a)",
          "text": "Containers of components, drug product containers, and closures shall be so stored and handled as to prevent contamination."
        }
      ]
    },
    {
      "cfr_section": "21 CFR 211.42",
      "title": "Design and construction features",
      "relevance": "indirect",
      "summary": "Any building used in the manufacture, processing, packing, or holding of a drug product shall be of suitable size, construction and location.",
      "product_types": ["drug"]
    }
  ],
  "similar_observations": [
    {
      "observation_id": "fda-483-2023-12345",
      "similarity_score": 0.89,
      "text": "Open containers of active pharmaceutical ingredients were stored without proper covering, exposing materials to potential contamination.",
      "cited_regulations": ["21 CFR 211.86", "21 CFR 211.94"],
      "facility_type": "Pharmaceutical Manufacturing",
      "inspection_year": 2023,
      "product_category": "drug",
      "source_metadata": {
        "source_type": "fda_483_observation",
        "source_id": "fda-483-2023-12345",
        "retrieval_method": "semantic_search",
        "embedding_model": "text-embedding-3-small"
      }
    },
    {
      "observation_id": "fda-483-2022-67890",
      "similarity_score": 0.84,
      "text": "Raw material containers were observed open in manufacturing areas without environmental controls.",
      "cited_regulations": ["21 CFR 211.86"],
      "facility_type": "API Manufacturing",
      "inspection_year": 2022,
      "product_category": "api",
      "source_metadata": {
        "source_type": "fda_483_observation",
        "source_id": "fda-483-2022-67890",
        "retrieval_method": "semantic_search",
        "embedding_model": "text-embedding-3-small"
      }
    },
    {
      "observation_id": "fda-483-2021-11223",
      "similarity_score": 0.78,
      "text": "Containers of components were not adequately protected from contamination during storage and use.",
      "cited_regulations": ["21 CFR 211.86", "21 CFR 211.122"],
      "facility_type": "Pharmaceutical Manufacturing",
      "inspection_year": 2021,
      "product_category": "drug",
      "source_metadata": {
        "source_type": "fda_483_observation",
        "source_id": "fda-483-2021-11223",
        "retrieval_method": "semantic_search",
        "embedding_model": "text-embedding-3-small"
      }
    }
  ],
  "ich_guideline_results": [
    {
      "guideline": "Q7",
      "guideline_title": "Good Manufacturing Practice Guide for Active Pharmaceutical Ingredients",
      "sections": [
        {
          "section": "10.20",
          "title": "Handling and Labeling",
          "text": "Containers should be assigned a distinctive code, batch, or receipt number and, where necessary, labeled with specified storage conditions.",
          "relevance_score": 0.87,
          "related_cfr": ["21 CFR 211.86", "21 CFR 211.94"]
        },
        {
          "section": "10.21",
          "title": "Sampling and Testing of Incoming Production Materials",
          "text": "Containers from which samples are withdrawn should be opened carefully and subsequently reclosed with precautions to prevent contamination.",
          "relevance_score": 0.82,
          "related_cfr": ["21 CFR 211.86"]
        }
      ]
    },
    {
      "guideline": "Q10",
      "guideline_title": "Pharmaceutical Quality System",
      "sections": [
        {
          "section": "2.5",
          "title": "Management of Outsourced Activities and Purchased Materials",
          "text": "The pharmaceutical quality system should ensure the control of outsourced activities and purchased materials.",
          "relevance_score": 0.71,
          "related_cfr": ["21 CFR 211.84"]
        }
      ]
    }
  ],
  "risk_assessment": {
    "risk_level": "high",
    "risk_score": 0.85,
    "impact_areas": [
      {
        "area": "Product Quality",
        "severity": "high",
        "rationale": "Uncovered containers expose raw materials to environmental contamination including particles, microorganisms, and foreign matter, directly impacting final product quality."
      },
      {
        "area": "Regulatory Compliance",
        "severity": "high",
        "rationale": "Direct violation of 21 CFR 211.86 requirements for container protection. Historically cited in multiple 483 observations with similar language."
      },
      {
        "area": "Patient Safety",
        "severity": "medium",
        "rationale": "Contaminated raw materials could lead to adulterated drug products, presenting potential patient safety risks depending on contamination type and product application."
      }
    ],
    "recommended_actions": [
      {
        "priority": "immediate",
        "action": "Quarantine all exposed raw materials pending quality assessment and disposition decision"
      },
      {
        "priority": "immediate",
        "action": "Implement immediate corrective action to cover all open containers and establish environmental controls"
      },
      {
        "priority": "short_term",
        "action": "Review and revise SOPs for materials handling to explicitly require container closure when not in active use"
      },
      {
        "priority": "short_term",
        "action": "Conduct training for all personnel handling raw materials on proper container management"
      },
      {
        "priority": "long_term",
        "action": "Implement visual management system (e.g., color-coded container status indicators) to prevent recurrence"
      }
    ],
    "similar_citation_frequency": {
      "total_similar_citations": 47,
      "time_period": "2020-2024",
      "trend": "increasing",
      "most_common_cfr": "21 CFR 211.86"
    }
  },
  "evidence_sources": [
    {
      "source_type": "event_taxonomy",
      "source_id": "event-taxonomy-v3.0.jsonl",
      "retrieval_method": "hybrid_keyword_embedding",
      "confidence": 0.92
    },
    {
      "source_type": "fda_483_database",
      "source_id": "fda-483-embeddings-2020-2024",
      "retrieval_method": "semantic_search",
      "confidence": 0.89,
      "documents_retrieved": 3
    },
    {
      "source_type": "ich_guidelines",
      "source_id": "ich-q7-q9-q10-2024",
      "retrieval_method": "semantic_search",
      "confidence": 0.87,
      "sections_retrieved": 3
    },
    {
      "source_type": "cfr_regulations",
      "source_id": "cfr-title21-2024",
      "retrieval_method": "direct_lookup",
      "confidence": 1.0
    }
  ],
  "evidence_chain": {
    "chain_integrity": "verified",
    "evidence_coverage": 0.94,
    "provenance_complete": true,
    "sources_verified": 4
  },
  "response_metadata": {
    "taxonomy_version": "v3.0",
    "processing_timestamp": "2026-03-03T12:00:00Z",
    "resolver_version": "1.0.0",
    "lambda_request_id": "xyz789-abc123",
    "processing_time_ms": 1247,
    "total_sources_consulted": 4
  }
}

Response Fields

Field	Type	Description
event_classification	object	Classified event details
event_classification.event_type	string	Event type from taxonomy
event_classification.confidence	number	Classification confidence (0-1)
event_classification.category	string	High-level category
event_classification.severity	string	Severity: critical, major, minor
event_classification.keywords_extracted	string[]	Key terms extracted from input text
applicable_regulations	array	Applicable CFR sections with full details
applicable_regulations[].cfr_section	string	CFR citation
applicable_regulations[].title	string	Official section title
applicable_regulations[].relevance	string	direct or indirect relevance
applicable_regulations[].summary	string	Section summary
applicable_regulations[].subsections	array	Relevant subsection details
similar_observations	array	Similar FDA 483 observations from historical data
similar_observations[].observation_id	string	Unique observation identifier
similar_observations[].similarity_score	number	Semantic similarity score (0-1)
similar_observations[].text	string	Observation text
similar_observations[].cited_regulations	string[]	CFR sections cited in this observation
similar_observations[].facility_type	string	Type of facility inspected
similar_observations[].inspection_year	number	Year of inspection
similar_observations[].product_category	string	Product category
ich_guideline_results	array	Relevant ICH guideline sections
ich_guideline_results[].guideline	string	Guideline identifier (Q7, Q9, Q10)
ich_guideline_results[].guideline_title	string	Full guideline title
ich_guideline_results[].sections	array	Relevant sections from the guideline
ich_guideline_results[].sections[].section	string	Section number
ich_guideline_results[].sections[].title	string	Section title
ich_guideline_results[].sections[].text	string	Section content excerpt
ich_guideline_results[].sections[].relevance_score	number	Relevance to query (0-1)
ich_guideline_results[].sections[].related_cfr	string[]	Related CFR sections
risk_assessment	object	AI-powered risk analysis
risk_assessment.risk_level	string	Overall risk: critical, high, medium, low
risk_assessment.risk_score	number	Quantitative risk score (0-1)
risk_assessment.impact_areas	array	Affected areas with severity
risk_assessment.recommended_actions	array	Prioritized corrective actions
risk_assessment.similar_citation_frequency	object	Historical citation frequency data
evidence_sources	array	All evidence sources used
evidence_chain	object	Evidence integrity metrics
response_metadata	object	Processing metadata

Error Responses

Status	Cause	Response Example	Resolution
400	Missing event field	{"error": "Missing required field: event"}	Include event text in request body
400	Invalid similarity_threshold	{"error": "similarity_threshold must be between 0 and 1"}	Use value between 0.0 and 1.0
403	Insufficient authorization	{"error": "Pro+ subscription required"}	Upgrade to Pro or Enterprise tier
500	Investigation failure	{"error": "Internal investigation error"}	Retry request; check Lambda logs
503	Service unavailable	{"error": "Entity Resolver unavailable"}	Retry with exponential backoff

Risk Assessment Levels

Risk Level	Score Range	Description	Typical Response
Critical	0.90 - 1.0	Immediate patient safety or product quality impact	Immediate action required, potential product recall
High	0.70 - 0.89	Significant compliance or quality risk	Urgent corrective action, regulatory reporting consideration
Medium	0.50 - 0.69	Moderate risk requiring attention	Planned corrective action, enhanced monitoring
Low	0.0 - 0.49	Minor risk or documentation issue	Standard CAPA process, routine follow-up

Usage Examples

Comprehensive Investigation

curl -X POST "https://api.ctwise.ai/v1/kg/investigate" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Cleaning validation study did not include worst-case product scenarios",
    "product_type": "drug",
    "include_similar": true,
    "include_ich": true,
    "include_risk_assessment": true
  }'

Investigation Without Risk Assessment

curl -X POST "https://api.ctwise.ai/v1/kg/investigate" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Temperature excursion in warehouse storage area",
    "product_type": "drug",
    "include_similar": true,
    "include_ich": false,
    "include_risk_assessment": false,
    "similarity_threshold": 0.80
  }'

Performance Characteristics

Metric	Typical Value	Notes
Response Time	1.0 - 2.5 seconds	Depends on enabled features and similarity threshold
Similar Observations Returned	3-10	Based on similarity_threshold; higher threshold = fewer results
ICH Sections Returned	2-8	Most relevant sections across Q7, Q9, Q10
Risk Assessment Generation	+500ms	AI-powered analysis adds processing time

Notes

• Authorization: Requires Pro+ subscription tier (includes Starter and Pro features)
• Evidence Framework: All responses include full provenance chain (P0 non-negotiable)
• Semantic Search: Similar observations use Amazon Bedrock Titan Text Embedding v2 model
• Classification Algorithm: Hybrid keyword + embedding scoring with Platt sigmoid calibration (v3.0)
• Historical Data: FDA 483 observation database covers 2020-2024 (updated quarterly)
• ICH Guidelines: Includes Q7 (API GMP), Q9 (Quality Risk Management), Q10 (Pharmaceutical Quality System)
• Rate Limiting: Pro tier: 100 requests/hour; Enterprise: unlimited
• Caching: Results cached for 24 hours based on input text hash
• Language Support: English only (multilingual support planned for Q3 2026)

Best Practices

1. Use Specific Event Descriptions: More detailed text improves classification accuracy and similar observation matching
2. Set Appropriate Similarity Threshold: Lower threshold (0.70) for broader research; higher threshold (0.85) for precise matches
3. Enable All Features for Complex Events: Use full investigation (all includes enabled) for major deviations or critical events
4. Review Evidence Sources: Always check evidence_sources and evidence_chain for transparency
5. Consider Historical Trends: Use similar_citation_frequency data to understand regulatory focus areas
6. Integrate with CAPA Systems: Use recommended_actions as starting point for corrective action planning

Related Endpoints

• Classify Event - Quick event classification only
• Get CFR Regulation - Retrieve full CFR section details
• Get ICH Guideline - Access complete ICH guidelines
• Analytics Trends - Industry-wide trending citations

483 Intelligence (Cross-Domain)

• POST /v1/483/observations/search - Search historical 483 observations that inform similar-citations results
• GET /v1/483/facilities/{fei} - Facility history for the FEI referenced in investigations
• GET /v1/483/risk-scores - Facility risk scores used in risk assessment
• Platform Intelligence Overview - How investigation draws from all data domains