Getting Started

This page explains how to integrate Factara into an AI agent or automated system so that real-world actions are only executed when they are sufficiently justified.

Overview

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

The proposal consists of:

Claims — explicit statements that must be supported for the action to be allowed
Sources — the only material Factara is allowed to rely on
Requirements & options — enforcement rules and runtime flags defining what “sufficient support” means

Factara 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

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)
Your system constructs a proposal
Claims that must be supported for the action to be allowed
Factara verifies the proposal
Claims are evaluated against the provided sources
Requirements are applied
Coverage thresholds, citation requirements, and enforcement rules are applied
Factara returns a decision
allow, deny, or needs_review, plus reasons and audit metadata
Your system enforces the outcome
Execute, block, or route for human review

Factara 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 jane.partner@northbridge.vc because it contains only public data and no customer PII."

The proposal sent to Factara might be:

curl -sS -X POST "https://factara-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": "jane.partner@northbridge.vc",
        "channel": "email"
      }
    },
    "claims": [
      { "id": "c1", "text": "report_123 is approved for external sharing." },
      { "id": "c2", "text": "jane.partner@northbridge.vc is allowed to receive report_123." },
      { "id": "c3", "text": "The latest DLP scan for report_123 found no PII." }
    ],
    "sources": [
      { "source_id": "src_data_classification_policy_v2" },
      { "source_id": "src_recipient_allowlist_q1_2026" },

      {
        "type": "context",
        "title": "Report ACL snapshot (generated by pipeline)",
        "data": {
          "resource": "reports/report_123",
          "exported_at": "2026-01-24T00:19:10Z",
          "owner": "finance@company.com",
          "external_sharing_allowed": true,
          "allowed_external_domains": ["northbridge.vc"],
          "allowed_external_recipients": ["jane.partner@northbridge.vc"]
        },
        "meta": {
          "content_type": "application/json",
          "system": "acl-exporter",
          "report_id": "report_123"
        }
      },
      {
        "type": "context",
        "title": "DLP scan results for report_123",
        "data": {
          "scanner": "acme-dlp",
          "scan_id": "dlp_7f1c19",
          "scanned_at": "2026-01-24T00:19:03Z",
          "status": "pass",
          "pii_findings": []
        },
        "meta": {
          "content_type": "application/json",
          "system": "acme-dlp",
          "report_id": "report_123"
        }
      }
    ],
    "requirements": {
      "min_claim_coverage": 0.9,
      "citations": { "required": true, "min_citations_per_claim": 1 }
    },
    "options": {
      "evidence_limit": 4,
      "deny_if_any_unsupported": true
    }
  }' | jq .

Notes: The canonical reference field is source_id. In v2 semantics, checksum represents a content-level hash of the extracted/normalized text. raw_checksum is the sha256 of raw upload bytes and is mainly useful for upload integrity.

Deterministic verification (default)

Factara 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.

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.

“Order #1842 was charged twice for the same amount within 24 hours.”
“Refunds are allowed only if (now - purchase_date) <= 30 days.”
“Refund amount $650 requires approval by a user with role Support_Manager.”
“digital_download_accessed is false for order #1842.”

Sources

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

Factara uses only the sources you supply. For URLs, verification/authorization will not fetch by default; you must opt in via options.allow_network.
Inline context is provided as a source (e.g., logs, ACL snapshots, payment facts) so claims can cite it.
Factara will not browse external sites or retrieve additional material beyond the supplied sources.
Factara 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 evidence limits

Requirements are deterministic and enforced by your system; LLMs cannot override them. Options tune runtime behavior (for example, adjusting evidence limits).

Decisions

allow

The proposal meets requirements. Your system may proceed with the action.

deny

The proposal violates requirements (for example, insufficient support). Your system must not execute the action.

needs_review

Support is incomplete or the action is sensitive. Your system should pause execution and route for human review.

Factara returns reasons and audit metadata with every decision.

How Actions Are Blocked

Factara does not block actions directly. Actions are blocked because your system does not execute them unless Factara 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

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

When to use which endpoint

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

Verify — use `/v2/verify`

Request per-claim verification results (coverage, citations, errors). Use when you want detailed evidence, debugging, or to pre-validate claims before enforcing requirements.

Authorize — use `/v2/authorize`

Request a single decision (allow/deny/needs_review) after applying requirements. Use when gating real-world actions or LLM output. Provide requirements and options to control enforcement.

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