Filtering & field shaping

List endpoints share one filter vocabulary. Combining filters narrows results — they are ANDed, not ORed.

Filters

Parameter	Description	Example
q	Full-text query across titles, summaries, entities, tags, and impact paths.	tariff
country	G20 country filter, drawn from the story's passive entities.	Japan
category	Normalized story category.	Trading & Markets
entity	Passive entity text or id.	Federal Reserve
impact_path	Impact path text, id, or lookup token.	oil
tag	Normalized story tag.	tariff
published_since	Published at or after this ISO timestamp.	2026-05-01T00:00:00Z
published_until	Published at or before this ISO timestamp.	2026-05-31T23:59:59Z
updated_since	Updated at or after this ISO timestamp.	2026-05-01T00:00:00Z
updated_until	Updated at or before this ISO timestamp.	2026-05-31T23:59:59Z
sort	pipeline for newest first, popular for 12-hour freshness-bucketed popularity.	popular

Discover valid values

GET /v1/filters returns the available filter vocabulary — the countries, categories, and tags actually present in the corpus. Prefer it over hardcoding strings.

Incremental sync

updated_since is the parameter for staying in sync. Stories are revised after publication — revision increments and updatedAt moves — so polling on published_since alone will miss corrections.

curl -sS -G "https://theneuralledger.com/v1/news" \
  -H "Authorization: Bearer $TNL_API_KEY" \
  --data-urlencode "updated_since=2026-07-25T00:00:00Z" \
  --data-urlencode "sort=pipeline" \
  --data-urlencode "page_size=100"

Shaping the response

Two parameters control payload size. They solve different problems.

fields — an allowlist

Comma-separated list of exactly the fields you want. id is always included when present.

fields=id,title,publishedAt,impactPaths

include — heavy field groups

The heavy fields are excluded by default. include adds them back:

Value	Adds
sources	The sources array
claims	The claims array
impactDetails	Expanded impact path detail
body	Full story body
full	Every field

include=sources,claims

Which to use

• Building a list view → fields, naming only what you render.
• Building a detail view → include=full on the single-story endpoint.
• Ingesting into a warehouse → include=full with cursor pagination.

# Compact list
curl -sS -G "https://theneuralledger.com/v1/news" \
  -H "Authorization: Bearer $TNL_API_KEY" \
  --data-urlencode "fields=id,title,publishedAt,urgencyScore" \
  --data-urlencode "page_size=50"

# Full detail for one story
curl -sS -G "https://theneuralledger.com/v1/news/sample-semiconductor-controls" \
  -H "Authorization: Bearer $TNL_API_KEY" \
  --data-urlencode "include=full"

Filtering by relationship

Some relationships have dedicated endpoints that are clearer than a filter:

Goal	Endpoint
Stories touching an entity	GET /v1/entities/{idOrSlug}/stories
Stories along an impact path	GET /v1/impact-paths/{idOrSlug}/stories
Stories affecting an asset	GET /v1/assets/{idOrSlug}/stories

Resolve the identifier first with GET /v1/entities?q=… or GET /v1/impact-paths?q=…. All three accept the same filter and pagination parameters as /v1/news.