---
title: "Full evidence research (~60-90s)"
method: POST
path: "/api/v1/agent/full"
tags: ["agent"]
---

# Full evidence research (~60-90s)

`POST /api/v1/agent/full`

## Request

- Base URL: `https://api.trueight.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.trueight.com/api/v1/agent/full`
- Auth: none declared

Complete evidence research pipeline — web + specialist APIs, all stages. ~50-70 seconds, £0.15.

Runs the full pipeline: fact-check lookup, web search and specialist providers (government,
academic, news, data APIs), LLM classification, coverage recovery, and
query answering.

Prefer `?async=true`: a 202 Accepted arrives immediately and you poll
`/agent/result/{checkId}` for the completed result. A synchronous call holds
one silent connection for the whole run, and proxies close a connection
idle for ~125 s.

**Response headers:** `X-Check-Id`, `X-Tru8-Tx-Id`

**Rate limit:** 5/minute

## Query parameters

- `async` boolean

## Headers

- `Idempotency-Key` string, nullable

## Request body

- AgentClaimRequest: Submit a claim or URL for evidence research.
  - `claim` string, required: The claim text to analyse, or a URL to extract claims from
  - `input_type` string, nullable: Input type: 'text' or 'url'. Auto-detected from the claim field if omitted.
  - `compact` boolean, nullable: If true, returns claims and claim maps only — no evidence arrays. Reduces payload size for agents that only need orientation.

## Response `200`

Complete evidence landscape (full tier)

