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.
Narrative is in alpha. The endpoint is live and stable enough to ship behind, but the output format, summarisation depth, and per-customer tailoring are actively evolving. We are deliberately keeping this surface flexible while we co-design it with the first wave of customers.If you have an opinion on how a narrative summary should read for your use case — newsroom desk-ready prose, SOC-grade incident framing, brand-risk tone, regulator-facing neutrality — email [email protected] and we will route your input directly into the roadmap. The customers who reach out now are the ones whose voice shapes the v1 contract. narrative endpoint returns an editorial summary of the dominant storyline on a topic or watchlist over the last rolling window, plus a structured breakdown of sub-narratives and their relative weights. Where trending gives you words and alerts gives you events, narrative gives you the story — written in English by the editorial summarisation pipeline, ready to drop into a tile, a digest, or a brief.
| Surface | Question | Shape |
|---|
| Trending | ”Which words are spiking?” | Ranked list with z-scores |
| Narrative | ”What is the story?” | Editorial summary + sub-narrative weights |
| Alerts | ”What just happened?” | Discrete events with severity |
What “alpha” means here
Concretely, today:
- The endpoint shape is stable.
summary, sub_narratives[], data_freshness, snapshot_id are the contract — these fields will not be removed without a major version bump. Build against them now.
- The summary length, voice, and sectioning are evolving. Today summaries are 1–3 sentences in a neutral editorial register. We are actively prototyping longer-form briefs, audience-tuned voices (newsroom / SOC / brand / regulator), and structured “what / who / where / why” breakdowns.
- Per-customer tailoring is on the immediate roadmap. Know-tier customers will be able to specify register, length, audience, and inclusion/exclusion preferences for the narrative on their own watchlists and private topics. The shape of that configuration is being decided now, with input from design-partner customers.
- Historical narratives (
/narratives/history) are stable and unaffected by this alpha — that surface is See/Know-tier production.
If your team needs a specific output shape (a daily desk-ready brief, a SOC ticket-ready paragraph, a regulator-facing neutral synopsis), tell us and we will build for it. The design partner program is open and unpaid — you get early access to the tailored output, we get the requirements signal.
The endpoints
| Endpoint | Tier | Returns | Status |
|---|
GET /v1/topics/{topic}/narrative | Watch+ | Latest narrative on a curated topic | alpha |
GET /v1/watchlists/{id}/narrative | See+ | Latest narrative on your watchlist | alpha |
GET /v1/topics/{topic}/narratives/history | See+ | Time-series of narrative shifts | stable |
GET /v1/topics/{topic}/narratives/posts | See+ | Source posts behind a narrative | stable |
The response envelope
{
"topic": "global",
"snapshot_id": "2026-05-19T13:00:00Z",
"summary": "Regional escalation between Iran and Israel dominates global conversation, with overlapping ECB rate signal and Eurovision aftermath as secondary threads. Coverage spans Western news, regional Persian and Hebrew sources, and platform-native commentary.",
"sub_narratives": [
{
"title": "Iran-Israel exchange",
"weight": 0.61,
"lead_terms": ["iran", "israel", "tehran", "idf"],
"domain_count": 142,
"language_count": 11
},
{
"title": "ECB June pivot rumours",
"weight": 0.22,
"lead_terms": ["ecb", "lagarde", "rate cut"],
"domain_count": 67,
"language_count": 8
},
{
"title": "Eurovision aftermath",
"weight": 0.17,
"lead_terms": ["eurovision", "winner", "voting"],
"domain_count": 54,
"language_count": 14
}
],
"source_diversity": { "domain_count": 263, "language_count": 21 },
"data_freshness": { "snapshot_age_seconds": 312, "level": "ok" },
"query_window": { "hours": 24, "effective_hours": 24 }
}
Field guide
| Field | Stability | Meaning |
|---|
topic / watchlist_id | stable | Scope identifier |
snapshot_id | stable | Pipeline run for reproducibility |
summary | alpha — wording evolving | Editorial-grade English, currently 1–3 sentences |
sub_narratives[] | stable shape, alpha titling | Threads composing the dominant story |
sub_narratives[].title | alpha — wording evolving | Short label suitable for a list item |
sub_narratives[].weight | stable | Fraction of the narrative volume (0.0–1.0, sums ≈ 1.0) |
sub_narratives[].lead_terms | stable | Top terms anchoring this sub-narrative |
sub_narratives[].domain_count | stable | Distinct source domains |
sub_narratives[].language_count | stable | Distinct languages |
source_diversity | stable | Aggregate breadth across all sub-narratives |
data_freshness | stable | Snapshot age + traffic-light level |
weight, lead_terms, domain_count, language_count, source_diversity) are the safe ones to build automation against today. The prose fields (summary, sub_narratives[].title) are where we expect the most evolution as we tailor for customers.
Calling it
curl https://intel-v1.exorde.io/v1/topics/global/narrative \
-H "X-API-Key: $EXORDE_API_KEY"
Reading the response
summary
Plain English, neutral register, drop straight into a Slack tile or email digest. Today’s summaries are 1–3 sentences. They are designed to be readable by a non-technical reader (an exec, a comms lead, a duty editor) without context.
Do not parse the summary in code. Treat it as an opaque string. If your application needs structured fields (entities mentioned, sentiment, geography), use the sub_narratives[] breakdown or pivot into entities and clusters.
sub_narratives[]
The dominant story is rarely monolithic — it’s usually composed of 2–5 threads with different emphases. sub_narratives[] exposes those threads with weights summing to roughly 1.0. Use them to:
- power a “what’s in the mix” expandable on a dashboard,
- detect a pivot (a thread’s weight jumping snapshot-over-snapshot),
- route to the right team (an Iran-Israel sub-narrative on
global goes to the foreign desk; an ECB sub-narrative goes to the markets desk).
source_diversity
The breadth of the conversation. A narrative with 263 domains and 21 languages is a genuinely global story; one with 12 domains and 2 languages is regional or niche. Useful as a filter for “is this worth surfacing to leadership.”
Cadence
Narrative regenerates on the same snapshot cadence as trending — every few minutes. The summarisation step is more expensive than ranking, so individual narrative responses may lag a snapshot or two behind trending under heavy load. data_freshness.snapshot_age_seconds always reflects the actual age of the data backing this narrative.
| Use case | Tier | Cadence |
|---|
| Dashboard tile | Watch | every 5 min |
| Hourly exec digest | See | every 60 min |
| Daily desk brief | See / Know | every 24h |
| Real-time wallboard | Know | every 5 min (snapshot cadence) |
Narrative on a watchlist
Same shape, scoped to your watchlist’s terms. Particularly useful for brand and risk monitoring — the narrative around your scope often diverges from the topic baseline.
curl https://intel-v1.exorde.io/v1/watchlists/wl_01HXYZ.../narrative \
-H "X-API-Key: $EXORDE_API_KEY"
acme-monitoring watchlist might surface a sub-narrative around an executive announcement that is invisible at the global level — exactly the kind of “what is my story” view that benefits most from per-customer voice tailoring.
Historical narratives (stable surface)
/v1/topics/{topic}/narratives/history returns the time-series of narrative shifts — when sub-narratives entered, peaked, and faded. Same envelope shape as the latest endpoint, plus a narratives[] array indexed by snapshot. Available See+ and not in alpha — the contract is stable. See Topics and watchlists.
Roadmap and how to influence it
The shortlist of items actively under design, in priority order:
- Audience-tuned voice. Per-key configuration of register:
editorial, analyst, executive, regulator. Same data, different tone.
- Per-customer brief format. Optional structured sections (
what, who, where, why_it_matters) for customers building automated briefs.
- Length controls.
concise (1 sentence), default (1–3), brief (paragraph), report (multi-paragraph with sub-headers).
- Inclusion/exclusion lexicons. Customer-specific stopwords and “always mention if present” terms baked into summarisation.
- Narrative deltas. A
vs_previous_snapshot field describing what changed — “ECB pivot rumours overtook Eurovision as the second-largest thread.”
- Multi-language summaries. French, German, Spanish, Arabic native summaries — not translations.
This list is not fixed. It will move based on what design-partner customers ask for. If your priority isn’t here, tell us — we are explicitly looking for the use cases we haven’t seen yet.
How to engage
- Email [email protected] with one paragraph: who you are, what scope you’d use narrative on, what shape of output would make it indispensable for your workflow.
- Or book a 30-minute design call via the same address — we run these weekly with prospective design partners.
- Or just send the JSON shape you wish you got back and we’ll tell you whether and when we can ship it.
The earliest customers shape the contract. Once we lock v1, the surface stabilises and tailoring moves behind a “preference profile” rather than a co-design conversation.
Operational guidance
- Don’t parse
summary. It’s prose, not structured data. Use sub_narratives[].title and lead_terms for structured logic.
- Watch
weight shifts snapshot-over-snapshot to detect narrative pivots — often the most valuable signal narrative gives you.
- Pair with trending for full state coverage: trending shows the spike, narrative shows the story it composes.
- Pair with alerts for full event coverage: an alert is the moment a sub-narrative is born; narrative is what it grew into 30 minutes later.
- Cite
snapshot_id in any downstream artefact (brief, ticket, dashboard) so the analysis is reproducible if the narrative shifts.
- Build against structural fields first — given the alpha status of the prose, automation that depends on
weight, lead_terms, domain_count is more durable today than automation that depends on summary wording.
Errors specific to narrative
| Status | error | When |
|---|
| 404 | narrative_unavailable | The pipeline hasn’t yet produced a narrative for this scope (very low-volume watchlists or freshly-created scopes) |
| 410 | snapshot_expired | Pinned snapshot_id is past retention — refetch latest |
| 503 | service_unavailable | Summarisation pipeline degraded — retry with backoff |
What’s not narrative
| You want | Use this |
|---|
| ”What words are spiking” | Trending |
| ”Posts behind this narrative” | /v1/topics/{t}/narratives/posts (See+) |
| “How the narrative shifted over time” | /v1/topics/{t}/narratives/history (See+) |
| “Editorial weekly intelligence brief” | /v1/topics/{t}/reports/latest (Know) |
| “Push me when something just broke” | Alerts |
Last reviewed: 2026-05-19. API version 1.2.8. summary and sub_narratives[].title wording in alpha — actively shaped by design-partner feedback.
