---
title: "Synchronous evidence research"
method: POST
path: "/api/v1/checks/run"
tags: ["checks"]
---

# Synchronous evidence research

`POST /api/v1/checks/run`

## 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/checks/run`
- Auth: none declared

Synchronous evidence research — single HTTP call, blocks until complete.

Recommended for agents and scripts. Submit a claim or URL, wait 60-120s,
receive the full result with claims, elements, evidence, and analytics.
No SSE, no polling, no claim selection required.

For URL/article inputs, claims are auto-selected (top-ranked, up to 5).

Sends nothing until the run finishes, and the edge closes a connection
silent for ~125 s, so a slow run (URL inputs especially) can be cut off
while it completes. Agents: use `/agent/check?async=true` and poll.

**Rate limit:** 10/minute

## Request body

- CreateCheckRequest: Submit content for evidence research.
  - `input_type` string, required: Input type: 'url' (article analysis), 'text' (direct claim), 'image' (OCR), or 'video' (transcript)
  - `content` string, nullable: Claim text (required when input_type is 'text'). Supports both statements and questions. Capped at 10,000 chars to prevent DoS via oversized inputs.
  - `url` string, nullable: URL to analyse (required when input_type is 'url' or 'video'). HTTPS prefix is added automatically if omitted.
  - `file_path` string, nullable: Server path for uploaded images (use POST /upload first)
  - `user_query` string, nullable: Optional Search Clarity question (max 200 chars). When provided, the pipeline generates a focused answer alongside the evidence landscape.
  - `frozen_evidence` object, nullable: Pre-supplied evidence for replay testing (internal use only)

## Response `200`

Complete evidence landscape with claims, elements, and evidence

- CheckResponse: Full check response with claims, evidence, and metadata.
  - `id` string, required: Check ID (UUID)
  - `inputType` 'url' | 'text' | 'image' | 'video', required: Supported input types for evidence research.
  - `inputContent` object, nullable: Original input data
  - `inputUrl` string, nullable: Source URL (if url input type)
  - `status` 'processing' | 'waiting_for_selection' | 'completed' | 'failed', required: Pipeline status values.
  - `creditsUsed` integer, required: Credits consumed by this check
  - `processingTimeMs` integer, nullable: Total pipeline processing time in milliseconds
  - `errorMessage` string, nullable: Error details (only present on failed checks)
  - `entryMode` string, nullable: How the check was initiated: article or direct
  - `selectedClaimsCount` integer, nullable: Number of claims selected for analysis
  - `articleDomain` string, nullable: Primary domain classification of the article
  - `articleSecondaryDomains` string[], nullable: Secondary domain classifications
  - `articleJurisdiction` string, nullable: Detected jurisdiction for adapter routing (UK, US, or global)
  - `articleClassificationSource` string, nullable: How the article domain was classified
  - `userQuery` string, nullable: User's Search Clarity question (if provided)
  - `queryResponse` string, nullable: Search Clarity answer
  - `queryConfidence` number, nullable: Search Clarity confidence score
  - `querySources` object[], nullable: Sources used for Search Clarity answer
  - `queryRelatedClaims` object[], nullable: Claims related to the Search Clarity question
  - `claims` ClaimDetail[], required: Extracted claims with full evidence landscapes
    - `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.
  - `createdAt` string, required: Check creation timestamp (ISO 8601)
  - `completedAt` string, nullable: Check completion timestamp (ISO 8601)
  - `currentStage` string, nullable: Current pipeline stage (only during processing): ingest, extract, retrieve, classify, map, etc.
  - `progress` number, nullable: Pipeline progress percentage (0-100)
  - `progressMessage` string, nullable: Human-readable progress message

## Other responses

- `400`: Invalid input
- `402`: Monthly credit limit reached
- `422`: Validation Error
- `502`: Pipeline error
- `504`: Pipeline timed out (>180s)

---

[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)