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