WorldFeedMonitor API

https://api.worldfeedmonitor.com/v1

The WorldFeedMonitor API streams structured, AI-enriched news from newsrooms around the world as clean JSON.

Feeds are ingested from thousands of RSS sources, deduplicated, categorized, and indexed for search. A single search endpoint lets you filter by country, continent, region, language, category, keyword and date, while a set of metadata endpoints expose the reference data (countries, sources, languages, categories) you use to build those filters.

Base URL

The API is served from its own host:

https://api.worldfeedmonitor.com/v1

That host serves the API and nothing else, and it is the only address the API answers on.

Authentication

All endpoints except account creation require HTTP Basic authentication. Your API key is the username and your API secret is the password. Credentials are issued from your dashboard.

Authorization: Basic base64(api_key:api_secret)

With curl, pass them via -u:

curl -u "YOUR_API_KEY:YOUR_API_SECRET" \
  "https://api.worldfeedmonitor.com/v1/feeds/search?country=USA"

Pagination

List responses return 25 items per page. Use the page query parameter to page through results and read the meta block (total_pages, has_next, has_previous) to navigate.

Your plan

Every plan carries an allowance, and searches are scoped to the countries the plan includes.

  • Requests are limited per minute, per day and per month, and every endpoint counts against them — metadata lookups as well as searches.
  • Countries must be chosen in your dashboard when the plan limits them. A search naming a country outside that selection is refused with 403, and a search naming none is restricted to the selection rather than the whole index.
  • Results are reachable only as deep as the plan allows. meta.total_items reports what you can reach, not what exists, and a page beyond that limit is refused with 422.

Read the current figures from your dashboard; they differ per plan.

Errors

The API uses conventional HTTP status codes.

Code Meaning
401 Missing, malformed or invalid credentials.
403 Valid credentials, but the account is not active or the plan does not include what was asked for. Retrying unchanged will not succeed.
422 Validation error, with a per-field errors object.
429 A plan allowance is spent. window names which one; Retry-After gives the seconds until it resets.

Feeds

Search the global news index.

Corpus statistics

GET https://api.worldfeedmonitor.com/v1/stats

How much is in the index, how fast it is arriving, and how recent the newest article is.

Figures cover the whole corpus, not the slice your plan reaches, and are cached briefly — they are counts, not news, and do not change meaningfully second to second.

This call counts against your plan allowance like any other.

200 The corpus as it stands.
401 Missing, malformed, or invalid credentials.
403
429
Response 
{
    "corpus": {
        "articles": 0,
        "sources": 0,
        "feeds": 0,
        "countries_covered": 0,
        "languages": 0
    },
    "ingested": {
        "yesterday": {
            "date": "string",
            "articles": 0,
            "sources_added": 0,
            "feeds_added": 0
        },
        "last_24h": {
            "articles": 0,
            "sources_added": 0,
            "feeds_added": 0
        },
        "last_7d": {
            "articles": 0,
            "sources_added": 0,
            "feeds_added": 0
        }
    },
    "freshness": {
        "newest_article_published_at": "2026-09-03 09:41:02",
        "newest_article_indexed_at": "2026-09-03 09:47:15"
    }
}

Metadata

Reference data used to build search filters — countries, sources, continents, regions, languages and categories. All values are cached and refreshed daily.

List categories

GET https://api.worldfeedmonitor.com/v1/metadata/categories

Raw categories as published by the source feeds, which number in the tens of thousands across languages — this endpoint is paginated and expects to be narrowed.

For a small, stable taxonomy to build against, use GET /metadata/macro-categories instead: twenty-one entries that do not grow with the feed catalogue.

Parameter Description
country
string
 Country, as an ISO 3166-1 alpha-2 or alpha-3 code — both are accepted, in any case. Restricts to categories used by feeds from that country.
IT
language
string
 Language code. Categories are held per language, so the same word in two languages is two entries.
en
macro_category
string
 Restrict to categories mapped to this macro category. Accepts its key or its uuid. A value matching neither is refused rather than ignored.
sport
q
string
 Matches categories whose name starts with this term.
sport
page
integer
 1-based page number.
per_page
integer
 Results per page.
