Quickstart

In the next few minutes you will create an API key, run your first scan, read the resulting snapshot, and download a PDF built from it. Everything here is plain curl; the SDKs wrap the same calls.

The example scans UK and EU for AML / KYC over a 12-month horizon — substitute your own. GET /v1/meta/jurisdictions and GET /v1/meta/areas list the vocabulary the product uses.

Create an API key

Keys live in the developer dashboard at api.regsn.app . Sign in, create a key, give it a name (for example production-backend), and copy the raw regsn_live_… string immediately.

The raw key is shown exactly once. Afterwards only the masked prefix (regsn_live_aBcD…) is visible. If you lose it, revoke the key and create a new one — see Authentication.

Put it in an environment variable for the rest of this guide:


export REGSN_API_KEY="regsn_live_aBcD1234eFgH5678iJkL9012mNoP3456"

Run a scan

By default POST /v1/scans runs synchronously: it blocks for up to 120 seconds and, if the scan finishes inside that window, returns the full snapshot inline.


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", "EU"],
    "areas": ["AML / KYC"],
    "horizon": 12
  }'

A completed sync response:


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

If the scan exceeds the 120-second ceiling you get 202 instead, with status: "running", a status_url, and a stream_url. That is not an error — the scan carries on in the background.

Either way, capture the scan id for the next step:


export SCAN_ID="…"   # scan_id from the response

Poll until complete

For a 202, poll the scan until it reaches a terminal status (or subscribe to the SSE stream):


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


{
  "id": "8f3d…",
  "status": "running",
  "progress": { "phase": "research", "percent": 62, "message": "…" },
  "snapshot_id": null,
  "created_at": "2026-07-20T09:12:03.000Z",
  "completed_at": null,
  "error": null,
  "cost_cents": null
}

When status is completed, snapshot_id is set — it also appears directly in a completed sync response, so if you skipped polling take it from there. Fetch the envelope:


export SNAPSHOT_ID="…"   # snapshot_id from the scan response or the poll


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

The envelope lives under data — data.items, data.trends, data.executive_summary, data.executive_narrative. Snapshots documents the full shape and the lightweight sub-resources (/items, /trends, /executive-summary, /executive-narrative, /drift).

Two envelope shapes. A fast sync scan returns the envelope flat under snapshot; GET /v1/snapshots/{id} nests it under data. Re-fetching the snapshot by id always gives you the nested shape — that is what the rest of these docs use.

Export and download a PDF

Queue an export against the snapshot. Exports are always asynchronous:


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\",
    \"provider\": \"internal-pdf\",
    \"artifact_type\": \"pdf\"
  }"


{
  "export_job_id": "c3d4…",
  "status": "queued",
  "status_url": "/v1/exports/c3d4…",
  "download_url": null
}

Capture the job id, then poll GET /v1/exports/{id} until status is completed:


export EXPORT_ID="…"   # export_job_id from the response


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

Once it is, download — -OJ saves the file under its server-supplied name:


curl -OJ https://api.regsn.app/v1/exports/$EXPORT_ID/download \
  -H "Authorization: Bearer $REGSN_API_KEY"

The full export catalogue — decks, infographics, audio briefings, and their per-type options — is at GET /v1/meta/export-types and documented in Exports.

Where next

Scans — sync vs async, cost estimates, streaming, cancellation.
Snapshots — the data model and every sub-resource.
Exports — all 16 export types and their options.
Errors — what to do when something goes wrong.

Make retries safe. Send Idempotency-Key: <fresh-uuid> on every POST /v1/scans and POST /v1/exports. If your request times out client-side, retrying with the same key returns the original response instead of running a duplicate scan. See Idempotency.