Data types

Field shapes below are taken from the live /v1/sample/news payload, which mirrors the production feed exactly.

Story object

The core record returned by /v1/news, /v1/search, and every /stories endpoint.

Field	Type	Notes
id	string	Stable identifier. Always present, and always returned even when fields omits it.
slug	string	URL-safe identifier. Accepted anywhere {idOrSlug} appears.
title	string	Headline.
excerpt	string	Short summary.
body	string	Full text. Heavy — excluded unless include=body or include=full.
category	string	Normalized category, e.g. Technology.
country	string	Primary country, or Global.
author	string	Byline, e.g. TNL Bot.
publishedAt	string	ISO 8601 UTC.
updatedAt	string	ISO 8601 UTC. Moves when the story is revised.
revision	number	Increments on each revision. Starts at 1.
verificationState	string	Verification status, e.g. verified.
truthPosterior	number	0–1. Modeled probability the account is accurate.
urgencyScore	number	0–1. Modeled urgency.
impactedAssets	string[]	Tickers/identifiers, e.g. ["NVDA", "ASML"].
impactedSectors	string[]	Sector names, e.g. ["Semiconductors"].
impactPaths	string[]	Causal chains as prose, e.g. "Export controls -> equipment demand -> production capacity".
entities	object[]	Entities referenced. See below.
sources	object[]	Citations. Heavy — needs include=sources.
claims	object[]	Extracted claims. Heavy — needs include=claims.
contradictions	object[]	Conflicts between sources. Empty array when none.

truthPosterior and urgencyScore are modeled

Both are model output, not measurements. truthPosterior is a probability estimate, not a fact-check verdict. Treat them as ranking signals rather than ground truth, and do not present either as a factual guarantee to end users.

entities[]

Field	Type	Notes
id	string	Entity identifier. Use with /v1/entities/{idOrSlug}/stories.
name	string	Display name, e.g. Example Trade Authority.
type	string	Entity kind, e.g. organization, country, person.

sources[]

Field	Type	Notes
id	string	Source identifier.
name	string	Publisher name.
url	string	Canonical URL of the cited item.

claims[]

Field	Type	Notes
id	string	Claim identifier.
text	string	The extracted claim.

contradictions[]

Populated when cited sources disagree. An empty array means no contradiction was detected — not that sources were checked and agreed.

Example story

{
  "id": "sample-story-1",
  "slug": "sample-semiconductor-controls",
  "title": "Sample: semiconductor equipment controls expand",
  "excerpt": "A synthetic policy event illustrates source-linked claims and downstream asset paths.",
  "category": "Technology",
  "country": "Global",
  "author": "TNL Bot",
  "publishedAt": "2026-07-15T08:00:00.000Z",
  "updatedAt": "2026-07-15T08:30:00.000Z",
  "revision": 2,
  "verificationState": "verified",
  "truthPosterior": 0.94,
  "urgencyScore": 0.72,
  "impactedAssets": ["NVDA", "ASML"],
  "impactedSectors": ["Semiconductors", "Capital Equipment"],
  "impactPaths": ["Export controls -> equipment demand -> production capacity"],
  "entities": [
    { "id": "sample-entity-1", "name": "Example Trade Authority", "type": "organization" }
  ],
  "sources": [
    { "id": "sample-source-1", "name": "Synthetic Public Register", "url": "https://example.com/tnl-sample" }
  ],
  "claims": [
    { "id": "sample-claim-1", "text": "The fictional control list expands to two equipment categories." }
  ],
  "contradictions": []
}

List envelope

Every list endpoint wraps results identically:

{
  "data": [ /* story objects */ ],
  "page": { /* see Pagination */ }
}

See Pagination for the page object.

Conventions

Timestamps are ISO 8601 in UTC with milliseconds (2026-07-15T08:00:00.000Z). Every filter accepting a date takes the same format.

Identifiers — anywhere the path says {idOrSlug}, either the id or the slug works. Slugs are readable but can change on revision; ids are stable. Store the id.

Nullability — cursor, next_cursor, monthlyLimit, remaining, and MCP publishedAt are nullable. Array fields are empty arrays rather than null.

Scores — truthPosterior and urgencyScore are floats in 0–1 inclusive.