200 A page of categories.
401 Missing, malformed, or invalid credentials.
403 Authenticated, but not permitted. Either the account is not active — a signup that never completed payment, or one deactivated after repeated payment failures — or the search asks for a country the plan does not include. Retrying unchanged will not succeed.
422 One or more parameters failed validation.
429 The plan's allowance for one of its windows is spent. window names which one and retry_after gives the seconds until it resets.
Response 
{
    "meta": {
        "total_items": 0,
        "total_pages": 0,
        "items_per_page": 0,
        "current_page": 0,
        "has_previous": true,
        "has_next": true,
        "applied_filters": []
    },
    "data": [
        {
            "uuid": "string",
            "name": "Europe",
            "key": "europe"
        }
    ]
}

Continent region

GET https://api.worldfeedmonitor.com/v1/metadata/continent-regions/{continent_region}

One continent region, addressed by its key or uuid, in any case.

A single record carries no meta block — pagination has nothing to say about one thing.

Parameter Description
continent_region
string · path
Required
 The continent region key or uuid.
southern_europe
200 The continent region.
401 Missing, malformed, or invalid credentials.
403
404 No continent region by that key or uuid.
429
Response 
{
    "data": {
        "uuid": "string",
        "name": "string",
        "key": "string"
    }
}

List continents

GET https://api.worldfeedmonitor.com/v1/metadata/continents

All continents. Use key as the continent filter on /feeds/search.

200 Every continent.
401 Missing, malformed, or invalid credentials.
403 Authenticated, but not permitted. Either the account is not active — a signup that never completed payment, or one deactivated after repeated payment failures — or the search asks for a country the plan does not include. Retrying unchanged will not succeed.
429 The plan's allowance for one of its windows is spent. window names which one and retry_after gives the seconds until it resets.
Response 
{
    "meta": {
        "total_items": 0,
        "total_pages": 0,
        "items_per_page": 0,
        "current_page": 0,
        "has_previous": true,
        "has_next": true,
        "applied_filters": []
    },
    "data": [
        {
            "uuid": "string",
            "name": "Europe",
            "key": "europe"
        }
    ]
}

List regions of a continent

GET https://api.worldfeedmonitor.com/v1/metadata/continents/{continent_key}/regions

Sub-regions belonging to a continent. Use key as the continent_region filter on /feeds/search.

Parameter Description
continent_key
string · path
Required
 Continent key. Discover valid values via GET /metadata/continents (key).
europe
200 The continent's regions.
401 Missing, malformed, or invalid credentials.
403 Authenticated, but not permitted. Either the account is not active — a signup that never completed payment, or one deactivated after repeated payment failures — or the search asks for a country the plan does not include. Retrying unchanged will not succeed.
422 One or more parameters failed validation.
429 The plan's allowance for one of its windows is spent. window names which one and retry_after gives the seconds until it resets.
Response 
{
    "meta": {
        "total_items": 0,
        "total_pages": 0,
        "items_per_page": 0,
        "current_page": 0,
        "has_previous": true,
        "has_next": true,
        "applied_filters": []
    },
    "data": [
        {
            "uuid": "string",
            "name": "Europe",
            "key": "europe"
        }
    ]
}

Continent

GET https://api.worldfeedmonitor.com/v1/metadata/continents/{continent}

One continent, addressed by its key or uuid, in any case.

A single record carries no meta block — pagination has nothing to say about one thing.

Parameter Description
continent
string · path
Required
 The continent key or uuid.
europe
200 The continent.
401 Missing, malformed, or invalid credentials.
403
404 No continent by that key or uuid.
429
Response 
{
    "data": {
        "uuid": "string",
        "name": "string",
        "key": "string"
    }
}

List countries

GET https://api.worldfeedmonitor.com/v1/metadata/countries

All countries with ISO codes. Use iso_3 as the country filter on /feeds/search.

