Skip to main content

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.

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 [email protected].
  • 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.
  • 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 [email protected].
  • Webhook for subscribers — Know-tier customers can add a release_note subscription type.
Last reviewed: 2026-05-19.