From adddcc047596940ea682c4dfe30953f1ee7fcd17 Mon Sep 17 00:00:00 2001
From: smaramwbc <145447586+smaramwbc@users.noreply.github.com>
Date: Mon, 31 Aug 2026 18:31:00 +0100
Subject: [PATCH] docs: document the timeline status filter

---
 api/v1-contract.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/api/v1-contract.md b/api/v1-contract.md
index 1d5fb75..b0a46dc 100644
--- a/api/v1-contract.md
+++ b/api/v1-contract.md
@@ -560,6 +560,7 @@ ascending chronological order.
 | `limit` | int | `100` | page size per collection, `1`–`200` |
 | `offset` | int | `0` | rows to skip per collection, `>= 0` — counted from the oldest end by default, or from the newest end when `newest_first=true` |
 | `newest_first` | bool | `false` | page from the most recent records instead of the oldest ones (see below) |
+| `status` | string | `all` | memory rows to include: `all` (superseded and expired rows returned, previous behaviour) or `active` (only currently authoritative rows: status `active` and not past `valid_to`). Episodes are never filtered. Added in v1.5.0 |
 
 Both collections are paged independently with the same `limit`/`offset`.
 
@@ -579,6 +580,10 @@ Under `newest_first=true`, `offset` counts back from the newest row: `offset=lim
 is the next-older page, and `episodes_has_more` / `memories_has_more` report
 whether older rows remain beyond it.
 
+With `status=active`, pagination and `memories_has_more` count only the
+included rows — a subject whose history has collapsed to one surviving fact
+returns it on the first page regardless of how many superseded rows exist.
+
 Ordering is a total order in both directions (timestamps, then row id), so
 paging never skips or repeats rows that share a timestamp.