History & Point-in-Time
Read a record's audit history, and reconstruct what it looked like at an instant in the past.
Overview
Two read-only endpoints expose the audit trail (action_logs) as a first-class part of a record's API surface:
| Endpoint | Answers |
|---|---|
GET /api/v1/{resource}/{id}/history |
What has happened to this record, and who did it? |
GET /api/v1/{resource}/{id}/as_at?at=… |
What did this record look like at a given instant? |
Both are available for four resources: rentals, invoices, accounts, and catalogue_items.
Neither endpoint is a projection engine. as_at reconstructs state by folding audit diffs backwards over the current row — it is the supported public approximation of a full event-sourced projection, and it tells you, on every response, exactly how faithful the retained evidence was. Action Log history is retention-bounded; pruning removes older entries and cannot be undone through this API.
This is distinct from immutable event-sourced temporal history. GET /api/v1/action_logs/state replays the aggregate's immutable event stream and remains available after its Action Log projection is pruned. Use the history and as_at endpoints for the retained audit projection; use event-sourced replay when a high-confidence aggregate timeline is required.
Authorisation
Both endpoints require two grants:
- the resource's own read permission and ability (
rentals.view/rentals:read, and so on), and - the audit-trail grants
action-log.view/action-log:read.
Rental snapshots require rentals.view and action-log.view, with token abilities rentals:read and action-log:read. These checks apply to REST and the MCP get-entity-as-at tool.
A token scoped only to the resource cannot use these endpoints as a side door into the audit trail.
After an approved privacy case anonymises an account, snapshots requested for instants before anonymisation continue to show the anonymised identity. Removed audit values cannot restore identifying data.
History
GET /api/v1/rentals/42/history?page=1&per_page=20
{
"data": [
{
"id": 9001,
"action": "rental.updated",
"actor_type": "user",
"actor_id": "7",
"actor_label": "Jo Bloggs",
"user_id": 7,
"user_name": "Jo Bloggs",
"old_values": { "status": "quote_pencilled" },
"new_values": { "status": "order_active" },
"via": "web",
"created_at": "2026-01-15T14:30:00+00:00"
}
],
"meta": {
"total": 12,
"per_page": 20,
"page": 1,
"last_page": 1,
"retention": {
"bounded": true,
"retention_months": 12,
"cutoff_at": "2025-01-15T14:30:00+00:00",
"oldest_available_at": "2025-01-15T14:30:00+00:00",
"limited": false,
"older_entries_unavailable": false
}
}
}
- Entries are newest first, offset-paginated with
pageandper_page. These history endpoints use their own paginator and do not currently support cursor paging; other collection endpoints publish their supported modes in pagination conventions. viais the surface the change came through (web,api,mcp,cli), lifted from the entry's metadata.- Action Log history is retention-bounded.
meta.retention.older_entries_unavailableistruewhen the entity predates the configured retention window and older evidence is unavailable; for relational rows withoutcreated_at, the same flag means retained evidence begins at or after the boundary. In either case, it is an evidence limitation, not proof that a specific deleted entry existed, and the returned page is not an assertion that the timeline is complete. - Soft-deleted records still answer. History outlives the record it describes. A
404means the id never existed, not that the record was deleted.
Point-in-time (as_at)
GET /api/v1/rentals/42/as_at?at=2026-01-01T00:00:00Z
at is required, must be a valid ISO 8601 timestamp, and must not be in the future (422 otherwise). If the record did not yet exist at that instant, the response is a 404 naming the earliest instant it can be evidenced at.
The not-created response uses the standard API error envelope:
HTTP/1.1 404 Not Found
{
"message": "No rental state exists for identifier 42 at 2026-01-01T00:00:00Z; it was first recorded at 2026-02-01T00:00:00Z.",
"code": "aggregate_not_created"
}
The response is the resource in its normal shape — the same DTO GET /api/v1/rentals/42 returns — plus a meta.reconstruction block:
{
"data": { "id": 42, "status": "quote_pencilled", "…": "…" },
"meta": {
"reconstruction": {
"as_at": "2026-01-01T00:00:00+00:00",
"complete": true,
"uncovered_fields": [],
"unaudited_fields": ["internal_notes"],
"events_folded": 6,
"relations": "Only the record's own columns are reconstructed. …",
"confidence": "medium",
"retention": {
"bounded": true,
"limited": false,
"older_entries_unavailable": false
}
}
}
}
How the fold works
Starting from the record as it stands today, every audit entry newer than at is undone, newest first. For each key in an entry's new_values that also appears in its old_values, the attribute is reset to the original value. Order matters: walking newest→oldest is what stops an intermediate value from surviving when the same field moved twice.
Read meta.reconstruction before trusting the answer
| Field | Meaning |
|---|---|
complete |
true only when every retained and folded diff was fully reversible. It does not mean Action Log entries were never pruned. |
uncovered_fields |
Attributes a folded diff changed but could not reverse — the audit entry recorded a new value with no matching original value. These fields still hold their current value. |
unaudited_fields |
Fillable attributes that appear in no audit diff for this record at all. Presented as-is; the audit trail cannot prove they never moved. |
events_folded |
How many audit entries were applied in reverse. |
relations |
A fixed caveat, repeated on every response: only the record's own columns are reconstructed. |
confidence |
medium for a reversible retained diff-walk, low when a diff is irreversible or the retention boundary leaves older evidence unavailable. |
retention |
The configured Action Log window and evidence boundary. older_entries_unavailable is the entity-level boundary; limited is true only when this requested as_at instant falls before that boundary. |
Known limits
- Account privacy processing remains effective.
GET /api/v1/accounts/{account}/as_atskips personal data anonymised by an approved privacy case. Requesting an instant before the case does not restore that data. Retained redacted values remain unavailable and are reported among uncovered fields when their diffs are folded. - Relationships are current, not historical. Included or lazily loaded relations reflect today's state. Only columns move.
- Type fidelity is the audit trail's fidelity. Values come back as the writer serialised them into JSONB — money stays an integer in minor units, datetimes come back as stored strings, JSON columns as decoded structures. They are re-hydrated through the model's casts, so scalar and JSON columns round-trip faithfully; anything the writer serialised lossily stays lossy.
- Nothing is persisted. The reconstructed record is built in memory and never saved.
Action Log versus immutable event history
Action Log rows are an audit projection with configurable retention. They are
useful for explaining recent changes, but pruning means an older history page
can be a partial timeline and a relational as_at result can have reduced
confidence. The complete flag remains about reversibility of the retained
diffs; retention limitations are reported separately in retention.
Event-sourced temporal replay is a separate read path. For supported
event-sourced aggregates, GET /api/v1/action_logs/state replays immutable Verbs
events and reports meta.method: replay with high confidence when replay
integrity checks pass. Action Log pruning does not remove those event records.
Evidence facts
The evidence ledger is a separate read-only provenance surface from Action Log history. Facts are proposed, scored, and decided by the surface that observed them — there is no write API for inventing a fact without an observation.
| Endpoint | Route | Answers |
|---|---|---|
GET /api/v1/evidence_facts |
api.v1.evidence_facts.index |
Which facts were proposed, for which subject/field, and how strong is the corroboration? |
GET /api/v1/evidence_facts/{evidence_fact} |
api.v1.evidence_facts.show |
Why does this fact exist — the full observation trail behind its score? |
Both require evidence.view and the evidence:read token ability. Index pages with filter[field][operator] filters (subject_type, subject_id, field, state, score, has_primary, …) and omits observations unless ?include=observations. Show always includes observations: each reports kind, weight_at_capture, whether it was a primary source, and source_reference.
score and has_primary stay separate — the first counts distinct corroboration, the second records whether any one observation was strong enough to carry the value alone. subject_id is always a string because subjects may use integer or UUID keys.
MCP
The same two surfaces are exposed as first-class MCP tools, both read-only:
| Tool | Arguments |
|---|---|
get-entity-history |
resource, id, page, per_page |
get-entity-as-at |
resource, id, at |
resource is one of rentals, invoices, accounts, catalogue_items.