v1.5.0CC BY 4.0

Censorship Data API

Real-time global censorship detection powered by 14.2M+ multi-source measurements (OONI, IODA, CensoredPlanet) across 50 countries. 99.8% classifier F1. Free for research.

14.2M+

Measurements

Countries

99.8%

Classifier F1

5,299

Incidents

Data fromOONIIODACensoredPlanetProbes (16)ML (99.8% F1)·15,468 evidence items

View Endpoints Try Playground Open Data

Quickstart

Check if Google is blocked in China with a single request. No signup required.

bash

"text-green-400">curl "text-purple-400">-X POST https://api.voidly.ai/hydra/v1/detect \
  "text-purple-400">-H "Content">-Type: application/json" \
  "text-purple-400">-H "X">-API">-Key: hydra_demo_key" \
  -d '{"country":"CN","target":"google.com"}'

Response

json

{
  "country": "CN",
  "target": "google.com",
  "blocked": true,
  "confidence": 0.95,
  "blockType": "dpi_block",
  "lastChecked": "2026-02-06T12:00:00Z",
  "sources": ["ooni", "ioda", "censoredplanet"]
}

Authentication

Pass your API key in the X-API-Key header. Public data endpoints require no authentication.

Demo API KeyNo Signup

Use this key for testing. Rate limited to 100 requests/minute.

Request Headers

