v1.6.0CC BY 4.0

Voidly Atlas API

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

25.3M+

Measurements

127

Countries

99.8% (internal eval)

Classifier F1

317

Incidents

Data fromOONIIODACensoredPlanetVoidly Probes (37)ML (99.8% F1, internal eval)·33,668 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

Developer Tools

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 continuously.

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

Check which VPN endpoints are blocked in each country. Voidly tests VPN reachability from 37+ global probe nodes — a unique dataset combining active probing with censorship intelligence.

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 research APIs packaging our censorship measurement data for researchers, journalists, circumvention developers, and civil society.

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.

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 circumvention tools, researchers, and civil society.

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 research and civil society 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, internal eval, retrained weekly) + historical election-incident correlation from 317 multi-source incidents.Explore live →

Incidents

317 confirmed censorship incidents with human-readable IDs (e.g., IR-2026-0142) for citation.

List Incidents

GET/data/incidentsList incidents (paginated)

GET/data/incidents/statsIncident counts and source breakdown

GET/data/incidents/export?format=csvBulk export (csv, jsonl, json)

GET/data/incidents/delta?since=:timestampDelta feed for incremental sync

GET/data/incidents/feed.rssRSS feed (also .atom)

bash

# List incidents for Iran, limit 10
"text-green-400">curl "https://api.voidly.ai/data/incidents?country=IR&limit=10"

Incident Detail

Lookup by human-readable ID (IR-2026-0142) or hash ID. Both formats work interchangeably.

GET/data/incidents/:id

bash

"text-green-400">curl "https://api.voidly.ai/data/incidents/IR-2026-0142"

Evidence Permalinks

Get verifiable evidence sources (OONI, IODA, CensoredPlanet measurements) for an incident.

GET/data/incidents/:id/evidence

bash

"text-green-400">curl "https://api.voidly.ai/data/incidents/IR-2026-0142/evidence"

Reports & Citation Export

Generate citable reports in multiple formats for academics and journalists.

GET/data/incidents/:id/report?format=markdownCitable markdown report

GET/data/incidents/:id/report?format=bibtexBibTeX citation

GET/data/incidents/:id/report?format=risRIS citation (Zotero, Mendeley)

bash

# BibTeX citation for academic papers
"text-green-400">curl "https://api.voidly.ai/data/incidents/IR-2026-0142/report?format=bibtex"

Community Probes

Run your own censorship probe node and contribute to the global measurement network. Install via pip install voidly-probe or Docker.

Register & Submit

POST/v1/community/registerRegister a new probe node (returns auth token)

POST/v1/community/validate-tokenValidate a node token

GET/v1/community/nodes/:nodeIdGet node details

Easiest way to start: The probe client handles registration automatically.

bash

pip install voidly-probe
voidly-probe "text-purple-400">--consent
# Alternative: python -m voidly_probe "text-purple-400">--consent

PyPI Docker Hub Learn more

Network & Leaderboard

GET/v1/community/leaderboardTop contributors by probe count

GET/v1/community/nodesAll active community nodes

bash

"text-green-400">curl "https://api.voidly.ai/v1/community/leaderboard"

Alerts & Webhooks

Subscribe to real-time censorship incident notifications. Webhooks are signed with HMAC-SHA256 and retried with exponential backoff.

POST/api/alerts/subscribeCreate a webhook subscription

GET/api/alerts/statsPublic alert system stats

bash

"text-green-400">curl "text-purple-400">-X POST "https://api.voidly.ai/api/alerts/subscribe" \
  "text-purple-400">-H "Content">-Type: application/json" \
  "text-purple-400">-H "X">-API">-Key: YOUR_KEY" \
  -d '{"country_code":"IR","min_severity":"high","webhook_url":"https://your-server.com/webhook"}'

Webhook Payload

json

{
  "event": "incident.created",
  "timestamp": "2026-02-10T12:00:00Z",
  "incident": {
    "id": "abc123",
    "hashId": "IR-2026-0142",
    "country": "IR",
    "title": "DNS blocking of twitter.com",
    "severity": "high",
    "confidence": 0.95
  }
}

Signed with X-Voidly-Signature: sha256=... (HMAC-SHA256). Retry: 2, 4, 8, 16, 32 min.

Manage Subscriptions

GET/api/alerts/subscriptionsList your subscriptions

DELETE/api/alerts/subscriptions/:idDelete a subscription

PATCH/api/alerts/subscriptions/:idToggle on/off

POST/api/alerts/webhook-testSend a test webhook

bash

# Toggle a subscription off
"text-green-400">curl "text-purple-400">-X PATCH "https://api.voidly.ai/api/alerts/subscriptions/sub_123" \
  "text-purple-400">-H "X">-API">-Key: YOUR_KEY" \
  -d '{"enabled": false}'

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

Developer Tools

Integrations for AI assistants, research tools, and developer workflows. Query censorship data from Claude, Cursor, or ChatGPT.

RecommendedMCP Server — 83 Tools

For Claude Desktop, Cursor, Windsurf, and Cline. 27 censorship intelligence tools + 56 agent relay tools with native MCP integration.

bash

npx @voidly/mcp-server

npm →GitHub →Explore All Tools →

NewPython SDK — LangChain & CrewAI

For Python AI agents. Async/sync messaging, encrypted channels, memory, tasks, discovery, trust scoring. Includes LangChain toolkit (9 tools) and CrewAI toolkit (7 tools).

bash

pip install voidly-agents[all]

PyPI →GitHub →Agent Relay →

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.6.02026-02-19

NEW: Community Voidly Network — anyone can run a censorship probe (pip install voidly-probe)
NEW: Published voidly-probe v1.0.1 to PyPI and Docker Hub
NEW: Community endpoints: /v1/community/register, /leaderboard, /nodes
Documented incident evidence and citation export endpoints
Documented alert subscription and webhook management endpoints

v1.5.02026-02-18

NEW: Platform Risk Scores — per-platform censorship risk across 127 countries
NEW: ISP Risk Index — composite ISP censorship scoring (aggressiveness, breadth, methods)
NEW: Service Accessibility API — real-time domain accessibility oracle
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.3.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 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, internal eval)
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