Validate API

POST

/v1/validate

The Validate API is Cortex's trust layer that cross-verifies information across multiple sources, detects contradictions, and provides confidence scores for fact-checking and source verification.

🎯 Overview

Validate claims and information by:

• Cross-source verification - Compare facts across multiple sites
• Contradiction detection - Identify conflicting information
• Confidence scoring - Rate trustworthiness of claims
• Source ranking - Rank sources by authority and reliability

Perfect for:

• Fact-checking systems
• News verification
• Research validation
• AI safety and accuracy

📝 Request Format

Basic Validation

curl -X POST https://api.usecortex.co/v1/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "claim": "The iPhone 15 was released in September 2023",
    "sources": ["apple.com", "techcrunch.com", "theverge.com"]
  }'

Advanced Validation

{
  "claim": "Tesla delivered over 1.8 million vehicles in 2023",
  "sources": [
    "https://ir.tesla.com/press-release/tesla-q4-2023-vehicle-production-deliveries",
    "https://techcrunch.com/tesla-deliveries-2023",
    "https://reuters.com/business/tesla-annual-deliveries"
  ],
  "options": {
    "confidence_threshold": 0.8,
    "require_primary_sources": true,
    "max_sources": 10,
    "timeout": 15
  },
  "context": {
    "domain": "automotive",
    "claim_type": "factual",
    "time_sensitive": true
  }
}

📋 Parameters

Required Parameters

Parameter	Type	Description
claim	string	Statement to validate (10-1000 characters)

Optional Parameters

Parameter	Type	Default	Description
sources	array	[]	Specific sources to check (URLs or domains)
confidence_threshold	float	0.7	Minimum confidence required (0.0-1.0)
require_primary_sources	boolean	false	Only use authoritative sources
max_sources	integer	5	Maximum sources to analyze (1-20)
context	object	{}	Additional context for validation

Context Parameters

Parameter	Type	Description
domain	string	Subject domain (news, science, finance, etc.)
claim_type	string	Type of claim (factual, opinion, prediction)
time_sensitive	boolean	Whether claim is time-dependent
geographic_region	string	Geographic relevance

📊 Response Format

Success Response

{
  "success": true,
  "data": {
    "claim": "Tesla delivered over 1.8 million vehicles in 2023",
    "validation_result": "VERIFIED",
    "confidence_score": 0.94,
    "consensus_level": "STRONG",
    "evidence": {
      "supporting": [
        {
          "source": "https://ir.tesla.com/press-release/tesla-q4-2023",
          "snippet": "Tesla delivered 1.81 million vehicles in 2023...",
          "confidence": 0.98,
          "authority_score": 0.95,
          "published_date": "2024-01-02T10:00:00Z",
          "evidence_strength": "STRONG"
        },
        {
          "source": "https://reuters.com/business/tesla-annual-deliveries",
          "snippet": "Tesla reported annual deliveries of 1.808 million...",
          "confidence": 0.92,
          "authority_score": 0.88,
          "published_date": "2024-01-02T14:30:00Z",
          "evidence_strength": "STRONG"
        }
      ],
      "contradicting": [],
      "neutral": [
        {
          "source": "https://example.com/tesla-analysis",
          "snippet": "Tesla's delivery numbers show strong growth...",
          "confidence": 0.65,
          "authority_score": 0.45,
          "note": "Discusses deliveries but doesn't specify exact numbers"
        }
      ]
    },
    "source_analysis": {
      "primary_sources": 2,
      "secondary_sources": 1,
      "total_analyzed": 8,
      "authority_distribution": {
        "high": 3,
        "medium": 4,
        "low": 1
      }
    },
    "fact_check_summary": {
      "verdict": "TRUE",
      "explanation": "Multiple authoritative sources confirm Tesla delivered 1.808 million vehicles in 2023...",
      "key_evidence": [
        "Official Tesla investor relations statement",
        "Consistent reporting across major news outlets",
        "SEC filing confirmation"
      ]
    }
  },
  "metadata": {
    "request_id": "req_validate_789",
    "processing_time": 3.45,
    "sources_checked": 8,
    "validation_method": "cross_verification",
    "timestamp": "2025-01-09T15:30:00Z"
  }
}

🎯 Validation Results

Result Categories

Result	Description	Confidence Range
VERIFIED	Claim confirmed by multiple sources	0.8-1.0
LIKELY_TRUE	Probable but not definitively confirmed	0.6-0.8
UNCERTAIN	Insufficient or conflicting evidence	0.4-0.6
LIKELY_FALSE	Probably incorrect based on evidence	0.2-0.4
DEBUNKED	Clearly false or misleading	0.0-0.2

Consensus Levels

Level	Description
STRONG	80%+ sources agree
MODERATE	60-80% sources agree
WEAK	40-60% sources agree
CONFLICTED	<40% agreement

🔍 Validation Types

Factual Claims

{
  "claim": "The Great Wall of China is visible from space",
  "context": {
    "claim_type": "factual",
    "domain": "science"
  },
  "require_primary_sources": true
}

Statistical Claims

{
  "claim": "Unemployment rate in the US dropped to 3.7% in December 2024",
  "context": {
    "claim_type": "statistical",
    "domain": "economics",
    "time_sensitive": true
  },
  "sources": ["bls.gov", "fed.gov"]
}

Event Claims

{
  "claim": "Apple announced new MacBook Pro models at WWDC 2024",
  "context": {
    "claim_type": "event",
    "domain": "technology",
    "time_sensitive": true
  }
}

