{"openapi":"3.1.0","info":{"title":"scope.breach.io API","version":"1.2.0","description":"Turn one public company domain into a conservative, evidence-backed attack-surface inventory and an authorization-disabled scope file. The service uses public sources and bounded read-only HTTP requests; it never exploits, authenticates to, or modifies a target.","license":{"name":"Proprietary"}},"servers":[{"url":"https://scope.breach.io","description":"Production"}],"externalDocs":{"description":"Human-readable integration guide","url":"https://scope.breach.io/docs"},"tags":[{"name":"Recon","description":"Bounded read-only domain reconnaissance."}],"paths":{"/api/v1":{"get":{"operationId":"getApiIndex","summary":"Discover the API","description":"Returns the current API version and links to the recon endpoint and documentation.","security":[],"responses":{"200":{"description":"API discovery document.","headers":{"X-Api-Version":{"description":"Semantic version of the API contract.","schema":{"type":"string"}},"X-Request-Id":{"description":"Unique identifier for this request.","schema":{"type":"string","format":"uuid"}},"X-Scope-Cache":{"description":"Whether a successful result was reused.","schema":{"type":"string","enum":["HIT","MISS"]}},"RateLimit-Limit":{"description":"Per-client requests permitted in the rate-limit window.","schema":{"type":"integer"}},"RateLimit-Policy":{"description":"Rate-limit policy in limit/window form.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiIndexResponse"}}}}}}},"/api/v1/openapi.json":{"get":{"operationId":"getOpenApiDocument","summary":"Download the OpenAPI document","security":[],"responses":{"200":{"description":"OpenAPI 3.1 document.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/recon":{"post":{"operationId":"runRecon","tags":["Recon"],"summary":"Search the public attack surface for a domain","description":"Accepts a bare domain or public HTTP(S) URL. Results are cached for 15 minutes. Returned scope files always have `authorized: false`; written authorization remains the caller's responsibility.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReconRequest"},"examples":{"domain":{"value":{"url":"example.com"}},"url":{"value":{"url":"https://www.example.com/about"}}}}}},"responses":{"200":{"description":"Recon completed or a cached result was reused.","headers":{"X-Api-Version":{"description":"Semantic version of the API contract.","schema":{"type":"string"}},"X-Request-Id":{"description":"Unique identifier for this request.","schema":{"type":"string","format":"uuid"}},"X-Scope-Cache":{"description":"Whether a successful result was reused.","schema":{"type":"string","enum":["HIT","MISS"]}},"RateLimit-Limit":{"description":"Per-client requests permitted in the rate-limit window.","schema":{"type":"integer"}},"RateLimit-Policy":{"description":"Rate-limit policy in limit/window form.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReconResponse"}}}},"400":{"description":"The JSON body is invalid or the target is not a public HTTP(S) domain.","headers":{"X-Api-Version":{"description":"Semantic version of the API contract.","schema":{"type":"string"}},"X-Request-Id":{"description":"Unique identifier for this request.","schema":{"type":"string","format":"uuid"}},"X-Scope-Cache":{"description":"Whether a successful result was reused.","schema":{"type":"string","enum":["HIT","MISS"]}},"RateLimit-Limit":{"description":"Per-client requests permitted in the rate-limit window.","schema":{"type":"integer"}},"RateLimit-Policy":{"description":"Rate-limit policy in limit/window form.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"The request body exceeds 4 KiB.","headers":{"X-Api-Version":{"description":"Semantic version of the API contract.","schema":{"type":"string"}},"X-Request-Id":{"description":"Unique identifier for this request.","schema":{"type":"string","format":"uuid"}},"X-Scope-Cache":{"description":"Whether a successful result was reused.","schema":{"type":"string","enum":["HIT","MISS"]}},"RateLimit-Limit":{"description":"Per-client requests permitted in the rate-limit window.","schema":{"type":"integer"}},"RateLimit-Policy":{"description":"Rate-limit policy in limit/window form.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"description":"Content-Type is not application/json.","headers":{"X-Api-Version":{"description":"Semantic version of the API contract.","schema":{"type":"string"}},"X-Request-Id":{"description":"Unique identifier for this request.","schema":{"type":"string","format":"uuid"}},"X-Scope-Cache":{"description":"Whether a successful result was reused.","schema":{"type":"string","enum":["HIT","MISS"]}},"RateLimit-Limit":{"description":"Per-client requests permitted in the rate-limit window.","schema":{"type":"integer"}},"RateLimit-Policy":{"description":"Rate-limit policy in limit/window form.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"The per-client or Cloudflare-location request limit was reached.","headers":{"X-Api-Version":{"description":"Semantic version of the API contract.","schema":{"type":"string"}},"X-Request-Id":{"description":"Unique identifier for this request.","schema":{"type":"string","format":"uuid"}},"X-Scope-Cache":{"description":"Whether a successful result was reused.","schema":{"type":"string","enum":["HIT","MISS"]}},"RateLimit-Limit":{"description":"Per-client requests permitted in the rate-limit window.","schema":{"type":"integer"}},"RateLimit-Policy":{"description":"Rate-limit policy in limit/window form.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds before retrying.","schema":{"type":"integer","example":60}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The search failed without exposing provider or internal details.","headers":{"X-Api-Version":{"description":"Semantic version of the API contract.","schema":{"type":"string"}},"X-Request-Id":{"description":"Unique identifier for this request.","schema":{"type":"string","format":"uuid"}},"X-Scope-Cache":{"description":"Whether a successful result was reused.","schema":{"type":"string","enum":["HIT","MISS"]}},"RateLimit-Limit":{"description":"Per-client requests permitted in the rate-limit window.","schema":{"type":"integer"}},"RateLimit-Policy":{"description":"Rate-limit policy in limit/window form.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"The bounded recon deadline elapsed.","headers":{"X-Api-Version":{"description":"Semantic version of the API contract.","schema":{"type":"string"}},"X-Request-Id":{"description":"Unique identifier for this request.","schema":{"type":"string","format":"uuid"}},"X-Scope-Cache":{"description":"Whether a successful result was reused.","schema":{"type":"string","enum":["HIT","MISS"]}},"RateLimit-Limit":{"description":"Per-client requests permitted in the rate-limit window.","schema":{"type":"integer"}},"RateLimit-Policy":{"description":"Rate-limit policy in limit/window form.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-rate-limit":{"client":{"limit":5,"windowSeconds":60},"cloudflareLocation":{"limit":100,"windowSeconds":60}}}}},"components":{"schemas":{"ReconRequest":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","minLength":1,"maxLength":2048,"description":"Bare public domain or public HTTP(S) URL.","examples":["example.com"]}}},"ApiIndexResponse":{"type":"object","additionalProperties":false,"required":["apiVersion","requestId","data"],"properties":{"apiVersion":{"type":"string","const":"1.2.0"},"requestId":{"type":"string","format":"uuid"},"data":{"type":"object","additionalProperties":false,"required":["name","recon","docs","openapi","authentication"],"properties":{"name":{"type":"string","const":"scope.breach.io API"},"recon":{"type":"string","const":"/api/v1/recon"},"docs":{"type":"string","const":"/docs"},"openapi":{"type":"string","const":"/api/v1/openapi.json"},"authentication":{"type":"string","const":"none"}}}}},"ReconResponse":{"type":"object","additionalProperties":false,"required":["apiVersion","requestId","data"],"properties":{"apiVersion":{"type":"string","const":"1.2.0"},"requestId":{"type":"string","format":"uuid"},"data":{"$ref":"#/components/schemas/ReconData"}}},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["apiVersion","requestId","error"],"properties":{"apiVersion":{"type":"string","const":"1.2.0"},"requestId":{"type":"string","format":"uuid"},"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_REQUEST","INVALID_TARGET","PAYLOAD_TOO_LARGE","RATE_LIMITED","RECON_TIMEOUT","UNSUPPORTED_MEDIA_TYPE","INTERNAL_ERROR"]},"message":{"type":"string"}}}}},"ReconData":{"type":"object","additionalProperties":false,"required":["apex","anchor","assets","github","gitlab","services","githubReferences","dnsRelations","relatedDomains","candidates","dangling","referenced","origins","fingerprints","scope","perSource","coverage","counts"],"properties":{"apex":{"type":"string","description":"Registrable apex domain derived with the Public Suffix List."},"anchor":{"$ref":"#/components/schemas/IdentityAnchor"},"assets":{"type":"array","items":{"$ref":"#/components/schemas/Asset"}},"github":{"type":"array","items":{"$ref":"#/components/schemas/GithubFinding"}},"gitlab":{"type":"array","items":{"$ref":"#/components/schemas/GitlabFinding"}},"services":{"type":"array","items":{"$ref":"#/components/schemas/ServiceDependency"}},"githubReferences":{"type":"array","items":{"$ref":"#/components/schemas/GithubReference"}},"dnsRelations":{"type":"array","items":{"$ref":"#/components/schemas/DnsRelation"}},"relatedDomains":{"type":"array","items":{"$ref":"#/components/schemas/RelatedDomain"}},"candidates":{"type":"array","items":{"$ref":"#/components/schemas/Asset"}},"dangling":{"type":"array","items":{"$ref":"#/components/schemas/Asset"}},"referenced":{"type":"array","items":{"$ref":"#/components/schemas/ReferencedHost"}},"origins":{"type":"array","items":{"$ref":"#/components/schemas/Origin"}},"fingerprints":{"$ref":"#/components/schemas/FingerprintReport"},"scope":{"$ref":"#/components/schemas/Scope"},"perSource":{"type":"object","additionalProperties":{"type":"integer","minimum":0}},"coverage":{"$ref":"#/components/schemas/Coverage"},"counts":{"type":"object","additionalProperties":false,"required":["CONFIRMED","THIRD_PARTY","CANDIDATE","DANGLING"],"properties":{"CONFIRMED":{"type":"integer","minimum":0},"THIRD_PARTY":{"type":"integer","minimum":0},"CANDIDATE":{"type":"integer","minimum":0},"DANGLING":{"type":"integer","minimum":0}}}}},"IdentityAnchor":{"type":"object","additionalProperties":false,"required":["apex","registrantOrg","registrantEmailDomain","certOrgs","githubOrgs"],"properties":{"apex":{"type":"string"},"registrantOrg":{"type":["string","null"]},"registrantEmailDomain":{"type":["string","null"]},"certOrgs":{"type":"array","items":{"type":"string"}},"githubOrgs":{"type":"array","items":{"type":"string"}}}},"Asset":{"type":"object","additionalProperties":false,"required":["host","source","dns","classification","reason"],"properties":{"host":{"type":"string"},"source":{"type":"array","items":{"type":"string"}},"dns":{"$ref":"#/components/schemas/DnsResolution"},"http":{"$ref":"#/components/schemas/HttpProbe"},"classification":{"type":"string","enum":["CONFIRMED","THIRD_PARTY","CANDIDATE","DANGLING"]},"reason":{"type":"string"},"takeover":{"anyOf":[{"type":"object","additionalProperties":false,"required":["vendor","fingerprint"],"properties":{"vendor":{"type":"string"},"fingerprint":{"type":"string"}}},{"type":"null"}]}}},"DnsResolution":{"type":"object","additionalProperties":false,"required":["a","aaaa","cname","resolved","nsDelegated"],"properties":{"a":{"type":"array","items":{"type":"string","format":"ipv4"}},"aaaa":{"type":"array","items":{"type":"string","format":"ipv6"}},"cname":{"type":"array","items":{"type":"string"}},"resolved":{"type":"boolean"},"nsDelegated":{"type":"boolean"}}},"HttpProbe":{"type":"object","additionalProperties":false,"required":["status","finalUrl","title","server","tech","cdn"],"properties":{"status":{"type":["integer","null"]},"finalUrl":{"type":["string","null"]},"title":{"type":["string","null"]},"server":{"type":["string","null"]},"tech":{"type":"array","items":{"type":"string"}},"cdn":{"type":["string","null"]}}},"GithubFinding":{"type":"object","additionalProperties":false,"required":["org","confirmed","confirmedBy","repos"],"properties":{"org":{"type":"string"},"confirmed":{"type":"boolean"},"confirmedBy":{"type":["string","null"]},"repos":{"type":"array","items":{"$ref":"#/components/schemas/GithubRepo"}}}},"GithubRepo":{"type":"object","additionalProperties":false,"required":["name","url","visibility","language","archived","fork","pushedAt","homepage","topics","defaultBranch"],"properties":{"name":{"type":"string"},"url":{"type":"string","format":"uri"},"visibility":{"type":"string"},"language":{"type":["string","null"]},"archived":{"type":"boolean"},"fork":{"type":"boolean"},"pushedAt":{"type":["string","null"],"format":"date-time"},"homepage":{"type":["string","null"]},"topics":{"type":"array","items":{"type":"string"}},"defaultBranch":{"type":["string","null"]}}},"GithubReference":{"type":"object","additionalProperties":false,"required":["host","org","repo","via","path","underApex","confirmedOrg"],"properties":{"host":{"type":"string"},"org":{"type":"string"},"repo":{"type":"string"},"via":{"type":"string","enum":["homepage","pages","deployment","repository-file","code-search"]},"path":{"type":["string","null"]},"underApex":{"type":"boolean"},"confirmedOrg":{"type":"boolean"}}},"GitlabFinding":{"type":"object","additionalProperties":false,"required":["group","confirmed","confirmedBy","repos"],"properties":{"group":{"type":"string"},"confirmed":{"type":"boolean","const":true},"confirmedBy":{"type":"string","enum":["site-link","security.txt"]},"repos":{"type":"array","items":{"$ref":"#/components/schemas/GitlabRepo"}}}},"GitlabRepo":{"type":"object","additionalProperties":false,"required":["name","pathWithNamespace","url","visibility","description","archived","lastActivityAt","defaultBranch"],"properties":{"name":{"type":"string"},"pathWithNamespace":{"type":"string"},"url":{"type":"string","format":"uri"},"visibility":{"type":"string"},"description":{"type":["string","null"]},"archived":{"type":"boolean"},"lastActivityAt":{"type":["string","null"],"format":"date-time"},"defaultBranch":{"type":["string","null"]}}},"ServiceDependency":{"type":"object","additionalProperties":false,"required":["host","target","provider","kind","evidence"],"properties":{"host":{"type":"string"},"target":{"type":"string"},"provider":{"type":"string"},"kind":{"type":"string","enum":["cname","mx"]},"evidence":{"type":"string"}}},"DnsRelation":{"type":"object","additionalProperties":false,"required":["queryName","recordType","target","underApex","seed"],"properties":{"queryName":{"type":"string"},"recordType":{"type":"string","enum":["TXT","CAA","SRV","HTTPS","SVCB"]},"target":{"type":"string"},"underApex":{"type":"boolean"},"seed":{"type":"boolean","description":"Whether this relation was eligible to enter the normal host classifier."}}},"RelatedDomain":{"type":"object","additionalProperties":false,"required":["domain","confidence","signals","evidence"],"properties":{"domain":{"type":"string"},"confidence":{"type":"string","enum":["confirmed","candidate"]},"signals":{"type":"integer","minimum":1},"evidence":{"type":"array","items":{"$ref":"#/components/schemas/RelatedDomainEvidence"}}}},"RelatedDomainEvidence":{"type":"object","additionalProperties":false,"required":["family","detail"],"properties":{"family":{"type":"string","enum":["github","cross-link","fingerprint","registrant","reverse-whois"]},"detail":{"type":"string"}}},"ReferencedHost":{"type":"object","additionalProperties":false,"required":["host","fromHost","via","underApex","resolves"],"properties":{"host":{"type":"string"},"fromHost":{"type":"string"},"via":{"type":"string","enum":["page-link","js","css","csp","cors","sitemap","robots","well-known","header","source-map","manifest","service-worker","openapi","oidc","assetlinks","apple-app-site-association"]},"underApex":{"type":"boolean"},"resolves":{"type":"boolean"}}},"Origin":{"type":"object","additionalProperties":false,"required":["ip","source","evidence","reverseDns"],"properties":{"ip":{"type":"string"},"source":{"type":"string","enum":["censys-cert","shodan-cert","securitytrails-history"]},"evidence":{"type":"string"},"reverseDns":{"type":["string","null"]}}},"FingerprintReport":{"type":"object","additionalProperties":false,"required":["signals","matches"],"properties":{"signals":{"type":"array","items":{"$ref":"#/components/schemas/FingerprintSignal"}},"matches":{"type":"array","items":{"$ref":"#/components/schemas/FingerprintMatch"}}}},"FingerprintSignal":{"type":"object","additionalProperties":false,"required":["kind","value","fromHost"],"properties":{"kind":{"type":"string","enum":["ga","gtm","favicon","favicon-sha256","copyright"]},"value":{"type":"string"},"fromHost":{"type":"string"}}},"FingerprintMatch":{"type":"object","additionalProperties":false,"required":["host","signal","source","sameApex"],"properties":{"host":{"type":"string"},"signal":{"type":"string"},"source":{"type":"string","enum":["publicwww","censys-favicon"]},"sameApex":{"type":"boolean"}}},"Scope":{"type":"object","additionalProperties":false,"required":["name","authorized","allowedHosts","excludedHosts","allowedSchemes","rateLimit","notes"],"properties":{"name":{"type":"string"},"authorized":{"type":"boolean","const":false,"description":"Always false until a human attests written permission."},"allowedHosts":{"type":"array","items":{"type":"string"},"minItems":1},"excludedHosts":{"type":"array","items":{"type":"string"}},"allowedSchemes":{"type":"array","items":{"type":"string","enum":["http","https"]}},"rateLimit":{"type":"object","additionalProperties":false,"required":["requestsPerSecond","parallelism"],"properties":{"requestsPerSecond":{"type":"integer","minimum":1},"parallelism":{"type":"integer","minimum":1}}},"notes":{"type":"string"}}},"Coverage":{"type":"object","additionalProperties":false,"required":["sources","discoveredHosts","processedHosts","truncatedHosts"],"properties":{"sources":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/SourceCoverage"}},"discoveredHosts":{"type":"integer","minimum":0},"processedHosts":{"type":"integer","minimum":0},"truncatedHosts":{"type":"integer","minimum":0}}},"SourceCoverage":{"type":"object","additionalProperties":false,"required":["status","count"],"properties":{"status":{"type":"string","enum":["ok","empty-or-unreachable","unavailable"]},"count":{"type":"integer","minimum":0}}}}}}