Documentation

POST /generate

Generate polished, truth-grounded content.

{
  "prompt": "Write a short essay on Bitcoin",
  "format": "essay",           // essay, summary, bullet_points, report, answer
  "tone": "professional",      // professional, casual, academic
  "max_words": 500,
  "mode": "fast"               // fast, balanced, deep
}

Response:

{
  "content": "Bitcoin, a digital cryptocurrency...",
  "format": "essay",
  "grounding_status": "corrected", // verified, corrected, or unverifiable
  "corrections_made": [
    {
      "wrong_claim": "Bitcoin is backed by gold",
      "correct_fact": "Bitcoin is not backed by physical assets",
      "source": "https://investopedia.com/..."
    }
  ],
  "confidence_score": 0.95,
  "citations": [
    {
      "id": "src_1",
      "url": "https://investopedia.com/...",
      "title": "Bitcoin Definition",
      "trust_tier": "tier_2",
      "snippet": "..."
    }
  ],
  "sources_used": 4,
  "models_consulted": 3,
  "factual_queries": ["What is Bitcoin?", "What is Bitcoin backed by?"],
  "latency_ms": 14000
}

Key Concept: Hallucination Correction. If the internal arbitration models hallucinate a fact (e.g. they all claim the current US President is Joe Biden), the grounding engine detects the contradiction with web evidence, flags the claim as `CRITICAL`, and extracts the true fact (Donald Trump). The synthesis engine is then forced to use the corrected fact in the final content. These corrections are returned in the corrections_made array for transparency.

POST /v1/verify

Submit one or more model outputs and receive a structured trust verdict with explicit action guidance.

Optional request fields include domain_risk_class, tenant_id, allow_escalation, and policy_overrides; each output may include cited_sources (URLs).

{
  "query": "Does the EU Pro plan include feature X?",
  "domain": "policy",
  "mode": "balanced",
  "outputs": [
    {"model":"gpt-4o","provider":"openai","claim":"Yes...","confidence":0.90},
    {"model":"claude-3-5-sonnet","provider":"anthropic","claim":"No...","confidence":0.86}
  ]
}

Response (illustrative; arrays/objects may be longer in production):

{
  "schema_version": "1.0.0",
  "run_id": "v_ab12cd34ef56",
  "created_at": "2026-01-15T12:00:00+00:00",
  "safe_to_display": false,
  "risk_level": "HIGH",
  "recommended_action": "HUMAN_REVIEW",
  "confidence_score": 0.42,
  "consensus_claim": "",
  "warnings": ["Multiple models disagree on material facts."],
  "failure_modes": [
    {
      "kind": "search_outage",
      "description": "Live evidence fetch degraded.",
      "severity": "HIGH",
      "related_atom_ids": ["a_abc123def0"]
    }
  ],
  "blocked_atoms": [],
  "edit_suggestions": [],
  "atoms": [
    {
      "id": "a_abc123def0",
      "text": "The EU Pro plan includes feature X.",
      "type": "fact",
      "sensitivity": "medium",
      "source_models": ["gpt-4o"]
    }
  ],
  "atom_verdicts": [
    {
      "atom_id": "a_abc123def0",
      "status": "conflicting",
      "authority_summary": {"tier_1": 0, "tier_2": 1, "tier_3": 0, "tier_4": 0},
      "nli_summary": {"entailment": 0, "contradiction": 1, "neutral": 0},
      "diversity_groups": 1,
      "freshness_ok": true,
      "notes": []
    }
  ],
  "evidence": [
    {
      "id": "e_xyz789",
      "url": "https://example.com/pricing",
      "hostname": "example.com",
      "authority_tier": "tier_2",
      "diversity_group": "example.com",
      "title": "",
      "snippet": "...",
      "relevance": 0.71,
      "nli_label": "contradiction",
      "nli_confidence": 0.82,
      "is_outdated": false
    }
  ],
  "models_used": ["gpt-4o", "claude-3-5-sonnet"],
  "policy": {
    "version": "1.0.0",
    "rules_fired": ["evidence.search_outage"],
    "domain_risk_class": "HIGH",
    "mode_used": "balanced",
    "escalated": false,
    "escalation_reason": null
  },
  "uncertainty": {
    "disclaimer": "Groundr reduces risk by arbitrating AI outputs and checking sources; it does not guarantee factual truth.",
    "notes": ["Review cited sources before acting."]
  },
  "atomizer_version": "1.0.0",
  "latency_ms": 1840,
  "cost_estimate_cents": 0.0
}

POST /v1/verify/{run_id}/override

Record what the user did after seeing the verdict. Powers override-rate KPI.

{"user_action_taken": "HUMAN_REVIEW"}

Use user_action_taken to describe the host product action. Common pattern: when the user explicitly followed Groundr, send the same string as recommended_action from the verify response (SHOW, SHOW_WITH_WARNING, EDIT_SUGGESTED, HUMAN_REVIEW, or BLOCK). Send IGNORED when the user dismissed or overrode Groundr's guidance (not an enum value on the verify response, but accepted here for analytics).

GET /v1/kpis

Returns operational trust KPIs (false-safe rate, interception rate, action mix, override rate, p95 latency). See Authentication for when X-API-Key is required.

GET /v1/audit/{tenant_id}

Tenant-scoped decision replay export for governance and compliance review.

GET /v1/providers/me/report

Provider-isolated feedback report. Requires X-Provider-Token.

GET /v1/health

Health and schema/policy version metadata for the v1 stack.

POST /validate/query

Legacy query arbitration endpoint.

POST /validate/

Legacy multi-output validation endpoint.

GET /validate/health

Legacy health endpoint.

POST /validate/query             -> POST /v1/verify (supply outputs[] or host-generated drafts)
GET  /validate/health            -> GET  /v1/health
legacy UI verdict parsing        -> use recommended_action + policy.rules_fired + uncertainty.notes

POST /agents

Register a new AI agent with the negotiation engine.

{
  "agent_id": "gpt-4",
  "name": "GPT-4 Turbo",
  "expertise": {"geography": 0.9, "finance": 0.85}
}

GET /agents

List all registered agents with reputation info, wins, losses, and active assertions.

GET /agents/{agent_id}/reputation

Get detailed reputation breakdown for a specific agent, including win rate and expertise scores.

POST /assertions

Submit an assertion from a registered agent.

{
  "agent_id": "gpt-4",
  "domain": "geography",
  "claim": "Lusaka is the capital of Zambia",
  "confidence": 0.98,
  "evidence": [
    {
      "source": "https://en.wikipedia.org/wiki/Zambia",
      "reliability": 0.85,
      "verification_tier": "verified",
      "is_truth_anchor": false
    }
  ]
}

POST /negotiate

Trigger the full negotiation pipeline: detect conflicts and resolve them. Supports all strategies.

{
  "strategy": "majority_vote"
}
// Valid strategies: "majority_vote", "bayesian_update", "weighted_consensus"

GET /shared-reality

Retrieve the current "Shared Reality" — all verified, arbitrated truths across all domains.

GET /conflicts

List all detected conflicts with semantic similarity scores between competing claims.