The headlines from 42 Gulf news outlets as JSON: newest first, sorted into sections, searchable, and grouped when several outlets carry the same story. Ashum checks every outlet every 10 minutes. The API also carries the companies of Dubai Financial Market (DFM): their prices, their disclosures with the text of the documents filed since November 2024, and the exchange’s calendar.
Endpoints
$0.005 a request, which is $5 for 1,000, paid as you go with no subscription. A new account starts with 200 free requests. API pricing
One DFM company as its page on ashum.ai shows it: the whole price line, its profile, the symbols it traded under before, the coming dates on DFM's calendar, and when it has filed its results in past years.
How a DFM company's shares are held by the holder's nationality, by session, newest first, with the limit on foreign holders; and its largest shareholders as DFM lists them.
A DFM share's margin trading by week, newest first, in UAE dirhams, as DFM's weekly report gives it: the shares available for margin trading, and what was bought and sold on margin in the week.
DFM's ranking of its brokers for a month, first by the value they traded, in UAE dirhams, with each broker's share of the market's value, volume and trades.
Every address starts with https://ashum.ai/api/v1. All requests are GET. Times are UTC. The example answers on this page show the real shape; the stories in them are placeholders. The DFM examples are real answers from 13 November 2026, cut short.
Keys
A key looks like ashum_ followed by 32 characters. It is shown once, when you create it; Ashum keeps only a fingerprint of it, so a lost key cannot be shown again. Revoke it and make another.
Call the API from your server. A key placed in a web page or in an app people download can be read by anyone, and whoever reads it spends your requests.
Price and limits
The API is pay as you go, with no subscription. A new account starts with 200 trial requests. After that, add funds ($20 to $1,000 at a time): every dollar is 200 requests, which is $0.005 a request.
Requests
How far back
A minute, per key
Keys
Trial: 200, once
30 days
300
10
From added funds
Everything, from 2008
300
10
What a call costs. One request, for most calls. A call that returns a list of stories costs one request for every 25 stories, or part of 25, in the answer: up to 25 stories is one request, 100 stories is four. A list of disclosures is counted the same way. A call that returns an error costs nothing, and /usage is always free. With no requests left, calls answer 402 until funds are added.
Once an account has added funds, its requests reach the whole archive. “Everything” is the archive from January 2008. Outlets joined at different times, so how far back one outlet goes depends on the outlet. Search by meaning covers every outlet from January 2024 and part of the archive before it; the words of every story are searchable. DFM disclosures go back to 2000, and DFM’s daily prices to 31 December 2024.
Every answer to a valid key says where you stand: X-Credits-Remaining is the number of requests left and X-Request-Cost is what this call took. X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the minute starts again) count the minute; past the limit the answer is 429 with a Retry-After header in seconds. Every call made with a valid key counts toward the minute, whatever it answers.
New stories arrive every 10 minutes, so asking more often than every few minutes returns the same answer.
The feed
GET/api/v1/stories
Stories, newest first. The same feed as the front page of ashum.ai.
You can send
What it is
topic
One section: business, economy, government, world, tech, sport or life.
source
One outlet, by its id from /sources (for example wam).
q
Only stories whose headline or summary contains these words. Quotes match an exact phrase. Up to 120 characters.
since
Only stories published at or after this time, such as 2026-11-01T00:00:00Z.
until
Only stories published before this time. On trial requests, a time more than 30 days back answers 402 funds_required.
limit
How many stories, 1 to 100. Default 25. Every 25 stories in the answer, or part of 25, counts as one request.
cursor
The next_cursor from the page before, to get the page after it.
{
"data": {
"id": "412345",
"headline": "Example headline, exactly as the publisher wrote it",
"summary": "The publisher's own first lines of the story.",
"url": "https://publisher.example/the-story",
"source": { "id": "wam", "name": "WAM" },
"topic": "economy",
"published_at": "2026-11-10T08:15:00.000Z",
"same_story": [
{
"id": "412391",
"headline": "The same event, as another outlet headlined it",
"url": "https://another-publisher.example/the-story",
"source": { "id": "gulf_news", "name": "Gulf News" },
"topic": "economy",
"published_at": "2026-11-10T08:40:00.000Z"
}
],
"related": []
}
}
In the answer
What it is
same_story
The same story as other outlets ran it, earliest first. Empty when no other outlet carried it.
related
Other stories on the same subject from the days around it. Empty when there are none.
Stories inside same_story and related carry no summary. Ask for each by its id if you need one.
Search
GET/api/v1/search
Stories about a subject, best match first. The search matches by meaning as well as by words, so a search for a subject finds stories that never use your exact words.
You can send
What it is
q
What to look for. Required, up to 120 characters.
when
How far back: week, month, year or any. Default month. Trial requests reach back 30 days, so year and any need added funds.
sort
best (default) or newest.
topic
One section: business, economy, government, world, tech, sport or life.
source
One outlet, by its id from /sources (for example wam).
limit
How many stories, 1 to 60. Default 25. Every 25 stories in the answer, or part of 25, counts as one request.
{
"data": [
{
"id": "412345",
"headline": "Example headline, exactly as the publisher wrote it",
"summary": "The publisher's own first lines of the story.",
"url": "https://publisher.example/the-story",
"source": { "id": "wam", "name": "WAM" },
"topic": "economy",
"published_at": "2026-11-10T08:15:00.000Z"
}
],
"matched_by": "meaning_and_words"
}
In the answer
What it is
data
The stories, best match first. A search returns one answer of up to 60 stories; it has no pages.
matched_by
meaning_and_words, or words when only the words were matched: a search with no Latin letters or digits in it (Arabic, for example), or the rare one where the meaning step did not answer in time.
Top stories
GET/api/v1/top
The stories that two or more outlets carried in the last 24 hours, the most widely carried first. Worked out again every 10 minutes.
You can send
What it is
limit
How many stories, 1 to 60. Default 25. Every 25 stories in the answer, or part of 25, counts as one request.
The section's id: what a story carries in topic, and what the topic filter takes.
name
The section's name, to show to people.
covers
One sentence on what is sorted into the section.
DFM companies
GET/api/v1/companies
Everything listed on Dubai Financial Market (DFM) today, in order of symbol: shares, funds, ETFs and REITs, each with its latest price. Prices are DFM's own, in UAE dirhams, read by Ashum every 10 minutes while the market is open.
The company's symbol on DFM today: what /companies/{symbol}, /prices/{symbol} and every symbol filter take.
name
The company's registered name. name_ar is the same in Arabic, or null.
sector
The sector DFM puts it in, or null.
isin
Its ISIN, or null where DFM gives none.
listed_on
The day it was listed on DFM, or null.
quote
The latest price: price, then change and change_pct (a percentage) against the previous close, and as_of, when Ashum read them from DFM. null for a share DFM gives no price for.
The list comes whole: one request returns every company. The example shows one of them. Shares listed on Nasdaq Dubai are not included.
One company
GET/api/v1/companies/{symbol}
One DFM company as its page on ashum.ai shows it: the whole price line, its profile, the symbols it traded under before, the coming dates on DFM's calendar, and when it has filed its results in past years. The symbol can be in any case, and a symbol the company used to trade under answers for the company as it is today.
The symbol the company trades under today, whichever one you asked with. name, name_ar, sector, isin and listed_on are as in /companies.
active
false for a company DFM no longer lists. Such a company is not in /companies, and still answers here.
quote
The whole price line. Beside the four fields of /companies: open, high, low and previous_close; high_52w and low_52w, the range of the last 52 weeks; volume (shares) and value (dirhams) traded in the session; market_cap; and traded_on, the day of that session. A figure DFM does not give is null: a share that has not traded today has no open, high or low.
profile
What the company has told DFM about itself: description, established (a day), fiscal_year_end, auditor, issued_shares, website, and the people on its board and in its management, each with a name and a title. Any of them can be null, and so can the whole profile.
former_symbols
The symbols the company traded under before, the latest first: the symbol, the name it carried, and until, the last day Ashum has it on record under them. Empty for most companies.
calendar
Up to 12 coming dates from DFM's calendar, the soonest first. Each has the fields of /calendar, without symbol and company.
results_timing
When the company has filed each set of results since 2019. period is Q1, Q2, Q3 or Yearly, name says it in words, and filed_at holds the time of the first filing in each year, oldest first. A period filed in fewer than three years is left out.
The example is cut short: the real answer lists every member of the board and of the management, every coming date and all four sets of results. A company that changed its symbol answers under both: /companies/GULFNAV returns ETIHADENERGY, with GULFNAV under former_symbols.
Disclosures
GET/api/v1/disclosures
What DFM companies have filed with the exchange, newest first: results, board decisions, dividends, notices. DFM publishes each disclosure twice, in English and in Arabic, as two records with their own ids; lang picks which you get.
You can send
What it is
symbol
Only one company's disclosures, by its symbol. Any case; a symbol it used to trade under works too.
category
Only disclosures of one kind: results, dividend, board, assembly, ownership, capital, governance, debt, legal, business or other.
major
true for only the disclosures scored 2 or over on importance: mostly results, dividends, changes of capital and deals.
q
Only disclosures whose headline contains these words. Quotes match an exact phrase. Up to 120 characters.
lang
en (default) or ar.
since
Only disclosures published at or after this time, such as 2026-11-01T00:00:00Z.
until
Only disclosures published before this time. On trial requests, a time more than 30 days back answers 402 funds_required.
limit
How many disclosures, 1 to 100. Default 25. Every 25 disclosures in the answer, or part of 25, counts as one request.
cursor
The next_cursor from the page before, to get the page after it.
The disclosure's id: what /disclosures/{id} takes. The English and the Arabic record of one disclosure have different ids.
symbol
The company's symbol on DFM today, and company, its name.
headline
The headline as it was filed, in the record's language.
published_at
When DFM published it. UTC, ISO 8601.
results_period
DFM's own label on a periodic report: on financial results Q1, Q2, Q3 or Yearly. null on everything else.
category
What kind of disclosure it is: results, dividend, board, assembly, ownership, capital, governance, debt, legal, business or other. A classifier picks it from the headline and the start of the document, so it can be wrong; other is also what a headline that says nothing gets while Ashum holds no text for it.
importance
How much the disclosure matters to a shareholder, from 0 (routine: the notice of a meeting) to 3 (major: results, a dividend, a change of capital, a deal). A classifier scores it from the headline and the start of the document, so it can be wrong; null while a new disclosure waits to be scored.
lang
en or ar.
documents
The files attached, in order; a disclosure can have none. Each has its title, its pages (null for a file Ashum has not read), has_text (whether Ashum holds its text) and text_from: file when the text was inside the file, scan when the pages are pictures of paper that a vision model read, file_and_scan when the file has pages of both kinds, null when no text is held.
url
The disclosure's page on ashum.ai, where its text can be read.
next_cursor
Where the next page starts, or null when there are no more disclosures. See Paging.
Disclosures go back to 2000. Ashum reads the text of PDF documents filed since 13 November 2024. A file scanned from paper has text only once its pages have been read, and not every scan has been read yet: has_text says which. The English files filed before that day are being read too, newest first: those with text inside the file have it, and the scanned ones get theirs over the coming weeks. Older Arabic files, and files that are not PDFs, are listed without text.
One disclosure and the text of its documents
GET/api/v1/disclosures/{id}
A single disclosure with the text of each attached document, a page at a time, and the address of the original file at DFM.
{
"data": {
"id": "bd7523db-e2b6-48b4-82fa-f191cfb6cb9a",
"symbol": "EMAAR",
"company": "Emaar Properties PJSC",
"headline": "Resolutions of General Assembly",
"published_at": "2026-11-04T12:38:28.000Z",
"results_period": null,
"category": "assembly",
"importance": 1.3,
"lang": "en",
"documents": [
{
"title": "EP General Assembly Results 4 Nov 26.Pdf",
"pages": 2,
"has_text": true,
"text_from": "scan",
"file_url": "https://feeds.dfm.ae/documents/2026/Nov/4/bd7523db-e2b6-48b4-82fa-f191cfb6cb9a/EP%20General%20Assembly%20Results%204%20Nov%2026.Pdf.pdf",
"text": [
"EMAAR\n\nDisclosure of the Results of General Assembly Meeting ...",
"EMAAR\n\nclosing date will be 16 November 2026. ..."
]
}
],
"url": "https://ashum.ai/stocks/EMAAR/disclosures/bd7523db-e2b6-48b4-82fa-f191cfb6cb9a"
}
}
In the answer
What it is
documents
As in /disclosures, and for each document also file_url and text. The other fields are those of /disclosures.
file_url
The original file on DFM's website. The file at DFM is the record.
text
The document's text, one entry for each page, in page order. A page without text is an empty entry. The list is empty when has_text is false.
The text is read from the file by program. Where text_from is scan or file_and_scan, the scanned pages were read by a vision model or a text-recognition program and can carry mistakes. In the example each page is cut to its first words.
Daily prices
GET/api/v1/prices/{symbol}
A share's daily prices as DFM gives them, oldest first, in UAE dirhams. DFM's history starts on 31 December 2024. The symbol can be in any case, and a former symbol works too.
You can send
What it is
since
Only days on or after this day, such as 2026-11-01.
until
Only days before this day. On trial requests, a day more than 30 days back answers 402 funds_required.
The days, oldest first. Everything asked for comes in one answer; there are no pages.
date
The trading day.
open
The day's first price. high, low and close are its highest, its lowest and its closing price.
volume
Shares traded that day.
value
Dirhams traded that day.
symbol
The symbol the company trades under today, whichever one you asked with.
Trial requests reach the last 30 days of this history. All of it opens once the account has added funds.
Financials
GET/api/v1/financials/{symbol}
A DFM company's headline figures by period: revenue (or, for a bank, total income), profit, cash from operations, total assets and total equity. The financial years come first, then the shorter periods, each newest first. Every figure is one the company printed in the financial statements it filed with DFM, and names the filing and the page it stands on.
How long the period is: 12 for a financial year, 3, 6 or 9 for a shorter one.
currency
The currency the company reports in: AED for most, KWD, USD or another for a company that reports in it. Values are in whole units of it.
figures
The lines held for the period, by name: revenue, total_income or total_operating_income (a company carries one of them), profit, operating_cash_flow, total_assets and total_equity. A line with no figure is absent. total_assets and total_equity are as at period_end.
value
The figure, with losses and cash used as negative numbers. label is the wording printed beside it in the statements.
page
The page of the filed document the figure stands on. disclosure_id is the filing, for /disclosures/{id}, and url its page on Ashum; both are null where the file is on no disclosure Ashum holds.
Figures are as first reported: where a later filing restates an earlier period, the earlier filing's figure stays. profit is the whole profit of the period, before the share of non-controlling interests is taken off, so it can be larger than the profit attributable to shareholders that other sources give. The figures were read from the filings by program; a period is left without a line rather than given a doubtful one. They go back to 2010 for the older companies. The example shows two of the five lines of one year.
DFM calendar
GET/api/v1/calendar
The dates on DFM's calendar: board meetings, general assemblies, earnings calls and the dates of a dividend. Earliest first. With neither since nor until, the answer starts today (Gulf time), so it is the coming dates.
You can send
What it is
symbol
Only one company's dates, by its symbol. Any case; a symbol it used to trade under works too.
since
Only days on or after this day, such as 2026-11-01.
until
Only days before this day. On trial requests, a day more than 30 days back answers 402 funds_required.
The company's symbol on DFM today, and company, its name.
kind
board_meeting, general_assembly, earnings_call, or one of the dates of a dividend: last_day_to_buy (the last day to buy the share and still receive it), ex_dividend, record_date and dividend_payment.
date
The day, as DFM's calendar has it.
title
DFM's own line for the date, or null.
disclosure_id
The disclosure the date comes from, to ask /disclosures/{id} for, or null.
Ashum reads DFM's calendar after each trading day, for the month before, the month itself and the three months after it. The dates it holds start in October 2026.
Who owns a company
GET/api/v1/ownership/{symbol}
How a DFM company's shares are held by the holder's nationality, by session, newest first, with the limit on foreign holders; and its largest shareholders as DFM lists them. The figures are DFM's own, read by Ashum the morning after each session.
You can send
What it is
since
Only sessions on or after this day, such as 2026-11-13.
until
Only sessions before this day. On trial requests, a day more than 30 days back answers 402 funds_required.
Percent of the company's shares held by UAE nationals. gcc_nationals, arab_nationals and other_nationalities are the shares held by nationals of the other Gulf states, by other Arab nationals and by everyone else.
foreign_owned
Percent held by all holders who are not UAE nationals, together.
foreign_limit
The most those holders may hold together, in percent. 100 means no limit; null where DFM gives none.
foreign_room
The limit less what is held, worked out by Ashum; null where either figure is missing.
largest_shareholders
The shareholders DFM lists for the company today, largest first, each with its percent and the day DFM gives it for. Names are as DFM writes them; some are in Arabic. An empty list where DFM lists none.
With neither since nor until, the answer is the last 30 sessions Ashum holds. Ashum holds these figures for every session from 2 January 2025. The largest shareholders are the latest list only. A company DFM gives no ownership for answers with an empty data.
Who bought and who sold
GET/api/v1/flows
What each kind of investor, and investors of each nationality, bought and sold on DFM in a session, newest session first, in UAE dirhams. The groups and the amounts are DFM's own, read by Ashum the morning after each session.
You can send
What it is
since
Only sessions on or after this day, such as 2026-11-01.
until
Only sessions before this day. On trial requests, a day more than 30 days back answers 402 funds_required.
DFM's kinds of investor: Banks, Companies, Institutions, Individuals and OTHER. Each has what it bought and sold in the session and net, the first less the second, worked out by Ashum.
by_nationality
The same session by the investor's nationality, in DFM's groups: UAE Nationals, GCC, ARAB and OTHERS.
unit
Always AED.
With neither since nor until, the answer is the last 30 sessions. DFM gives these figures from 2 January 2025. Across the groups of one list the buying equals the selling. The example shows two of the five kinds of investor and one of the four nationalities.
Block trades
GET/api/v1/block-trades
The block trades DFM lists (it calls them direct deals), newest first, in UAE dirhams. Each row is one share on one day at one price, with how many deals were done at it. The figures are DFM's own, read by Ashum each morning.
You can send
What it is
symbol
Only one company's, such as SALIK. An unknown symbol answers 404 not_found.
since
Only days on or after this day, such as 2026-11-01.
until
Only days before this day. On trial requests, a day more than 30 days back answers 402 funds_required.
With neither since nor until, the answer is the newest 100 (on trial requests, those of the last 30 days). DFM lists block trades from 2016. A share can have more than one row on a day, one for each price.
Margin trading of a share
GET/api/v1/margin/{symbol}
A DFM share's margin trading by week, newest first, in UAE dirhams, as DFM's weekly report gives it: the shares available for margin trading, and what was bought and sold on margin in the week.
You can send
What it is
since
Only weeks ending on or after this day, such as 2026-10-01.
until
Only weeks ending before this day. On trial requests, a day more than 30 days back answers 402 funds_required.
The last day of the week the figures are for, as DFM gives it.
available_shares
The shares available for margin trading, as DFM reports it.
bought
What was bought on margin in the week: the number of trades, the shares, and their value in dirhams. sold is the same for what was sold.
With neither since nor until, the answer is the last 12 weeks Ashum holds (on trial requests, those of the last 30 days). Ashum holds these weeks from January 2025. A share DFM reports no margin trading for answers with an empty data.
Shari'a-compliant companies
GET/api/v1/sharia
The DFM companies on DFM's own list of Shari'a-compliant companies for a quarter: the newest list held, or the quarter asked for. The list is DFM's; Ashum makes no judgement of its own.
You can send
What it is
year
The year of the quarter, such as 2025. Give it together with quarter.
quarter
The quarter, 1 to 4. On trial requests, a quarter other than the newest that ended more than 30 days ago answers 402 funds_required.
What DFM writes beside the company on the list. The list holds the compliant companies only: a company that is not in the answer is not on that quarter's list.
year
The year of the list answered, and quarter its quarter.
DFM publishes the list months after the quarter it is for, so the newest list is answered however old it is. Lists are held from the third quarter of 2012. A quarter with no list held answers 404 not_found. The example shows one of the 50 companies on the list.
Broker ranking
GET/api/v1/brokers
DFM's ranking of its brokers for a month, first by the value they traded, in UAE dirhams, with each broker's share of the market's value, volume and trades. The figures are DFM's own.
You can send
What it is
month
A month, such as 2026-09. Without it, the newest month held. On trial requests, a month other than the newest that ended more than 30 days ago answers 402 funds_required.
The broker's name as DFM writes it; its code where DFM gives no name.
value
What the broker traded in the month, in dirhams, and value_percent what that is of the whole market's. volume (shares) and trades have their own percentages.
DFM ranks a month once it has ended, so the newest month is the last whole one. Ashum holds the ranking from January 2025. A month with no ranking held answers 404 not_found. The example shows the first of 30 brokers.
Exchange rates, fuel and oil prices, and other dated figures
Only one kind of figure. fx: the Central Bank's exchange rates. fuel: the month's fuel prices. oil: the spot prices of Brent and WTI crude.
day
A day, such as 2026-11-14. The answer is then each figure in force on that day: the newest one on or before it, under its own date. A Saturday answers with Friday's rates. On trial requests, a day more than 30 days back answers 402 funds_required.
{
"data": [
{
"code": "fx-usd", "name": "US dollar", "group": "fx",
"unit": "AED per 1 USD", "every": "day",
"source": "Central Bank of the UAE",
"date": "2026-11-13", "value": 3.6725
}
],
"day": "2026-11-14"
}
In the answer
What it is
code
The figure's code: what /series/{code} takes. An exchange rate is fx- and the currency's code in small letters.
unit
What value is counted in. An exchange rate is in dirhams for one unit of the currency, as the Central Bank publishes it: 0.038968 for the Indian rupee means one dirham buys 1 ÷ 0.038968 = 25.66 rupees.
every
How often the source gives a new figure: day or month.
date
The day the source gives the figure for.
value
The figure, as a number.
first_date
The first day Ashum holds the figure for. Not in an answer to day.
day
The day asked for, when one was.
Without day, each figure is its latest. The Central Bank gives one rate a currency each working day, out after 18:00 Gulf time, and none at a weekend; Ashum holds them from January 2019. It is an official rate, not a live market rate: a bank or an exchange house sets its own. The example shows one of the 77 currencies. Fuel prices (fuel-super98, fuel-special95, fuel-eplus91, fuel-diesel) are set for each month by the UAE's fuel price committee: a month's prices carry the date of its first day, and Ashum keeps a month only once two of the outlets it follows report the same four prices, so a month it could not confirm is missing. Months from before Ashum began reading were entered by hand from the outlets' own stories and price tables, each only where two outlets give the same figure. Oil spot prices (oil-brent-spot, oil-wti-spot) are the US Energy Information Administration's, a public-domain publication: one price a working day, published weekly a few days behind, from 1987 for Brent and 1986 for WTI. The futures closes on the site's oil page come from Yahoo Finance and are not in the API.
One dated figure over time
GET/api/v1/series/{code}
One dated figure day by day, newest first. The Central Bank of the UAE's rate for the Indian rupee is fx-inr; /series lists every code.
You can send
What it is
since
Only days on or after this day, such as 2026-11-01.
until
Only days before this day. On trial requests, a day more than 30 days back answers 402 funds_required.
{
"data": [
{ "date": "2026-11-13", "value": 0.038968 },
{ "date": "2026-11-12", "value": 0.039049 }
],
"code": "fx-inr", "name": "Indian rupee", "group": "fx",
"unit": "AED per 1 INR", "every": "day",
"source": "Central Bank of the UAE"
}
In the answer
What it is
date
The day the source gives the figure for. A day with no figure (a weekend, a public holiday) is not listed.
value
The figure, in the series' unit.
An answer carries 1,000 days at most. With neither since nor until it is the newest 1,000 that Ashum holds; for older days, ask again with until set to the last date you were given. A code that does not exist answers 404 not_found.
Your balance and usage
GET/api/v1/usage
Where the account stands: the requests it holds, what they are worth, and how many calls it made today. This call is free and answers even with no requests left.
trial while the account is on its trial requests, payg once it has added funds.
credits
The requests left on the account. One credit is one request; the X-Credits-Remaining header carries the same number.
balance_usd
What those requests are worth in US dollars.
requests_per_minute
How many requests each key may make in a minute.
used_today
Calls made today (the UTC day) with any of the account's keys. Free calls and calls that ended in an error count too.
archive_days
How many days back the account's requests reach: 30 on trial requests, null (the whole archive) once it has added funds.
A story
Every story, in every answer, has these fields.
Field
What it is
id
The story's id on Ashum. A string of digits; keep it as text.
headline
The publisher's headline, unchanged.
summary
The publisher's own short description, or null when the outlet gives none. Ashum keeps up to 1,000 characters, and a summary that was cut mid-sentence ends with ….
url
The story on the publisher's site.
source
The outlet: its id and its name.
topic
The section the story was sorted into, or null for the few minutes before a new story is sorted.
published_at
When the publisher says the story went out. UTC, ISO 8601.
Headlines and summaries belong to their publishers. Show the outlet’s name with each story and link to the original.
Paging
/stories returns one page and a next_cursor. Send it back as cursor, with the same filters, to get the next page. A next_cursor of null means there is no more. The cursor marks a place in the feed, so pages stay correct while new stories arrive above them. /disclosures pages the same way, with cursors of its own.
Only /stories and /disclosures have pages. /search and /top answer with up to 60 stories at once, and the other lists come whole.
Errors
An error has an HTTP status and one shape. The code is for your program; the message is for you.
An error
{
"error": {
"code": "invalid_parameter",
"message": "limit: must be a whole number from 1 to 100"
}
}
Status
Code
What happened
400
invalid_parameter
Something in the address is not what the endpoint takes: a value out of range, or a name it does not list. The message names it.
401
missing_key
No key was sent in the Authorization header. Your keys
401
invalid_key
The key is not recognised, or it was revoked. Your keys