Header	Value	Required
`X-API-Key`	Your API key	For /hydra/* endpoints
`Content-Type`	application/json	For POST requests

Integrations

AI Systems

MCP server for Claude, Cursor, Windsurf. OpenAI Action for ChatGPT.

Real-time Feeds

RSS/Atom feeds, delta sync, bulk export (CSV, JSONL).

Citations

BibTeX and RIS export for academic papers. Citable incident IDs.

Webhooks

Real-time incident alerts with HMAC-SHA256 signed payloads.

Endpoints

POST/hydra/v1/detect

Check if a domain is actively blocked in a country. Returns block status, confidence, and detection method.

Try It

Country

Target

Request Body

Field	Type	Description
`country`	string	ISO 3166-1 alpha-2 code (e.g., "CN", "IR")
`target`	string	Domain to check (e.g., "google.com")
`includeISPs`	boolean	Include per-ISP breakdown (optional)

Response Schema

Field	Type	Description
`blocked`	boolean	Whether target is blocked
`confidence`	number	ML model confidence (0-1)
`blockType`	string	"dpi_block" \| "dns_block" \| "ip_block" \| "none"
`sources`	string[]	Data sources used: "ooni", "ioda", "censoredplanet", "probe", "ml"
`lastChecked`	string	ISO 8601 timestamp

POST/hydra/v1/predict

Predict future censorship risk for a country using the ML model. Returns trend and contributing factors.

Request Body

Field	Type	Description
`country`	string	ISO 3166-1 alpha-2 code
`target`	string?	Optional domain to predict risk for
`horizon`	number	Prediction horizon in days (default: 7)

bash

"text-green-400">curl "text-purple-400">-X POST https://api.voidly.ai/hydra/v1/predict \
  "text-purple-400">-H "Content">-Type: application/json" \
  "text-purple-400">-H "X">-API">-Key: hydra_demo_key" \
  -d '{"country":"RU","horizon":30}'

GET/v1/forecast/:country/7dayNEW

Get a 7-day predictive risk forecast for a country. Uses machine learning trained on historical censorship patterns, election calendars, and political events to predict shutdown risk.

Response Fields

Field	Type	Description
`forecast`	array	8 days of predictions (day 0-7)
`forecast[].risk`	number	Risk score 0-1 (0.5+ is elevated)
`forecast[].drivers`	string[]	Risk factors (election, protest, etc.)
`summary.max_risk`	number	Peak risk in the 7-day window
`confidence`	number	Model confidence (0-1)

bash

# Get 7-day forecast for Iran
"text-green-400">curl "https://api.voidly.ai/v1/forecast/IR/7day"

# Get all high-risk countries (threshold 0.3)
"text-green-400">curl "https://api.voidly.ai/v1/forecast/high-risk?threshold=0.3"

# Batch forecast for multiple countries
"text-green-400">curl "text-purple-400">-X POST "https://api.voidly.ai/v1/forecast/batch" \
  "text-purple-400">-H "Content">-Type: application/json" \
  -d '{"countries":["IR","CN","RU"]}'

Example Response

json

{
  "country": "IR",
  "country_name": "Iran",
  "forecast": [
    {"day": 0, "date": "2026-02-10", "risk": 0.26, "drivers": []},
    {"day": 1, "date": "2026-02-11", "risk": 0.28, "drivers": []},
    {"day": 7, "date": "2026-02-17", "risk": 0.35, "drivers": ["election"]}
  ],
  "summary": {
    "max_risk": 0.35,
    "max_risk_day": 7,
    "avg_risk": 0.27,
    "key_drivers": ["election"]
  },
  "confidence": 0.85,
  "model_version": "v1"
}

GET/hydra/v1/threat-level/:country

Get the current threat level for a country with recommendations and optional 30-day history.

bash

"text-green-400">curl "text-purple-400">-H "X">-API">-Key: hydra_demo_key" \
  "https://api.voidly.ai/hydra/v1/threat-level/IR?includeHistory=true"

GET/hydra/v1/scores

Get censorship scores for all tracked countries, sorted by severity.

Query Parameters

Param	Type	Description
`minConfidence`	number	Minimum confidence threshold (0-1, default: 0.5)
`limit`	number	Max results (default: 50)

GET/hydra/v1/model/info

Get ML model metadata including version, accuracy metrics, and training details.

bash

"text-green-400">curl "text-purple-400">-H "X">-API">-Key: hydra_demo_key" "https://api.voidly.ai/hydra/v1/model/info"

Public Data

Open datasets available without authentication. Licensed under CC BY 4.0.

GET/data/censorship-index.jsonNo Auth

Full censorship index dataset with Schema.org structured data. Updated daily.

JSON CSV

GET/data/country/:codeNo Auth

Detailed censorship data for a single country.

bash

"text-green-400">curl "https://api.voidly.ai/data/country/CN"

GET/v1/vpn-accessibilityNo AuthUnique Data

Exclusive: Check which VPN endpoints are blocked in each country. Only Voidly can provide this data by testing VPN reachability from 16 global probe nodes.

Query Parameters

Param	Type	Description
`country`	string	Filter by probe node country (where test runs FROM)
`provider`	string	VPN provider: voidly, nordvpn, protonvpn, mullvad

bash

"text-green-400">curl "https://api.voidly.ai/v1/vpn-accessibility?country=IR"

Why this matters: Journalists and researchers often ask "Can users in Iran connect to VPNs?" This endpoint answers that question with real probe data from our global infrastructure.

GET/data/methodologyNo Auth

Machine-readable methodology including scoring algorithm and data sources.

Risk Intelligence

Four new API product lines packaging our censorship measurement data for governments, journalists, cyber risk firms, and platforms.

Platform Risk Scores

Per-platform censorship risk across all monitored countries. How blocked is WhatsApp globally?

GET/v1/platforms/scoresAll platforms ranked by global risk

GET/v1/platform/:platform/riskGlobal risk profile for a platform

GET/v1/platform/:platform/risk/:countryPlatform risk in specific country

GET/v1/platforms/country/:countryAll platforms ranked for a country

bash

"text-green-400">curl https://api.voidly.ai/v1/platforms/scores

Platforms tracked: Twitter/X, WhatsApp, Telegram, YouTube, Signal, Facebook, Instagram, TikTok, Wikipedia, Tor, Reddit, Medium.Explore live →

ISP Risk Index

Composite ISP censorship scores measuring aggressiveness, category breadth, and blocking methods. The first index of its kind.

GET/v1/isp/index?country=:CCISPs ranked by censorship score

GET/v1/isp/:asn/profileDetailed ISP profile

GET/v1/isp/worst?limit=20Global worst ISPs

GET/v1/isp/compare?asns=:asn1,:asn2Side-by-side ISP comparison

bash

"text-green-400">curl "https://api.voidly.ai/v1/isp/index?country=IR"

Composite score (0-100) based on block rate, method aggressiveness, and category breadth.Explore live →

Service Accessibility API

Real-time "Can users in country X access service Y?" oracle. Designed for OEMs, app stores, and platforms.

GET/v1/accessibility/check?domain=:d&country=:CCQuick accessibility check

POST/v1/accessibility/batchBatch check (up to 50 domains)

GET/v1/accessibility/service/:nameCheck by service name

GET/v1/accessibility/country/:CC/summaryCountry-wide summary

bash

"text-green-400">curl "https://api.voidly.ai/v1/accessibility/check?domain=twitter.com&country=IR"

200 req/min rate limit (higher on request for OEM integrations).Try it live →

Election Risk Briefings

Election-aware censorship risk combining our 7-day forecast with historical election-censorship correlation.

GET/v1/elections/upcoming?days=90Upcoming elections with risk overlay

GET/v1/elections/:country/briefingFull election risk briefing

GET/v1/elections/calendarAll elections calendar

bash

"text-green-400">curl "https://api.voidly.ai/v1/elections/IR/briefing"

Uses XGBoost forecast (74.6% ROC AUC, retrained weekly) + historical election-incident correlation from 5,299 multi-source incidents.Explore live →

Errors

The API uses standard HTTP status codes. All errors return JSON with error and message fields.

Code	Name	Resolution
`400`	Bad Request	Invalid request parameters. Check country codes (ISO 3166-1 alpha-2) and required fields.
`401`	Unauthorized	Invalid or missing API key. Include X-API-Key header.
`404`	Not Found	Country or resource not found. Check the country code exists in our dataset.
`429`	Rate Limited	Too many requests. Wait 60 seconds and retry with exponential backoff.
`500`	Server Error	Internal error. Retry with backoff. If persistent, contact support.
`503`	Service Unavailable	API temporarily unavailable. Check status page.

Error Response Format

json

{
  "error": "BAD_REQUEST",
  "message": "country and target are required"
}

Rate Limits

API requests are rate limited to ensure fair usage. Limits vary by endpoint and key type.

Key Type	Rate Limit	Burst
Demo Key	100 requests/minute	20 requests
Research Key	1,000 requests/minute	100 requests
Public Data	No limit	—

Rate Limit Headers

Header	Description
`X-RateLimit-Limit`	Maximum requests per window
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when window resets

AI Integrations

Native integrations for AI assistants and LLMs. Get censorship data directly in Claude, Cursor, or ChatGPT.

RecommendedMCP Server

For Claude Desktop, Cursor, Windsurf, and Cline. Native tool access to censorship data.

bash

npx @voidly/mcp-server

npm →GitHub →

OpenAI Action

For ChatGPT custom GPTs. Import OpenAPI spec into GPT Builder.

Download openapi.json →

llms.txt

AI-optimized context file. Add to prompts for instant censorship data awareness.

View llms.txt →

Changelog

v1.5.02026-02-18

NEW: Platform Risk Scores — per-platform censorship risk across 50 countries
NEW: ISP Risk Index — composite ISP censorship scoring (aggressiveness, breadth, methods)
NEW: Service Accessibility API — real-time domain accessibility oracle for OEMs
NEW: Election Risk Briefings — election-censorship correlation + forecast overlay
MCP server v1.5.0 with 4 new tools: get_platform_risk, get_isp_risk_index, check_service_accessibility, get_election_risk

v1.4.02026-02-10

NEW: Predictive Risk Forecasting API - 7-day shutdown predictions using ML
NEW: Real-time webhook alerts for censorship incidents
NEW: RSS/Atom feeds for incident monitoring
Added BibTeX/RIS citation export for academics
Election and political event calendar integration (Wikipedia + GDELT)

v1.4.02026-02-08

NEW: VPN Accessibility API - unique data showing which VPN endpoints are blocked in each country
NEW: Block page fingerprinting - identifies blocking entity (Roskomnadzor, Iran TIC, etc.)
Added 100+ domain categories from Citizen Lab test-lists
MCP server now includes check_vpn_accessibility tool

v1.2.02026-02-04

Added /incidents endpoint with 5,299 confirmed censorship events
Incident reports now include citable permalinks
Added confidence scores to all detection responses

v1.1.02026-01-15

Upgraded ML model to v2 (99.8% F1 score)
Added ISP-level breakdown in /detect responses
New /predict endpoint for future risk assessment

v1.0.02025-12-01

Initial public release
Core endpoints: /detect, /threat-level, /scores
Public data endpoints with CC BY 4.0 license

Ready to get started?

No signup required. Use the demo key and start making requests.

Open Playground Browse Data View Source