Skip to content

Objects

Times are ISO 8601 in UTC. Ids are stable. A field listed here is always present; one that can be empty is marked or null. New fields can be added within version 1 (Versioning), so ignore fields you do not know.

Object Returned by
Signal GET /signals
Story GET /stories
Story (in full) GET /stories/{id}
Outlook GET /outlooks
Forecast GET /forecasts, and in a story’s forecasts
Coordination finding GET /coordination
Party a coordination finding’s orchestrator, orchestrator_allies and target
Report (in a list) GET /reports
Report GET /reports/{id}
Source GET /sources and POST /sources
Source item GET /sources/items
Workspace GET /workspace
Error every error

One article in the workspace’s scope. Returned by GET /signals.

Field Type Values What it is
id integer The article’s id. Stable.
title string The headline as the outlet published it, in its own language.
url string (url) The article’s address on the outlet’s site.
published_at string (time) When the outlet published it (UTC).
language string or null ISO 639-1 code of the headline’s language (en, hi, ta …), or null where it was not detected.
outlet object Who published it.
outlet.id string The outlet’s stable slug.
outlet.name string The outlet’s name.
sectors array of strings a sector key Sectors the article was read as touching. Can be empty.
states array of strings a state slug States and union territories the article is about. Empty when it names none (national or foreign news).
story object or null The story the article was grouped into, or null while it stands alone.
story.id integer The story’s id; pass it to GET /stories/{id}.
story.label string The story’s headline.
story.independent_outlets integer How many independent outlets carry the story.

Articles about one event, grouped. Returned by GET /stories.

Field Type Values What it is
id integer The story’s id. Stable: when two stories merge, the old id still answers on GET /stories/{id}.
label string A headline for the story, from its most representative article.
independent_outlets integer Outlets carrying the story independently: syndicated wire copy and copy credited to a news agency count once.
articles integer Every article in the story, syndicated copies included.
trajectory string or null new, rising, steady, decaying Where coverage is heading: new, rising, steady or decaying.
first_seen string (time) The first article’s publication time.
last_seen string (time) The latest article’s publication time.
sectors array of strings a sector key Sectors the story touches.
states array of strings a state slug States and union territories the story is about.
place string or null The story’s main place (a city, district or state), or null.
risk_score integer or null 0 to 100: how much disruption the reporting describes, read by Alethman. Higher is more severe. Comparable across sectors and over time.
risk_level string or null low, guarded, elevated, high, severe The band the score falls in: low, guarded, elevated, high or severe. Use it as the headline; band edges are not published and may be tuned.
reading string or null One sentence: what happened, in plain English whatever the articles’ language.
event_type string or null protest, strike_bandh, violence_attack, security_operation, policy_decision, court_ruling, election_politics, economic_indicator, corporate_move, trade_action, disaster_accident, crime, diplomatic, other What kind of event the story is.

One story in full. Returned by GET /stories/{id}.

