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 |
Signal
Section titled “Signal”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. |
Story (in full)
Section titled “Story (in full)”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. |
Outlook
Section titled “Outlook”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. |
Forecast
Section titled “Forecast”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. |
Coordination finding
Section titled “Coordination finding”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. |
Report (in a list)
Section titled “Report (in a list)”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. |
Report
Section titled “Report”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. |
Source
Section titled “Source”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. |
Source item
Section titled “Source item”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. |
Workspace
Section titled “Workspace”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. |