Protocol Validation Endpoint

Validate clinical trial protocols against regulatory requirements and best practices.

POST /rules/validate

Submit a protocol for comprehensive compliance analysis.

Request

POST /v1/rules/validate
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request Body

{
  "protocol": {
    "title": "A Randomized Phase III Study of Drug X in Advanced NSCLC",
    "therapeutic_area": "Oncology",
    "indication": "Non-Small Cell Lung Cancer",
    "phase": "III",
    "study_design": {
      "type": "randomized_controlled",
      "blinding": "double_blind",
      "arms": 2,
      "control_type": "active_comparator"
    },
    "endpoints": {
      "primary": {
        "name": "Overall Survival",
        "definition": "Time from randomization to death from any cause",
        "assessment_schedule": "Every 12 weeks"
      },
      "secondary": [
        {
          "name": "Progression-Free Survival",
          "definition": "Time from randomization to disease progression or death"
        },
        {
          "name": "Objective Response Rate",
          "definition": "Proportion of patients with confirmed CR or PR"
        }
      ]
    },
    "sample_size": {
      "planned_enrollment": 500,
      "power": 0.90,
      "alpha": 0.05,
      "effect_size": "HR 0.75"
    },
    "target_authorities": ["FDA", "EMA"]
  },
  "validation_options": {
    "include_recommendations": true,
    "check_recent_guidance": true,
    "compare_similar_trials": true
  }
}

Protocol Object

Field	Type	Required	Description
title	string	Yes	Protocol title
therapeutic_area	string	Yes	Therapeutic area
indication	string	Yes	Disease indication
phase	string	Yes	Clinical phase (I, II, III, IV)
study_design	object	Yes	Study design details
endpoints	object	Yes	Primary and secondary endpoints
sample_size	object	Yes	Sample size justification
target_authorities	array	No	Target regulatory authorities

Validation Options

Option	Type	Default	Description
include_recommendations	boolean	true	Include improvement recommendations
check_recent_guidance	boolean	true	Check against recent regulatory guidance
compare_similar_trials	boolean	false	Compare with similar approved trials

Response

{
  "validation_id": "val_abc123",
  "timestamp": "2025-01-15T10:30:00Z",
  "overall_status": "needs_attention",
  "compliance_score": 78,
  "summary": {
    "total_checks": 45,
    "passed": 35,
    "warnings": 7,
    "critical": 3
  },
  "issues": [
    {
      "issue_id": "ISS-001",
      "severity": "critical",
      "category": "endpoint_definition",
      "title": "Primary Endpoint Assessment Schedule Gap",
      "description": "OS assessment every 12 weeks may miss interim events. FDA guidance recommends more frequent assessments.",
      "regulatory_reference": {
        "authority": "FDA",
        "document": "Clinical Trial Endpoints for the Approval of Cancer Drugs",
        "section": "III.B.2"
      },
      "recommendation": "Consider assessment every 8 weeks or continuous survival follow-up.",
      "impact": {
        "approval_risk": "medium",
        "delay_risk_months": 3
      }
    },
    {
      "issue_id": "ISS-002",
      "severity": "warning",
      "category": "sample_size",
      "title": "Effect Size Assumption",
      "description": "HR 0.75 is optimistic based on similar trial outcomes.",
      "recommendation": "Consider sensitivity analysis with HR 0.80.",
      "similar_trials": [
        {
          "trial_id": "NCT03215001",
          "observed_hr": 0.82
        }
      ]
    }
  ],
  "compliance_by_authority": {
    "FDA": {
      "score": 82,
      "status": "acceptable",
      "key_gaps": ["Assessment frequency"]
    },
    "EMA": {
      "score": 75,
      "status": "needs_attention",
      "key_gaps": ["QoL endpoint missing", "Assessment frequency"]
    }
  },
  "recommendations": [
    {
      "priority": 1,
      "action": "Update OS assessment schedule to every 8 weeks",
      "rationale": "Aligns with FDA expectations and reduces approval risk",
      "effort": "low"
    },
    {
      "priority": 2,
      "action": "Add Quality of Life secondary endpoint",
      "rationale": "Required for EMA submission, increasingly expected by FDA",
      "effort": "medium"
    }
  ],
  "similar_approved_trials": [
    {
      "trial_id": "NCT02453282",
      "title": "KEYNOTE-024",
      "therapeutic_area": "Oncology",
      "indication": "NSCLC",
      "approval_date": "2016-10-24",
      "relevance_score": 0.92
    }
  ]
}

