Machine-readable docs: llms.txt (index), llms-full.txt (complete reference), OpenAPI specification.

NewsAPI.ai API Documentation | Endpoints, SDKs, and Key Access Explained: Access the complete API documentation for NewsAPI.ai. Learn about endpoints, parameters, Python and Node.js SDKs, rate limits, and response codes. Get started quickly with free registration and your API key.
Semantic Annotation API | Identify Entities in Text with NewsAPI.ai: Use NewsAPI.ai's annotation tool to uniquely identify people, locations, organizations, and concepts within documents. Supports over 100 languages with semantic annotations linked to Wikipedia pages.
Semantic Similarity API | Compare Cross-Language Document Similarity with NewsAPI.ai: Compare the semantic similarity between two documents in different languages with NewsAPI.ai's Semantic Similarity API. Identify shared entities and gain deep contextual insights.
Get Articles API | Search News and PR Content with Advanced Filters from NewsAPI.ai: Find news articles matching one or more search conditions with NewsAPI.ai's Get Articles API. Use advanced search parameters to retrieve the most relevant content, from keywords to locations.
Get Articles for Topic Page API | Topic-Based News Search with NewsAPI.ai: Retrieve news articles that match a user-generated topic page with NewsAPI.ai's Get Articles for Topic Page API. Use unique URIs to easily filter by concepts, keywords, news sources, and more.
Stream New News Articles in Real-Time with NewsAPI.ai: Access new articles added to Event Registry with NewsAPI.ai's 'Stream of New Articles' endpoint. Set up filters to get the latest news content directly to your application.
Search and Retrieve Events by Keyword or Concept with NewsAPI.ai: Discover events related to your interests with NewsAPI.ai. Use the Get Events endpoint to find events that match specific keywords, concepts, categories, and more.
Retrieve Events for User-Generated Topic Pages with NewsAPI.ai: Use NewsAPI.ai's Get Events for a Topic Page to retrieve events that match your user-generated topics. Customize searches with topic-specific URIs.
Retrieve Comprehensive Event Details with NewsAPI.ai: Obtain comprehensive details about specific events using NewsAPI.ai's Get Event Details endpoint. Retrieve articles, summaries, and other event metadata.
Access Real-Time Stream of Events with NewsAPI.ai: Access real-time streams of events added or updated in the last few minutes with NewsAPI.ai's Stream of Events endpoint. Filter by language, keywords, or locations.
Retrieve the Latest Breaking Events with NewsAPI.ai: Get a list of the most recent breaking events with NewsAPI.ai's Breaking Events endpoint. Retrieve events based on their breaking score and reporting intensity.
Suggest Concepts for API Queries with NewsAPI.ai: Find concept URIs with NewsAPI.ai's Suggest Concepts API. Retrieve concept details for various API queries by searching partial or full concept labels.
Suggest Categories for API Queries with NewsAPI.ai: Retrieve category URIs with NewsAPI.ai's Suggest Categories API. Search for categories by partial or full label to assist in filtering various API calls.
Suggest News Sources for API Queries with NewsAPI.ai: Use NewsAPI.ai's Suggest Sources API to retrieve news source URIs. Search by source name or domain name to assist in filtering API requests.
Suggest Authors for API Queries with NewsAPI.ai: Find author URIs with NewsAPI.ai's Suggest Authors API. Retrieve authors by name, including partial matches, to assist in API queries.
Suggest Locations for API Queries with NewsAPI.ai: Retrieve location URIs using NewsAPI.ai's Suggest Locations API. Search by city or country name to get relevant URIs for API filtering.
Suggest Event Types for API Queries with NewsAPI.ai: Find event type URIs with NewsAPI.ai's Suggest Event Types API. Retrieve event types for API calls by providing a label or prefix.
Terminology and Definitions for NewsAPI.ai & Event Registry: Explore terminology used in Event Registry and NewsAPI.ai. Learn about articles, events, concepts, categories, sources, and locations for API queries.
Supported Languages and Language Codes | NewsAPI.ai: See the full list of languages supported by NewsAPI.ai and Event Registry, with the language codes to use in the lang parameter of your API calls.
Advanced Search Query Language | NewsAPI.ai Documentation: Build advanced NewsAPI.ai queries with AND, OR and NOT logic. Learn the JSON query language to combine keywords, concepts, categories, sources and filters.
Keyword Search Modes — Phrase, Boolean & Simple | NewsAPI.ai: Learn NewsAPI.ai's keyword search modes: exact phrase matching, full Boolean logic (AND/OR/NOT, NEAR, NEXT), and relevance-based simple search, with examples.
Response Format and Data Models | NewsAPI.ai Documentation: Understand the response format of NewsAPI.ai. Explore the data models for articles, events, concepts, categories, sources and other returned JSON objects.
MCP Integration Guide | NewsAPI.ai for AI Assistants: Connect NewsAPI.ai to Claude, Codex, Cursor and other AI assistants with the hosted Model Context Protocol (MCP) server. Search news, track events, find mentions and use topic pages.
n8n Integration Overview | NewsAPI.ai Automation: Automate news workflows with NewsAPI.ai and n8n. Learn how to set up API credentials and connect Event Registry endpoints to no-code n8n automations.
n8n Example: Content Research Workflow | NewsAPI.ai: Build a content research assistant with NewsAPI.ai and n8n. Step-by-step workflow to fetch, split and email relevant news articles automatically.
n8n Example: News Alert System | NewsAPI.ai: Create a news alert system with NewsAPI.ai and n8n. Schedule searches, filter results with conditions, and send email alerts for breaking news automatically.
n8n Example: Sentiment Analysis Workflow | NewsAPI.ai: Track news sentiment with NewsAPI.ai and n8n. Build a workflow that collects articles, extracts sentiment, and logs results to Google Sheets for analysis.
Named entity recognition | Event Registry API documentation: Reference for the Named entity recognition endpoint of the Event Registry API: parameters, request examples and the response format.
Categorize | Event Registry API documentation: Reference for the Categorize endpoint of the Event Registry API: parameters, request examples and the response format.
Sentiment | Event Registry API documentation: Reference for the Sentiment endpoint of the Event Registry API: parameters, request examples and the response format.
Extract article information | Event Registry API documentation: Reference for the Extract article information endpoint of the Event Registry API: parameters, request examples and the response format.
Detect language | Event Registry API documentation: Reference for the Detect language endpoint of the Event Registry API: parameters, request examples and the response format.
Get article details | Event Registry API documentation: Reference for the Get article details endpoint of the Event Registry API: parameters, request examples and the response format.
Get mentions | Event Registry API documentation: Reference for the Get mentions endpoint of the Event Registry API: parameters, request examples and the response format.
API Usage | Event Registry API documentation: Reference for the API Usage endpoint of the Event Registry API: parameters, request examples and the response format.

