> ## 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.

# GET /api/v1/articles — list threat intelligence articles

> Retrieve aggregated cybersecurity articles from 30+ feeds, with filtering, full-text search, cursor pagination, and IOC/CVE expansions. Free tier.

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

<ParamField query="q" type="string">
  Full-text search query. Matches against article titles, summaries, and extracted tags.
</ParamField>

<ParamField query="category" type="string">
  Filter by article category. Common values: `vulnerabilities`, `malware`, `threat-intelligence`, `data-breaches`, `ransomware`.
</ParamField>

<ParamField query="severity" type="string">
  Filter by severity level. Accepted values: `critical`, `high`, `medium`, `low`.
</ParamField>

<ParamField query="since" type="string">
  ISO 8601 timestamp. Returns only articles published after this time. Use for delta polling — see the note below.
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor returned in `meta.next_cursor` from a previous response. Pass this value to retrieve the next page of results.
</ParamField>

<ParamField query="limit" type="integer" default="30">
  Number of results per page. Maximum is 100 on the Free tier and 1,000 on Pro.
</ParamField>

<ParamField query="has_iocs" type="boolean">
  When `true`, returns only articles that have extracted indicators of compromise (IOCs).
</ParamField>

<ParamField query="threat_actor" type="string">
  Filter by threat actor name, for example `APT28` or `Lazarus Group`.
</ParamField>

<ParamField query="industry" type="string">
  Filter by targeted industry sector, for example `healthcare`, `finance`, or `energy`.
</ParamField>

<ParamField query="mitre_technique" type="string">
  Filter by MITRE ATT\&CK technique ID, for example `T1566` (Phishing).
</ParamField>

<ParamField query="format" type="string" default="json">
  Response format. Accepted values: `json` (default), `ndjson`, `csv`. NDJSON and CSV bulk export require a Pro subscription.
</ParamField>

## Example request

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

## Example response

```json theme={null}
{
  "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

<ResponseField name="meta" type="object">
  Pagination metadata for the response.

  <Expandable title="properties">
    <ResponseField name="meta.total" type="integer">
      Total number of articles matching the query across all pages.
    </ResponseField>

    <ResponseField name="meta.limit" type="integer">
      The page size used for this response.
    </ResponseField>

    <ResponseField name="meta.next_cursor" type="string">
      Opaque cursor for the next page. Pass this as the `cursor` query parameter to retrieve the following page. Absent when there are no more results.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data" type="object[]">
  Array of article objects matching the query.

  <Expandable title="properties">
    <ResponseField name="data[].id" type="string">
      Unique article UUID. Use this to fetch the full article with expansions via `GET /api/v1/articles/{id}`.
    </ResponseField>

    <ResponseField name="data[].title" type="string">
      Article title as published by the source.
    </ResponseField>

    <ResponseField name="data[].url" type="string">
      Canonical URL of the original article.
    </ResponseField>

    <ResponseField name="data[].source" type="string">
      Domain of the publishing source, for example `bleepingcomputer.com` or `cisa.gov`.
    </ResponseField>

    <ResponseField name="data[].published_at" type="string">
      ISO 8601 timestamp of when the article was published by the source.
    </ResponseField>

    <ResponseField name="data[].categories" type="string[]">
      Array of category labels assigned to the article, for example `["vulnerabilities", "ransomware"]`.
    </ResponseField>

    <ResponseField name="data[].severity" type="string">
      Assessed severity level: `critical`, `high`, `medium`, or `low`.
    </ResponseField>

    <ResponseField name="data[].tags" type="string[]">
      Array of extracted hashtag-style tags, for example `["#vulnerability", "#exploit"]`.
    </ResponseField>

    <ResponseField name="data[].has_iocs" type="boolean">
      `true` if the article has at least one extracted indicator of compromise. Fetch the full article to retrieve the `iocs` array.
    </ResponseField>

    <ResponseField name="data[].points" type="integer">
      Relevance or engagement score assigned to the article by the platform.
    </ResponseField>
  </Expandable>
</ResponseField>

## 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.

```bash theme={null}
# 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"
```