Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.socdefenders.ai/llms.txt

Use this file to discover all available pages before exploring further.

The articles endpoint aggregates cybersecurity news from 30+ sources — including CISA alerts, vendor advisories, and independent threat research — into a single paginated feed. You can filter by category, severity, threat actor, or MITRE technique, run full-text searches, and poll incrementally using the since parameter to retrieve only new content since your last request.

​
Endpoint

Method: GET https://socdefenders.ai/api/v1/articles Authentication: Required — pass your API key in the Authorization header as a Bearer token. Tier: Free. Bulk export in NDJSON or CSV format requires a Pro subscription.

​
Query parameters

​
q
string
Full-text search query. Matches against article titles, summaries, and extracted tags.
​
category
string
Filter by article category. Common values: vulnerabilities, malware, threat-intelligence, data-breaches, ransomware.
​
severity
string
Filter by severity level. Accepted values: critical, high, medium, low.
​
since
string
ISO 8601 timestamp. Returns only articles published after this time. Use for delta polling — see the note below.
​
cursor
string
Pagination cursor returned in meta.next_cursor from a previous response. Pass this value to retrieve the next page of results.
​
limit
integer
default:"30"
Number of results per page. Maximum is 100 on the Free tier and 1,000 on Pro.
​
has_iocs
boolean
When true, returns only articles that have extracted indicators of compromise (IOCs).
​
threat_actor
string
Filter by threat actor name, for example APT28 or Lazarus Group.
​
industry
string
Filter by targeted industry sector, for example healthcare, finance, or energy.
​
mitre_technique
string
Filter by MITRE ATT&CK technique ID, for example T1566 (Phishing).
​
format
string
default:"json"
Response format. Accepted values: json (default), ndjson, csv. NDJSON and CSV bulk export require a Pro subscription.

​
Example request

curl -H "Authorization: Bearer sk_live_YOUR_KEY" \
  "https://socdefenders.ai/api/v1/articles?category=vulnerabilities&severity=critical&limit=30"

​
Example response

{
  "meta": {
    "total": 15926,
    "limit": 30,
    "next_cursor": "cursor_abc123"
  },
  "data": [
    {
      "id": "d0d2789a-cf57-4bfc-aaa5-cf9111a08f1c",
      "title": "Example Security Article Title",
      "url": "https://example.com/article",
      "source": "bleepingcomputer.com",
      "published_at": "2024-01-15T10:00:00Z",
      "categories": ["vulnerabilities"],
      "severity": "high",
      "tags": ["#vulnerability", "#exploit"],
      "has_iocs": true,
      "points": 3
    }
  ]
}

​
Response fields

​
meta
object
Pagination metadata for the response.
​
data
object[]
Array of article objects matching the query.

​
Delta polling

To continuously ingest new articles without re-fetching old ones, record the highest published_at value from each response and pass it as the since parameter on your next request. This returns only articles published after that timestamp, making it efficient to poll on a schedule. 
# First poll — fetch recent critical articles
curl -H "Authorization: Bearer sk_live_YOUR_KEY" \
  "https://socdefenders.ai/api/v1/articles?severity=critical&limit=100"

# Subsequent poll — only articles newer than your last result
curl -H "Authorization: Bearer sk_live_YOUR_KEY" \
  "https://socdefenders.ai/api/v1/articles?severity=critical&limit=100&since=2024-01-15T10:00:00Z"