Search query language

Simple queries

For simple queries, you can specify parameters such as keyword, conceptUri, categoryUri, sourceUri, etc. directly in the query parameters of the API call. This allows you to specify queries where multiple different conditions have to be met.

To control how the keyword parameter is matched against articles — as an exact phrase, a Boolean expression, or a relevance-based search — see the Keyword search modes section.

            
            {
    "conceptUri": "http://en.wikipedia.org/wiki/OpenAI",
    "conceptUri": "http://en.wikipedia.org/wiki/Amazon_(company)",
    "keyword": "AWS",
    "categoryUri": "news/Business",
    "sourceGroupUri": "business/top100",
    "apiKey": "YOUR_API_KEY"
}

Making a POST request with a JSON body from the example above would return you the list of articles that mention both companies, keyword "AWS", are categorized into Business category and are published by top 100 business news sources. As you can see, each added condition, additionally restrains the set of returned articles.

Advanced query language

For many users, however, a more complex way of specifying a query is required - such that contains a combination of AND, OR and NOT conditions. For such purposes, we provide a query language where conditions can be specified in a particular JSON object, that resembles the query language used by MongoDB. Using this language you can specify queries that are not possible to express directly using parameters keyword, conceptUri, categoryUri, etc.

When using the advanced query language, you specify the search conditions using a query parameter which contains a JSON object. The details of what the JSON object should look like are described in the sections below.

Note: When using the query parameter, you are not allowed to also specify regular parameters such as keyword, conceptUri, sourceUri, etc. as in the first example. Using a query like that would return an error since it is not clear how the regular parameters should be combined with the conditions specified in the query parameter.

            
            {
    "query": {          # JSON object matching the ComplexArticleQuery grammar below
        "$query": {
            ...
        }
    },
    "apiKey": "YOUR_API_KEY"
}

Query grammar

            
            ComplexArticleQuery ::=
{
    "$query": CombinedQuery | BaseQuery,

    "$filter": null | {
        "dataType": null | "news" | "blog" | "pr" | ["news", ...]
        "isDuplicate": null | "keepAll" | "skipDuplicates" | "keepOnlyDuplicates",
        "hasEvent": null | "keepAll" | "skipArticlesWithoutEvent" | "keepOnlyArticlesWithoutEvent",
        "startSourceRankPercentile": null | 0 | 10 | 20 | 30 | 40 | 50 | 60 | 70 | 80 | 90,
        "endSourceRankPercentile": null | 10 | 20 | 30 | 40 | 50 | 60 | 70 | 80 | 90 | 100,
        "minSentiment": null | float([-1,1]),
        "maxSentiment": null | float([-1,1])
    }
}

