{"openapi":"3.1.0","info":{"title":"Fact It API","version":"1.0.0","description":"Real-time fact-checking for AI-generated text. POST a response and Fact It extracts its claims, retrieves live evidence, and returns per-claim verdicts with confidence scores and citations. The same contract is available self-hosted (see the @fact-it/api service). All request and response bodies are the Zod schemas from @fact-it/shared — this document is generated from them, so it never drifts from what the server validates.","contact":{"name":"Fact It","url":"https://fact-it-web-412159981305.us-central1.run.app"}},"servers":[{"url":"https://fact-it-web-412159981305.us-central1.run.app","description":"Hosted Fact It API"}],"components":{"securitySchemes":{"bearerToken":{"type":"http","scheme":"bearer","description":"Required to call the fact-check routes. Programmatic callers pass an API token minted at /account as `Authorization: Bearer fk_…` (shown once at creation; stored only as a SHA-256 hash). The signed-in dashboard and browser extension authenticate with a better-auth session cookie instead. A token is low-privilege: it can only call /api/check, /api/check/stream, and read /api/account/usage — it cannot mint tokens, change settings, or touch BYOK provider keys."}},"schemas":{"CheckRequest":{"type":"object","properties":{"response":{"type":"string","minLength":1},"prompt":{"type":"string"},"sourceApp":{"default":"other","type":"string","enum":["chatgpt-web","claude-web","gemini-web","perplexity-web","chatgpt-desktop","claude-desktop","dashboard","cli","other"]},"sensitivity":{"default":"balanced","type":"string","enum":["strict","balanced","light"]},"bypassCache":{"type":"boolean"},"review":{"type":"object","properties":{"reason":{"type":"string","enum":["user-thumbs-down"]},"priorVerdicts":{"type":"array","items":{"type":"object","properties":{"claimText":{"type":"string"},"status":{"type":"string","enum":["supported","partial","contradicted","unsupported"]},"confidence":{"type":"number","minimum":0,"maximum":1},"reasoning":{"type":"string"}},"required":["claimText","status","confidence","reasoning"],"additionalProperties":false}}},"required":["reason"],"additionalProperties":false},"verifierModel":{"type":"string"}},"required":["response"],"additionalProperties":false},"Check":{"type":"object","properties":{"id":{"type":"string"},"sourceApp":{"type":"string","enum":["chatgpt-web","claude-web","gemini-web","perplexity-web","chatgpt-desktop","claude-desktop","dashboard","cli","other"]},"prompt":{"type":"string"},"response":{"type":"string"},"verdicts":{"type":"array","items":{"type":"object","properties":{"claimId":{"type":"string"},"status":{"type":"string","enum":["supported","partial","contradicted","unsupported","pending"]},"confidence":{"type":"number","minimum":0,"maximum":1},"evidence":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"title":{"type":"string"},"snippet":{"type":"string"},"lastModifiedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"authorityScore":{"type":"number","minimum":0,"maximum":1},"recencyScore":{"type":"number","minimum":0,"maximum":1},"relevanceScore":{"type":"number","minimum":0,"maximum":1},"providerId":{"type":"string"}},"required":["url","title","snippet","authorityScore","recencyScore","relevanceScore","providerId"],"additionalProperties":false}},"reasoning":{"type":"string"}},"required":["claimId","status","confidence","evidence","reasoning"],"additionalProperties":false}},"degradedProviders":{"type":"array","items":{"type":"object","properties":{"providerId":{"type":"string"},"kind":{"type":"string","enum":["quota","auth","rate-limit","upstream","network"]},"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"message":{"type":"string"}},"required":["providerId","kind","message"],"additionalProperties":false}},"overallConfidence":{"type":"number","minimum":0,"maximum":1},"model":{"type":"object","properties":{"extractor":{"type":"string"},"verifier":{"type":"string"}},"required":["extractor","verifier"],"additionalProperties":false},"cost":{"type":"object","properties":{"usd":{"type":"number","minimum":0},"inputTokens":{"type":"integer","minimum":0,"maximum":9007199254740991},"outputTokens":{"type":"integer","minimum":0,"maximum":9007199254740991},"cacheReadTokens":{"type":"integer","minimum":0,"maximum":9007199254740991},"cacheWriteTokens":{"type":"integer","minimum":0,"maximum":9007199254740991},"searchCalls":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["usd","inputTokens","outputTokens","cacheReadTokens","cacheWriteTokens","searchCalls"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","sourceApp","response","verdicts","overallConfidence","model","createdAt"],"additionalProperties":false},"Verdict":{"type":"object","properties":{"claimId":{"type":"string"},"status":{"type":"string","enum":["supported","partial","contradicted","unsupported","pending"]},"confidence":{"type":"number","minimum":0,"maximum":1},"evidence":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"title":{"type":"string"},"snippet":{"type":"string"},"lastModifiedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"authorityScore":{"type":"number","minimum":0,"maximum":1},"recencyScore":{"type":"number","minimum":0,"maximum":1},"relevanceScore":{"type":"number","minimum":0,"maximum":1},"providerId":{"type":"string"}},"required":["url","title","snippet","authorityScore","recencyScore","relevanceScore","providerId"],"additionalProperties":false}},"reasoning":{"type":"string"}},"required":["claimId","status","confidence","evidence","reasoning"],"additionalProperties":false},"Evidence":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"title":{"type":"string"},"snippet":{"type":"string"},"lastModifiedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"authorityScore":{"type":"number","minimum":0,"maximum":1},"recencyScore":{"type":"number","minimum":0,"maximum":1},"relevanceScore":{"type":"number","minimum":0,"maximum":1},"providerId":{"type":"string"}},"required":["url","title","snippet","authorityScore","recencyScore","relevanceScore","providerId"],"additionalProperties":false},"Claim":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"},"span":{"type":"object","properties":{"start":{"type":"integer","minimum":0,"maximum":9007199254740991},"end":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["start","end"],"additionalProperties":false},"type":{"type":"string","enum":["numeric","historical","current_event","scientific","biographical","definition","opinion"]},"importance":{"type":"string","enum":["core","supporting","aside"]},"freshnessNeed":{"type":"string","enum":["live","recent","evergreen"]},"searchQuery":{"type":"string"},"domain":{"default":"general","type":"string","enum":["general","medical","legal","scientific","financial","news","personal"]}},"required":["id","text","span","type","importance","freshnessNeed","domain"],"additionalProperties":false},"CostSummary":{"type":"object","properties":{"usd":{"type":"number","minimum":0},"inputTokens":{"type":"integer","minimum":0,"maximum":9007199254740991},"outputTokens":{"type":"integer","minimum":0,"maximum":9007199254740991},"cacheReadTokens":{"type":"integer","minimum":0,"maximum":9007199254740991},"cacheWriteTokens":{"type":"integer","minimum":0,"maximum":9007199254740991},"searchCalls":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["usd","inputTokens","outputTokens","cacheReadTokens","cacheWriteTokens","searchCalls"],"additionalProperties":false},"Feedback":{"type":"object","properties":{"checkId":{"type":"string"},"sourceApp":{"type":"string","enum":["chatgpt-web","claude-web","gemini-web","perplexity-web","chatgpt-desktop","claude-desktop","dashboard","cli","other"]},"rating":{"type":"string","enum":["up","down"]},"responseSnippet":{"type":"string","maxLength":2000},"priorVerdicts":{"type":"array","items":{"type":"object","properties":{"claimText":{"type":"string"},"status":{"type":"string","enum":["supported","partial","contradicted","unsupported"]},"confidence":{"type":"number","minimum":0,"maximum":1},"reasoning":{"type":"string"}},"required":["claimText","status","confidence","reasoning"],"additionalProperties":false}},"overallConfidence":{"type":"number","minimum":0,"maximum":1},"comment":{"type":"string","maxLength":1000}},"required":["sourceApp","rating"],"additionalProperties":false},"PipelineEvent":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"extracted"},"claims":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"},"span":{"type":"object","properties":{"start":{"type":"integer","minimum":0,"maximum":9007199254740991},"end":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["start","end"],"additionalProperties":false},"type":{"type":"string","enum":["numeric","historical","current_event","scientific","biographical","definition","opinion"]},"importance":{"type":"string","enum":["core","supporting","aside"]},"freshnessNeed":{"type":"string","enum":["live","recent","evergreen"]},"searchQuery":{"type":"string"},"domain":{"default":"general","type":"string","enum":["general","medical","legal","scientific","financial","news","personal"]}},"required":["id","text","span","type","importance","freshnessNeed","domain"],"additionalProperties":false}}},"required":["type","claims"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"retrieving"},"claimId":{"type":"string"}},"required":["type","claimId"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"retrieved"},"claimId":{"type":"string"},"evidence":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"title":{"type":"string"},"snippet":{"type":"string"},"lastModifiedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"authorityScore":{"type":"number","minimum":0,"maximum":1},"recencyScore":{"type":"number","minimum":0,"maximum":1},"relevanceScore":{"type":"number","minimum":0,"maximum":1},"providerId":{"type":"string"}},"required":["url","title","snippet","authorityScore","recencyScore","relevanceScore","providerId"],"additionalProperties":false}}},"required":["type","claimId","evidence"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"verdict"},"verdict":{"type":"object","properties":{"claimId":{"type":"string"},"status":{"type":"string","enum":["supported","partial","contradicted","unsupported","pending"]},"confidence":{"type":"number","minimum":0,"maximum":1},"evidence":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"title":{"type":"string"},"snippet":{"type":"string"},"lastModifiedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"authorityScore":{"type":"number","minimum":0,"maximum":1},"recencyScore":{"type":"number","minimum":0,"maximum":1},"relevanceScore":{"type":"number","minimum":0,"maximum":1},"providerId":{"type":"string"}},"required":["url","title","snippet","authorityScore","recencyScore","relevanceScore","providerId"],"additionalProperties":false}},"reasoning":{"type":"string"}},"required":["claimId","status","confidence","evidence","reasoning"],"additionalProperties":false}},"required":["type","verdict"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"done"},"check":{"type":"object","properties":{"id":{"type":"string"},"sourceApp":{"type":"string","enum":["chatgpt-web","claude-web","gemini-web","perplexity-web","chatgpt-desktop","claude-desktop","dashboard","cli","other"]},"prompt":{"type":"string"},"response":{"type":"string"},"verdicts":{"type":"array","items":{"type":"object","properties":{"claimId":{"type":"string"},"status":{"type":"string","enum":["supported","partial","contradicted","unsupported","pending"]},"confidence":{"type":"number","minimum":0,"maximum":1},"evidence":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"title":{"type":"string"},"snippet":{"type":"string"},"lastModifiedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"authorityScore":{"type":"number","minimum":0,"maximum":1},"recencyScore":{"type":"number","minimum":0,"maximum":1},"relevanceScore":{"type":"number","minimum":0,"maximum":1},"providerId":{"type":"string"}},"required":["url","title","snippet","authorityScore","recencyScore","relevanceScore","providerId"],"additionalProperties":false}},"reasoning":{"type":"string"}},"required":["claimId","status","confidence","evidence","reasoning"],"additionalProperties":false}},"degradedProviders":{"type":"array","items":{"type":"object","properties":{"providerId":{"type":"string"},"kind":{"type":"string","enum":["quota","auth","rate-limit","upstream","network"]},"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"message":{"type":"string"}},"required":["providerId","kind","message"],"additionalProperties":false}},"overallConfidence":{"type":"number","minimum":0,"maximum":1},"model":{"type":"object","properties":{"extractor":{"type":"string"},"verifier":{"type":"string"}},"required":["extractor","verifier"],"additionalProperties":false},"cost":{"type":"object","properties":{"usd":{"type":"number","minimum":0},"inputTokens":{"type":"integer","minimum":0,"maximum":9007199254740991},"outputTokens":{"type":"integer","minimum":0,"maximum":9007199254740991},"cacheReadTokens":{"type":"integer","minimum":0,"maximum":9007199254740991},"cacheWriteTokens":{"type":"integer","minimum":0,"maximum":9007199254740991},"searchCalls":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["usd","inputTokens","outputTokens","cacheReadTokens","cacheWriteTokens","searchCalls"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","sourceApp","response","verdicts","overallConfidence","model","createdAt"],"additionalProperties":false}},"required":["type","check"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"error"},"message":{"type":"string"},"claimId":{"type":"string"}},"required":["type","message"],"additionalProperties":false}]},"UsageSummary":{"type":"object","description":"Plan name and remaining credit balance for the authenticated caller.","properties":{"plan":{"type":"string","description":"Plan identifier, e.g. \"free\" or \"pro\"."},"monthlyCreditAllowance":{"type":"integer","description":"Credits included with the plan each period. NOT the usable total on its own — add bonusCredits, or just read creditsRemaining."},"bonusCredits":{"type":"integer","description":"One-off credits granted on top of the plan allowance for the current period (e.g. an approved top-up request). Cleared when the period rolls over. Absent on older servers."},"creditsUsed":{"type":"integer"},"creditsRemaining":{"type":"integer","description":"monthlyCreditAllowance + bonusCredits - creditsUsed, floored at 0."},"periodStart":{"type":"string","format":"date-time"},"byokEnabled":{"type":"boolean","description":"Whether the caller has a bring-your-own-key verifier configured."}},"required":["plan","monthlyCreditAllowance","creditsUsed","creditsRemaining","periodStart","byokEnabled"],"additionalProperties":false},"Ok":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false},"Error":{"type":"object","description":"Error envelope returned by non-2xx JSON responses.","properties":{"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Stable machine code, present on some errors (e.g. \"credits_exhausted\")."}},"required":["error"],"additionalProperties":true}}},"paths":{"/api/check":{"post":{"summary":"Fact-check a response","description":"Extract claims from `response`, verify each against live evidence, and return the final Check. Non-streaming — the connection stays open until every verdict is ready. Use /api/check/stream to render verdicts as they land.","security":[{"bearerToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckRequest"}}}},"responses":{"200":{"description":"The completed fact-check.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Check"}}}},"400":{"description":"The request body failed CheckRequest validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required — no session cookie or API token was supplied (code: unauthenticated).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Monthly credit allowance exhausted (code: credits_exhausted).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Daily budget cap reached, or a transient identity/metering failure; retry (see Retry-After).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/check/stream":{"post":{"summary":"Fact-check a response (streaming)","description":"Same input as /api/check, streamed as Server-Sent Events. Each event is a PipelineEvent encoded as `data: <json>\\n\\n`. The terminal event is either `{ \"type\": \"done\", \"check\": Check }` or `{ \"type\": \"error\", ... }`.","security":[{"bearerToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckRequest"}}}},"responses":{"200":{"description":"An SSE stream of PipelineEvent objects.","content":{"text/event-stream":{"schema":{"$ref":"#/components/schemas/PipelineEvent"}}}},"400":{"description":"Invalid JSON or CheckRequest.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required — no session cookie or API token was supplied (code: unauthenticated).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Monthly credit allowance exhausted (code: credits_exhausted).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Daily budget cap reached, or a transient identity/metering failure; retry (see Retry-After).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/feedback":{"post":{"summary":"Rate a check","description":"Submit an anonymous thumbs up/down on a check. Fire-and-forget; returns 202 and stores no account id (see the Feedback schema).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Feedback"}}}},"responses":{"202":{"description":"Feedback accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"}}}},"400":{"description":"The request body failed Feedback validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded."}}}},"/api/account/usage":{"get":{"summary":"Get credit balance","description":"Plan and remaining credits for the authenticated caller. The one /api/account route that accepts an API token (read-only); the others require a session cookie.","security":[{"bearerToken":[]}],"responses":{"200":{"description":"Current usage summary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageSummary"}}}},"401":{"description":"Missing or invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}