Skip to Content
API for developersQuickstart

Quickstart

In the next five minutes you will: create an API key, run your first scan, and read the executive narrative out of the resulting snapshot. The example uses UK as the jurisdiction and AML (anti-money-laundering) as the topic over a 12-month horizon — substitute your own.

Pick a language below. Every other page in these docs follows the same three-tab pattern. New to the vocabulary? The glossary has one-sentence definitions for every term.

1. Create an API key

API keys live in the developer dashboard at api.regsn.app . Sign in, click Create key, give it a name (e.g. production-backend), and copy the raw regsn_live_… string out of the modal immediately.

[!WARNING] The raw key is shown exactly once. After you close the modal you can only see the masked prefix (regsn_live_x9k…). If you lose it, revoke the key and create a new one. See Authentication for the full lifecycle.

Stash the key in an environment variable for the rest of this guide:

export REGSN_API_KEY="regsn_live_aBcD1234eFgH5678iJkL9012mNoP3456"

Both SDKs read REGSN_API_KEY automatically; the curl examples reference it via $REGSN_API_KEY.

2. Run a scan

A scan is a request for a fresh look at the regulatory landscape for a set of jurisdictions and topics. By default POST /v1/scans blocks for up to 120 seconds and returns the full snapshot inline — perfect for one-off scripts. For longer-running scans or background jobs, pass ?mode=async and poll.

curl

curl https://api.regsn.app/v1/scans \
  -H "Authorization: Bearer $REGSN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "jurisdictions": ["UK"],
    "areas": ["AML"],
    "horizon": 12
  }'

A successful sync response looks like:

{
  "scan_id": "8f3d…",
  "status": "completed",
  "snapshot_id": "a1b2…",
  "snapshot": {
    "items": [...],
    "trends": [...],
    "executive_summary": { "bottom_line": "...", "priorities": [...] },
    "executive_narrative": "Over the next twelve months...",
    "_meta": { "engine": "v2", "model": "sonnet", "...": "..." }
  }
}

If the scan exceeds the 120-second ceiling, you’ll get a 202 with status: "running" and a status_url to poll. See Scans for the full pattern.

Python

from regsn import RegSn
 
client = RegSn()  # picks up REGSN_API_KEY from env
 
result = client.scans.create(
    jurisdictions=["UK"],
    areas=["AML"],
    horizon=12,
)
# The SDK auto-polls if the scan exceeds the sync ceiling — by here, the snapshot is ready.
# Re-fetch the snapshot for a deterministic envelope shape (see note below).
snapshot = client.snapshots.get(result["snapshot_id"])
print(snapshot["data"]["executive_narrative"])

JavaScript

import { RegSn } from '@regsn/api';
 
const client = new RegSn();  // picks up REGSN_API_KEY from process.env
 
const result = await client.scans.create({
  jurisdictions: ['UK'],
  areas: ['AML'],
  horizon: 12,
});
// Re-fetch the snapshot for a deterministic envelope shape (see note below).
const snapshot = await client.snapshots.get(result.snapshot_id);
console.log(snapshot.data.executive_narrative);

[!NOTE] Two envelope shapes, one fix. A fast sync scan returns the envelope flat under snapshot (result.snapshot.items); a scan that exceeds the 120 s sync ceiling returns it nested under snapshot.data after the SDK polls. Fetching the snapshot explicitly with client.snapshots.get(snapshot_id) always returns the nested { data: { ... } } shape — that’s what the rest of these docs use.

3. Inspect the snapshot

The snapshot envelope is the central data model. Its top-level shape:

items[]              regulatory items returned by the analyst
trends[]             cross-item trends
executive_summary    { bottom_line, priorities[] }
executive_narrative  prose paragraph for an executive audience
driftOverlay         optional comparison against a prior scan (the product UI shows this as "Changes")
_meta                { engine, model, searches, estimatedCost, ... }

The driftOverlay is the API-layer name for what the product UI shows as Changes — same data, kept under that name for stability.

You can fetch the whole envelope back any time with GET /v1/snapshots/{id}, or hit one of the lightweight sub-resources:

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

See Snapshots for every sub-resource (/items, /trends, /executive-summary, /executive-narrative, /drift).

4. Generate an export

Want a PDF tearsheet, a slide deck, or an audio briefing built from your snapshot? Kick off an export job:

curl https://api.regsn.app/v1/exports \
  -H "Authorization: Bearer $REGSN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "{
    \"snapshot_id\": \"$SNAPSHOT_ID\",
    \"artifact_type\": \"pdf\",
    \"provider\": \"internal-pdf\"
  }"

Exports are always async — you get a 202 with an export_job_id. Poll GET /v1/exports/{id} until status: "completed", then download from the returned download_url. See Exports.

Where next

  • Authentication — bearer key lifecycle, rotation, the dashboard.
  • Scans — sync vs async, SSE streaming, fingerprint determinism.
  • Snapshots — full data model and every sub-resource.
  • Errors — what to do when something goes wrong.

[!TIP] Idempotency keys make retries safe. Always send Idempotency-Key: <a fresh uuid> on POST /v1/scans and POST /v1/exports. If the request times out at your end, retrying with the same key returns the cached response instead of running a duplicate scan. Both SDKs do this automatically. See Idempotency.

[!TIP] Quote the request ID in any support email. Every API response carries an X-Request-Id header (and the same value lives on error responses as request_id). Including it in a bug report lets us pull the full trace end-to-end. See Errors.

OverviewAuthentication