Field Type Values What it is
id integer The story’s current id. Differs from requested_id when the story you asked for was merged into this one.
requested_id integer The id you asked for.
label string The story’s headline.
proposition string or null The claim at the centre of the coverage, as one sentence outlets can agree or disagree with.
independent_outlets integer Independent outlets carrying it.
articles_count integer Every article in it.
trajectory string or null new, rising, steady, decaying Where coverage is heading: new, rising, steady or decaying.
first_seen string (time) The first article’s time.
last_seen string (time) The latest article’s time.
tag object or null How Alethman read the story, or null before it is read.
tag.sectors array of strings a sector key Sectors it touches.
tag.event_type string or null protest, strike_bandh, violence_attack, security_operation, policy_decision, court_ruling, election_politics, economic_indicator, corporate_move, trade_action, disaster_accident, crime, diplomatic, other What kind of event the story is.
tag.theme string or null A slug for its theme.
tag.risk_score integer or null 0 to 100: how much disruption the reporting describes, read by Alethman. Higher is more severe. Comparable across sectors and over time.
tag.risk_level string or null low, guarded, elevated, high, severe The band the score falls in: low, guarded, elevated, high or severe. Use it as the headline; band edges are not published and may be tuned.
tag.risk_basis string or null One sentence: what in the reporting the risk reading rests on.
tag.reading string or null One sentence: what happened.
tag.coordinated boolean True when the story is part of a coordination finding.
tag.coordination_basis string or null Why, when coordinated is true; else null.
tag.named_by_reporting array of objects The parties the reporting names, each with its role and how it is attributed.
tag.named_by_reporting[].kind string What the party is (as Party.kind).
tag.named_by_reporting[].name string The party’s name.
tag.named_by_reporting[].role string Its role (as Party.role).
tag.named_by_reporting[].article_ids array of integers The articles that name it so.
tag.named_by_reporting[].attribution string official_statement, claim_by_actor, reported, alleged_by_opponent, speculation How the reporting attributes the role, strongest first: official_statement, claim_by_actor (the party’s own claim), reported (plain reporting), alleged_by_opponent, speculation.
summary string or null A paragraph: what happened, where outlets agree and where they differ.
places array of objects Places the story names.
places[].name string The place’s name.
places[].kind string city, district, state and so on.
places[].state string or null The state it is in.
places[].primary boolean True for the story’s main place.
articles array of objects Every article in the story, newest first.
articles[].id integer The article’s id.
articles[].title string Its headline.
articles[].url string (url) Its address.
articles[].outlet string The outlet’s name.
articles[].published_at string (time) When it was published.
articles[].language string or null Its language.
articles[].wire string or null The news agency it credits (PTI, ANI, Reuters …), or null for the outlet’s own reporting.
bloc_finding object or null How coverage of the proposition divides, or null when not yet read.
bloc_finding.statement string Whether coverage splits into camps, and how.
bloc_finding.evidence_grade string A, B, C, D A to D, strongest first: how clearly coverage splits. D: no split.
bloc_finding.coordination_likelihood string low, moderate, elevated low, moderate or elevated: how far the split looks organised rather than ordinary disagreement.
bloc_finding.what_would_change string What new coverage would change the finding.
by_country array of objects The coverage by the home country of its outlets.
by_country[].country string ISO 3166-1 alpha-3 code of the outlets’ home country.
by_country[].articles integer Articles from that country’s outlets.
by_country[].voices integer Independent outlets from that country.
by_country[].supports integer Of those read for stance: outlets that support the proposition.
by_country[].opposes integer Outlets that oppose it.
by_country[].neutral integer Outlets that report it without a side.
by_country[].labelled integer Articles read for stance.
by_country[].frame string or null How that country’s outlets frame the story, in a few words.
forecasts array of objects Forecasts made about this story.
forecasts[].id integer The forecast’s id.
forecasts[].sector string a sector key A sector key. See Countries and scopes for the list.
forecasts[].question string A yes-or-no question with a date in it.
forecasts[].probability number 0 to 1 The probability of yes when the forecast was made, 0 to 1. It is never revised.
forecasts[].made_at string (time) When the forecast was made.
forecasts[].resolves_by string (time) The deadline.
forecasts[].resolution_rule string What counts as yes, written before the outcome was known.
forecasts[].status string open, awaiting, resolved open: the deadline is ahead. awaiting: the deadline has passed and no verdict is in yet. resolved: judged.
forecasts[].resolved_at string (time) or null When it was judged, or null.
forecasts[].outcome boolean or null True if it came true, false if not; null until resolved, or when a resolved forecast was voided.
forecasts[].verdict string or null The judgement in a sentence, with what it rests on, or null.
forecasts[].rationale string Why the probability was set where it was, written when it was made.

The latest reading for one of the workspace’s sectors. Returned by GET /outlooks.

Field Type Values What it is
sector string a sector key A sector key. See Countries and scopes for the list.
name string The sector’s name.
quiet boolean True when the sector had too little reporting in its window to read: the score, level, direction and verdict are then null.
risk_score integer or null 0 to 100: how much disruption the reporting describes, read by Alethman. Higher is more severe. Comparable across sectors and over time.
risk_level string or null low, guarded, elevated, high, severe The band the score falls in: low, guarded, elevated, high or severe. Use it as the headline; band edges are not published and may be tuned.
previous_score integer or null The score of the reading before this one, or null for a first reading.
direction string or null rising, steady, easing, new How this reading compares with the one before: rising, steady, easing, or new for a first reading.
verdict string or null A short paragraph: what is driving the sector now and what to watch.
drivers array of objects The stories driving the reading, most important first.
drivers[].story_id integer A story id; pass it to GET /stories/{id}.
drivers[].label string The story’s headline.
drivers[].why string One line: why this story moves the sector.
stories_read integer How many stories the reading weighed.
open_forecasts integer Open forecasts in this sector.
generated_at string (time) or null When the reading was made.

A dated, checkable forecast. Returned by GET /forecasts, and in a story’s forecasts.

Field Type Values What it is
id integer The forecast’s id.
sector string a sector key A sector key. See Countries and scopes for the list.
question string A yes-or-no question with a date in it.
probability number 0 to 1 The probability of yes when the forecast was made, 0 to 1. It is never revised.
made_at string (time) When the forecast was made.
resolves_by string (time) The deadline.
resolution_rule string What counts as yes, written before the outcome was known.
status string open, awaiting, resolved open: the deadline is ahead. awaiting: the deadline has passed and no verdict is in yet. resolved: judged.
resolved_at string (time) or null When it was judged, or null.
outcome boolean or null True if it came true, false if not; null until resolved, or when a resolved forecast was voided.
verdict string or null The judgement in a sentence, with what it rests on, or null.
rationale string Why the probability was set where it was, written when it was made.

