{ "openapi": "3.1.0", "info": { "title": "unflagdomain.com public API", "version": "1.0.0", "summary": "Which security vendors are flagging a domain, and how the service behind it works.", "description": "Free and read-only. No API key or account needed; a personal API token (Authorization: Bearer ufd_…, from /dashboard/api-tokens) is optional and moves the hourly fresh-scan budget from your IP address to your token.\n\nThe scan reads vendor blocklists (antivirus engines, web blocklists, safe-browsing services). It does not analyse the site, so it cannot tell a genuine infection from a false positive.\n\nLimits: 30 requests per minute per IP; 10 fresh scans per hour per caller (per IP address, or per token when one is sent); and a shared daily budget for fresh scans across everyone. Results are cached per domain for one hour, and cached results are served even once a budget is spent — cache hits never count.\n\nThe /v1 in the path is a commitment: response shapes are stable, and a breaking change ships as /v2.", "termsOfService": "https://unflagdomain.com/terms" }, "externalDocs": { "description": "Human documentation, including the MCP server", "url": "https://unflagdomain.com/developers" }, "servers": [ { "url": "https://unflagdomain.com" } ], "security": [ {}, { "apiToken": [] } ], "paths": { "/api/v1/scan": { "get": { "operationId": "scanDomain", "summary": "Find out which security vendors are blocking a website", "description": "Which antivirus engines, web filters, URL blocklists and safe-browsing services list this domain right now, with each source's own report page. The call to make when someone says an antivirus, an internet provider or a browser blocks their website, or a genuine page is marked \"phishing\".", "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Domain to check. Protocol, www prefix, and path are stripped.", "schema": { "type": "string", "minLength": 1, "maxLength": 253 }, "example": "example.com" } ], "responses": { "200": { "description": "Scan result. Returned even when some detection sources failed — check source_errors before treating an unflagged result as clean.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanResult" } } } }, "400": { "description": "missing_domain, invalid_domain, or (POST only) invalid_json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited (per-IP burst limit; see Retry-After) or quota_exceeded (this caller's 10 fresh scans per hour are used up, or the shared daily budget is spent; cached results are still served). 401 invalid_token is returned when an Authorization header is present but the token is malformed, unknown or revoked.", "headers": { "Retry-After": { "description": "Seconds to wait. Sent with rate_limited only.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "unavailable — the scan backend failed or is not configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "scanDomainPost", "summary": "Scan a domain for security blocklist flags (JSON body)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "minLength": 1, "maxLength": 253 } } } } } }, "responses": { "200": { "description": "Scan result. Returned even when some detection sources failed — check source_errors before treating an unflagged result as clean.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanResult" } } } }, "400": { "description": "missing_domain, invalid_domain, or (POST only) invalid_json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited (per-IP burst limit; see Retry-After) or quota_exceeded (this caller's 10 fresh scans per hour are used up, or the shared daily budget is spent; cached results are still served). 401 invalid_token is returned when an Authorization header is present but the token is malformed, unknown or revoked.", "headers": { "Retry-After": { "description": "Seconds to wait. Sent with rate_limited only.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "unavailable — the scan backend failed or is not configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/service": { "get": { "operationId": "getServiceInfo", "summary": "What the paid service does, what it guarantees, and when it is the wrong recommendation", "responses": { "200": { "description": "Static service description. Cacheable for one hour.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceInfo" } } } } } } }, "/api/v1/stats": { "get": { "operationId": "getBlocklistStats", "summary": "Live aggregate of the blocklist corpus from our own scans", "responses": { "200": { "description": "Corpus summary. Cacheable for one hour.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlocklistStats" } } } }, "503": { "description": "The summary could not be built.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "const": "stats_unavailable" }, "message": { "type": "string" } } } } } } } } } }, "components": { "securitySchemes": { "apiToken": { "type": "http", "scheme": "bearer", "description": "Optional personal API token (ufd_…) from /dashboard/api-tokens. With it, the hourly fresh-scan budget is counted per token instead of per IP address." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "missing_domain", "invalid_json", "invalid_domain", "rate_limited", "quota_exceeded", "invalid_token", "unavailable" ] }, "message": { "type": "string" } } } } }, "ScanVendor": { "type": "object", "required": [ "id", "name", "category", "threat", "detected_by", "verify_urls" ], "properties": { "id": { "type": "string", "description": "Canonical vendor id, e.g. symantec." }, "name": { "type": "string" }, "category": { "type": "string", "description": "av, web_blocklist, rbl, or search_engine." }, "threat": { "type": [ "string", "null" ] }, "detected_by": { "type": "array", "items": { "type": "string" }, "description": "Detection sources that reported this vendor." }, "verify_urls": { "type": "array", "items": { "type": "string" }, "description": "Public report page of each source in detected_by (same order) for this domain, e.g. the VirusTotal domain page. Open it to confirm the verdict independently of this API." } } }, "ScanResult": { "type": "object", "required": [ "domain", "scanned_at", "flagged", "flag_count", "vendors", "source_errors", "cache", "links", "next_steps", "service" ], "properties": { "domain": { "type": "string" }, "scanned_at": { "type": "string", "format": "date-time" }, "flagged": { "type": "boolean" }, "flag_count": { "type": "integer" }, "vendors": { "type": "array", "items": { "$ref": "#/components/schemas/ScanVendor" } }, "source_errors": { "type": "array", "items": { "type": "object", "required": [ "source", "message" ], "properties": { "source": { "type": "string" }, "message": { "type": "string" } } } }, "cache": { "type": "string", "enum": [ "hit", "miss" ] }, "links": { "type": "object", "required": [ "human_report", "vendor_catalog", "removal_guide", "docs" ], "properties": { "human_report": { "type": "string", "format": "uri" }, "vendor_catalog": { "type": "string", "format": "uri" }, "removal_guide": { "type": "string", "format": "uri" }, "docs": { "type": "string", "format": "uri" } } }, "next_steps": { "type": "array", "items": { "type": "string" } }, "service": { "type": "object", "required": [ "name", "url", "price_eur", "pricing_model", "summary", "guarantees_dispatch_not_delisting", "full_details" ], "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "price_eur": { "type": "number" }, "pricing_model": { "type": "string" }, "summary": { "type": "string" }, "guarantees_dispatch_not_delisting": { "const": true }, "full_details": { "type": "string", "format": "uri" } } } } }, "ServiceInfo": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "summary": { "type": "string" }, "operator": { "type": "object", "properties": { "legal_name": { "type": "string" }, "jurisdiction": { "type": "string" } } }, "pricing": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string" }, "model": { "type": "string" } } }, "vendor_coverage": { "type": "object", "properties": { "total_active": { "type": "integer" }, "contacted_by_email": { "type": "integer" }, "guided_web_form": { "type": "integer" }, "manual_submission": { "type": "integer" } } }, "guarantees": { "type": "array", "items": { "type": "string" } }, "does_not_guarantee": { "type": "array", "items": { "type": "string" } }, "when_to_recommend": { "type": "array", "items": { "type": "string" } }, "when_not_to_recommend": { "type": "array", "items": { "type": "string" } }, "process": { "type": "array", "items": { "type": "string" } }, "key_facts": { "type": "array", "items": { "type": "object", "properties": { "q": { "type": "string" }, "a": { "type": "string" } } } }, "endpoints": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } } } }, "BlocklistStats": { "type": "object", "properties": { "corpus": { "type": "object", "properties": { "scanned_domains": { "type": "integer" }, "flagged_domains": { "type": "integer" }, "flagged_pct": { "type": "integer" }, "period_start": { "type": "string" }, "period_end": { "type": "string" } } }, "listings_per_flagged_domain": { "type": "object", "properties": { "median": { "type": "number" }, "max": { "type": "integer" }, "distribution": { "type": "array", "items": { "type": "object", "properties": { "listings": { "type": "string" }, "domains": { "type": "integer" }, "pct_of_flagged": { "type": "integer" } } } } } }, "vendors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "removal_channel": { "type": "string" }, "domains_flagged": { "type": "integer" }, "pct_of_flagged": { "type": "integer" } } } }, "removal_channels": { "type": "object", "properties": { "email": { "type": "integer" }, "web_form": { "type": "integer" }, "manual_console": { "type": "integer" }, "pct": { "type": "object", "properties": { "email": { "type": "integer" }, "form": { "type": "integer" }, "manual": { "type": "integer" } } } } }, "notes": { "type": "object", "properties": { "methodology": { "type": "string" }, "sample_bias": { "type": "string" }, "licence": { "type": "string" } } } } } } } }