ContextGrade
API Reference

ContextGrade API

A REST API for content intelligence and brand safety analysis. Authenticate with your API key, send a URL, and receive structured JSON with 50+ metrics.

Quick Start

Make your first analysis request in seconds. Replace YOUR_API_KEY with your actual key.

curl -X POST https://api.contextgrade.org/api/analyze \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "url": "https://example.com/article",
    "fields": ["article", "site", "brand_safety_article", "brand_safety_site"]
  }'
POST
/api/analyze
Analyze a URL for content intelligence and brand safety metrics
Auth: x-api-key header
GET
/api/sites
List all analyzed domains in your account
Auth: x-api-key header
GET
/api/sites/:domain
Get detailed analysis for a specific domain including compliance data
Auth: x-api-key header
GET
/api/sites/:domain/compliance
Get site-level compliance, CrUX, advertising tech, and tech stack data
Auth: x-api-key header
GET
/api/sites/:domain/brand-safety
Get aggregated brand safety scores for a domain
Auth: x-api-key header
GET
/api/sites/:domain/articles
Get analyzed articles for a domain with pagination
Auth: x-api-key header
POST
/api/site-scan/request
Request a full site scan (sitemap crawl + article analysis)
Auth: x-api-key header
GET
/api/analyze/history
Get analysis history with pagination
Auth: x-api-key header

Site-Level Qualitative Scores

ContextGrade calculates site-level scores using deterministic algorithms without requiring AI inference for most metrics. This enables fast, cost-effective site analysis at scale.

Site Trust Score (0-100)

A NewsGuard-style composite score calculated from weighted components:

  • Brand Safety25 pts
  • Content Quality20 pts
  • Credibility15 pts
  • MFA Risk (inverted)15 pts
  • Transparency10 pts
  • User Experience10 pts
  • Link Profile5 pts
MFA Detection Score

Made For Advertising detection using heuristic signals:

  • Ad-to-content ratio analysis
  • Above-fold ad density
  • Clickbait headline patterns
  • Slideshow/pagination abuse
  • Low content-to-wrapper ratio
Chrome UX Report (CrUX)

Real-world performance data from Chrome users:

  • LCP (Largest Contentful Paint)
  • INP (Interaction to Next Paint)
  • CLS (Cumulative Layout Shift)
  • FCP (First Contentful Paint)
  • TTFB (Time to First Byte)
Advertising Tech Detection

Header bidding and ad tech stack analysis:

  • Prebid.js version & modules
  • Header bidding wrappers
  • Ad unit identifiers
  • TCF consent management
  • Ad server detection
Technology Stack

Framework and infrastructure detection:

  • Framework (Next.js, React, Vue)
  • CMS (WordPress, Drupal)
  • CDN provider
  • Analytics platforms
  • Tag managers
Compliance Signals

Transparency and compliance indicators:

  • Ads.txt presence & validity
  • Privacy policy detection
  • Sitemap existence
  • Inbound link quality
  • Risk/quality signal breakdown

Example Response

Response
200 OK
{
  "url": "https://example.com/article",
  "domain": "example.com",
  "requested_fields": ["article", "brand_safety_article"],
  "cached": false,
  "analyzed_at": "2024-01-15T10:30:00Z",
  "article": {
    "demographics": {
      "age_group": "25-44",
      "gender_split": { "male": 0.55, "female": 0.45 },
      "income_bracket": "middle-upper"
    },
    "keywords": {
      "context": "technology",
      "primary_topics": ["AI", "machine learning", "startups"]
    },
    "emotions": { "valence": 0.6, "optimism": 0.7, "trust": 0.8 },
    "credibility_score": 0.85,
    "entities": { "companies": ["OpenAI", "Google"] }
  },
  "brand_safety_article": {
    "overall_score": 0.92,
    "advertiser_friendliness": "high",
    "risk_heatmap": {
      "violence": "safe",
      "political": "mild",
      "misinformation": "safe"
    }
  }
}