> ## Documentation Index
> Fetch the complete documentation index at: https://docs.exorde.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Topics and watchlists

> Curated topics out of the box. Custom watchlists for anything else. Same analytics surface for both.

## Two scopes, one analytics surface

Every analytical endpoint in the Intel API runs against a **scope**. There are two kinds, and both expose the same surface — the only thing that changes is the path prefix.

| Scope | What | Maintained by | Available on |
| - | - | - | - |
| **Curated topic** | Named, stable slice (`global`, `cyber`, `finance`, `disinfo`) | Exorde | Every tier; topic scope per key |
| **Custom watchlist** | Your own keyword, phrase, entity, or domain scope | You | See and Know |

Both expose [trending](/trending), volume, volume-by-keyword, [narrative](/narrative), entities, platforms, posts, and [alerts](/alerts). Cluster analytics on watchlists require Know.

A useful mental model: a **curated topic** is a slice Exorde already runs at scale with a learned 14-day baseline; a **watchlist** is the same machinery pointed at terms you define. Same code path, same envelope shape, same ranking math.

***

## Curated topics

The four public curated topics:

| Topic | What it tracks | Typical signal |
| - | - | - |
| `global` | Top storylines across the global conversation — geopolitics, macro, mainstream news | Iran-Israel exchange, ECB rate decision, Eurovision aftermath |
| `cyber` | Cybersecurity incidents, threat actors, vulnerabilities, ransomware, breaches | "dark web" 6.67σ spike on breach disclosures |
| `finance` | Markets, central banks, crypto, earnings, macro indicators | Fed pivot rumours, Bitcoin ETF flows, earnings beats |
| `disinfo` | Coordinated narrative ops, bot activity, deepfake claims, info-warfare signals | Multi-platform synchronised posting around an election |

<Note>
  Additional curated slices (defense, energy, geopolitics, MENA, ai\_tech, named-entity slices) are available to enterprise Know customers on request — email [intel@exorde.io](mailto:intel@exorde.io) with the desired scope.
</Note>

Topic access is **scoped per key**. `GET /v1/me` returns your `topics` array. A Watch-tier trial is scoped to `global` only.

```bash theme={null}
curl https://intel-v1.exorde.io/v1/topics/cyber/trending \
  -H "X-API-Key: $EXORDE_API_KEY"
```

If you call a topic your key isn't scoped for, you get `403 topic_denied`. The error envelope tells you which topics you do have:

```json theme={null}
{
  "error": "topic_denied",
  "message": "Key not authorised for topic 'cyber'",
  "requested_topic": "cyber",
  "allowed_topics": ["global"],
  "trace_id": "8b3a47ce91d04f17"
}
```

### Listing topics

```bash theme={null}
curl https://intel-v1.exorde.io/v1/topics \
  -H "X-API-Key: $EXORDE_API_KEY"
```

```json theme={null}
{
  "topics": [
    { "topic": "global",  "is_default": true,  "description": "Global conversation" },
    { "topic": "cyber",   "is_default": false, "description": "Cybersecurity" },
    { "topic": "finance", "is_default": false, "description": "Markets & macro" },
    { "topic": "disinfo", "is_default": false, "description": "Information operations" }
  ],
  "count": 4,
  "default_topic": "global"
}
```

***

## Analytics endpoints on curated topics

The full surface, by tier. Concept pages cover the response envelopes in depth.

