List, search, and bulk-export aggregated cybersecurity news
The workhorse endpoint for the News API. One URL gives you list, filter, full-text search, delta polling, and bulk export — composed via query parameters.
What it returns
A flat Article object per row. Every field is top-level (source_name not source.name) so streaming and CSV parsing are zero-friction. See the Article schema for the complete shape.
Common use cases
1. Today’s critical-severity vulnerabilities
2. Delta poll for SIEM/SOAR sync (recommended pattern)
Persist the last modified_at you saw on each run; pass it back as modified_since on the next call. Use X-Next-Cursor to walk multi-page deltas.
3. Bulk NDJSON export with IOC expansions (Pro)
Returns one homogeneous JSON object per line. Stream-parse with for line in r: json.loads(line).
4. Threat-actor research feed
5. Industry-targeted intel (finance + healthcare)
6. Sparse fields for high-volume polling
Cuts payload by ~80% and reduces DB I/O proportionally.
Tier behavior
| Tier | Lookback | Per-request cap | Formats |
|---|---|---|---|
| Free | 7 days | 100 | JSON |
| Pro | 365 days | 1,000 (5,000 for export) | + NDJSON, CSV (requires read:articles:export) |
Pagination
Use cursor pagination for any walk past 1,000 rows. The response contains links.next (full URL) and X-Next-Cursor (header) — pass either back as ?cursor=. Offsets > 1000 are rejected with deep_paging_unsupported.
Response signaling headers
| Header | When | Meaning |
|---|---|---|
X-Next-Cursor | More pages exist | Opaque cursor for next page |
X-Tier-Lookback-Days | Always | Effective lookback window for the caller’s tier |
X-Tier-Lookback-Clamped | since was clamped | Caller asked for older data than tier allows; clamped silently |
X-Limit-Capped | limit exceeded tier cap | Caller’s requested limit was reduced |
X-Format-Cost-Multiplier | Always | Rate-limit cost multiplier for this format (NDJSON/CSV cost more) |
Deprecation + Sunset | Legacy ?cve= param used | Migrate to cve_text_search |
Query Parameters
Comma-separated source names. Use exact names from /api/v1/sources (or the supported sources docs).
"BleepingComputer,Krebs on Security"
Comma-separated canonical category slugs. Available: attacks-breaches, vulnerabilities, threat-intel, malware, cloud-security, endpoint-security, network-security, identity-access, application-security, data-security, security-operations, incident-response, compliance, ai-ml-security, iot-ot.
"vulnerabilities,malware"
CVE ID substring match against title + ai_summary. Note: a proper join via cve_article_mentions is not yet populated; matches today are full-text only and may include false positives (e.g. CVE-2024-1234 matches CVE-2024-12345). The legacy cve parameter remains as a deprecated alias and triggers Deprecation / Sunset response headers.
CVE-\d{4}-\d{4,7}"CVE-2024-12345"
Which time field since/until apply to. published_at (default) is the article's original publication time. modified_at is when SOC Defenders last updated the row (use for delta polling). fetched_at is when we first crawled it. created_at is the DB insert time.
published_at, fetched_at, modified_at, created_at "modified_at"
Sort order. published:desc (default) is newest-first. engagement:desc ranks by rank_score (HN-style decay). severity:desc surfaces critical vulnerabilities first.
published:desc, published:asc, modified:desc, severity:desc, engagement:desc "severity:desc"
Response
Successful response. See Article for the complete per-row shape and headers section for pagination/clamping signals.