A fact API should make a claim easier to inspect, not simply make an answer sound more certain. The useful unit is a checkable statement connected to evidence, a clear assessment, and enough context for another person to understand the decision. That makes a fact API different from a collection of interesting trivia and different from a chatbot that supplies an answer without showing its work.
This guide introduces an evidence-first approach for developers, editors, and research teams. The architecture described here is a proposed implementation pattern, not a description of a hosted FactAPI.com service. Start with a narrow question, keep the underlying material accessible, and treat uncertainty as information worth returning to the caller.
Decide which kind of fact API you need
The phrase “fact API” can describe several different jobs. A structured data API returns recorded attributes such as a publication date or measurement. A fact-check search API finds existing reviews of claims. A claim-verification system compares a statement with selected evidence. A fact-extraction API identifies assertions in a document. These tasks can work together, but their outputs should not be presented as interchangeable.
Google’s Fact Check Tools API documentation distinguishes searching published fact checks from managing ClaimReview markup. Its claim-search capability retrieves existing fact-check results; it should not be interpreted as an automatic verdict on every newly submitted assertion. This distinction is a useful starting point for defining your own product boundary. Specify whether you are returning records, finding reviews, or performing a new assessment before choosing an endpoint name.
Define the claim before choosing the model
Consider a fictional sentence: “The Atlas archive opened in 2021 and contains twelve collections.” It contains at least two independently checkable assertions. A source could support the opening year while providing no evidence about the collection count. Returning one green badge for the entire sentence would hide that difference.
Give each extracted claim an identifier and preserve its original wording. Add normalized wording only when it makes the claim easier to search without changing its meaning. Record the subject, the relevant period, and any important qualifiers. “Contains twelve collections” and “contained twelve collections at launch” are different claims. A model that silently rewrites one into the other can create an apparently successful verification of the wrong statement.
Return evidence, not just a verdict
A useful response contains the claim, the evidence selected, and the relationship between them. For each evidence item, include a stable source identifier, a title, a retrieval timestamp, and a locator such as a section heading or paragraph number. Where your permissions allow it, include a short passage so the user can inspect the exact support.
Keep the assessment separate from the source record. One document may support several claims, and a later correction may change only one of those relationships. A response also needs room for an explanation that names the relevant limitation. “The record supports the launch year but does not state the number of collections” is more actionable than an unexplained confidence percentage. The explanation should point to the evidence rather than introduce additional uncited assertions.
Use status labels that preserve uncertainty
A small, documented vocabulary is easier to integrate than a different phrase for every result. In our proposed examples, supported means the available passage supports the claim within its stated scope. contradicted means relevant evidence conflicts with it. insufficient_evidence means the current evidence set cannot resolve it. These labels describe an assessment against a specified evidence set, not a guarantee of universal truth.
Distinguish those assessment labels from operational states. A failed request, an unavailable document, an unsupported language, and an ambiguous claim should not all become “false.” Return a separate processing status or error field. This lets an application retry an unavailable source, request clarification for ambiguous wording, or route a difficult case to a reviewer without treating every failure as a factual conclusion.
Design the pipeline as separate stages
A practical pipeline has four boundaries: extract the claim, retrieve evidence, assess the relationship, and record the decision. Each stage should produce inspectable output. This is especially useful when a result is wrong. You can ask whether the system selected the wrong statement, missed the right document, misunderstood an available passage, or displayed the assessment incorrectly.
Do not let later stages erase earlier context. Preserve the original document span beside the normalized claim. Keep evidence candidates alongside the selected passage when storage and licensing permit. Record the extraction and assessment versions separately. A retrieval improvement should be testable without changing the claim set, and a new assessment model should be comparable against the same evidence. That separation makes debugging much more specific than repeatedly changing a single all-purpose prompt.
Build a small, demanding test collection
Before connecting the API to a publishing workflow, create a manually reviewed collection of examples from the intended domain. Include statements that are straightforward, partly supported, time-sensitive, ambiguous, and impossible to answer from the permitted sources. Add claims with near-matching names, mismatched units, and quantities attached to different reporting periods.
For a fictional archive application, one test might deliberately pair a launch-year claim with a document about a later renovation. Another could use a real-looking collection count that appears nowhere in the evidence pack. These examples test whether the system understands relationships rather than whether it can repeat familiar sentences. Keep expected evidence and expected assessments together, and document how reviewers resolved disagreements. A label without an evidence rationale is difficult to audit later.
Plan for the user who needs to challenge a result
The interface should make it possible to inspect, question, and correct an assessment. Show the source title, the relevant passage, and the date of the check near the result. Avoid hiding the only meaningful evidence behind a generic “verified” label. Users should be able to distinguish the publisher’s words from the system’s explanation at a glance.
Build a correction path that records what changed and why. A claim may have been extracted incorrectly, a source may have been revised, or an assessor may have overstated the support. Those are different events. Keep the earlier record for audit purposes when appropriate, but ensure downstream applications can identify the current assessment. A correction process is not an admission that evidence workflows failed; it is part of making them useful over time.
Set a practical first-release boundary
A first implementation should cover a source collection and claim type that your team can evaluate responsibly. For example, checking dates and titles within a controlled document archive is a narrower assignment than adjudicating arbitrary claims across the public web. A narrow scope gives you a clearer definition of adequate evidence and a better chance of noticing missing coverage.
Set a rule for when the API must decline to decide. Specify which sources are allowed, how old evidence may be, and which cases require human review. Give callers realistic response semantics before offering performance promises. For costs, measure actual retrieval, assessment, storage, and review work on your own sample; do not assume that the cheapest model produces the cheapest reviewed result. Rework can change that calculation substantially.
Make the evidence trail the product
The strongest starting point is a response that another person can reconstruct: this was the claim, these were the sources, this passage mattered, and this was the limited conclusion. That contract is useful whether the assessment comes from deterministic rules, an LLM, a human reviewer, or a combination of them.
Continue with the Fact API architecture guide to map the components, then inspect the illustrative JSON examples. Build around traceability first. More models, sources, and automation can be added later; a missing relationship between a claim and its evidence is much harder to repair after the result has already been published.
