Module — Developer API

Evidence Research for AI Agents

Submit a claim, URL, or article. Get back structured evidence — organised by source tier (primary, reporting, commentary) and type (data, official, news, analysis, academic), with element decomposition and relationship mapping.

One API call.
Multi-source evidence retrieval.
Structured, not summarised.
Your agent decides what matters.

Module — Quick Start

Three Steps

Get an API key

Create a key in your dashboard settings. Your key is shown once — store it in an environment variable immediately:

# Store your key as an environment variable — never hardcode it
export TRU8_API_KEY="tru8_sk_..."

Key security

Your API key carries your identity and usage quota. Treat it like a password.

Store in environment variables or a secrets manager — never in source code
Never commit keys to git, logs, or client-side bundles
If a key is exposed, revoke it immediately in dashboard settings and create a new one
Use separate keys per agent or environment for auditability

Submit a claim

curl -X POST https://api.trueight.com/api/v1/agent/quick \
  -H "X-API-Key: $TRU8_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"claim": "Global average temperature rose 1.1°C since pre-industrial times"}'

Returns structured result with _meta (executedTier, chargedPence)

Retrieve the result

curl https://api.trueight.com/api/v1/agent/result/{check_id} \
  -H "X-API-Key: $TRU8_API_KEY"

Completed checks return the full evidence landscape. Processing checks return status for polling.

Module — Pipeline

What Each Tier Runs

Pipeline stage	Quick	Full
Claim extraction + decomposition	Yes	Yes
Web search (Serper/Brave/SerpAPI)	1 query/element	3 queries/element
Government + academic APIs	No	Yes
Google Fact-Check API	No	Yes
Evidence classification	Heuristic	LLM
LLM relevance scoring	No	Yes
Evidence mapping + orientation	Yes	Yes
Coverage recovery	No	Yes

Lookup and Consensus tiers return previously computed results — no pipeline execution.

Module — MCP Integration

MCP Server

Tru8 exposes three tools via the Model Context Protocol. Any MCP-compatible agent (Claude, GPT, Gemini) can discover and use Tru8 automatically.

tru8_check

Evidence research with tier fallback (lookup → consensus → quick → full). Set max_tier to control depth and cost.

varies

tru8_get_result

Retrieve completed check with pre-computed analytics (_computed block)

<1s

tru8_get_result_raw

Retrieve raw check data without computed analytics

<1s

Configure for Claude Desktop:

{
  "mcpServers": {
    "tru8": {
      "command": "python",
      "args": ["-m", "tru8_mcp"],
      "env": {
        "TRU8_API_KEY": "tru8_sk_..."
      }
    }
  }
}

The env block is injected at server startup — the key is never sent to the model. Your Claude Desktop config file (claude_desktop_config.json) is local-only, but ensure it is excluded from any version control or backup sync that could expose secrets.

Module — Pricing

What You Pay For

Agent API calls are charged per call, deducted from your prepaid credit balance. This is separate from dashboard subscriptions.

Per-call pricing

Lookupinstant

£0.02

Cached prior analysis. Instant hash match on your previous research.

Consensusinstant

£0.03

Cross-user aggregate landscape. Available when 3+ independent checks exist.

Quick~15s

£0.07

Web search + heuristic classification. Fast triage for time-sensitive queries.

Full~60-90s

£0.15

30+ sources, LLM classification, element decomposition, coverage recovery.

How it works

1.Top up your agent credit balance (prepaid, in GBP pence)
2.Each API call deducts the tier price from your balance
3.Use max_tier to cap maximum spend per call
4.You are only charged for the tier actually executed, not the tier requested

Agent credits vs dashboard subscription

Dashboard subscriptions (Starter, Professional) give you a monthly check allowance for the web dashboard. Agent API credits are a separate prepaid balance for programmatic access. Both are available on any account — you can use the dashboard and the API independently.

Module — Async Mode

Non-Blocking Submission

Add ?async=true to /agent/quick or /agent/full to get an immediate 202 response. The pipeline runs in the background — poll for the result when ready.