Response Fields

Field	Type	Description	Tier
compliance_score	number	Overall score (0-100)	All
summary	object	Issue counts by severity	All
issues	array	Identified compliance issues	All
issues[].recommendation	string	Fix recommendation	Starter
compliance_by_authority	object	Per-authority breakdown	Starter
recommendations	array	Prioritized action items	Starter
similar_approved_trials	array	Reference trials	Starter

Severity Levels

Level	Description	Action Required
critical	May prevent approval	Immediate attention
warning	Could delay approval	Address before submission
info	Best practice suggestion	Consider for optimization

Examples

Full Validation

curl -X POST "https://api.ctwise.ai/v1/rules/validate" \
  -H "Authorization: Bearer ctwise_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": {
      "title": "Phase III Oncology Study",
      "therapeutic_area": "Oncology",
      "indication": "NSCLC",
      "phase": "III",
      "study_design": {
        "type": "randomized_controlled",
        "blinding": "double_blind",
        "arms": 2
      },
      "endpoints": {
        "primary": {
          "name": "Overall Survival",
          "definition": "Time to death"
        }
      },
      "sample_size": {
        "planned_enrollment": 500
      }
    }
  }'

Python Example

import requests

API_KEY = "ctwise_sk_live_xxx"
BASE_URL = "https://api.ctwise.ai/v1"

protocol = {
    "title": "Phase III Oncology Study",
    "therapeutic_area": "Oncology",
    "indication": "NSCLC",
    "phase": "III",
    "study_design": {
        "type": "randomized_controlled",
        "blinding": "double_blind",
        "arms": 2,
        "control_type": "active_comparator"
    },
    "endpoints": {
        "primary": {
            "name": "Overall Survival",
            "definition": "Time from randomization to death"
        }
    },
    "sample_size": {
        "planned_enrollment": 500,
        "power": 0.90
    },
    "target_authorities": ["FDA", "EMA"]
}

response = requests.post(
    f"{BASE_URL}/rules/validate",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "protocol": protocol,
        "validation_options": {
            "include_recommendations": True,
            "compare_similar_trials": True
        }
    }
)

result = response.json()
print(f"Compliance Score: {result['compliance_score']}%")
print(f"Status: {result['overall_status']}")

print("\nCritical Issues:")
for issue in result['issues']:
    if issue['severity'] == 'critical':
        print(f"  - {issue['title']}")
        print(f"    {issue['description']}")

Error Responses

Invalid Protocol Structure

{
  "error": {
    "code": "INVALID_PROTOCOL",
    "message": "Protocol must include title, therapeutic_area, phase, and endpoints",
    "details": {
      "missing_fields": ["endpoints"]
    }
  }
}

Status: 400 Bad Request

Protocol Too Complex

{
  "error": {
    "code": "PROTOCOL_TOO_COMPLEX",
    "message": "Protocol exceeds maximum complexity for your tier. Upgrade to Pro for unlimited validation."
  }
}

Status: 403 Forbidden

Tier Differences

Feature	Free	Starter
Validations per month	5	50
Basic compliance score	✅	✅
Recommendations	❌	✅
Authority breakdown	❌	✅
Similar trial comparison	❌	✅
Detailed issue analysis	❌	✅

---

Related Endpoints

• POST /requirements/search - Search requirements
• GET /patterns/{therapeutic_area} - Amendment patterns