{"openapi":"3.1.0","info":{"title":"DomainRating.org API","version":"1.1.0","description":"Open Authority Rating (OAR) data from the public Common Crawl web graph. The base score endpoint is free and unauthenticated. Enrichment data and top lists require an API key on the paid tier (keys are created on your account page; the paid flag is enabled manually — see /docs/api). Facts we cannot prove are null or explicitly 'unavailable', never estimated."},"servers":[{"url":"https://domainrating.org"}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key from your account page, e.g. 'Authorization: Bearer drk_…'"}},"schemas":{"Domain":{"type":"object","properties":{"domain":{"type":"string"},"oar":{"type":["integer","null"],"minimum":0,"maximum":100},"dataSufficient":{"type":"boolean"},"hcRank":{"type":["integer","null"]},"prRank":{"type":["integer","null"]},"crawlRelease":{"type":"string"},"lastComputedAt":{"type":"string","format":"date-time"},"verified":{"type":"boolean"}}},"EnrichmentSource":{"type":"object","description":"One enrichment source's result. data is null unless status is 'ok'.","properties":{"status":{"type":"string","enum":["ok","unavailable","error","opted-out"]},"source":{"type":"string"},"fetchedAt":{"type":"string","format":"date-time"},"reason":{"type":["string","null"]},"data":{"type":["object","null"]}}},"Enrichment":{"type":["object","null"],"description":"Null when the domain has not been enriched yet (enrichment is gathered lazily after a page view, refreshed ~monthly).","properties":{"refreshedAt":{"type":"string","format":"date-time"},"rdap":{"$ref":"#/components/schemas/EnrichmentSource"},"dns":{"$ref":"#/components/schemas/EnrichmentSource"},"asn":{"$ref":"#/components/schemas/EnrichmentSource"},"tls":{"$ref":"#/components/schemas/EnrichmentSource"},"http":{"$ref":"#/components/schemas/EnrichmentSource"}}},"ToplistRow":{"type":"object","properties":{"domain":{"type":"string"},"oar":{"type":"integer"},"hcRank":{"type":"integer"},"prRank":{"type":"integer"}}},"Error":{"type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/api/v1/domains/{domain}":{"get":{"summary":"A domain's Open Authority Rating","description":"Free and unauthenticated. Add ?include=history with any API key to embed the latest scored crawl releases (3 on the free tier, 12 on paid), and ?include=enrichment with a paid-tier key to embed registration/DNS/hosting/TLS/homepage facts; combine them as ?include=enrichment,history. Anonymous requests are rate limited per IP (120/hour on cache misses); keyed requests per key (1000/hour free, 10000/hour paid).","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"},"example":"wikipedia.org"},{"name":"include","in":"query","schema":{"type":"string","examples":["history","enrichment","enrichment,history"]},"description":"Comma-separated: history (any API key), enrichment (paid-tier key)."}],"responses":{"200":{"description":"The domain's current rating (plus enrichment and history when requested).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Domain"},{"type":"object","properties":{"enrichment":{"$ref":"#/components/schemas/Enrichment"},"history":{"type":"array","description":"Oldest first, ending with the latest release: up to 3 points on the free tier, 12 on paid.","items":{"type":"object","required":["crawlRelease","oar","computedAt"],"properties":{"crawlRelease":{"type":"string"},"oar":{"type":["integer","null"],"description":"Null when the domain had too little link data in that release."},"computedAt":{"type":"string","format":"date-time"}}}},"historyComplete":{"type":"boolean","description":"False when older releases exist beyond the tier's limit."}}}]}}}},"308":{"description":"Redirect to the canonical (normalized) domain URL."},"401":{"description":"Missing or invalid API key (only with ?include=history or ?include=enrichment).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is on the free tier; enrichment requires paid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown or invalid domain (this endpoint never triggers scoring).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited."}}}},"/api/v1/top":{"get":{"summary":"Top domains by OAR (prebuilt per crawl release)","description":"Paid tier only. Rows are ordered by harmonic-centrality rank, OAR's primary input. Lists are prebuilt when a release is ingested; 503 means this installation hasn't built them yet.","security":[{"apiKey":[]}],"parameters":[{"name":"list","in":"query","schema":{"type":"string"},"description":"\"global\" (default) or \"tld:<suffix>\", e.g. tld:com, tld:co.uk."},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1},"description":"Prebuilt page of 100 rows."}],"responses":{"200":{"description":"One page of the list.","content":{"application/json":{"schema":{"type":"object","properties":{"releaseId":{"type":"string"},"totalDomains":{"type":"integer"},"list":{"type":"string"},"page":{"type":"integer"},"pageCount":{"type":"integer"},"rows":{"type":"array","items":{"$ref":"#/components/schemas/ToplistRow"}}}}}}},"400":{"description":"Invalid list or page parameter."},"401":{"description":"Missing or invalid API key."},"403":{"description":"Key is on the free tier."},"404":{"description":"Page beyond the list's prebuilt depth, or unknown TLD list."},"429":{"description":"Rate limited."},"503":{"description":"Top lists not built yet for any ingested release."}}}}}}