Regulatory Snapshot API

The Regulatory Snapshot API gives you programmatic access to the same horizon-scanning engine that powers the regsn.app dashboard. Configure a set of jurisdictions and regulatory areas, run a scan, and get back a structured snapshot — items, trends, an executive summary and narrative, and (when a prior comparable snapshot exists) an overlay of changes between snapshots. From any snapshot you can then generate exportable artefacts: PDFs, slide decks, infographics, audio briefings, and more.

The API is a small JSON-over-HTTPS surface at https://api.regsn.app/v1. Bearer-key authentication, idempotent retries, rate limits, RFC 9457 errors, and Server-Sent Events for long-running scans are all first-class. If you have used Stripe or Plaid, the shape will feel familiar.

The lifecycle

One scan produces one snapshot; one snapshot can feed many exports. Everything else is a read.

A sync scan (POST /v1/scans, the default mode) blocks for up to 120 seconds and returns the finished snapshot inline. Anything longer — and every export — is asynchronous: you get an id back, then poll or stream until it completes.

Endpoint map

Method & path	What it does	Reference
`POST /v1/scans`	Run a scan (sync up to 120 s, or `?mode=async`)	Scans
`POST /v1/scans/estimate`	Cost envelope for a scan config, without running it	Scans
`GET /v1/scans/{id}`	Poll scan status and progress	Scans
`GET /v1/scans/{id}/stream`	Server-Sent Events progress stream	Scans
`POST /v1/scans/{id}/cancel`	Cancel a running scan	Scans
`GET /v1/snapshots`	List snapshots with filters and paging	Snapshots
`GET /v1/snapshots/{id}`	Full snapshot envelope	Snapshots
`GET /v1/snapshots/{id}/items`	Items only	Snapshots
`GET /v1/snapshots/{id}/trends`	Trends only	Snapshots
`GET /v1/snapshots/{id}/executive-summary`	Executive summary block	Snapshots
`GET /v1/snapshots/{id}/executive-narrative`	Narrative prose, with `?language=`	Snapshots
`GET /v1/snapshots/{id}/drift`	Changes overlay against a prior snapshot	Snapshots
`POST /v1/exports`	Queue an export job against a snapshot	Exports
`GET /v1/exports`	List your export jobs	Exports
`GET /v1/exports/{id}`	Poll one export job	Exports
`GET /v1/exports/{id}/download`	Download the finished artefact	Exports
`DELETE /v1/exports/{id}`	Delete a job and its artefact bytes	Exports
`GET /v1/meta/engines`	Supported engines and horizons	Discovery
`GET /v1/meta/models`	Model catalogue per provider	Discovery
`GET /v1/meta/jurisdictions`	Jurisdiction vocabulary, with regulators	Discovery
`GET /v1/meta/areas`	Regulatory-area vocabulary	Discovery
`GET /v1/meta/export-types`	Export catalogue incl. per-type option schemas	Discovery
`GET /v1/usage`	Request, scan, export, and cost telemetry	Usage
`GET /v1/usage/budget`	Current budget, spend, and remaining	Usage
`POST /v1/keys`	Create an API key (dashboard session)	Authentication
`GET /v1/keys`	List keys, masked (dashboard session)	Authentication
`POST /v1/keys/{id}/revoke`	Revoke a key (dashboard session)	Authentication

Conventions

Base URL — https://api.regsn.app. All paths are prefixed /v1.
Authentication — Authorization: Bearer regsn_live_… on every call except the dashboard-session /v1/keys/* endpoints. See Authentication.
Content type — application/json requests and responses; errors use application/problem+json. Request bodies are capped at 2 MB.
Request IDs — every response carries an X-Request-Id header (req_…); quote it in support requests. The same value appears as request_id in error bodies.
Idempotency — POST /v1/scans and POST /v1/exports accept an Idempotency-Key header: same key + same body returns the cached response for 24 hours. See Idempotency.
Budget — all scan and export work depletes the same budget pool the regsn.app UI consumes; there is no separate API meter. Check GET /v1/usage/budget before a large run. See Usage & budget.
Amounts — every *_cents field is US cents, and may carry fractions of a cent.

What you can build

Compliance dashboards — pull snapshots into your own UI and slice by jurisdiction or area.
Briefing pipelines — run scheduled scans, then export the snapshot as a PDF, deck, or audio briefing and route it to the people who need it.
Change monitoring — compare snapshots over time; GET /v1/snapshots/{id}/drift returns what shifted between snapshots, not just what each one said.
Workflow integrations — trigger a scan from a ticketing system, attach the tearsheet to the ticket, post the narrative to chat.

SDKs

Language	Package	Requirements
JavaScript	`@regsn/api`	Node 18+, ESM
Python	`regsn`	Python ≥ 3.8, stdlib only

Both SDKs cover the core scan → snapshot → export flow, retry on 429 and 5xx, and generate idempotency keys automatically. They are thin wrappers — anything they do not cover is a plain HTTPS call away. See each SDK page for current availability.