canonical: https://jentic.com/apis/newswhip.com/newswhip # NewsWhip API NewsWhip provides social engagement data for news articles and Facebook posts, exposing 10 endpoints across content discovery, statistics, and influencer identification. The API surfaces region-, publisher-, and topic-scoped feeds via GET /region, /publisher, /local, and /search, while POST endpoints - /articles, /fbPosts, /stats, /fbInfluencers, /articlesByHrefs, /syndicatedArticles - accept richer query bodies for engagement analysis and influencer ranking. Authentication uses an API key passed as the key query parameter. ## For AI agents Find articles and Facebook posts ranked by social engagement, identify top influencers, and pull engagement stats by region, publisher, or topic. ## Scope Does not handle posting to social media, sentiment scoring, or article full-text retrieval - use for engagement-ranked content discovery and influencer identification only. ## Capabilities - Surface trending content by geographic region through GET /region with country and language filters - Pull all articles published by a specific outlet via GET /publisher for competitive coverage analysis - Search articles and Facebook posts ranked by engagement using POST /articles and POST /fbPosts - Identify top Facebook influencers for a topic or audience via POST /fbInfluencers - Aggregate engagement statistics across a search query with POST /stats - Resolve specific URLs to engagement data through POST /articlesByHrefs - Trace syndicated reuses of an article across the publisher network with POST /syndicatedArticles ## Use cases ### Earned-Media Campaign Tracking Communications and PR teams use NewsWhip to track how a story performs once published - POST /articles ranked by engagement, POST /stats for total shares, and POST /syndicatedArticles to find every outlet that picked the story up. The data feeds weekly campaign reports that show reach beyond the issuing outlet, including syndicated coverage that traditional clipping services miss. Example prompt: Find the top 20 most-shared English-language articles mentioning 'Project Alpha' in the last 7 days and aggregate total Facebook shares ### Influencer Discovery for Facebook Campaigns Marketing teams launching a Facebook-led campaign use POST /fbInfluencers to identify the public pages and accounts driving conversation in their topic. The endpoint returns ranked influencers with engagement metrics, so an agent can shortlist candidates for partnership outreach without manual scrolling through Facebook search. Example prompt: Identify the top 10 Facebook influencers posting about sustainable fashion in the last 30 days ### Regional Content Trend Monitoring Newsroom and analyst teams pull country-scoped feeds through GET /region and GET /local to see what is trending in specific markets. Combined with POST /stats, this gives a continuously updated view of share volume and engagement velocity per region, enabling editorial decisions on which stories to translate, syndicate, or follow up. Example prompt: Get the most-engaged English-language articles in Ireland for the last 24 hours from GET /region ### Agent-Assisted Engagement Research An AI agent uses NewsWhip through Jentic to answer engagement questions in natural language. The agent translates 'what was the most-shared article about the AI Act last month' into a POST /articles call with the right query and date range, summarises the response, and cites the top URLs. Jentic handles the API key injection and parameter shaping. Example prompt: Answer 'what were the top 5 most-shared articles about the EU AI Act in May' using POST /articles and return the URLs with share counts ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/articles` | Search articles ranked by social engagement | | POST | `/fbPosts` | Search Facebook posts ranked by engagement | | POST | `/stats` | Aggregate engagement statistics for a query | | POST | `/fbInfluencers` | Identify top Facebook influencers for a topic | | GET | `/region` | Get trending content by country and language | | GET | `/publisher` | Get articles by a specific publisher | | POST | `/articlesByHrefs` | Look up engagement data for specific article URLs | ## Key resources - **Region** — Surface engagement-ranked content scoped to a country or language - **Publisher** — Retrieve articles published by a specific outlet - **Articles** — Search articles by query and rank by social engagement metrics - **Facebook Posts** — Search public Facebook posts and identify high-engagement content - **Influencers** — Identify top Facebook influencers for a topic or query - **Stats** — Aggregate engagement statistics across a search query - **Syndicated Articles** — Trace the spread of an article across the publisher network ## Why Jentic - **Setup:** Wiring NewsWhip by hand means appending its API key as a query parameter on every call, pointing at the api.newswhip.com/v1 host, and shaping the POST search bodies yourself. Through Jentic you install once, import the NewsWhip API from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** NewsWhip carries its search targets in the request body rather than the URL path, so scope your agent by operation: limit it to the operations it needs, such as ranking articles or identifying Facebook influencers, and leave the others out of the allowed set. You choose which operations it may call. - **Credential handling:** Your NewsWhip API key is stored once, encrypted, by your own Jentic One instance and appended to the request as the key query parameter at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'find the most-shared articles about a topic' or 'identify Facebook influencers', and Jentic returns the matching NewsWhip operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **News API** — News API returns article text and headlines without engagement metrics; NewsWhip ranks the same article universe by social shares - **Mediastack API** — Mediastack provides article search across 7,500+ sources without engagement ranking - **GNews API** — GNews offers global news article search without share-count or influencer endpoints ## FAQ ### What authentication does the NewsWhip API use? NewsWhip authenticates with an API key passed as the key query parameter on every request. Through Jentic the key is held in the encrypted vault and Jentic appends it to outgoing requests, so the raw value never appears in agent prompts or logs. ### Can I find Facebook influencers by topic with the NewsWhip API? Yes. POST /fbInfluencers accepts a query body and returns ranked Facebook pages and accounts with engagement metrics. This is the endpoint to use when an agent needs a shortlist of public influencers in a niche, rather than the per-post ranking that POST /fbPosts provides. ### What is the difference between /articles and /publisher in the NewsWhip API? POST /articles searches across all indexed publishers using a query body and ranks by engagement. GET /publisher returns articles from a single specified outlet without engagement-based ranking. Use /articles for topic-driven research and /publisher for competitive coverage analysis of a specific site. ### How do I trace where an article was syndicated through Jentic? Search Jentic for 'find syndicated copies of an article', load the POST /syndicatedArticles schema, and execute with the original URL. Jentic injects the API key automatically and the response lists every detected republication. ### Does the NewsWhip API include historical engagement data? The API surfaces engagement at the time of the call and supports look-back queries within the limits of the NewsWhip account plan. Date-range parameters on the search endpoints let an agent specify the window - historical depth and per-call result limits depend on the subscription tier. ### Can I limit what my agent is allowed to do with the NewsWhip API? Yes. Because you run Jentic One yourself, your own rules decide which NewsWhip operations and credentials the agent can use. Since NewsWhip carries its search targets in the request body rather than the URL path, you scope the agent by operation: allow only the ones it needs, such as POST /articles for ranking articles or POST /fbInfluencers for identifying Facebook influencers, and leave the rest out of the allowed set. Operations you do not permit, like POST /syndicatedArticles or GET /publisher, stay off limits, and your stored API key is appended at execution time without ever entering the agent's prompt.