# Submit async
curl -X POST "https://api.trueight.com/api/v1/agent/full?async=true" \
  -H "X-API-Key: $TRU8_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"claim": "The UK left the EU in 2020"}'

# Response: 202 Accepted
{
  "checkId": "abc-123",
  "status": "processing",
  "tier": "full",
  "chargedPence": 15,
  "pollUrl": "/api/v1/agent/result/abc-123",
  "estimatedSeconds": 60
}

# Poll for result
curl "https://api.trueight.com/api/v1/agent/result/abc-123" \
  -H "X-API-Key: $TRU8_API_KEY"
# While processing: { "status": "processing", "checkId": "abc-123", "hit": false }
# When complete:   { full result payload }

Prefer webhooks over polling — register a callback URL and receive events when checks complete or fail.

Module — Batch Mode

Multi-Claim Submission

Submit up to 10 claims in a single call. All claims run concurrently in the background at the same tier. Each creates its own check with a separate poll URL.

curl -X POST https://api.trueight.com/api/v1/agent/batch \
  -H "X-API-Key: $TRU8_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tier": "quick",
    "claims": [
      { "claim": "Global sea levels rose 3.6mm per year since 2006" },
      { "claim": "The Amazon rainforest produces 20% of world oxygen" },
      { "claim": "Electric vehicles have lower lifetime emissions than petrol cars" }
    ]
  }'

# Response: 202 Accepted
{
  "accepted": 3,
  "tier": "quick",
  "totalChargedCents": 21,
  "estimatedSeconds": 15,
  "checks": [
    { "index": 0, "checkId": "...", "pollUrl": "/api/v1/agent/result/..." },
    { "index": 1, "checkId": "...", "pollUrl": "/api/v1/agent/result/..." },
    { "index": 2, "checkId": "...", "pollUrl": "/api/v1/agent/result/..." }
  ]
}

Upfront balance check

Total cost is verified before any claims are submitted. If your balance can't cover all claims, the entire batch is rejected with 402.

Webhook per claim

Each claim fires its own check.completed or check.failed webhook event independently.

Idempotency in batch

If you send an Idempotency-Key header, each claim receives a derived key (your-key_0, your-key_1, etc). Safe to retry the entire batch on network failure.

Module — Webhooks

Event Notifications

Register a webhook URL in your dashboard settings to receive POST callbacks when checks complete or fail. No polling required.

check.completed

Pipeline finished successfully. Result is ready to retrieve.

{ "checkId": "...", "status": "completed", "tier": "quick" }

check.failed

Pipeline error or timeout. Credits have been refunded.

{ "checkId": "...", "status": "failed", "error": "Pipeline timed out" }

Delivery guarantee

Webhooks are delivered best-effort with automatic retries (3 attempts, exponential backoff). If your endpoint returns a non-2xx status, delivery is retried. Design your handler to be idempotent — you may receive the same event more than once.

Module — Agent Discovery

Self-Service Endpoints

These endpoints let agents inspect the API programmatically — check availability, discover pricing, and verify their own identity before submitting work.

GET

/agent/health

API and dependency status (database, Redis). No auth required.

public

GET

/agent/tiers

Available tiers with per-call pricing (pence) and estimated latency. No auth required.

public

GET

/agent/me

Authenticated identity, provider type, and current credit balance.

auth

GET

/agent/stats

Usage analytics — transactions by tier and provider, total agent checks.

auth

GET

/agent/credits/balance

Current prepaid credit balance in pence.

auth

An agent can call /agent/health to confirm the API is live, then /agent/tiers to discover current pricing, then /agent/me to check its balance — all before submitting a single claim.

Module — Rate Limits

Throttling

Rate limits are applied per API key, not per IP address. Agents sharing a cloud IP won't interfere with each other.

Endpoint group	Limit	Scope
`POST /agent/lookup`	30/minute	Per API key
`POST /agent/quick`	10/minute	Per API key
`POST /agent/full`	5/minute	Per API key
`POST /agent/check`	10/minute	Per API key
`POST /agent/batch`	5/minute	Per API key
`GET /agent/result/*`	30/minute	Per API key
`GET /agent/health, /tiers, /me`	60/minute	Per API key