200 Every country.
401 Missing, malformed, or invalid credentials.
403 Authenticated, but not permitted. Either the account is not active — a signup that never completed payment, or one deactivated after repeated payment failures — or the search asks for a country the plan does not include. Retrying unchanged will not succeed.
429 The plan's allowance for one of its windows is spent. window names which one and retry_after gives the seconds until it resets.
Response 
{
    "meta": {
        "total_items": 0,
        "total_pages": 0,
        "items_per_page": 0,
        "current_page": 0,
        "has_previous": true,
        "has_next": true,
        "applied_filters": []
    },
    "data": [
        {
            "uuid": "string",
            "name": "United States",
            "iso_2": "US",
            "iso_3": "USA"
        }
    ]
}

List sources

GET https://api.worldfeedmonitor.com/v1/metadata/countries/{country_code}/sources

News sources published from one country.

The country goes where it belongs: under /metadata/countries, with sources last, because the last collection in the path is what comes back.

Parameter Description
country_code
string · path
 Country, as an ISO 3166-1 alpha-2 or alpha-3 code — both are accepted, in any case. Discover valid values via GET /metadata/countries (iso_2 or iso_3).
US
page
integer
 1-based page number.
per_page
integer
 Results per page.
200 A page of sources.
401 Missing, malformed, or invalid credentials.
403 Authenticated, but not permitted. Either the account is not active — a signup that never completed payment, or one deactivated after repeated payment failures — or the search asks for a country the plan does not include. Retrying unchanged will not succeed.
422 One or more parameters failed validation.
429 The plan's allowance for one of its windows is spent. window names which one and retry_after gives the seconds until it resets.
Response 
{
    "meta": {
        "total_items": 0,
        "total_pages": 0,
        "items_per_page": 0,
        "current_page": 0,
        "has_previous": true,
        "has_next": true,
        "applied_filters": []
    },
    "data": [
        {
            "uuid": "string",
            "key": "rnz-pacific-mh",
            "name": "Example News",
            "url": "https://example-news.com",
            "type": {
                "uuid": "string",
                "key": "regulator",
                "name": "Regulator"
            },
            "sector": {
                "uuid": "string",
                "key": "pharmaceuticals",
                "name": "Pharmaceuticals"
            }
        }
    ]
}

List languages

GET https://api.worldfeedmonitor.com/v1/metadata/languages

All languages. Use code as the language filter on /feeds/search.

200 Every language.
401 Missing, malformed, or invalid credentials.
403 Authenticated, but not permitted. Either the account is not active — a signup that never completed payment, or one deactivated after repeated payment failures — or the search asks for a country the plan does not include. Retrying unchanged will not succeed.
429 The plan's allowance for one of its windows is spent. window names which one and retry_after gives the seconds until it resets.
Response 
{
    "meta": {
        "total_items": 0,
        "total_pages": 0,
        "items_per_page": 0,
        "current_page": 0,
        "has_previous": true,
        "has_next": true,
        "applied_filters": []
    },
    "data": [
        {
            "uuid": "string",
            "name": "English",
            "local_name": "English",
            "code": "en"
        }
    ]
}

List macro-categories

GET https://api.worldfeedmonitor.com/v1/metadata/macro-categories

Top-level AI categories. Use key as the category filter on /feeds/search.

200 The macro taxonomy.
401 Missing, malformed, or invalid credentials.
403 Authenticated, but not permitted. Either the account is not active — a signup that never completed payment, or one deactivated after repeated payment failures — or the search asks for a country the plan does not include. Retrying unchanged will not succeed.
429 The plan's allowance for one of its windows is spent. window names which one and retry_after gives the seconds until it resets.
Response 
{
    "meta": {
        "total_items": 0,
        "total_pages": 0,
        "items_per_page": 0,
        "current_page": 0,
        "has_previous": true,
        "has_next": true,
        "applied_filters": []
    },
    "data": [
        {
            "uuid": "string",
            "name": "Europe",
            "key": "europe"
        }
    ]
}

Macro category

GET https://api.worldfeedmonitor.com/v1/metadata/macro-categories/{macro_category}

One macro category, addressed by its key or uuid, in any case.

A single record carries no meta block — pagination has nothing to say about one thing.

Parameter Description
macro_category
string · path
Required
 The macro category key or uuid.
sports
200 The macro category.
401 Missing, malformed, or invalid credentials.
403
404 No macro category by that key or uuid.
429
Response 
{
    "data": {
        "uuid": "string",
        "name": "string",
        "key": "string"
    }
}

