SIGNALS Docs
Exit Reader View
100%
Theme

Reader View

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 page and per_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.
  • via is 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_unavailable is true when the entity predates the configured retention window and older evidence is unavailable; for relational rows without created_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 404 means 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_at skips 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.