Back to Documentation

API Endpoints

A concise guide to Verifact endpoints: what each one does, when to use it, and short examples.

Verify vs Authorize

Verify

Verification checks whether statements are supported by the evidence you provide. It produces factual support results, not permission.

Returns: Supported / unsupported / ambiguous per claim; Supporting evidence or gaps

Use when: Reports, review, debugging, and presenting evidence

Authorize

Authorization applies requirements to verified statements to decide whether an action or piece of output is allowed, denied, or requires review. Verifact supports two authorization modes: Actions and Output. Use <code>requirements</code> and <code>options</code> to control enforcement.

Returns: Decision: allow / deny / needs_review; Reasons and audit metadata

Use when: Gating actions (refunds, access, transactions) or governing generated text (customer responses, public-facing content)

Verifact separates truth (verification) from permission (authorization). Use "Actions" when you can provide explicit, structured claims to deterministically gate real-world operations (use /v2/authorize). Use "Output" when you are gating LLM-generated text; Verifact will perform best-effort claim extraction from the answer before verification (use /v2/authorize).

Endpoint groups

Verification

Check whether claims are supported by the evidence you provide.

Authorization

Make authorization decisions for Actions (explicit claims) and Output (LLM text). Returns allow/deny/needs_review with detailed evidence, reasons, and metrics.

Jobs & async

Run verification at scale using batch submission and job polling.

Health & status

Basic health endpoints for monitoring.

Verification

Check whether claims are supported by the evidence you provide.

  • Use when you have claims to verify against explicit sources.
  • Get per-claim status, scores, and evidence spans.

Endpoints

  • POST /v2/verify — Verify Actions (explicit claims) against provided sources.
  • POST /v1/verify-claims-batch — Submit many claim-sets for async processing (returns job_id).
Example: Minimal verify request
POST /v2/verify
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "claims": [{ "text": "Paris is the capital of France" }],
  "sources": [
    {
      "source_id": "s1",
      "type": "text",
      "uri": "https://example.com/data/geography/paris.txt",
      "checksum": "sha256:abcdef"
    }
  ]
}
{
  "request_id": "req_abc123",
  "request_hash": "sha256:abc123",
  "verdict": "supported",
  "coverage_score": 1.0,
  "checks": [
    {
      "claim_id": "c1",
      "claim_text": "Paris is the capital of France",
      "coverage": 1.0,
      "citations": [ { "source_id": "s1", "quote": "Paris is the capital of France", "start": 0, "end": 29 } ],
      "evidence": [ { "source_id": "s1", "snippet": "Paris is the capital of France" } ]
    }
  ]
}

Verifact only verifies against evidence you explicitly provide or reference.

Use batch endpoints for large-scale or background processing.

Responses are compact-by-default; include `response: { "mode": "verbose" }` in your request to receive per-claim details.

Authorization

Make authorization decisions for Actions (explicit claims) and Output (LLM text). Returns allow/deny/needs_review with detailed evidence, reasons, and metrics.

  • Verifact returns a decision: allow, deny, or needs_review.
  • Includes evaluated_at timestamp, request_id for correlation, and request_hash for caching.
  • Reasons provide stable codes for programmatic handling.
  • Metrics show latency, claims processed, and sources used.
  • Proceed only on allow; needs_review requires human review.

Endpoints

  • POST /v2/authorize — Authorize Actions (explicit claims) — deterministic, enforcement-oriented
  • POST /v2/authorize — Authorize (LLM or Actions) — verifies claims and applies requirements
Example: authorize-output example (customer support response)
POST /v2/authorize
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "action": { "type": "refund", "params": { "order_id": "order_1842", "amount": 49.99, "currency": "USD" } },
  "claims": [ { "text": "We can refund purchases within 30 days of the order date. Please provide your order number and we'll process the refund." } ],
  "sources": [{ "source_id": "refund_policy_v3", "type": "text", "text": "Refunds are permitted within 30 days of purchase." }],
  "options": { "min_coverage": 0.85 }
}
{
  "request_id": "req_1234567890abcdef",
  "request_hash": "sha256:abc123def456",
  "decision": "allow",
  "reason": "coverage_sufficient",
  "coverage_score": 1.0,
  "diagnostics": [
    { "claim_id": "c1", "claim_text": "We can refund purchases within 30 days of the order date.", "coverage": 1.0, "citations": [{ "source_id": "refund_policy_v3", "quote": "Refunds are permitted within 30 days of purchase." }], "evidence": [{ "source_id": "refund_policy_v3", "snippet": "Refunds are permitted within 30 days of purchase." }] }
  ],
  "audit": { "record_id": "cc50711e-e6c0-4b9f-bf3f-0123456789ab", "record_hash": "sha256:32514406a64...", "key_id": "audit_v2", "merkle_root": "sha256:5b0ab5785e0b...", "proof": [ { "hash": "sha256:aaa111...", "position": "left" }, { "hash": "sha256:bbb222...", "position": "right" } ] }
}

Actions vs Output: Use /v2/authorize for both Actions (explicit claims) and Output (LLM text). Provide explicit claims for deterministic enforcement; provide an answer for best-effort claim extraction. Output is governance-oriented, Actions are enforcement-oriented and more deterministic.

Response includes request_id (correlates with X-Request-ID header), request_hash (SHA-256 fingerprint), and evaluated_at (server UTC time).

Reasons use stable codes such as unsupported_claims, missing_citations, fetch_failed, and policy_violation.

Metrics provide observability: latency_ms, claims_total, claims_supported, sources_total.

Responses are compact-by-default and omit claims/citations/diagnostics. To receive full details include `response: { "mode": "verbose" }` in your request body.

To obtain the canonical signed Merkle proof and batch signature, call `GET /v2/audit/{record_id}/proof` and fetch the signing key via `GET /v2/audit/keys/{key_id}`.

Jobs & async

Run verification at scale using batch submission and job polling.

  • Use batch endpoints for bulk verification and nightly audits.
  • Poll job status to retrieve results when complete.

Endpoints

  • POST /v1/verify-claims-batch — Submit many verification requests (returns job_id).
  • GET /v2/jobs/{job_id} — Poll job status and retrieve results.
Example: Submit a batch
POST /v1/verify-claims-batch
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{ "jobs": [ { "claims": [{ "text": "Claim 1" }], "sources": [{ "id": "s1", "text": "..." }] } ] }
{
  "job_id": "88ac7904-1371-48e7-a66b-2a2507a4216a",
  "status": "queued"
}

Supports Idempotency-Key header to avoid duplicate work.

Health & status

Basic health endpoints for monitoring.

  • Lightweight endpoints useful for load balancers and uptime checks.

Endpoints

  • GET /health — Simple health check (returns healthy/ok).
  • GET /health/detailed — Detailed health with component checks.

These endpoints are typically unauthenticated and used for monitoring.

Related docs

Sources & Auditing
How Verifact treats sources and audit proofs
Authorization
How decisions are made and why
API Reference
Endpoints, schemas, and examples