Categories within a macro category

GET https://api.worldfeedmonitor.com/v1/metadata/macro-categories/{macro_category}/categories

The categories listing scoped to one macro category, which is taken from the path by key or uuid. Every other filter still applies, so this is the same listing narrowed rather than a different one.

Use it to walk the taxonomy: GET /metadata/macro-categories for the twenty-one stable entries, then this for the raw feed categories mapped beneath one of them.

Parameter Description
macro_category
string · path
Required
 The macro category, by key or uuid.
sport
country
string
 Country, as an ISO 3166-1 alpha-2 or alpha-3 code — both are accepted, in any case. Restricts to categories used by feeds from that country.
IT
language
string
 Language code. Categories are held per language, so the same word in two languages is two entries.
en
q
string
 Matches categories whose name starts with this term.
sport
page
integer
 1-based page number.
per_page
integer
 Results per page.
200 A page of categories.
401 Missing, malformed, or invalid credentials.
403 Authenticated, but not permitted. Either the account is not active — a signup that never completed payment, or one deactivated after repeated payment failures — or the search asks for a country the plan does not include. Retrying unchanged will not succeed.
404 No macro category matches the given key or uuid.
422 One or more parameters failed validation.
429 The plan's allowance for one of its windows is spent. window names which one and retry_after gives the seconds until it resets.
Response 
{
    "meta": {
        "total_items": 0,
        "total_pages": 0,
        "items_per_page": 0,
        "current_page": 0,
        "has_previous": true,
        "has_next": true,
        "applied_filters": []
    },
    "data": [
        {
            "uuid": "string",
            "name": "Europe",
            "key": "europe"
        }
    ]
}

List sectors

GET https://api.worldfeedmonitor.com/v1/metadata/sectors

What a publisher is about — thirty-four values, fixed. Use key as the sector filter on /feeds/search. general is the value for a publisher with no subject speciality and is the most common answer, not a missing one.

200 List sectors.
401 Missing, malformed, or invalid credentials.
403 Authenticated, but not permitted. Either the account is not active — a signup that never completed payment, or one deactivated after repeated payment failures — or the search asks for a country the plan does not include. Retrying unchanged will not succeed.
429 The plan's allowance for one of its windows is spent. window names which one and retry_after gives the seconds until it resets.
Response 
{
    "meta": {
        "total_items": 0,
        "total_pages": 0,
        "items_per_page": 0,
        "current_page": 0,
        "has_previous": true,
        "has_next": true,
        "applied_filters": []
    },
    "data": [
        {
            "uuid": "string",
            "key": "regulator",
            "name": "Regulator",
            "description": "A supervisory body with statutory power over a market."
        }
    ]
}

Sector

GET https://api.worldfeedmonitor.com/v1/metadata/sectors/{sector}

One sector, addressed by its key or uuid, in any case.

Parameter Description
sector
string · path
Required
 The sector key or uuid.
pharmaceuticals
200 Sector.
401 Missing, malformed, or invalid credentials.
403
404 No macro category by that key or uuid.
429
Response 
{
    "data": {
        "uuid": "string",
        "key": "regulator",
        "name": "Regulator",
        "description": "A supervisory body with statutory power over a market."
    }
}

List source types

GET https://api.worldfeedmonitor.com/v1/metadata/source-types

What a publisher is — eight values, fixed. Use key as the source_type filter on /feeds/search. Each entry carries the sentence that defines it, which is the same definition the classifier works from.

200 List source types.
401 Missing, malformed, or invalid credentials.
403 Authenticated, but not permitted. Either the account is not active — a signup that never completed payment, or one deactivated after repeated payment failures — or the search asks for a country the plan does not include. Retrying unchanged will not succeed.
429 The plan's allowance for one of its windows is spent. window names which one and retry_after gives the seconds until it resets.
Response 
{
    "meta": {
        "total_items": 0,
        "total_pages": 0,
        "items_per_page": 0,
        "current_page": 0,
        "has_previous": true,
        "has_next": true,
        "applied_filters": []
    },
    "data": [
        {
            "uuid": "string",
            "key": "regulator",
            "name": "Regulator",
            "description": "A supervisory body with statutory power over a market."
        }
    ]
}

