API documentation
News monitoring
Stonewake reads global news coverage of every company your workspace holds in its book or watches, and of every natural person it watches, and keeps a daily tone reading per company and person together with the articles it rests on. The readings are served over the API and to AI assistants over MCP.
Where the news comes from
The articles come from the GDELT Project, which publishes a file every 15 minutes listing the news it found worldwide, in English and machine translated from about 65 languages. For every article the file names the organisations and persons it mentions and the tone of the document as a whole. Stonewake reads each English file as it appears and each translated file about an hour after its time, the first moment GDELT's download server serves it, and keeps only the articles that name a company or a person some workspace monitors.
Data from GDELT is shown with its citation and a link to the GDELT Project (https://www.gdeltproject.org/). Every answer carries both in its attribution field.
How an article is matched to a company
A company matches an organisation named in an article when the two whole names are equal, compared the way Stonewake's screening compares names. Case, punctuation, hyphens and accents do not count, letters such as ø, æ and ł count as o, ae and l, a legal form is compared spelled out, so AG and Aktiengesellschaft are the same, and a registered name also counts without the legal form at its end, so Adolf Würth GmbH & Co. KG matches Adolf Wurth and Novo Nordisk A/S matches Novo Nordisk. The names a register states for the company, former names included, count as its names. So do the brand and short names Stonewake's alias list states for the company's LEI, such as BMW for Bayerische Motoren Werke Aktiengesellschaft or VW for Volkswagen, and they count only for the company that holds that LEI. The alias list is built from Wikidata and GLEIF. A brand or short name in neither, or any brand name of a company without its LEI, does not match, and a reading counts matched articles only.
A name that merely contains another never matches, so BP never matches bpost. A name two monitored companies share matches neither of them, and so does a name the alias list states for two companies, such as Porsche. A name on Stonewake's reviewed list of names that in the news also mean another company, a place, an institution or a common word never matches, whichever company states it. Merck also names the US company Merck & Co., so Merck KGaA is matched as Merck KGaA and never as Merck alone. The same holds for Hermes, Continental, Metro, Otto, Shell, Mercedes, Caterpillar, Bayer, RBI and about 30 more names. Each match keeps the organisation name the article used and the company name it equalled.
A natural person your workspace watches matches a person an article names when the whole names are equal, compared the same way. The registered name counts with the given names first, so MUSTER, Anna Maria matches Anna Maria Muster, and so does the first given name with the surname, Anna Muster. A single word never matches, and a name two watched subjects share matches neither. A namesake with the same whole name can match, so read the articles. Persons are monitored only where person data is switched on for your workspace, and never a person who objected.
What is kept
For each matched article Stonewake keeps its address, the publisher's domain, the publication date, the language and GDELT's tone of the document. No headline and no article text is kept, and no person's name except the name that matched a person your workspace watches. Daily readings are kept for one year, and the articles and their matches for one year and 30 days, so every kept reading can be traced to its articles. Then they are deleted.
The daily reading
Each company has one reading per day, in UTC. It looks at the articles that named the company in the 30 days ending on that day, and it has one of three states.
- reading. At least three articles.
tone_meanis the mean GDELT tone of these articles. GDELT measures the tone of most documents between about -10, very negative, and +10, very positive. The mean describes the coverage that names the company, not each article's view of the company. A brand name also names the company's products, so a car maker's articles include car reviews and traffic reports, and the mean describes that coverage too. - too_little_coverage. Fewer than three articles, while every one of the 30 days was read in full. No tone is shown.
- feed_gap. The day itself was not read in full, or there are fewer than three articles while some of the 30 days were not read in full, so missing articles cannot be ruled out. No tone is shown.
Every reading lists article_keys, the newest 100 of the articles it rests on, each key the SHA-256 of the article's address, while articles_window counts them all, and gap_days, how many of its 30 days were not read in full. A day is read in full when every 15 minute file of that day has been read in both the English and the translated stream, or GDELT did not publish the file within a day of its time, or the file could not be read on three attempts. The day in progress is therefore never read in full, and its reading is feed_gap until its last file has been read.
Your workspace's readings rest only on articles matched for your workspace, against your workspace's own companies. Stonewake also reads past files again, up to 30 days back, for every company your workspace holds or watches, however recently it joined your book or watch list, so the company's 30 days can be full from the start. Until those files have been read again, the day monitoring started and the days before it are not read in full for your workspace. A reading never shows coverage that another workspace's interest collected.
Tone and the credit view
The tone reading is context beside the credit view. It is no input of the risk score, which uses no model and no news. For a person your workspace watches, the reading is context for the due diligence your institution runs on that person, never a score of the person. A sole trader, a natural person's business, has no tone, neither a reading nor an article's tone, so it answers latest null and no readings, while its articles and news events are served.
News events and alerts
Stonewake also looks for serious events in the news about each company your workspace holds or watches, and alerts your desk when a news check confirms one. An event type comes from GDELT's own theme codes, through a reviewed and versioned mapping. A model only reads the articles afterwards and can confirm the event or keep it from alerting, see The news check below. The types are insolvency, sanctions or a penalty, fraud, corruption or money laundering, a cyberattack or data breach, an industrial accident, a lawsuit or antitrust action, an executive exit or arrest, layoffs or closures, a strike, and an environmental or human rights incident. GDELT has no theme for a product recall or a rating downgrade, so neither is found here.
An article counts toward an event only when the theme sits within 200 characters of a place where the article names the company, the article names the company at least four times and first within its first 200 characters, its tone is at or below -1.5, and no police, theft or road traffic theme sits near the company, which on real files marked a crime or a crash involving a car or a shop of the brand. An executive exit also needs a role such as chief executive or chairman near the company. A sole trader and a watched person get events and alerts like a company. No person and no sole trader is ever scored, and a sole trader carries no tone.
The articles of one company and type within 48 hours make an event when they come from at least two independent sources, where copies of one syndicated article count once, and when they are at least twice the company's own usual rate for that type over the 14 days before. Later articles in any language join the open event instead of raising a new alert. A new alert follows only when a more severe type appears or the 48 hours have passed. Files read again by the backfill never raise an alert.
An insolvency is critical when at least three independent sources in at least two languages report it, else high. Sanctions, a strike, an executive exit and an environmental or human rights incident are information, the other types are high. A news event the news check confirmed alerts as a press candidate through your team subscriptions, quiet hours and every budget guard like any other alert, and it reaches a phone only when it is critical. The mail names the company, the event type, how many articles in how many languages and the link to the company's news in the dashboard. Teams cards and webhook bodies set to detailed carry the type and the counts, and an SMS stays the short message without a name.
The news check
Before any alert, a news check reads the articles. Stonewake fetches the event's newest articles, at most eight and one per story, through its usual fetch layer, under the same robots.txt rules, sites that wait for our request and budget limits as every other fetch. A page that does not answer in time is left out. Claude Haiku 5.5 reads up to five of them together with the company's identity, its register name, the names its registers state, its country, legal form and identifiers such as the LEI. For a watched person it reads the registered name and the country, with a prompt written for a person, as part of the due diligence your institution runs on that person. The model answers yes, no or unsure, names the event type and quotes the articles.
When fewer than five articles can be read, a second source can add full texts. Stonewake then searches NewsAPI.ai (Event Registry) once for the event, for the company's approved search name together with the words of the event's type over the event's 48 hours, and adds articles of further publishers whose text names the company near such a word, one per publisher, up to five articles in all. It searches only for a company whose search profile our operators set up by hand and approved after reading a sample of what the name finds, so that namesakes stay out, never for a person or a sole trader, and only for a workspace without its own list of search providers. The second source never opens an event, adds a type or raises a severity, its articles pass the same gate as every other article, and the company's news card, the API and MCP list the ones the check read under the event's check, with their link, publisher, date and language, never their headline or text. It is switched off unless your contract includes it.
The answer counts only when a deterministic gate confirms it. Each quote must come from one of the articles the check read, the event's own or the second source's, and appear word for word in the text the check read. The type must be one the theme mapping already found for the event, so the model can narrow an event and never widen it. A yes needs quotes from at least two different publishers, so the articles of one publisher alone never raise an alert. Two publishers count as one when they quote the same passage, such as one syndicated wire sentence, and also when each one's article carries the passage quoted from the other, such as one wire story on two sites. The gate checks where a quote stands, not what it proves. A model misled by an article can therefore still confirm an event the rule found. It can never add an event, choose a type the mapping did not find or set a higher severity. Article text that reads like instructions to a model is left out of the check and named to our operators. Any other answer counts as unsure. The severity follows the confirmed type and never rises above the rule's, so only an event the rule already rated critical can reach a phone.
Only a confirmed event alerts. Every other event stays on the company's news card as coverage to read, without a type or a severity, and it is never hidden or deleted. When the check cannot run because the model, the budget or the fetch is unavailable, no alert goes out, the event records why, our operators see a count of such events, and the check runs again once the cause is gone. Stonewake keeps only the verdict, the confirmed type, the key of the first cited article, the model and prompt version and the time of the check, and the link, publisher, date and language of each NewsAPI.ai article the check read. The article text and the quotes are held in memory for the check and then dropped. A workspace on the EU route is checked on its own model there.
A workspace that watches the company receives one event for the whole workspace. A company held only in team books gets one event for each team that holds it, so no team's alert names a company in another team's book.
Measured on four weeks of real files against 150 large listed companies, the rule raised about 1.4 events a day for all 150 together, and about four in ten of them were a true serious event about the company. The figure is a judgement on each event and probabilistic. With the news check in place, a replay of three weeks of the same files raised 6 alerts for the 150 companies instead of 32, and in our reading each was a serious event about the company, while about two thirds of the true events stayed coverage to read, most because the model did not read them as a serious event about the company and some because only one publisher's article could be read. On a second book of 30 companies followed in practice, the check held back all 6 alerts the rule would have raised, none of which was clearly a serious event about the company. On the same replay with NewsAPI.ai as the second source, the check confirmed 9 of the 14 true events we had labelled instead of 4, and 1 or 2 of the 21 false ones in two runs against 1 without it. These figures are judgements too, and the model's answers vary a little from run to run. Treat coverage to read as early warning, and a confirmed event as a report to read before acting, not as a finding.
Routes
GET /v1/news/companieslists the companies of your workspace's book and watch list and the persons it watches, withnode_typeperson, each with its newest reading of a day read in full, paged withlimitandoffset. A company without a stored reading answerslatestnull, which says nothing about its coverage.GET /v1/news/companies/{node_id}answers one company's readings, newest first,daysof them (30 unless stated, at most 90), and the newest 100 articles behind the newest one together with every article its events list, each witharticle_key,url,publisher_host,published_at,language,gdelt_toneandmatched_organization. Itseventslist the company's news events of the same days, newest first, at most 20, each withevent_type,severity,opened_at(the first article),detected_at,closes_at,last_article_at,articles,sources,languages,alerted,article_keys(the newest 20 articles),mapping_version,rule_versionandcheck, the news check with itsstatus(confirmed,not_confirmed,pending,uncheckedorcovered),verdict, the confirmedevent_typeandseverity, the first citedarticle_key,reason,model,prompt_version,checked_atandsecond_source_articles, the NewsAPI.ai articles the check read beside the event's own, each witharticle_key,url,publisher_host,published_at,languageandprovider. Only aconfirmedevent alerts. A team reads its own team's events and the workspace wide ones.
A key reads the companies of its own team's book and the companies and persons its workspace watches. Any other company answers 404, so the routes never show which companies another workspace follows. The MCP tool company_news reads both routes.