| Endpoint | Purpose | Watch | See | Know |
| - | - | - | - | - |
| [`/v1/topics/{t}/trending`](/trending) | Top terms by rolling z-score | ✅ | ✅ | ✅ |
| `/v1/topics/{t}/volume` | Time-series of conversation volume | ✅ | ✅ | ✅ |
| `/v1/topics/{t}/volume/keywords` | Per-keyword volume breakdown | ✅ | ✅ | ✅ |
| [`/v1/topics/{t}/narrative`](/narrative) | Editorial summary + sub-narrative weights *(alpha)* | ✅ | ✅ | ✅ |
| [`/v1/topics/{t}/alerts`](/alerts) | LLM-validated volume-spike alerts | ✅ | ✅ | ✅ |
| `/v1/topics/{t}/clusters` | Conversation clusters with titles + entities | ❌ | ✅ | ✅ |
| `/v1/topics/{t}/entities` | Named-entity leaderboard | ❌ | ✅ | ✅ |
| `/v1/topics/{t}/entities/cooccurrence` | Entity co-occurrence graph | ❌ | ✅ | ✅ |
| `/v1/topics/{t}/entities/timeline` | Entity mention time-series | ❌ | ✅ | ✅ |
| `/v1/topics/{t}/platforms` | Source-platform breakdown | ❌ | ✅ | ✅ |
| `/v1/topics/{t}/search` | Full-text search across topic | ❌ | ✅ | ✅ |
| [`/v1/topics/{t}/narratives/history`](/narrative#historical-narratives-stable-surface) | Time-series of narrative shifts | ❌ | ✅ | ✅ |
| `/v1/topics/{t}/posts` (cluster/entity/narrative evidence) | Source posts | ❌ | ✅ | ✅ |
| `/v1/topics/{t}/reports/latest` | Editorial intelligence reports | ❌ | ❌ | ✅ |
| `/v1/topics/{t}/reports/archive` | Historical reports | ❌ | ❌ | ✅ |

Hitting an endpoint above your tier returns `403 upgrade_required` with `current_tier`, `required_tier`, and `feature` in the envelope. See [Errors](/errors).

***

## Custom watchlists

Watchlists are **your private scopes**. You define the terms; the API runs the same analytics against the matching post stream.

### Term types

| Type | Matches | Example |
| - | - | - |
| `keyword` | Substring match against entity names and cluster themes | `ransomware` |
| `phrase` | Same mechanism as keyword; may contain spaces | `zero day exploit` |
| `entity` | Exact lowercase match on cluster entities | `lockbit` |
| `domain` | Exact match on cluster top domains | `bleepingcomputer.com` |

Mixed-type watchlists work and are common. A brand watchlist typically combines `keyword` (brand name + variants), `domain` (corporate sites), and `entity` (key executives). A threat-intel watchlist combines `entity` (named threat actors) and `keyword` (CVE families, malware names).

### Create a watchlist

```bash theme={null}
curl -X POST https://intel-v1.exorde.io/v1/watchlists \
  -H "X-API-Key: $EXORDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "acme-monitoring",
    "base_topic": "global",
    "terms": [
      { "type": "keyword", "value": "acme" },
      { "type": "keyword", "value": "acme corp" },
      { "type": "domain",  "value": "acme.com" },
      { "type": "entity",  "value": "jane doe" }
    ]
  }'
```

```json theme={null}
{
  "id": "wl_01HXYZ7DKMSV2X9WJEQ5RQ4N3F",
  "client_id": "see_a8c41d92",
  "name": "acme-monitoring",
  "base_topic": "global",
  "terms": [
    { "type": "keyword", "value": "acme" },
    { "type": "keyword", "value": "acme corp" },
    { "type": "domain",  "value": "acme.com" },
    { "type": "entity",  "value": "jane doe" }
  ],
  "term_count": 4,
  "created_at": "2026-05-19T13:00:00Z",
  "updated_at": "2026-05-19T13:00:00Z"
}
```

`base_topic` defines the universe the watchlist filters from. `global` matches the broadest stream; `cyber` filters to cybersecurity-tagged posts only. Most brand watchlists base on `global`; most threat-intel watchlists base on `cyber`.

### Query a watchlist

The full analytics surface mirrors topic endpoints, with `/watchlists/{id}/...` instead of `/topics/{topic}/...`. Same JSON shapes, same tier gates.

```bash theme={null}
# All See-tier:
curl https://intel-v1.exorde.io/v1/watchlists/wl_01HXYZ.../trending  -H "X-API-Key: $K"
curl https://intel-v1.exorde.io/v1/watchlists/wl_01HXYZ.../narrative -H "X-API-Key: $K"
curl https://intel-v1.exorde.io/v1/watchlists/wl_01HXYZ.../alerts    -H "X-API-Key: $K"
curl https://intel-v1.exorde.io/v1/watchlists/wl_01HXYZ.../entities  -H "X-API-Key: $K"
curl https://intel-v1.exorde.io/v1/watchlists/wl_01HXYZ.../platforms -H "X-API-Key: $K"
curl https://intel-v1.exorde.io/v1/watchlists/wl_01HXYZ.../volume    -H "X-API-Key: $K"
curl https://intel-v1.exorde.io/v1/watchlists/wl_01HXYZ.../posts     -H "X-API-Key: $K"

# Know-tier only:
curl https://intel-v1.exorde.io/v1/watchlists/wl_01HXYZ.../clusters  -H "X-API-Key: $K"
```

A trending response on a watchlist:

```json theme={null}
{
  "watchlist_id": "wl_01HXYZ7DKMSV2X9WJEQ5RQ4N3F",
  "name": "acme-monitoring",
  "snapshot_id": "2026-05-19T13:00:00Z",
  "terms": [
    { "term": "acme",     "score": 142.3, "rank": 1, "delta_24h": 0.4 },
    { "term": "ceo",      "score":  87.1, "rank": 2, "delta_24h": 1.2 },
    { "term": "earnings", "score":  61.8, "rank": 3, "delta_24h": 3.7 }
  ],
  "data_freshness": { "snapshot_age_seconds": 312, "level": "ok" }
}
```

Identical envelope to [`/topics/{t}/trending`](/trending), with `watchlist_id` + `name` swapping in for `topic`. **Code written for one works on the other.**

### Update or delete

```bash theme={null}
# Rename
curl -X PATCH https://intel-v1.exorde.io/v1/watchlists/wl_01HXYZ... \
  -H "X-API-Key: $EXORDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "acme-brand-q3"}'

# Replace terms (whole-array replacement)
curl -X PATCH https://intel-v1.exorde.io/v1/watchlists/wl_01HXYZ... \
  -H "X-API-Key: $EXORDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"terms": [{"type":"keyword","value":"acme"},{"type":"domain","value":"acme.com"}]}'

# Delete
curl -X DELETE https://intel-v1.exorde.io/v1/watchlists/wl_01HXYZ... \
  -H "X-API-Key: $EXORDE_API_KEY"
```

PATCH on `terms` is **whole-array replacement**, not a delta. Send the full intended term list; anything missing from the new array is removed.

### Limits and validation

| Quota | Watch | See | Know |
| - | - | - | - |
| Custom watchlists | — | 4 | 20 |
| Terms per watchlist | — | 10 | 50 |

Hitting a cap returns a typed envelope:

```json theme={null}
{
  "error": "watchlist_limit_reached",
  "message": "Your tier allows up to 4 watchlists",
  "current_tier": "see",
  "limit": 4,
  "current": 4,
  "trace_id": "8b3a47ce91d04f17"
}
```

Validation errors at create/patch time:

| `error` | When |
| - | - |
| `watchlist_term_limit_reached` | More than allowed terms in payload |
| `validation_error` | Empty `terms`, missing `name`, invalid `term_type` |
| `unknown_topic` | `base_topic` not in curated set |
| `duplicate_watchlist_name` | Name already used by this client |

Full list: [Errors](/errors).

***

## Webhooks (push delivery)

See and Know tiers can register webhook URLs to receive alerts and watchlist signals as they fire, instead of polling.

```bash theme={null}
curl -X POST https://intel-v1.exorde.io/v1/subscriptions \
  -H "X-API-Key: $EXORDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "alert",
    "scope": { "kind": "topic", "topic": "cyber" },
    "delivery": {
      "kind": "webhook",
      "url":  "https://your.app/exorde-webhook",
      "secret": "whsec_..."
    }
  }'
```

| Quota | Watch | See | Know |
| - | - | - | - |
| Webhook subscriptions | — | 20 | 50 |

Webhook payloads carry the same JSON shape as the corresponding poll endpoint, plus a `delivery_id` for dedup and an HMAC-SHA256 signature in the `X-Exorde-Signature` header for verification. Full setup, signature verification, and dedup pattern: [Alerts → Webhook delivery](/alerts#webhook-delivery-see-and-know).

***

## When to use which

* **Use a curated topic** when your use case aligns with one of the four public slices. Less setup, same analytics, baselines already learned over months of data.
* **Use a watchlist** for anything outside the curated slices — a specific brand, actor, campaign, domain, or niche.
* **Combine both.** A common pattern: poll [`/v1/topics/cyber/alerts`](/alerts) for industry-wide signals **and** maintain a watchlist scoped to your own brand for company-specific monitoring.
* **Know-tier customers** can request **private curated topics** — a topic that behaves like `cyber` or `finance` but is exclusive to your account, with bespoke baselines and audience-tuned [narrative](/narrative) voice. Email [intel@exorde.io](mailto:intel@exorde.io) with the desired scope.

<Note>Last reviewed: 2026-05-19. API version 1.2.8.</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.