Source type

GET https://api.worldfeedmonitor.com/v1/metadata/source-types/{source_type}

One source type, addressed by its key or uuid, in any case.

Parameter Description
source_type
string · path
Required
 The source type key or uuid.
regulator
200 Source type.
401 Missing, malformed, or invalid credentials.
403
404 No macro category by that key or uuid.
429
Response 
{
    "data": {
        "uuid": "string",
        "key": "regulator",
        "name": "Regulator",
        "description": "A supervisory body with statutory power over a market."
    }
}

Sectors a source type can take

GET https://api.worldfeedmonitor.com/v1/metadata/source-types/{source_type}/sectors

The sectors this kind of publisher can be about. The pairing is part of the taxonomy rather than a suggestion: source_type=government&sector=semiconductors matches nothing because no such publisher is classifiable, and this is how to find that out without guessing.

Parameter Description
source_type
string · path
Required
 The source type key or uuid.
company
200 Sectors a source type can take.
401 Missing, malformed, or invalid credentials.
403 Authenticated, but not permitted. Either the account is not active — a signup that never completed payment, or one deactivated after repeated payment failures — or the search asks for a country the plan does not include. Retrying unchanged will not succeed.
429 The plan's allowance for one of its windows is spent. window names which one and retry_after gives the seconds until it resets.
Response 
{
    "meta": {
        "total_items": 0,
        "total_pages": 0,
        "items_per_page": 0,
        "current_page": 0,
        "has_previous": true,
        "has_next": true,
        "applied_filters": []
    },
    "data": [
        {
            "uuid": "string",
            "key": "regulator",
            "name": "Regulator",
            "description": "A supervisory body with statutory power over a market."
        }
    ]
}

Sources

GET https://api.worldfeedmonitor.com/v1/metadata/sources

Every news source, paginated.

For the sources of one country, use GET /metadata/countries/{country_code}/sources.

Parameter Description
page
integer
 1-based page number.
per_page
integer
 Results per page.
200 A page of sources.
401 Missing, malformed, or invalid credentials.
403 Authenticated, but not permitted. Either the account is not active — a signup that never completed payment, or one deactivated after repeated payment failures — or the search asks for a country the plan does not include. Retrying unchanged will not succeed.
422 One or more parameters failed validation.
429 The plan's allowance for one of its windows is spent. window names which one and retry_after gives the seconds until it resets.
Response 
{
    "meta": {
        "total_items": 0,
        "total_pages": 0,
        "items_per_page": 0,
        "current_page": 0,
        "has_previous": true,
        "has_next": true,
        "applied_filters": []
    },
    "data": [
        {
            "uuid": "string",
            "key": "rnz-pacific-mh",
            "name": "Example News",
            "url": "https://example-news.com",
            "type": {
                "uuid": "string",
                "key": "regulator",
                "name": "Regulator"
            },
            "sector": {
                "uuid": "string",
                "key": "pharmaceuticals",
                "name": "Pharmaceuticals"
            }
        }
    ]
}

Source

GET https://api.worldfeedmonitor.com/v1/metadata/sources/{source}

One news source, addressed by its uuid or its exact name.

The country it belongs to comes with it: a caller arriving from a search result has an identifier and little else, and the country is usually what they need next.

A single record carries no meta block.

Parameter Description
source
string · path
Required
 The source key or uuid, either of which identifies exactly one source. Its exact name is still accepted, but names are not unique and an ambiguous one returns an arbitrary match.
rnz-pacific-mh
200 The source.
401 Missing, malformed, or invalid credentials.
403
404 No source by that uuid or name.
429
Response 
{
    "data": {
        "uuid": "string",
        "key": "rnz-pacific-mh",
        "name": "string",
        "url": "string",
        "type": {
            "uuid": "string",
            "key": "media",
            "name": "Media"
        },
        "sector": {
            "uuid": "string",
            "key": "general",
            "name": "General"
        },
        "country": {
            "uuid": "string",
            "name": "string",
            "iso_2": "string",
            "iso_3": "string"
        }
    }
}