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

# Changelog

> Release-by-release notes. What changed, what broke, what to know.

We follow semantic versioning on the API contract: **MAJOR** = breaking, **MINOR** = additive, **PATCH** = fixes & internal.

The current production version is reported by `GET /v1/version`.

***

## v1.2.8 — 2026-05-19

**Polish & defaults release. Customer-facing improvements without contract changes.**

### Changed

* **Default `hours` parameter on `/v1/topics/{t}/alerts` is now 168 (7 days).** Previously 24, which returned empty arrays on quiet days for low-volume topics like `cyber` and `disinfo`. Existing integrations passing `hours=` explicitly are unaffected.
* `/v1/keys/current` for `exd_test_*` keys now returns 200 with the synthetic test envelope instead of 503.
* `/v1/status` freshness probes refactored — typical response time dropped from 5,000 ms to under 50 ms by removing a non-leading sort-key WHERE clause that forced full part scans on `volume_signals` and `topic_narratives`.

### Fixed

* Trial mint email regex (`_EMAIL_RE`) accepts the full RFC 5322 character set including `+`, `-`, `_`, `.` in the local part. Previously rejected addresses like `qa+smoke@exorde.io`.
* Test-mode keys correctly short-circuit `get_current_client()` instead of attempting a database lookup that returned 503.

### Internal (no API impact)

* QA suite at 205 / 205 PASS.
* 30s response cache on `/v1/status` now has a useful hit rate (was bypassed by the slow probe path).

***

## v1.2.7 — 2026-05-15

**Auth middleware rewrite & error envelope unification.**

### Added

* **Typed error envelopes everywhere.** Every non-2xx response now carries `error` (stable enum), `message` (human), `trace_id` (16-hex). Match on `error` in code; show `message` to users; quote `trace_id` in support tickets.
* **`X-Exorde-Trace-Id` header** on every response, success and error.
* **Ghost-topic gate.** Topic slugs we know about but don't expose (legacy or restricted) now return `404 unknown_topic` instead of leaking through with empty payloads.
* **IOC extractor** now covers `volume_spike` alerts in addition to content alerts. Extracts URLs, IPs, domains, MD5/SHA1/SHA256 hashes, CVEs, crypto wallets, emails.
* **`GET /v1/me`** returns full tier entitlements: tier, topics, rate limit, all quotas, current usage. Build tier-aware UIs without polling billing.

### Changed

* `auth.py` rewritten end to end. Faster topic gate (\~1.5× lower p50 on auth path), `Retry-After` honored on watch-tier mint replays, expiry check now happens after tier gating so an expired See key returns `key_expired` not `upgrade_required`.

### Fixed

* Trial mint replay returns the same key with `reused: true` and `Retry-After` set, instead of issuing duplicate trials within a window.

***

## v1.2.6 — 2026-05-08

### Added

* **Watchlist analytics surface complete.** `/v1/watchlists/{id}/{trending|volume|volume/keywords|narrative|entities|platforms|posts|alerts|clusters}` all live. Same JSON shapes as the topic equivalents.
* **Webhook subscriptions** on See/Know tiers — push delivery for alerts and digests, with HMAC-SHA256 signed payloads (`X-Exorde-Signature`).
* **Subscription quota envelope** — `429 subscription_limit_reached` with current/limit fields.

### Changed

* Watchlist term limits enforced at create + patch time: `422 watchlist_term_limit_reached`.

***

## v1.2.5 — 2026-04-29

### Added

* **`GET /v1/topics/{t}/alerts`** stable. Volume-spike alerts with severity (`deviation_sigma`, `current_value`, `baseline_value`), spread (`domain_count`, `language_count`), `llm_validated` flag, `matched_cluster` link.
* **Test-mode key prefix** `exd_test_*` — synthetic `know`-tier path with deterministic fixtures for integrator plumbing tests.

### Fixed

* `/v1/topics/{t}/clusters/{id}/posts` no longer 500s when the cluster has zero evidence posts (returns `404 unknown_cluster` or empty `posts: []` depending on cause).

***

## v1.2.0 — 2026-04-15

**Major release: tiers, watchlists, and the four curated topics.**

### Added

* **Three-tier model** — Watch / See / Know. See [Tiers and quotas](/tiers).
* **Four curated topics** — `global`, `cyber`, `finance`, `disinfo`. Topic scope per key.
* **Custom watchlists** with four term types (`keyword`, `phrase`, `entity`, `domain`).
* **Editorial reports** (`/v1/topics/{t}/reports/latest`, `/archive`) — Know tier.
* **Trial mint endpoint** `POST /v1/keys/trial` with email idempotency.

### Changed

* Auth header standardised on `X-API-Key`. Legacy `Authorization: Bearer` removed.

***

## v1.1 — 2026-03-12

### Added

* Cluster analytics, entity leaderboards, full-text search.
* Snapshot model: every analytics response includes a `snapshot_id` you can pin to.

***

## v1.0 — 2026-02-01

Public launch. Trending, volume, narrative, posts. Single-tier, single-topic.

***

## Versioning policy

* **MAJOR**: contract-breaking. Field removed, type changed, error code semantics changed.
* **MINOR**: additive. New endpoints, new fields, new error codes.
* **PATCH**: fixes and internal improvements.

We never silently change a stable `error` code. If a code is renamed, the old code remains as an alias for at least one MAJOR version.

## Subscribing

* Email digest of releases — opt in via [intel@exorde.io](mailto:intel@exorde.io).
* Webhook for subscribers — Know-tier customers can add a `release_note` subscription type.

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