CombinedQuery ::=
{
    "$or": [ CombinedQuery | BaseQuery, ... ],
    "$not": null | CombinedQuery | BaseQuery
}

CombinedQuery ::=
{
    "$and": [ CombinedQuery | BaseQuery, ... ],
    "$not": null | CombinedQuery | BaseQuery
}

BaseQuery ::=
{
    "conceptUri": null | string | { "$or": [ string, ... ]} | { "$and": [ string, ... ]},
    "keyword": null | string | { "$or": [ string, ... ]} | { "$and": [ string, ... ]},
    "categoryUri": null | string | { "$or": [ string, ... ]} | { "$and": [ string, ... ]},
    "lang": null | string | { "$or": [ string, ... ]} | { "$and": [ string, ... ]},

    "sourceUri": null | string | { "$or": [ string, ... ]},
    "sourceLocationUri": null | string | { "$or": [ string, ... ]},
    "sourceGroupUri": null | string | { "$or": [ string, ... ]},

    "authorUri": null | string | { "$or": [ string, ... ]} | { "$and": [ string, ... ]},

    "locationUri": null | string | { "$or": [ string, ... ]},

    "dateStart": null | string,
    "dateEnd": null | string,
    "dateMention": null | [string, ... ],

    "keywordLoc": null | "body" | "title" | "title,body",
    "keywordSearchMode": null | "simple" | "exact" | "phrase",

    "minArticlesInEvent": null | int,
    "maxArticlesInEvent": null | int,

    "$not": null | CombinedQuery | BaseQuery
}

Explanation

Each complex article query needs to be a JSON object that has a $query key and optionally a $filter key. The $query key must contain another JSON object that should be parsable as a CombinedQuery or a BaseQuery. A CombinedQuery can be used to specify a list of conditions, where all ($and) or any ($or) conditions should hold. The CombinedQuery can also contain a $not key containing another CombinedQuery or BaseQuery defining the results that should be excluded from the results computed by the $and or $or conditions.

The BaseQuery represents a JSON object with actual conditions to search for. These (positive) conditions can include concepts, keywords, categories, sources, authors, etc. to search for. If multiple conditions are specified — for example, a conceptUri as well as a sourceUri — then results will have to match all the conditions. The BaseQuery can also contain the $not key specifying results to exclude from the results matching the positive conditions. A BaseQuery containing only the $not key is not a valid query (since it has no positive conditions to exclude results from).

The complex article query can also have a $filter object. It can contain information about which data types to search for — the dataType property — which can be a simple string value or an array of values. You can also specify what should happen with articles that are (a) duplicates of other articles, (b) were later copied by other sources, and (c) are describing an event. Finally, you can also set the startSourceRankPercentile and endSourceRankPercentile filters to limit the results to certain subsets of news sources based on global Alexa ranking. By setting startSourceRankPercentile to 0 and endSourceRankPercentile to 20 you can limit the results to top-ranking news sources so that the resulting number of articles will be approximately 20% of all content that would be received without the filter.

Examples

A query that returns articles that mention the concept AI or the phrases "deep learning" or "machine learning", while excluding results that mention "data mining" in the article title. The results should also have a positive sentiment (>0.2) and should not be duplicates of other articles.

            
            {
    "query": {
        "$query": {
            "$or": [
                { "conceptUri": "http://en.wikipedia.org/wiki/Artificial_Intelligence" },
                {
                    "keyword": {
                        "$or": [ "deep learning", "machine learning" ]
                    }
                }
            ],
            "$not": {
                "keyword": "data mining",
                "keywordLoc": "title"
            }
        },
        "$filter": {
            "minSentiment": 0.2,
            "isDuplicate": "skipDuplicates"
        }
    },
    "apiKey": "YOUR_API_KEY"
}

A query that returns politics-related articles about both Donald Trump and Hillary Clinton, or business-related news that mention Elon Musk:

            
            {
    "query": {
        "$query": {
            "$or": [
                {
                    "conceptUri": {
                        "$and": [
                            "http://en.wikipedia.org/wiki/Donald_Trump",
                            "http://en.wikipedia.org/wiki/Hillary_Rodham_Clinton"
                        ]
                    },
                    "categoryUri": "dmoz/Society/Politics"
                },
                {
                    "conceptUri": "http://en.wikipedia.org/wiki/Elon_Musk",
                    "categoryUri": "dmoz/Business"
                }
            ]
        }
    },
    "apiKey": "YOUR_API_KEY"
}