{"openapi":"3.1.0","info":{"title":"OuterCheck API","description":"OuterCheck verifies the externally observable state of a public website — use it after deployment or web changes.\n\n**Input:** a public URL. **Output:** deterministic JSON — per-check PASS/WARN/FAIL/UNKNOWN verdicts with evidence, ONE priority action, overall state, recheck support.\n\nWorkflow: `POST /v1/verify` → poll `GET /v1/results/{id}` until `status == \"completed\"` → read `overall`, `summary`, `priority_action`, `checks[].evidence` → after fixing, `POST /v1/results/{id}/recheck` and read `recheck.fixed` / `recheck.verdict`.\n\nHonesty rule: OuterCheck never claims a page \"is indexed by Google\"; `search_index_status` is always `unknown` in v0.1.","version":"0.1.0"},"paths":{"/health":{"get":{"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Service + queue status.","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Health Health Get"}}}}}}},"/v1/verify":{"post":{"summary":"Verify a public URL","description":"Enqueues an external verification of `url`. Poll `GET /v1/results/{id}` until `status` is `completed` (usually 3–15 s).","operationId":"create_verify_v1_verify_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyRequest"}}},"required":true},"responses":{"202":{"description":"Verification enqueued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyAcceptedResponse"}}}},"400":{"description":"Policy-blocked or invalid URL.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/results/{ver_id}":{"get":{"summary":"Fetch a verification result","description":"Returns the job state; once `completed`, the full evidence-first result.","operationId":"get_result_v1_results__ver_id__get","parameters":[{"name":"ver_id","in":"path","required":true,"schema":{"type":"string","title":"Ver Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationResult"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not Found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/results/{ver_id}/recheck":{"post":{"summary":"Re-verify after a fix","description":"Creates a new verification linked to this one. The child result carries `recheck`: which checks were fixed / regressed / new / unchanged.","operationId":"recheck_v1_results__ver_id__recheck_post","parameters":[{"name":"ver_id","in":"path","required":true,"schema":{"type":"string","title":"Ver Id"}}],"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyAcceptedResponse"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not Found"},"409":{"description":"Parent not completed yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too Many Requests"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/results/{ver_id}/rechecks":{"get":{"summary":"List Rechecks","description":"Children (rechecks) of a verification.","operationId":"list_rechecks_v1_results__ver_id__rechecks_get","parameters":[{"name":"ver_id","in":"path","required":true,"schema":{"type":"string","title":"Ver Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not Found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"CheckEvidence":{"properties":{"source":{"type":"string","enum":["html","header","robots","sitemap","dns","tls","transport","policy"],"title":"Source","description":"Where the evidence came from."},"selector":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Selector","description":"CSS/header selector when source=html|header."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"URL of the artifact (robots, sitemap, page)."},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail","description":"Observed value(s), truncated as needed."}},"type":"object","required":["source"],"title":"CheckEvidence"},"ErrorResponse":{"properties":{"error":{"type":"string","title":"Error","description":"Stable machine code, e.g. blocked_private_target."},"message":{"type":"string","title":"Message"}},"type":"object","required":["error","message"],"title":"ErrorResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"NextAction":{"properties":{"id":{"type":"string","title":"Id"},"rank":{"type":"integer","maximum":4.0,"minimum":2.0,"title":"Rank"},"check_id":{"type":"string","title":"Check Id"},"severity":{"type":"string","enum":["critical","high","medium","low"],"title":"Severity"},"title":{"type":"string","title":"Title"},"why":{"type":"string","title":"Why"},"how":{"type":"string","title":"How","default":""},"check_status":{"anyOf":[{"type":"string","enum":["pass","warn","fail","unknown"]},{"type":"null"}],"title":"Check Status"},"observed":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Observed"},"evidence":{"items":{"$ref":"#/components/schemas/CheckEvidence"},"type":"array","title":"Evidence"}},"type":"object","required":["id","rank","check_id","severity","title","why"],"title":"NextAction"},"PriorityAction":{"properties":{"id":{"type":"string","title":"Id"},"rank":{"type":"integer","const":1,"title":"Rank","description":"1 marks THE priority action; next_actions are ranked 2+."},"check_id":{"type":"string","title":"Check Id"},"severity":{"type":"string","enum":["critical","high","medium","low"],"title":"Severity"},"title":{"type":"string","title":"Title"},"why":{"type":"string","title":"Why"},"how":{"type":"string","title":"How","default":""},"check_status":{"anyOf":[{"type":"string","enum":["pass","warn","fail","unknown"]},{"type":"null"}],"title":"Check Status"},"observed":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Observed"},"evidence":{"items":{"$ref":"#/components/schemas/CheckEvidence"},"type":"array","title":"Evidence"}},"type":"object","required":["id","rank","check_id","severity","title","why"],"title":"PriorityAction"},"RecheckDiff":{"properties":{"recheck_of":{"type":"string","title":"Recheck Of","description":"public_id of the parent verification."},"verdict":{"type":"string","enum":["improved","worse","mixed","unchanged"],"title":"Verdict"},"fixed":{"items":{"type":"string"},"type":"array","title":"Fixed"},"regressed":{"items":{"type":"string"},"type":"array","title":"Regressed"},"new":{"items":{"type":"string"},"type":"array","title":"New"},"unchanged":{"items":{"type":"string"},"type":"array","title":"Unchanged"},"counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Counts"},"issues_before":{"type":"integer","title":"Issues Before"},"issues_after":{"type":"integer","title":"Issues After"},"human":{"type":"string","title":"Human","description":"One-line human summary, e.g. '1 fixed — overall state improved'."}},"type":"object","required":["recheck_of","verdict","fixed","regressed","new","unchanged","counts","issues_before","issues_after","human"],"title":"RecheckDiff"},"SnapshotModel":{"properties":{"kind":{"type":"string","enum":["robots","sitemap","html","headers"],"title":"Kind"},"url":{"type":"string","title":"Url"},"content_sha256":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Sha256"},"bytes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Bytes"},"truncated":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Truncated"},"content_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Type"},"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content","description":"First ~256 KB of the artifact (retained 30 days)."}},"type":"object","required":["kind","url"],"title":"SnapshotModel"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VerificationCheck":{"properties":{"check_id":{"type":"string","title":"Check Id","description":"Stable check identifier, e.g. indexability (docs/schema.md)."},"category":{"type":"string","enum":["network","html","crawling","indexing","agent_discovery"],"title":"Category"},"status":{"type":"string","enum":["pass","warn","fail","unknown"],"title":"Status"},"message":{"type":"string","title":"Message"},"observed":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Observed","description":"What was actually seen."},"expected":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Expected"},"evidence":{"items":{"$ref":"#/components/schemas/CheckEvidence"},"type":"array","title":"Evidence"},"duration_ms":{"type":"integer","title":"Duration Ms","default":0}},"type":"object","required":["check_id","category","status","message"],"title":"VerificationCheck"},"VerificationResult":{"properties":{"id":{"type":"string","title":"Id"},"public_id":{"type":"string","title":"Public Id"},"api_version":{"type":"string","const":"v1","title":"Api Version"},"schema_version":{"type":"string","title":"Schema Version"},"target":{"type":"string","title":"Target"},"final_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Final Url"},"status":{"type":"string","enum":["queued","running","completed","failed"],"title":"Status"},"overall":{"anyOf":[{"type":"string","enum":["ready","degraded","broken","unknown"]},{"type":"null"}],"title":"Overall"},"trigger":{"type":"string","enum":["initial","recheck"],"title":"Trigger","default":"initial"},"parent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Id"},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Started At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"},"duration_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Duration Ms"},"bytes_in":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Bytes In"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Machine error code when status=failed."},"summary":{"anyOf":[{"$ref":"#/components/schemas/VerificationSummary"},{"type":"null"}]},"priority_action":{"anyOf":[{"$ref":"#/components/schemas/PriorityAction"},{"type":"null"}]},"next_actions":{"items":{"$ref":"#/components/schemas/NextAction"},"type":"array","title":"Next Actions"},"checks":{"items":{"$ref":"#/components/schemas/VerificationCheck"},"type":"array","title":"Checks"},"snapshots":{"items":{"$ref":"#/components/schemas/SnapshotModel"},"type":"array","title":"Snapshots"},"recheck":{"anyOf":[{"$ref":"#/components/schemas/RecheckDiff"},{"type":"null"}],"description":"BEFORE/AFTER diff vs the parent (present on rechecks)."}},"type":"object","required":["id","public_id","api_version","schema_version","target","status"],"title":"VerificationResult","description":"Full result of GET /v1/results/{id}."},"VerificationSummary":{"properties":{"pass":{"type":"integer","title":"Pass","description":"Checks with status=pass."},"warn":{"type":"integer","title":"Warn"},"fail":{"type":"integer","title":"Fail"},"unknown":{"type":"integer","title":"Unknown"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["pass","warn","fail","unknown","total"],"title":"VerificationSummary"},"VerifyAcceptedResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Opaque verification id; use it to poll results."},"public_id":{"type":"string","title":"Public Id","description":"128-bit capability id for the shareable /r/{public_id} proof URL."},"status":{"type":"string","enum":["queued","running","completed","failed"],"title":"Status"},"target":{"type":"string","title":"Target"},"api_version":{"type":"string","const":"v1","title":"Api Version"},"schema_version":{"type":"string","title":"Schema Version"},"links":{"additionalProperties":{"type":"string"},"type":"object","title":"Links","description":"self / proof / recheck relative URLs."}},"type":"object","required":["id","public_id","status","target","api_version","schema_version","links"],"title":"VerifyAcceptedResponse","description":"202 body of POST /v1/verify and POST /v1/results/{id}/recheck."},"VerifyRequest":{"properties":{"url":{"type":"string","title":"Url","description":"Public URL or hostname to verify. http/https, ports 80/443, public hosts only.","examples":["https://example.com"]}},"type":"object","required":["url"],"title":"VerifyRequest"}}}}