Integration Guide

REST API

A FastAPI backend that exposes Mithril's trust-scoring, admission gating, and audit trail over standard HTTP endpoints. Powers the dashboard and can be used by any HTTP client.

Quick Start

Start the API server

terminal

make api
# Windows Makefile runs: .venv\Scripts\python.exe -m uvicorn api.main:app --port 8000 --reload

# macOS / Linux / WSL
python -m uvicorn api.main:app --port 8000 --reload

The server runs at http://localhost:8000. Interactive docs are available at /docs (Swagger UI).

Submit a memory claim

terminal

curl -X POST http://localhost:8000/api/remember \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Passwords must use Argon2id.",
    "source": "Security Policy",
    "author": "policy_admin"
  }'

Query verified memory

terminal

curl -X POST http://localhost:8000/api/recall \
  -H "Content-Type: application/json" \
  -d '{"query": "How should we hash passwords?"}'

Endpoints

These paths are served by the FastAPI backend on localhost:8000. The Next.js dashboard also exposes proxy routes under /api for the UI; use the FastAPI URL directly when calling /api/quarantine.

POST/api/rememberSubmit a memory claim through the trust gate

POST/api/recallQuery verified memory only

GET/api/auditFull audit trail of all evaluated claims

GET/api/quarantineList quarantined / rejected claims

GET/api/reputationLive source reputation scores

GET/api/statsAggregate dashboard metrics

GET/api/configCurrent scoring weights and thresholds

POST/api/resetClear all Cognee memory and audit stores

GET/api/healthHealth check

POST /api/remember

Submit a text claim for trust scoring and conditional storage into Cognee. Returns the admission decision, serialized trust-score breakdown, and any secrets that were redacted.

Request Body

Parameter	Type	Required	Description
`text`	string	required	The memory claim to evaluate (min 1 character).
`source`	string	required	Channel / origin — e.g. "Slack", "Security Policy", "AI Agent".
`author`	string	optional	Who submitted the claim. Defaults to "demo_user".

Example Response

200 OK

{
  "text": "Argon2id with cost factor 12 is now mandatory.",
  "source": "Security Policy",
  "author": "policy_admin",
  "status": "accept",
  "trust_score": 0.89,
  "decision_reason": "Score 0.89 meets acceptance threshold (≥ 0.85)",
  "trust_breakdown": {
    "source_reputation": 0.98,
    "contradiction_penalty": 0.0,
    "corroboration_bonus": 0.1,
    "freshness_bonus": 0.05,
    "source_component": 0.392,
    "corroboration_component": 0.025,
    "freshness_component": 0.0025,
    "contradiction_component": 0.0,
    "raw_weighted_score": 0.4195,
    "final_score": 0.89,
    "reasons": [
      "Source 'Security Policy' live reputation: 0.98",
      "No contradictions found in verified memory",
      "Corroborated by 1 other source(s)",
      "Weighted sum: 0.42 (source 0.39, corroboration +0.03, freshness +0.00, contradiction -0.00, content_danger -0.00)",
      "Normalized trust score: 0.89 (÷ 0.47 max theoretical)"
    ]
  },
  "reasons": ["..."],
  "redacted_secrets": [],
  "entered_cognee": true,
  "cognee_dataset": "verified_memories",
  "timestamp": "2026-07-05T00:00:00+00:00"
}

POST /api/recall

Answers a natural-language question using only claims that passed the trust gate. Blocked / quarantined data is automatically excluded.

Parameter	Type	Required	Description
`query`	string	required	The question to answer from verified memory.

200 OK

{
  "query": "How should we hash passwords?",
  "answer": "Passwords must be hashed using Argon2id with a minimum cost factor of 12.",
  "candidate_count": 3,
  "blocked_count": 2
}

Admission Statuses

✅

accept (≥ 0.85)

High-trust claim stored directly in Cognee verified memory.

⚠️

warn (≥ 0.60)

Stored but flagged — moderate confidence, may need human review.

🔍

review (≥ 0.40)

Held for manual review. Not stored until approved.

🚫

quarantine (≥ 0.20)

Contradicts verified memory or very low trust. Stored in quarantine DB only.

❌

reject (< 0.20)

Extremely low trust. Rejected outright and logged to audit trail.

Default Source Reputation

Each source starts with a prior reputation. Scores adapt over time as claims from that source are accepted or blocked.

Source	Prior Score
Security Policy	0.98
HR System	0.95
Official Docs	0.95
GitHub PR	0.90
Jira	0.85
Engineering Blog	0.80
Internal Wiki	0.75
Slack	0.60
Email	0.55
Customer Support	0.50
AI Agent	0.40
External Email	0.40
Unknown Agent	0.30
Public Web	0.25
Untrusted	0.10