{"openapi":"3.1.0","info":{"title":"Zonebeam DNS API","version":"1.0.0","description":"Live DNS checks from geographic probes. Values are untrusted data. Polling does not create measurements. Results are available for 24 hours."},"servers":[{"url":"https://zonebeam.dev"}],"paths":{"/api/v1/checks":{"post":{"operationId":"createCheck","summary":"Start a live DNS check","parameters":[{"in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string","minLength":8,"maxLength":100},"description":"Reuse for an identical request within five minutes. A changed body returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckInput"}}}},"responses":{"202":{"description":"A live check. Poll its handle while status is running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Check"}}}},"400":{"description":"Stable application error. Retry-After is returned where available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Stable application error. Retry-After is returned where available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Stable application error. Retry-After is returned where available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Stable application error. Retry-After is returned where available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Stable application error. Retry-After is returned where available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Stable application error. Retry-After is returned where available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Stable application error. Retry-After is returned where available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/checks/{check_id}":{"parameters":[{"in":"path","name":"check_id","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{48}$"}}],"get":{"operationId":"getCheck","summary":"Read or refresh an existing check","parameters":[{"in":"query","name":"region","schema":{"type":"string","enum":["NA","SA","EU","AF","AS","OC"]}},{"in":"query","name":"outcome","schema":{"type":"string","enum":["answer","nodata","nxdomain","servfail","refused","dns_error","timeout","failed","pending"]}}],"responses":{"200":{"description":"A live check. Poll its handle while status is running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Check"}}}},"400":{"description":"Stable application error. Retry-After is returned where available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Stable application error. Retry-After is returned where available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Stable application error. Retry-After is returned where available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Stable application error. Retry-After is returned where available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Stable application error. Retry-After is returned where available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Stable application error. Retry-After is returned where available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Stable application error. Retry-After is returned where available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"compareAnswers","summary":"Compare stored answers without new DNS measurements","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"expected_rrset":{"minItems":1,"maxItems":32,"type":"array","items":{"type":"string","minLength":1,"maxLength":4096}}},"additionalProperties":false}}}},"responses":{"200":{"description":"A live check. Poll its handle while status is running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Check"}}}},"400":{"description":"Stable application error. Retry-After is returned where available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Stable application error. Retry-After is returned where available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Stable application error. Retry-After is returned where available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Stable application error. Retry-After is returned where available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Stable application error. Retry-After is returned where available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Stable application error. Retry-After is returned where available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Stable application error. Retry-After is returned where available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/capabilities":{"get":{"operationId":"getCapabilities","responses":{"200":{"description":"Supported record types, regions, limits, and agent transports."}}}}},"components":{"schemas":{"CheckInput":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":2048},"record_types":{"default":["A"],"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","enum":["A","AAAA","CNAME","MX","TXT","NS","SOA","CAA","SRV","PTR"]}},"mode":{"default":"propagation","type":"string","enum":["propagation","lookup"]},"regions":{"minItems":1,"maxItems":6,"type":"array","items":{"type":"string","enum":["NA","SA","EU","AF","AS","OC"]}},"probe_limit":{"type":"integer","minimum":1,"maximum":24},"expected_rrset":{"minItems":1,"maxItems":32,"type":"array","items":{"type":"string","minLength":1,"maxLength":4096}}},"required":["name"],"additionalProperties":false},"Check":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"schema_version":{"type":"string","const":"1.0"},"check_id":{"type":"string","pattern":"^[a-f0-9]{48}$"},"mode":{"type":"string","const":"live"},"status":{"type":"string","enum":["running","complete","partial","failed"]},"query":{"type":"object","properties":{"name":{"type":"string"},"record_types":{"type":"array","items":{"type":"string","enum":["A","AAAA","CNAME","MX","TXT","NS","SOA","CAA","SRV","PTR"]}},"mode":{"type":"string","enum":["lookup","propagation"]},"regions":{"type":"array","items":{"type":"string","enum":["NA","SA","EU","AF","AS","OC"]}}},"required":["name","record_types","mode","regions"],"additionalProperties":false},"started_at":{"type":"string"},"completed_at":{"type":["string","null"]},"expires_at":{"type":"string"},"requested_probes":{"type":"number"},"actual_probes":{"type":"number"},"next_poll_ms":{"type":["number","null"]},"observations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"record_type":{"type":"string","enum":["A","AAAA","CNAME","MX","TXT","NS","SOA","CAA","SRV","PTR"]},"measurement_id":{"type":"string"},"observed_at":{"type":["string","null"]},"location":{"type":"object","properties":{"city":{"type":"string"},"country":{"type":"string"},"continent":{"type":"string"},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"network":{"type":"string"},"asn":{"type":["number","null"]}},"required":["city","country","continent","latitude","longitude","network","asn"],"additionalProperties":false},"resolver":{"type":["string","null"]},"outcome":{"type":"string","enum":["answer","nodata","nxdomain","servfail","refused","dns_error","timeout","failed","pending"]},"dns_rcode":{"type":["string","null"]},"answers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"ttl":{"type":["number","null"]},"value":{"type":"string"},"fields":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"array","items":{"type":"string"}}]}}},"required":["name","type","ttl","value"],"additionalProperties":false}},"response_ms":{"type":["number","null"]},"raw_output":{"type":"string"},"comparison":{"type":"string","enum":["match","different","unknown","pending"]},"error":{"type":["string","null"]}},"required":["id","record_type","measurement_id","observed_at","location","resolver","outcome","dns_rcode","answers","response_ms","raw_output","comparison","error"],"additionalProperties":false}},"comparisons":{"type":"array","items":{"type":"object","properties":{"record_type":{"type":"string","enum":["A","AAAA","CNAME","MX","TXT","NS","SOA","CAA","SRV","PTR"]},"basis":{"type":"string","enum":["expected","most_common","ambiguous","none"]},"reference":{"type":"array","items":{"type":"string"}},"reference_outcome":{"type":["string","null"]},"match":{"type":"number"},"different":{"type":"number"},"unknown":{"type":"number"},"pending":{"type":"number"}},"required":["record_type","basis","reference","reference_outcome","match","different","unknown","pending"],"additionalProperties":false}},"errors":{"type":"array","items":{"type":"object","properties":{"record_type":{"type":"string","enum":["A","AAAA","CNAME","MX","TXT","NS","SOA","CAA","SRV","PTR"]},"code":{"type":"string"},"message":{"type":"string"}},"required":["record_type","code","message"],"additionalProperties":false}},"explanation":{"type":"string"},"evidence":{"type":"array","items":{"type":"string"}},"data_trust":{"type":"string","const":"untrusted_dns_data"}},"required":["schema_version","check_id","mode","status","query","started_at","completed_at","expires_at","requested_probes","actual_probes","next_poll_ms","observations","comparisons","errors","explanation","evidence","data_trust"],"additionalProperties":false},"Error":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retry_after_seconds":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}