Documentation Index
Fetch the complete documentation index at: https://docs.wokelo.ai/llms.txt
Use this file to discover all available pages before exploring further.
1. Overview
The Company News Monitoring API fetches the latest news articles for a given company, enriched with AI-generated summaries, structured event categories, sentiment classifications, publisher metadata, and scraped article text. Results are returned synchronously in the HTTP response — no job polling required. This is a synchronous GET API — you pass a company identifier and optional filters as URL parameters, and receive a paginated array of enriched news articles immediately. Each article in the response includes:- AI summary — a concise, machine-generated synopsis of the article’s key facts and implications
- Event categorisation — a
primary_tagand up to severalsecondary_tagsdrawn from Wokelo’s 86-category news taxonomy - Sentiment signal —
Positive,Neutral, orNegativeclassification at the article level - Newsworthiness impact —
High,Medium, orLowrating assessing the article’s strategic significance - Publisher and author metadata — source domain, author name, publication date, and original language
- Company mentions — a structured array of all companies named in the article, with their resolved websites
- Full article text — the complete
scraped_textfor downstream summarisation, embedding, or LLM processing
- Portfolio adverse signal monitoring — Filter for
LEGAL AND COMPLIANCE,LAY-OFFS,FINANCIAL DISTRESS & RESTRUCTURING, orCYBERSECURITY INCIDENTScategories to catch early warning signals across a watchlist - Deal due diligence — Pull all news for a target company in the past 12 months, filter by
MERGERS & ACQUISITIONS,REGULATORY APPROVALS & CERTIFICATIONS, andLEGAL PROCEEDINGS & LITIGATIONto surface relevant deal context fast - Competitive intelligence — Monitor
PRODUCT LAUNCHES & ENHANCEMENTS,PARTNERSHIPS & ALLIANCES, andGEOGRAPHIC EXPANSIONcategories for a set of competitors on a rolling basis - Executive monitoring — Track
C-SUITE APPOINTMENTS & DEPARTURES,EXECUTIVE COMMENTARY & INTERVIEWS, andSUCCESSION PLANNINGfor key personnel across your coverage universe - LLM-powered research — Use the
scraped_textfield to feed full article content directly into your own summarisation or RAG pipeline, pre-filtered by category and date
This API is synchronous. Results are returned directly in the HTTP response — no job submission or polling required. See How Sync APIs work.
2. Quick Start
Step 1 — Make a simple request3. Authentication
All requests must include a Bearer token in theAuthorization HTTP header. No other authentication method is supported.
4. Request Reference
Endpoint| Parameter | Type | Required | Description |
|---|---|---|---|
company | string | Required | Company permalink (e.g. "tesla") or a full company URL (e.g. "https://www.tesla.com/"). Use the Company Search API to resolve a company name to its permalink. |
start_date | string | Optional | Start of the date window for articles (YYYY-MM-DD). Inclusive. |
end_date | string | Optional | End of the date window for articles (YYYY-MM-DD). Inclusive. |
category | string | Optional | Comma-separated list of news categories to filter by. Returns only articles whose primary_tag or secondary_tags match. View all 86 supported categories. Example: "MERGERS & ACQUISITIONS, PRODUCT LAUNCHES & ENHANCEMENTS". |
limit | integer | Optional | Maximum number of articles to return. Default 100, max 1000. |
offset | integer | Optional | Number of articles to skip before returning results. Use with limit for pagination. |
blacklisted | string | Optional | Comma-separated list of publisher domains to exclude. Include the full domain starting with https:// (e.g. "https://www.prnewswire.com/"). |
publishers | string | Optional | Comma-separated list of publisher domains to include exclusively. All other publishers are excluded. |
5. Response
Response structure
| Field | Type | Description |
|---|---|---|
status | string | "success" when the request was processed successfully. |
data | array | Array of enriched article objects. |
count | integer | Number of articles returned in this response. |
total | integer | Total number of matching articles available (before limit and offset are applied). |
limit | integer | The limit value that was applied. |
offset | integer | The offset value that was applied. |
Article object fields
Each object in thedata array contains the following fields:
Article content
| Field | Type | Description |
|---|---|---|
title | string | Headline of the article. |
url | string | Canonical URL of the original article. |
ai_summary | string | AI-generated 2–4 sentence summary of the article’s key facts and implications. |
scraped_text | string | Full text content of the article as scraped from the source. Use this for downstream LLM processing, embeddings, or detailed analysis. May be empty for paywalled articles. |
published_date | string | Publication datetime in YYYY-MM-DD HH:MM:SS format (UTC). |
original_language | string | ISO 639-1 language code of the original article (e.g. "EN"). Empty string when not detected. |
| Field | Type | Description |
|---|---|---|
publisher | string | Domain name of the publishing outlet (e.g. "bloomberg", "techcrunch"). |
author | string | Author name(s) as extracted from the article. May contain multiple names or be empty. |
source | string | Wokelo’s internal signal source designation. Either "Wokelo" (directly indexed) or "Google" (sourced via search). |
| Field | Type | Description |
|---|---|---|
primary_tag | string | The single most relevant event category from Wokelo’s 86-category taxonomy. See supported categories. May be empty for older articles. |
type | string | Alias for primary_tag. Present in some responses; use primary_tag as the canonical field. |
secondary_tags | string[] | Additional relevant categories from the taxonomy. Empty array when no secondary categories apply. |
| Field | Type | Description |
|---|---|---|
sentiment | string | Article-level sentiment: "Positive", "Neutral", or "Negative". Empty string when not yet classified. |
newsworthiness_impact | string | Strategic significance rating: "High", "Medium", or "Low". Empty string when not yet classified. |
| Field | Type | Description |
|---|---|---|
countries | string[] | Array of ISO 3166-1 alpha-3 country codes relevant to the article (e.g. ["USA", "CHN"]). Empty array when not detected. |
company_name | string | The company that was queried (mirrors the company parameter). |
company_names | object[] | Structured array of all companies mentioned in the article. Each object contains name (string) and website (string). Useful for identifying deal counterparties, partners, and competitors referenced in the article. |
The
company_names array includes all entities mentioned in the article — not just the queried company. This makes it useful for surfacing deal counterparties, lead investors, named competitors, and co-signatories in regulatory filings without having to parse the article text.Sentiment values
| Value | Meaning |
|---|---|
"Positive" | Article conveys favourable news — growth, wins, new partnerships, positive earnings |
"Neutral" | Factual or mixed coverage with no clear directional bias |
"Negative" | Article conveys unfavourable news — regulatory action, layoffs, declining metrics, litigation |
"" | Sentiment classification not yet available for this article |
Newsworthiness impact values
| Value | Meaning |
|---|---|
"High" | Material signal likely to affect strategic positioning, valuation, or stakeholder decisions |
"Medium" | Notable development worth tracking but not immediately actionable |
"Low" | Routine coverage, minor updates, or tangentially related content |
"" | Impact rating not yet available for this article |
Notes on empty fields
Several fields can be empty strings or empty arrays in valid responses:sentiment,newsworthiness_impact,primary_tag,original_language— empty string when classification has not yet been applied to this article, particularly for older contentsecondary_tags,countries,company_names— empty array when no values were detectedscraped_text— empty string for paywalled articles or pages that blocked scrapingauthor— empty string when the byline was not present or parseable
6. Examples
Portfolio adverse signal monitoring
Get all legal, compliance, layoff, and financial distress news for a portfolio company to catch early warning signals.Deal due diligence — target company news sweep
Pull all news for an acquisition target over a defined period, prioritise by category, and exclude press release sources to focus on independent coverage.Competitive monitoring — product launches and partnerships
Track product and partnership news for a set of competitors over a rolling 90-day window.Paginating through large result sets
Whentotal exceeds limit, paginate using offset to retrieve all matching articles.
Extracting article text for LLM processing
Usescraped_text to feed full article content into a summarisation or classification pipeline.
JavaScript / Node.js
7. Error Handling
The API uses standard HTTP status codes. All error responses include a JSON body with adetail or message field.
| Status | Meaning | Cause & Resolution |
|---|---|---|
200 OK | Success | Articles returned successfully. |
400 Bad Request | Invalid parameters | A required parameter is missing or a value is invalid — e.g. missing company, malformed start_date, or unrecognised category string. Check the detail field. |
401 Unauthorized | Auth failed | The Authorization header is missing, malformed, or contains an invalid token. Verify your key in Settings → API Keys. |
403 Forbidden | Insufficient access | Your plan does not include access to this endpoint or company. Contact support@wokelo.ai to review your plan. |
404 Not Found | Company not found | The company permalink could not be resolved. Use the Company Search API to verify the permalink before querying. |
429 Too Many Requests | Rate limit exceeded | Implement exponential back-off. The response includes a Retry-After header. |
500 Internal Server Error | Server error | Retry after a brief delay. If the issue persists, contact support@wokelo.ai. |
8. Best Practices
Use thecompany permalink, not a display name
The company parameter expects a permalink (e.g. "tesla", "brex") or a full URL. Passing a display name like "Tesla Inc." will not resolve correctly. Use the Company Search API to look up the permalink for any company:
category to reduce noise — this is the highest-impact parameter
Returning all news for a major company like Tesla or Apple can yield hundreds of articles, many of which are market data reports, stock price articles, or tangentially related coverage. Use the category filter aggressively to surface only the signal types relevant to your workflow. Combine multiple categories with a comma:
blacklisted
Wire service articles (prnewswire.com, businesswire.com, globenewswire.com) are often company-issued press releases that add volume without independent editorial perspective. Blacklist them for competitive intelligence and monitoring use cases where you want journalist-authored coverage:
newsworthiness_impact to triage before reading
When processing large result sets, filter to "High" impact articles first for executive briefings or urgent monitoring workflows. "Medium" and "Low" articles can be batch-processed later:
primary_tag, sentiment, newsworthiness_impact, and original_language can be empty strings for older articles or articles still pending classification. Always use .get() with a default rather than direct key access:
scraped_text for downstream LLM pipelines — but expect some gaps
scraped_text contains the full article body and is ideal for passing to summarisation, classification, or embedding models. However, paywalled articles (Bloomberg, FT, WSJ) will often have empty or truncated scraped_text. Use ai_summary as a fallback:
total exceeds limit
The default limit is 100 and the maximum is 1000. For queries returning large result sets, check total against count and paginate using offset until all records are retrieved. Stop when count returns 0 or len(all_articles) >= total.
Use company_names to map article networks
The company_names array resolves all entity mentions in the article, not just the queried company. This lets you identify deal counterparties, named investors, or competitors without text parsing — useful for building relationship graphs across a coverage universe.
9. Related APIs
Industry News Monitoring
Monitor the latest news across an entire industry or sector, rather than a single company.
Newsfeed
Retrieve a curated, cross-company newsfeed based on a topic, theme, or portfolio watchlist.
Company Deep Intelligence
Generate a comprehensive AI intelligence report on any company — strategy, financials, and competitive position.
Company Instant Enrichment
Synchronously enrich firmographic and financial data for any company by permalink or URL.
Target Screening
Identify and score potential acquisition targets — AI-ranked with deal feasibility, synergy, and precedent scores.
Supporting APIs
Company Search, Request Status, and other utilities used alongside monitoring workflows.