Pipeline endpoints also enforce a concurrency limit of 5 simultaneous processing checks per API key. If you hit this limit, you'll receive a 429 with aRetry-After: 30 header.

Module — Error Handling

Error Codes

All errors return JSON with a detail field. Agents should handle these programmatically — retry on 429/504, alert on 402, and log on 502.

Code	Meaning	Agent action
401	Missing or invalid API key	Check X-API-Key header
402	Insufficient credit balance	Top up via /agent/credits/purchase
404	Check not found or not owned	Verify check ID and ownership
409	Idempotency key reused with different params	Use a new idempotency key
429	Rate limit or concurrency limit exceeded	Wait for Retry-After header value
502	Pipeline processing error	Retry with same idempotency key
504	Pipeline timed out (no charge)	Retry — consider async mode

Refund policy

Pipeline errors (502) and timeouts (504) are automatically refunded — credits are returned to your balance immediately. Only successful completions are charged.

Module — Response Shape

What You Get Back

{
  "id": "check-uuid",
  "status": "completed",
  "claims": [
    {
      "text": "Global average temperature rose 1.1°C since pre-industrial times",
      "claimType": "statistical",
      "claimMap": {
        "elements": [
          {
            "elementId": "e1",
            "text": "Global average temperature increase",
            "state": "supported",
            "evidenceRefs": [
              {
                "evidenceId": "ev1",
                "relationship": "supports",
                "reasoning": "NASA GISS dataset confirms 1.1°C anomaly..."
              }
            ]
          }
        ],
        "orientation": "Evidence broadly supports this claim..."
      },
      "evidence": [
        {
          "evidenceId": "ev1",
          "title": "GISS Surface Temperature Analysis",
          "url": "https://data.giss.nasa.gov/gistemp/",
          "tier": "primary",
          "evidenceType": "data",
          "snippet": "Global mean surface temperature anomaly..."
        }
      ]
    }
  ],
  "_meta": {
    "executedTier": "quick",
    "chargedPence": 7,
    "limitations": ["heuristic_classification", "no_coverage_recovery"],
    "cached": false,
    "landscape": {
      "sourceDiversity": { "uniqueDomains": 5, "typeCoverage": 3 },
      "freshness": { "freshestDaysAgo": 2, "undatedCount": 1 },
      "gaps": [],
      "providerStatus": null
    }
  },
  "_manifest": {
    "checkId": "check-uuid",
    "landscapeHash": "a1b2c3d4...",
    "signedAt": "2026-03-09T12:00:00Z",
    "signature": "hmac-sha256-...",
    "kid": "tru8-2026-03",
    "verifyUrl": "/verify/check-uuid"
  },
  "_computed": {
    "summary": { "totalElements": 3, "supported": 2, "disputed": 0, "unresolved": 1 },
    "evidenceByTier": { "primary": 4, "reporting": 8, "commentary": 2 },
    "evidenceByType": { "data": 3, "official": 2, "news": 5, "analysis": 3, "academic": 1 },
    "corroboration": { "groups": [...], "convergenceCount": 3 },
    "diagnosticValues": [...]
  }
}

claims[].claimMap

Each claim is decomposed into 1–5 elements. Evidence maps to elements with relationship types (supports/challenges/context) and reasoning.

_meta vs _computed

_meta is always present — tier, cost, limitations, landscape. _computed requires ?computed=true — adds analytics, corroboration, diagnostics.

_manifest

HMAC-signed tamper-evidence. Agents can verify results haven't been modified via GET /verify/{check_id}.

Module — Resources

Documentation

Interactive API Docs

Swagger UI with all endpoints, request/response schemas, and try-it-out.

/api/docs

ReDoc Reference

Clean reference documentation with detailed type definitions.

/api/redoc

Start Building

Create an API key and submit your first check in under a minute.

Get API Key

TRU8 — DEVELOPERS — V1.1