A coordination finding: stories the reporting links into one pattern. Returned by GET /coordination.

Field Type Values What it is
id integer The finding’s id.
label string A short label for the finding.
pattern string same_actor, same_theme, called_action What joins its stories: same_actor (the reporting names one party in each), same_theme (a shared theme and sector), or called_action (one action described as called or multi-site).
theme string or null A slug for the shared theme.
grade string A, B, C The evidence grade, strongest first. A: strongest support in the reporting. B: a pattern across stories or places. C: an early pattern to watch, not yet a finding to rely on. A grade says how much the reporting supports a pattern, not that anyone coordinated it.
verdict string The finding in a sentence or two.
orchestrator object or null The party the reporting names as running it, or null when no one is named.
orchestrator.kind string organisation, movement, party, state_agency, armed_group, union, company, public_official, public_figure What the party is: an organisation, movement, party, state agency, armed group, union, company, public official or public figure.
orchestrator.name string The party’s name as the reporting gives it.
orchestrator.role string organiser, claimant, blamed, accused, target, responder The role the reporting gives it in this finding.
orchestrator.stories integer In how many of the finding’s stories it has that role.
orchestrator.attribution string official_statement, claim_by_actor, reported, alleged_by_opponent, speculation How the reporting attributes the role, strongest first: official_statement, claim_by_actor (the party’s own claim), reported (plain reporting), alleged_by_opponent, speculation.
orchestrator_allies array of objects Parties named alongside the orchestrator in the same role.
orchestrator_allies[].kind string organisation, movement, party, state_agency, armed_group, union, company, public_official, public_figure What the party is: an organisation, movement, party, state agency, armed group, union, company, public official or public figure.
orchestrator_allies[].name string The party’s name as the reporting gives it.
orchestrator_allies[].role string organiser, claimant, blamed, accused, target, responder The role the reporting gives it in this finding.
orchestrator_allies[].stories integer In how many of the finding’s stories it has that role.
orchestrator_allies[].attribution string official_statement, claim_by_actor, reported, alleged_by_opponent, speculation How the reporting attributes the role, strongest first: official_statement, claim_by_actor (the party’s own claim), reported (plain reporting), alleged_by_opponent, speculation.
mediums array of objects The outlets carrying the finding hardest, most first.
mediums[].outlet string The outlet’s name.
mediums[].articles integer Its articles in the finding.
mediums[].stories integer The finding’s stories it carried.
mediums[].share number Its share of the finding’s articles, 0 to 1.
mediums[].lift number or null Its share of this finding against its usual share of protest, strike and attack coverage: above 1 means it carries this more than usual. Null when there is too little history to compare.
target object or null The party the reporting names as its target, or null.
target.kind string organisation, movement, party, state_agency, armed_group, union, company, public_official, public_figure What the party is: an organisation, movement, party, state agency, armed group, union, company, public official or public figure.
target.name string The party’s name as the reporting gives it.
target.role string organiser, claimant, blamed, accused, target, responder The role the reporting gives it in this finding.
target.stories integer In how many of the finding’s stories it has that role.
target.attribution string official_statement, claim_by_actor, reported, alleged_by_opponent, speculation How the reporting attributes the role, strongest first: official_statement, claim_by_actor (the party’s own claim), reported (plain reporting), alleged_by_opponent, speculation.
statement string The full finding as one paragraph, citable as it stands.
what_would_change string What new reporting would raise, lower or overturn the grade.
sectors array of strings a sector key Sectors its stories touch.
states array of strings a state slug States its stories are in.
story_ids array of integers Its stories; pass each to GET /stories/{id}.
independent_outlets integer Independent outlets across its stories.
first_seen string (time) The first article’s time.
last_seen string (time) The latest article’s time.
attributed_by_reporting array of objects Every party the reporting names in the finding’s stories, with how it is attributed.
attributed_by_reporting[].name string The party’s name.
attributed_by_reporting[].kind string What the party is (as Party.kind).
attributed_by_reporting[].roles array of strings The roles the reporting gives it.
attributed_by_reporting[].carried_as string official_statement, claim_by_actor, reported, alleged_by_opponent, speculation How the reporting attributes the role, strongest first: official_statement, claim_by_actor (the party’s own claim), reported (plain reporting), alleged_by_opponent, speculation.

A party the reporting names, in one role. Returned by a coordination finding’s orchestrator, orchestrator_allies and target.

