Is It Blocked?

Developer platform · API v1

From first request to useful evidence.

Public, read-only endpoints; bounded cache behavior; explicit errors; and a machine-readable contract. No API key is required for the current public tier.

OpenAPI JSON Service status

60-second quickstart

Run one request.

Use the v1 path in production integrations. Responses are JSON and dates are ISO 8601 UTC.

curl
curl --get "https://isitblocked.com/api/v1/domain" \
  --data-urlencode "domain=example.com" \
  --data-urlencode "days=30"
JavaScript
const url = new URL("https://isitblocked.com/api/v1/domain");
url.search = new URLSearchParams({ domain: "example.com", days: "30" });

const response = await fetch(url, { headers: { Accept: "application/json" } });
if (response.status === 429) {
  throw new Error(`Retry after ${response.headers.get("Retry-After")} seconds`);
}
if (!response.ok) throw new Error(`HTTP ${response.status}`);

const report = await response.json();
console.log(report.verdict, report.countries);

Surface area

Small, composable endpoints.

The overview, country, incident, and feed surfaces read published cache state. Domain detail is the deliberate drill-down path.

MethodPathUse
GET/api/v1/overviewOne KV-only snapshot for headlines, map, and rankings. Never starts a scan.
GET/api/v1/domain?domain=&days=A 7, 30, or 90 day domain report. A cache miss may query bounded upstream evidence.
GET/api/v1/countries/:ccCached detail for one ISO 3166-1 alpha-2 country code.
GET/api/v1/incidentsCached incident collection with stable IDs and evidence context.
GET/feeds/incidents.jsonJSON Feed; optional domain, country, and severity filters.
GET/feeds/incidents.atomAtom feed with the same optional filters.
GET/api/v1/healthMachine-readable API and scanner health.
GET/api/v1/openapi.jsonThe canonical OpenAPI 3 contract.

Response model

Evidence before certainty.

Arrays may be empty. A missing row means insufficient cached coverage, not clear access. Provider brands and source provenance stay available in evidence details and the source ledger.

Illustrative domain response
{
  "apiVersion": "v1",
  "domain": "example.com",
  "verdict": "detected",
  "cachedAt": "2026-07-14T22:00:00.000Z",
  "since": "2026-06-14",
  "until": "2026-07-14",
  "totalMeasurements": 24,
  "totalCountries": 1,
  "blockedCountries": 1,
  "countries": [
    {
      "probeCc": "CN",
      "measurements": 24,
      "blockedScore": 0.92,
      "blockedOutcome": "dns",
      "likelyBlockedProtocols": [
        { "protocol": "dns", "score": 0.92 }
      ]
    }
  ],
  "sourceSummary": {
    "available": 1,
    "blocked": 1,
    "restricted": 0,
    "accessible": 0,
    "unavailable": 0,
    "unknown": 0,
    "influentialAvailable": 1,
    "influentialBlocked": 1,
    "influentialRestricted": 0,
    "influentialAccessible": 0,
    "agreement": "single-source"
  },
  "sourceSignals": [
    {
      "id": "ooni-global",
      "name": "OONI measurements",
      "status": "blocked",
      "type": "measurement",
      "evidenceRole": "primary",
      "influencesVerdict": true,
      "evidenceCount": 24,
      "detail": "Measured access outcomes for this domain and window.",
      "url": "https://explorer.ooni.org/",
      "provenance": ["OONI data"],
      "methods": ["web_connectivity"]
    }
  ],
  "meta": {
    "provenanceRequired": true,
    "requestedAt": "2026-07-14T22:00:01.000Z",
    "termsUrl": "https://github.com/ooni/license/blob/master/data/LICENSE.md"
  }
}
verdict

detected, clear, or insufficient. Never infer clear from upstream failure.

countries[]

probeCc, measurement count, blockedScore, outcome, and protocol objects shaped as { protocol, score }.

sourceSummary

Availability and verdict-influence counts plus the cross-source agreement classification.

sourceSignals[]

Status, evidence role, methods, URLs, and provenance for each evidence lane.

cachedAt

When the domain evidence was cached, in ISO 8601 UTC. This is not the request time.

meta

Request time, provenance requirement, and the applicable upstream data terms URL.

Operational contract

Cache and rate behavior are part of the API.

Snapshot reads

/overview, country detail, incidents, and feeds are cache-only. Reading them never starts scanner fan-out.

Domain detail

Common results can come from KV or the edge. A normal cache miss may perform bounded source requests; explicit live/detail modes have stricter limits.

Freshness

Use generatedAt, scan status, and response Cache-Control. Do not substitute request time for evidence time.

Public limits

Rate limits protect shared evidence services. Honor 429 and Retry-After; add jitter before retrying.

Failure model

Errors stay machine-readable.

400invalid_domainFix the input; do not retry unchanged.
404not_foundThe endpoint or cached entity does not exist.
429rate_limitedWait for the Retry-After interval.
502upstream_failureNo verdict was inferred from unavailable evidence.
Download OpenAPI Open JSON Feed Open Atom Feed