Getting Started

Overview

Before an agent takes a real-world action, it submits a proposal to Verifact.

The proposal consists of:

• Claims — statements that justify the action
• Sources — the only material Verifact is allowed to rely on
• Requirements & options — rules and runtime flags defining what “sufficient support” means

Verifact verifies support for the claims, applies requirements, and returns one of three decisions: allow, deny, or needs_review. Your system should respect this decision before executing anything.

The Integration Flow

1. Agent proposes an Action or produces LLM output
   (e.g. send an email, issue a refund, grant access; or generate a customer response or public-facing text)
2. Your system constructs a proposal
   Claims that must be true for the action to be allowed
3. Verifact verifies the proposal
   Claims are evaluated against the provided sources
4. Requirements are applied
   Coverage thresholds, citation requirements, and enforcement rules are applied
5. Verifact returns a decision
   allow, deny, or needs_review, plus reasons and audit metadata
6. Your system
   Execute, block, or route for human review

Verifact never executes actions itself.

What Is a Proposal?

A proposal is not an instruction like “send this email.” A proposal is the justification for taking an action.

Example

An AI agent proposes sending a financial report to an external investor as part of an automated workflow:

"Send report_123 to investor@company.com because it contains only public data."

The proposal sent to Verifact might be:

curl -sS -X POST "https://verifact-api.fly.dev/v2/authorize"   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{
    "action": {
      "type": "send_report",
      "params": { "report_id": "report_123", "recipient": "investor@company.com" }
    },
    "claims": [
      { "text": "Report report_123 contains only public data" }
    ],
    "sources": [ { "source_id": "src_..." } ]
  }' | jq .

# Step 1 — upload PDF -> get a source_id + checksum
curl -X POST "https://verifact-api.fly.dev/v2/sources"   -H "Authorization: Bearer $API_KEY"   -F "file=@report.pdf"   -F "title=report_123"

# Step 2 — authorize against the stored source by reference
curl -X POST "https://verifact-api.fly.dev/v2/authorize"   -H "Authorization: Bearer $API_KEY"   -H "Content-Type: application/json"   -d '{
    "action": {
      "type": "send_report",
      "params": { "report_id": "report_123", "recipient": "investor@company.com" }
    },
    "claims": [
      { "text": "Report report_123 contains only public data" }
    ],
    "sources": [ { "source_id": "src_..." } ]
  }' | jq .

# Example — requirements + options to control enforcement
{
  "requirements": {
    "min_claim_coverage": 0.9,
    "citations": { "required": true, "min_citations_per_claim": 1 }
  },
  "options": {
    "semantic_verify": true,
    "evidence_limit": 3,
    "deny_if_any_unsupported": true
  }
}

Notes: The canonical field is source_id. In v2 semantics, checksum represents a content-level hash (content_hash) of the extracted/normalized text; raw_checksum is the sha256 of raw upload bytes and should only be used for uploads.

In this flow the agent supplies a proposal (what it intends to do), explicit claims to check, and the sources to verify against. Verifact deterministically verifies each claim against the provided sources and returns a decision; authorization requirements should be applied after verification before taking action.

Verifact does not classify documents. It verifies claims against authoritative evidence artifacts (such as DLP scan results and access control lists) supplied by the caller.

Deterministic verification (default)

Verifact first applies deterministic verification against the supplied sources. This default behavior uses exact substring matching, token-overlap heuristics, and short-claim exact-match rules to find supporting citations. Deterministic verification is fast, auditable, and always applied.

• Short claims that appear verbatim in a source are treated as fully supported.
• Longer claims are matched by passage overlap and structured extraction.
• If no deterministic citation is found, you may opt into hybrid semantic verification per-request.

Hybrid (semantic) verification (opt-in)

Optional hybrid verification uses embedding-based retrieval + NLI entailment as a fallback when deterministic verification returns no citations. Enable it per-request with "options": { "semantic_verify": true }. Semantic verification returns concise sentence-level citations and a confidence score; if models are unavailable the service falls back to deterministic verification and marks the check with a semantic_verify_unavailable error.

# Example — enable semantic verification (opt-in)
curl -X POST "https://verifact-api.fly.dev/v2/verify"   -H "Authorization: Bearer $API_KEY"   -H "Content-Type: application/json"   -d '{
    "claims": [ { "text": "Customers on plan X receive expedited shipping." } ],
    "sources": [ { "source_id": "policy_v3", "type": "text", "content": "Premium customers receive expedited shipping in 2 days." } ],
    "options": { "semantic_verify": true, "evidence_limit": 3 }
  }' | jq .

Claims

A claim is a single, testable assertion expressed in plain text.

Claims should represent the conditions that must be satisfied for the action to proceed. Good claims are explicit, narrow, and independently verifiable.

• “Customer Y was charged twice for order #1842.”
• “Refunds are permitted within 30 days of purchase.”
• “User X is authorized to access this resource.”

Sources

Sources are the only material Verifact is allowed to rely on. Sources are provided explicitly in the request and treated as reference material.

• Verifact uses only the sources you supply; a source can be uploaded as a document or included as a url that is fetched with an optional checksum to be completed for validity.
• Verifact will not browse external sites or retrieve additional material beyond the supplied sources.
• Verifact does not infer facts beyond what is supplied.

If a claim is not supported by the provided sources, it will not pass verification.

Requirements & Options

Requirements and options define how verification results are interpreted and enforced at runtime.

Common controls include:

• Minimum required claim support
• Whether citations are required
• How unsupported claims are handled (deny or route for review)
• Runtime options such as semantic verification flags and evidence limits

Requirements are deterministic and enforced by your system; LLMs cannot override them. Options tune runtime behavior (for example, enabling semantic verification).

Decisions

Verifact returns reasons and audit metadata with every decision.

How Actions Are Blocked

Verifact does not block actions directly. Actions are blocked because your system does not execute them unless Verifact returns allow and the request meets your configured requirements.

Blocking is enforced through control flow, not interception.

Why Proposals Are Denied

• Required evidence is missing
• Claims are only partially supported
• Claims are contradicted by the sources
• New facts are introduced without support
• Requirements require higher support than is present

A denial does not mean the proposal is “false” — only that it is insufficiently justified.

Key Guarantees

• Decisions are deterministic
• Evaluation is limited to supplied sources
• Requirements are enforced consistently
• All outcomes are auditable

Verifact does not: execute actions, generate answers, or infer facts beyond provided sources.

Next Steps

• Learn how verification works in detail: Claim Coverage
• Configure enforcement rules: Authorization
• See request/response schemas: API Reference

When to use which endpoint

Verifact exposes two endpoints: /v2/verify and /v2/authorize. Choose the one that matches your use case.

Note: Prefer explicit claims when gating real-world operations. Use /v2/authorize for enforcement, and /v2/verify for per-claim inspection or automated workflows that need granular evidence.