{"openapi":"3.1.0","info":{"title":"Vurl","version":"0.1.0","description":"Claim-bound URL validation. Given a URL and a claim, Vurl returns the exact span of the page that supports, contradicts, or fails to mention that claim, freezes a hash and copy of the page at that instant, and issues a passport link that keeps working after the page changes or dies.\n\nVurl reports what a page says, not whether it is true. It does not rate publishers or score source credibility."},"servers":[{"url":"https://vurl.ai"}],"paths":{"/api/v1/validate":{"post":{"operationId":"validateClaim","summary":"Check a claim against a URL and freeze the evidence","description":"Call this BEFORE citing a URL. Returns a verdict anchored to verbatim quoted spans, plus a permanent passport link. Every returned quote is verified to exist in the frozen text; unverifiable quotes are dropped and the verdict is downgraded to `unknown`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"The page to check."},"claim":{"type":"string","maxLength":2000,"description":"The single sentence this URL is being cited for. Omit to freeze the page without a claim check."},"push_archive":{"type":"boolean","description":"Also push a copy to the Internet Archive (best effort)."}}}}}},"responses":{"201":{"description":"Passport created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Passport"}}}},"400":{"description":"Bad URL, or the page could not be fetched"},"429":{"description":"Rate limited"}}}},"/api/v1/passport/{id}":{"get":{"operationId":"getPassport","summary":"Fetch an existing passport","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Passport","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Passport"}}}},"404":{"description":"No such passport"}}}},"/api/v1/recheck/{id}":{"post":{"operationId":"recheckPassport","summary":"Re-fetch the URL and report drift since the freeze","description":"Cheap: one fetch, one hash comparison, one substring search per quoted span. Answers 'has this citation drifted?' without re-running the analysis.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Recheck result"},"404":{"description":"No such passport"}}}},"/v/{id}/raw":{"get":{"operationId":"getStoredCopy","summary":"Stored HTML copy (creator only)","description":"Requires the owner token returned at validate time, as `X-Vurl-Owner` or `Authorization: Bearer`. Vurl does not republish stored pages publicly.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Stored HTML"},"403":{"description":"Not the creator"},"410":{"description":"Reproduction removed on request; hash retained"}}}},"/healthz":{"get":{"operationId":"health","summary":"Service status and counters","responses":{"200":{"description":"OK"}}}}},"components":{"schemas":{"Passport":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","description":"The shareable passport link."},"created_at":{"type":"string","format":"date-time"},"claim":{"type":"string","nullable":true},"source":{"type":"object","properties":{"requested_url":{"type":"string"},"final_url":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"site_name":{"type":"string","nullable":true},"published_at":{"type":"string","nullable":true}}},"fetch":{"type":"object","description":"What happened when Vurl tried to read the page. Orthogonal to the claim verdict.","properties":{"state":{"type":"string","enum":["ok","paywalled","blocked","dead","error","unsupported","invalid"]},"label":{"type":"string"},"http_status":{"type":"integer","nullable":true}}},"verdict":{"type":"object","properties":{"relation":{"type":"string","enum":["supports","partial","contradicts","silent","unknown"],"description":"`silent` means the page does not address the claim - the most common failure of a bad citation. `unknown` means Vurl declined to assert anything."},"label":{"type":"string"},"confidence":{"type":"number","minimum":0,"maximum":1},"claim_type":{"type":"string","nullable":true,"enum":["factual","opinion","unverifiable","malformed",null]},"analyzer":{"type":"string","nullable":true,"enum":["model","lexical","none",null]},"rationale":{"type":"string","nullable":true},"summary":{"type":"string"}}},"evidence":{"type":"array","description":"The load-bearing part. Verbatim spans located in the frozen text, with character offsets. A reader can overrule the verdict by reading these.","items":{"type":"object","properties":{"quote":{"type":"string"},"role":{"type":"string","enum":["support","contradict","context"]},"char_start":{"type":"integer"},"char_end":{"type":"integer"},"exact":{"type":"boolean"},"fingerprint":{"type":"string","nullable":true}}}},"freeze":{"type":"object","properties":{"text_sha256":{"type":"string","nullable":true,"description":"Hash of normalized visible text. Use this for drift."},"raw_sha256":{"type":"string","nullable":true,"description":"Hash of raw bytes. Provenance only - changes on nearly every load."},"text_chars":{"type":"integer","nullable":true},"frozen_at":{"type":"string","format":"date-time"},"reproduction_available":{"type":"boolean"},"wayback_url":{"type":"string","nullable":true}}},"drift":{"type":"object","nullable":true,"properties":{"checked_at":{"type":"string","format":"date-time"},"changed":{"type":"boolean"},"spans_intact":{"type":"boolean","nullable":true},"fetch_state":{"type":"string"},"note":{"type":"string"}}},"syndication":{"type":"array","description":"Other URLs Vurl has seen carrying the identical wording, oldest first. Repetition is not corroboration.","items":{"type":"object","properties":{"url":{"type":"string"},"first_seen":{"type":"string","nullable":true},"match":{"type":"string","enum":["identical_passage","near_duplicate_page"]},"similarity":{"type":"number"}}}},"notes":{"type":"array","items":{"type":"string"}},"owner_token":{"type":"string","description":"Returned once, at creation. Grants read access to the stored copy. Store it; Vurl keeps only a hash."}}}}}}