Quote Verification

{
  "claim": "Elon Musk said 'Mars is the next step for humanity' in 2023",
  "context": {
    "claim_type": "quote",
    "domain": "technology",
    "person": "Elon Musk"
  },
  "require_primary_sources": true
}

📈 Batch Validation

Validate multiple claims simultaneously:

{
  "claims": [
    {
      "id": "claim_1",
      "claim": "ChatGPT was released in November 2022",
      "context": {"domain": "technology"}
    },
    {
      "id": "claim_2", 
      "claim": "The iPhone 15 supports USB-C charging",
      "context": {"domain": "technology"}
    },
    {
      "id": "claim_3",
      "claim": "Bitcoin reached $100,000 in 2024",
      "context": {"domain": "finance", "time_sensitive": true}
    }
  ],
  "options": {
    "parallel_processing": true,
    "confidence_threshold": 0.7
  }
}

Batch Response:

{
  "success": true,
  "data": {
    "results": [
      {
        "id": "claim_1",
        "validation_result": "VERIFIED",
        "confidence_score": 0.96
      },
      {
        "id": "claim_2",
        "validation_result": "VERIFIED", 
        "confidence_score": 0.92
      },
      {
        "id": "claim_3",
        "validation_result": "LIKELY_FALSE",
        "confidence_score": 0.15
      }
    ],
    "summary": {
      "total_claims": 3,
      "verified": 2,
      "debunked": 1,
      "avg_confidence": 0.67
    }
  }
}

🔧 Source Authority Scoring

Sources are scored based on:

Factor	Weight	Description
Domain Authority	30%	Website credibility and reputation
Publication Type	25%	Primary vs secondary source
Expertise	20%	Author credentials and expertise
Recency	15%	How recent the information is
Citations	10%	Number of citations and references

Authority Levels

• High (0.8-1.0): Official sources, peer-reviewed journals, government agencies
• Medium (0.5-0.8): Established news outlets, expert blogs, industry reports
• Low (0.0-0.5): Social media, forums, unverified sources

🚨 Error Handling

Common Errors

Error Code	Description	Solution
CLAIM_TOO_SHORT	Claim under 10 characters	Provide more detailed claim
CLAIM_TOO_LONG	Claim over 1000 characters	Break into smaller claims
INSUFFICIENT_SOURCES	Not enough sources found	Broaden search or provide sources
VALIDATION_TIMEOUT	Processing took too long	Reduce scope or increase timeout

Error Response

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SOURCES",
    "message": "Could not find enough reliable sources to validate the claim",
    "details": {
      "claim": "Very specific technical claim",
      "sources_found": 1,
      "sources_required": 2,
      "suggestion": "Try rephrasing the claim or providing specific sources"
    }
  },
  "request_id": "req_validate_error_123"
}

💡 Use Cases

News Verification

from cortex import CortexClient

client = CortexClient(api_key="your_key")

# Verify breaking news
result = client.validate(
    claim="Major earthquake hits Tokyo causing widespread damage",
    sources=["reuters.com", "bbc.com", "cnn.com"],
    context={
        "claim_type": "event",
        "domain": "news",
        "time_sensitive": True
    }
)

if result.validation_result == "VERIFIED":
    print("News confirmed by multiple sources")
else:
    print(f"Verification status: {result.validation_result}")

Fact-Checking Pipeline

# Automated fact-checking
claims = [
    "Python is the most popular programming language",
    "Tesla is the largest car manufacturer by market cap",
    "The human brain has 100 billion neurons"
]

results = client.validate_batch(
    claims=claims,
    confidence_threshold=0.8,
    require_primary_sources=True
)

for result in results:
    print(f"Claim: {result.claim}")
    print(f"Status: {result.validation_result}")
    print(f"Confidence: {result.confidence_score:.2f}")

Research Validation

# Validate research claims
result = client.validate(
    claim="Regular exercise reduces risk of heart disease by 35%",
    context={
        "claim_type": "statistical",
        "domain": "health",
        "require_studies": True
    },
    sources=["pubmed.ncbi.nlm.nih.gov", "nejm.org", "harvard.edu"]
)

print(f"Medical claim validation: {result.fact_check_summary.verdict}")
print(f"Key evidence: {result.fact_check_summary.key_evidence}")

🎨 Integration Examples

JavaScript SDK

import Cortex from '@cortex/sdk';

const cortex = new Cortex({ apiKey: 'your_key' });

// Validate a claim
const result = await cortex.validate({
  claim: 'The iPhone 15 was released in September 2023',
  sources: ['apple.com', 'techcrunch.com'],
  confidenceThreshold: 0.8
});

console.log(`Validation: ${result.validationResult}`);
console.log(`Confidence: ${result.confidenceScore}`);

// Process evidence
result.evidence.supporting.forEach(evidence => {
  console.log(`Source: ${evidence.source}`);
  console.log(`Authority: ${evidence.authorityScore}`);
});

cURL Examples

# Basic validation
curl -X POST https://api.usecortex.co/v1/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "claim": "The Earth is round",
    "context": {"claim_type": "factual", "domain": "science"}
  }'

# Batch validation
curl -X POST https://api.usecortex.co/v1/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "claims": [
      {"claim": "Water boils at 100°C at sea level"},
      {"claim": "The moon is made of cheese"}
    ]
  }'

---

Next: Cache API → - Trust cache management