Field Type Values What it is
kind string organisation, movement, party, state_agency, armed_group, union, company, public_official, public_figure What the party is: an organisation, movement, party, state agency, armed group, union, company, public official or public figure.
name string The party’s name as the reporting gives it.
role string organiser, claimant, blamed, accused, target, responder The role the reporting gives it in this finding.
stories integer In how many of the finding’s stories it has that role.
attribution string official_statement, claim_by_actor, reported, alleged_by_opponent, speculation How the reporting attributes the role, strongest first: official_statement, claim_by_actor (the party’s own claim), reported (plain reporting), alleged_by_opponent, speculation.

A compiled report. Returned by GET /reports.

Field Type Values What it is
id string (uuid) The report’s id.
title string The report’s title.
trigger string scheduled, on_demand scheduled (the workspace’s report schedule) or on_demand (someone asked for it).
period_start string (time) Start of the period it covers.
period_end string (time) End of the period it covers.
created_at string (time) When it was compiled.

A compiled report with its content. Returned by GET /reports/{id}.

Field Type Values What it is
id string (uuid) The report’s id.
title string The report’s title.
trigger string scheduled, on_demand scheduled (the workspace’s report schedule) or on_demand (someone asked for it).
period_start string (time) Start of the period it covers.
period_end string (time) End of the period it covers.
created_at string (time) When it was compiled.
content object The report’s structured content, as the dashboard renders it. It carries version (the content format; fields are added within a version, never renamed), title, org, period, data_through, generated_at, and one key per section the workspace’s reports include: judgements, memo, outlooks, stories, states, forecasts, coordination, sources, products, settings. For a report to read, ask for format=markdown.

A feed the workspace follows, on top of Alethman’s own coverage. Returned by GET /sources and POST /sources.

Field Type Values What it is
id string (uuid) The source’s id.
url string (url) The feed’s address.
site_url string or null The site the feed belongs to.
title string The feed’s title.
kind string rss, atom rss or atom.
status string active, paused, failing active: polled about every 20 minutes. paused: an owner or admin paused it. failing: recent polls failed; see last_error.
last_polled_at string (time) or null The last poll, successful or not.
last_ok_at string (time) or null The last successful poll.
last_error string or null Why the last poll failed, or null.
items integer Items stored from this feed.
items_7d integer Items stored in the last 7 days.
created_at string (time) When the workspace started following it.

One item a followed feed carried. Returned by GET /sources/items.

Field Type Values What it is
id integer The item’s id.
source object The feed it came from.
source.id string (uuid) The source’s id.
source.title string The source’s title.
title string The item’s title.
url string (url) The item’s address.
summary string or null The feed’s summary of the item, or null.
published_at string (time) or null When the feed says it was published.
fetched_at string (time) When Alethman read it.
sectors array of strings a sector key Sectors the item was read as touching.
states array of strings a state slug States it is about.

The workspace a key belongs to. Returned by GET /workspace.

Field Type Values What it is
workspace object
workspace.name string The workspace’s name.
workspace.slug string Its slug.
scope object What the workspace follows. Every endpoint reads through this.
scope.sectors array of strings a sector key The sectors it follows. Every list in the API stays inside these.
scope.states array of strings a state slug The states it follows; empty when it follows all of India.
scope.all_india boolean True when it follows every state.
scope.national boolean True when it also follows national news that names no state.
coverage array of strings signals, live, stories, outlooks, forecasts, coordination The parts of Alethman the workspace has turned on.
reports object Report settings.
reports.frequency string daily, weekdays, weekly, fortnightly, monthly, on_demand How often reports are compiled.
reports.depth string brief, standard, dossier How long each report runs.
reports.organise string sector, state, risk How its stories are grouped.
reports.sections array of strings judgements, outlooks, stories, states, forecasts, coordination, sources The sections each report includes.
reports.screenshots boolean True when reports carry screenshots of key articles.
reports.next_at string (time) or null When the next scheduled report is due.
alerts object Alert settings.
alerts.threshold integer The risk score from which alerts fire, set by the workspace (0 to 100).
alerts.kinds array of strings threshold, rising, coordination, forecast, report, source The alert kinds turned on.
key object The key that made the request.
key.name string The name this key was given.
key.scopes array of strings signals:read, intel:read, reports:read, sources:read, sources:write The scopes this key carries.

Every error has this body. Returned by every error.

Field Type Values What it is
error object
error.code string bad_request, unauthenticated, invalid_key, insufficient_scope, not_found, workspace_not_ready, unprocessable, rate_limited, internal A stable, machine-readable code. Branch on this, never on the message.
error.message string One sentence for a person: what was wrong and what to do.