- AgentCheckResponse: Full agent response with evidence landscape, metadata, and signed manifest. Returned by /agent/check, /agent/quick, /agent/full, and /agent/lookup (on cache hit). **Note:** In the actual JSON response, the metadata fields are prefixed with underscores: `_meta`, `_manifest`, `_computed`. The schema below shows them without the prefix for documentation purposes.
  - `id` string, required: Check ID (UUID)
  - `status` 'processing' | 'waiting_for_selection' | 'completed' | 'failed', required: Pipeline status values.
  - `claims` ClaimDetail[], required: Claims with full evidence, elements, and orientation
    - `id` string, required: Claim database ID
    - `text` string, required: Original claim text as extracted
    - `position` integer, required: Claim position within the check (0-indexed)
    - `claimMap` ClaimMapSchema: Structured analysis of a single claim — elements, evidence mapping, and orientation.
      - `normalisedClaim` string, required: The claim restated in neutral, verifiable language
      - `claimType` 'empirical' | 'definitional' | 'causal_interpretive' | 'predictive' | 'normative_flagged': Claim type classification.
      - `elements` ClaimElement[], required: 1-5 verifiable sub-questions decomposed from the claim
        - `elementId` string, required: Unique element identifier
        - `description` string, required: The verifiable sub-question this element investigates
        - `state` 'supported' | 'disputed' | 'unresolved', required: Evidence state for a claim element.
        - `evidenceRefs` EvidenceRef[], required: Evidence items mapped to this element with relationship labels
          - `evidenceId` string, required: ID of the referenced evidence item
          - `relationship` 'supports' | 'challenges' | 'context', required: How a piece of evidence relates to an element.
          - `snippet` string, nullable: Key excerpt used for this mapping
        - `uncertaintyNote` string, nullable: Note on limitations or ambiguity in the evidence
        - `bountyText` string, nullable: User-authored note requesting specific evidence for this element (Seeker feature)
        - `basis` object, nullable: Metadata breakdown: evidence count, tier/relationship/classification/content_basis distributions
      - `orientation` string, nullable: Evidence-centred summary derived mechanically from element states (no LLM). Describes what the evidence landscape shows, not a verdict.
      - `orientationBasis` object, nullable: Mechanical derivation data: element state counts and the rule that produced the orientation line
      - `metadata` object, nullable: Claim map metadata (input hash, model version)
    - `claimType` 'empirical' | 'definitional' | 'causal_interpretive' | 'predictive' | 'normative_flagged': Claim type classification.
    - `isSelected` boolean, nullable: Whether this claim was selected for full analysis (article mode)
    - `significanceRank` integer, nullable: Significance ranking within the article (lower = more significant)
    - `subjectContext` string, nullable: Subject area context for the claim
    - `keyEntities` string[], nullable: Key named entities mentioned in the claim
    - `sourceTitle` string, nullable: Title of the source article (URL inputs)
    - `sourceUrl` string, nullable: URL of the source article
    - `sourcesReviewedCount` integer, nullable: Number of raw sources reviewed for this claim before filtering
    - `evidence` EvidenceItem[]: Evidence items organised by the pipeline — classified, mapped, and receipted
      - `id` string, required: Internal database ID
      - `evidenceId` string, required: Stable evidence identifier (URL hash)
      - `source` string, nullable: Human-readable source name (e.g. 'BBC News', 'WHO')
      - `url` string, nullable: Source URL
      - `title` string, nullable: Article or document title
      - `snippet` string, nullable: Relevant excerpt from the source (up to 1,000 characters)
      - `publishedDate` string, nullable: Publication date in ISO 8601 format
      - `relevanceScore` number, nullable: Topical relevance score (1-5 scale). Measures how on-topic the source is, not source authority.
      - `tier` 'primary' | 'reporting' | 'commentary': Source tier classification — structural role of the source.
      - `evidenceType` 'data' | 'official' | 'news' | 'analysis' | 'opinion' | 'academic': Source type classification — content category.
      - `receiptStatus` 'found' | 'extracted' | 'classified' | 'excluded' | 'shown': Pipeline receipt status — tracks evidence through the pipeline.
      - `corroborationGroupId` string, nullable: Group ID linking corroborating sources
      - `corroboratingEvidenceIds` string[], nullable: IDs of sources that corroborate this evidence
      - `isFactcheck` boolean, nullable: Whether this is from a fact-checking organisation
      - `externalSourceProvider` string, nullable: API provider that supplied this evidence (e.g. 'semantic_scholar', 'pubmed')
      - `sourceType` string, nullable: Retrieval method: web_search or api
      - `archivedUrl` string, nullable: Wayback Machine archived URL (auto-archived for permanence)
      - `llmRelevanceScore` number, nullable: Raw LLM relevance score before normalisation
      - `classificationMethod` 'llm' | 'heuristic' | 'api_metadata': How the evidence was classified.
      - `textProvenance` object, nullable: Retained extraction excerpts; not verified relationship citations
      - `contentBasis` 'full' | 'snippet' | 'api' | 'pdf': How the evidence content was obtained.
  - `hit` boolean, nullable: Cache hit indicator (true = served from cache, absent = fresh pipeline run)
  - `meta` AgentMeta, required: Agent response metadata — tier, cost, and landscape summary.
    - `executedTier` 'lookup' | 'consensus' | 'quick' | 'full', required: Agent pipeline tiers — determines depth and cost.
    - `chargedPence` integer, required: Amount charged in pence GBP (0 for free retrievals)
    - `limitations` string[], required: Pipeline stages skipped in quick mode (empty for full tier). Values: heuristic_classification, no_factcheck_lookup, no_api_sources, no_llm_relevance_scoring, no_coverage_recovery, no_query_answering
    - `landscape` LandscapeMetrics, required: Structured summary of the evidence landscape — designed for programmatic consumption.
      - `elementCount` integer, required: Total number of verifiable elements across all claims
      - `elementStates` object, required: Count of elements in each state: supported, disputed, unresolved
      - `evidenceDensity` integer, required: Total evidence items across all claims
      - `sourcesConsidered` integer, required: Total sources reviewed (same as evidenceDensity for organised sources)
      - `sourceDiversity` SourceDiversity, required: Source diversity breakdown within the evidence landscape.
        - `tierSpread` object, required: Count of evidence items per tier (primary, reporting, commentary)
        - `uniqueDomains` integer, required: Number of distinct source domains in the evidence set
        - `typeCoverage` integer, required: Number of distinct source types represented (max 6)
      - `freshness` Freshness, required: Evidence freshness metrics.
        - `freshestDaysAgo` integer, nullable: Days since the most recent dated evidence item
        - `dateSpanDays` integer, nullable: Time span in days between oldest and newest dated evidence
        - `undatedCount` integer, required: Number of evidence items without a publication date
      - `gaps` LandscapeGap[], required: Identified gaps in the evidence landscape (elements without evidence, missing source types)
        - `elementId` string, nullable: Element ID (if element-level gap)
        - `description` string, nullable: Element description (if element-level gap)
        - `claimPosition` integer, nullable: Parent claim position
        - `reason` string, required: Gap type: no_evidence, unresolved, no_primary_sources, or no_academic_sources
        - `evidenceCount` integer, nullable: Evidence count for unresolved elements
      - `providerStatus` object, nullable: Aggregated provider status: which search/API providers succeeded, failed, or timed out during retrieval
    - `cachedFrom` string, nullable: ISO 8601 timestamp of the cached result (present only on lookup hits)
  - `manifest` AgentManifest: HMAC-signed manifest. Verify the signed fields haven't changed since signing via GET /verify/{checkId}.
    - `checkId` string, required: Check ID this manifest covers
    - `landscapeHash` string, required: SHA-256 hash of the canonical evidence landscape
    - `signedAt` string, required: Signing timestamp (ISO 8601)
    - `signature` string, required: HMAC-SHA256 signature (hex)
    - `kid` string, required: Key ID used for signing
    - `verifyUrl` string, required: Relative URL for public verification: /verify/{checkId}
  - `computed` object, nullable: (JSON key: `_computed`) Pre-computed analytics: tier/type distributions, corroboration groups, diagnostic values, timeline, element state summaries

## Other responses

- `202`: Accepted with `?async=true`: {checkId, status, tier, chargedPence, txId, pollUrl}. Poll `pollUrl` (GET /agent/result/{checkId}).
- `402`: Insufficient credits or payment required
- `422`: Validation Error
- `502`: Pipeline error — charge refunded
- `504`: Pipeline timed out — no charge applied

---

[API](https://skmtc.dev/trueight/apis/tru8-evidence-research-api.md) · [All operations](https://skmtc.dev/trueight/apis/tru8-evidence-research-api/llms.txt) · [OpenAPI document](https://skmtc.dev/trueight/apis/tru8-evidence-research-api/revisions/5684065fa01a?raw)