Regulatory Snapshot API

The Regulatory Snapshot API gives you programmatic access to the same regulatory horizon-scanning engine that powers the regsn.app dashboard. Configure a set of jurisdictions and topics, fire a scan, and get back a structured snapshot — items, trends, an executive narrative, and an optional drift overlay against prior scans (the product UI surfaces this as Changes) — plus the ability to generate exportable artifacts (PDFs, slide decks, audio briefings, infographics).

The API is a small, stable JSON-over-HTTPS surface at https://api.regsn.app/v1. Everything is documented from a single OpenAPI 3.1 spec; bearer key authentication, idempotency, rate limits, RFC 9457 errors, and Server-Sent Events for long-running scans are all first-class.

If you’ve used Stripe or Plaid, the shape will feel familiar. The rest of these docs go endpoint by endpoint, with copy-pastable curl, Python, and JavaScript examples on every page.

What you can build

Compliance dashboards — pull snapshots into your own UI, slice by jurisdiction or topic, surface only the items that matter to your team.
Briefing pipelines — schedule scans nightly, stream them to an LLM for a tailored summary, or fan them out to an audio briefing for the C-suite.
Change detection — diff snapshots over time. The drift overlay tells you what shifted between two scans, not just what each scan said.
Workflow integrations — fire a scan from your ticketing system, attach the resulting PDF tearsheet to a Jira issue, post the narrative into Slack.

Where to start

Page	When to read
Quickstart	First request in 5 minutes. curl, Python, JS — pick one.
Authentication	How bearer keys work, how to create them, how to rotate.
Scans	The core endpoint. Sync vs async, SSE streaming, idempotency.
Snapshots	The data model. What’s in the envelope.
Exports	Generate PDFs, decks, audio briefings, infographics.
Usage	Monitor your spend.

Conventions

Base URL: https://api.regsn.app
All paths: prefixed with /v1 — e.g. /v1/scans, /v1/snapshots/{id}.
Content type: application/json on every request and response (errors use application/problem+json).
Authentication: Authorization: Bearer regsn_live_<32 chars> on every /v1/* call except the dashboard-only /v1/keys/* endpoints.
Request IDs: every response carries X-Request-Id — include it when you file a bug.
Idempotency: POST /v1/scans and POST /v1/exports accept an Idempotency-Key header. Same key + same body = same response for 24 hours. See Idempotency.
Budget: all scan and export work depletes the same budget pool consumed by the regsn.app UI. There is no separate API meter.

Mental model

Two writes (POST /v1/scans and POST /v1/exports); everything else is a read. The lifecycle of a scan and the lifecycle of an export are independent — one snapshot can spawn many exports.

SDKs

Language	Package	Notes
Python	`regsn` (≥3.8, stdlib only)	Python SDK guide
JavaScript / TypeScript	`@regsn/api` (Node 18+, ESM)	JavaScript SDK guide

Both SDKs wrap the full HTTP surface, handle retries on 5xx and 429, auto-generate idempotency keys, and expose a client.scans.create(...) shortcut that polls until the snapshot is ready.

For other languages, the API is plain JSON over HTTPS — anything that can make an HTTP request can use it. See the Quickstart for a raw curl example.

[!TIP] Don’t put your key in a URL. Always use the Authorization header. Keys in URLs end up in browser history, server access logs, and HTTP referrers.