Snapshots

A snapshot is the structured output of a scan. It is the single richest object the API returns — every other read endpoint either lists snapshots, projects one field out of a snapshot, or drives a downstream artifact off of a snapshot.

This page walks through the shape of the envelope, the seven read endpoints, and the filter parameters on the list endpoint. The complete JSON Schema lives at /openapi/regsn-v1-snapshot-schema.json and is treated as load-bearing — fields documented here are guaranteed to be stable within v1.

[!NOTE] Two envelope shapes. When you fetch a snapshot via GET /v1/snapshots/{id}, the envelope is nested under a top-level data key alongside metadata (id, title, config, cost_cents, created_at). When POST /v1/scans returns a completed snapshot inline (sync mode, ≤120 s), the same envelope sits flat under snapshot. The fields described below are identical in either location.

The envelope

Top-level keys:

Items

Each item represents one regulatory development. The required fields are jurisdiction and area; the rest can be null depending on the engine and the underlying source.

{
  "jurisdiction": "UK",
  "area": "AML",
  "title": "Fifth Anti-Money-Laundering Directive review",
  "source": "https://www.fca.org.uk/...",
  "impact": "High",
  "likelihood": "Confirmed",
  "date": "2026-09-30",
  "summary": "The FCA has announced a consultation on...",
  "_meta": { ... }
}

impact is one of High / Medium / Low / null. likelihood is one of Confirmed / Likely / Possible / null. The full schema allows additional properties — newer engine versions may add fields without breaking older clients.

Executive summary vs. narrative

These are two different things:

• executive_summary is structured — a bottom_line headline and a list of priorities you can render as bullets in your UI.
• executive_narrative is unstructured prose, written in a single paragraph for a busy reader. This is what most downstream artifacts (audio briefings, slide intros) consume.

If your integration is building a UI, use executive_summary. If your integration is feeding an LLM or generating audio, use executive_narrative.

_meta

Engine telemetry — useful for cost monitoring and for filtering snapshots that were generated by a particular engine version.

{
  "engine": "v4.5-beta",
  "model": "sonnet",
  "searches": 14,
  "estimatedCost": 0.42,
  "inputFingerprint": "9c1a4f…"
}

List: GET /v1/snapshots

Returns the snapshots owned by the calling account (most recent first). Soft-deleted snapshots are excluded.

curl "https://api.regsn.app/v1/snapshots?limit=10&starred=true" \
  -H "Authorization: Bearer $REGSN_API_KEY"

Query parameters:

Response:

{
  "data": [
    {
      "id": "a1b2…",
      "title": "UK / EU · AML · 12 months",
      "created_at": "2026-05-14T09:14:02Z",
      "starred": false,
      "item_count": 23,
      "trend_count": 4,
      "jurisdiction_count": 2,
      "cost_cents": 42,
      "actual_cost_cents": 39
    }
  ],
  "pagination": { "limit": 10, "offset": 0, "total": 187 }
}

The list endpoint does not return the full envelope — that would be expensive and most callers don’t need it. Fetch the full envelope with GET /v1/snapshots/{id} once you’ve picked the one you want.

Retrieve: GET /v1/snapshots/{id}

Returns the full snapshot.

curl https://api.regsn.app/v1/snapshots/$SNAPSHOT_ID \
  -H "Authorization: Bearer $REGSN_API_KEY"

{
  "id": "a1b2…",
  "title": "UK / EU · AML · 12 months",
  "config": { "jurisdictions": ["UK","EU"], "areas": ["AML"], "horizon": 12, "engine": "v4.5-beta", "...": "..." },
  "data": {
    "items": [...],
    "trends": [...],
    "executive_summary": {...},
    "executive_narrative": "...",
    "_meta": {...}
  },
  "cost_cents": 39,
  "created_at": "2026-05-14T09:14:02Z"
}

data is the envelope described above. config echoes back the original scan request.

actual_cost_cents takes priority over cost_cents when both exist — the API picks actual if available, falling back to estimated.

Sub-resources

If you only need one slice of the envelope, use a sub-resource. Each returns a minimal JSON object and counts against the reads rate-limit bucket the same as the full retrieve — but the payload is much smaller, which matters at scale.

GET /v1/snapshots/{id}/items

{ "data": [ { "jurisdiction": "UK", "area": "AML", ... }, ... ] }

GET /v1/snapshots/{id}/trends

{ "data": [ { ... }, ... ] }

GET /v1/snapshots/{id}/executive-summary

{ "data": { "bottom_line": "...", "priorities": [ ... ] } }

GET /v1/snapshots/{id}/executive-narrative

{ "executive_narrative": "Over the next twelve months...", "language": "en" }

Accepts ?language= (ISO 639-1, default en). For a translation that doesn’t exist on the snapshot, you get 404 translation_not_available. An empty narrative (no analyst content) also returns 404 rather than an empty string — so you can rely on the success response being non-empty.

[!TIP] Translations are generated on demand the first time a user opens a snapshot in a non-English language from the dashboard. Once cached on the snapshot, the API serves them directly. If you need a language that hasn’t been requested yet, opening the snapshot in the dashboard once will populate the translations map for subsequent API reads.

curl "https://api.regsn.app/v1/snapshots/$SNAPSHOT_ID/executive-narrative?language=fr" \
  -H "Authorization: Bearer $REGSN_API_KEY"

GET /v1/snapshots/{id}/drift

In the product UI, this concept is shown as Changes. The drift resource name is the API-layer term — same data, kept under that name for stability. If you’re cross-referencing the dashboard with your integration, that’s the mapping.

Returns the drift overlay — a structured comparison against an earlier snapshot — or { "available": false } when no drift overlay exists on this snapshot.

{ "available": false }

Drift overlays are produced only when the engine has prior snapshots in scope to compare against; new accounts won’t see them until they’ve accumulated a second scan in the same jurisdiction × topic configuration.

Translations

Some snapshots ship with executive-narrative translations alongside the English original. The translations key on the envelope is keyed by ISO 639-1 codes:

"translations": {
  "fr": { "executive_narrative": "Au cours des douze prochains mois..." },
  "de": { "executive_narrative": "In den nächsten zwölf Monaten..." }
}

The /executive-narrative?language= endpoint is the easiest way to read a translation — it picks the right one for you and 404s cleanly if it isn’t there.

Code: walk through a result

from regsn import RegSn
client = RegSn()
 
# Step 1: find the most recent snapshot.
snaps = client.snapshots.list(limit=1)
sid = snaps["data"][0]["id"]
 
# Step 2: fetch the full envelope.
full = client.snapshots.get(sid)
env = full["data"]
 
# Step 3: walk the items.
for it in env["items"]:
    print(f"[{it['impact']}] {it['jurisdiction']} · {it['area']} — {it['title']}")
 
# Step 4: print the narrative.
print(env["executive_narrative"])

See also

• Scans — the endpoint that produces snapshots.
• Exports — turn a snapshot into a PDF, deck, audio briefing, or infographic.
• What is a snapshot? — the same data model explained in product terms.
• Changes between scans — the product framing of the drift sub-resource.
• Errors — 404 not_found and 404 translation_not_available.
• Glossary — definitions for every term used here.