Python SDK

regsn is a single-file, standard-library-only Python client for the API — no dependencies to vet.

Property	Value
Package	`regsn`, version 0.2.0
Python	≥ 3.8
Dependencies	None (stdlib `urllib`)

Availability. The regsn package is source-available; publication to the public PyPI index is pending, so pip install regsn does not work yet. Until it lands, call the HTTP API directly — every page in this reference carries copy-pasteable curl. This page documents the SDK for teams who already have the source.

Setup


from regsn import RegSn
 
client = RegSn(api_key="regsn_live_…")

Constructor argument	Default	Notes
`api_key`	env `REGSN_API_KEY`	Required, one way or the other.
`base_url`	`https://api.regsn.app`	Override for testing.
`timeout_s`	`180`	Per-request timeout in seconds.

Methods

Method	Calls	Notes
`client.scans.create(**config, mode="sync", idempotency_key=None, poll_until_done=True)`	`POST /v1/scans`	Scan config fields are keyword arguments. If the API returns `202`, polls until terminal.
`client.scans.create_async(**config, idempotency_key=None)`	`POST /v1/scans?mode=async`	Returns the `202` body immediately.
`client.scans.get(scan_id)`	`GET /v1/scans/{id}`
`client.scans.wait(scan_id, poll_s=5, timeout_s=720)`	polls `GET /v1/scans/{id}`	Returns `{"scan_id", "status", "snapshot_id", "snapshot"}` — `"snapshot"` is the full `GET /v1/snapshots/{id}` body. Raises on failure or timeout.
`client.snapshots.list(**filters)`	`GET /v1/snapshots`	`from`/`to` (pass as `**{"from": …}`), `jurisdiction`, `area`, `limit`, `offset`.
`client.snapshots.get(snapshot_id)`	`GET /v1/snapshots/{id}`
`client.snapshots.get_items(id)` / `get_trends(id)` / `get_executive_summary(id)`	sub-resources
`client.snapshots.get_executive_narrative(id, language="en")`	`GET …/executive-narrative`
`client.snapshots.get_drift(id)`	`GET …/drift`
`client.exports.create(snapshot_id=…, artifact_type=…, provider=…, options=None, idempotency_key=None)`	`POST /v1/exports`
`client.exports.get(export_id)`	`GET /v1/exports/{id}`
`client.usage.get(**filters)`	`GET /v1/usage`	`group_by`, `from`, `to`.

0.2.0 also wraps scans.estimate, scans.cancel, export list/download/delete, usage.budget, and the five /v1/meta/* reads. Still not wrapped: the SSE stream — use any SSE client. Key management is excluded by design: keys are minted and revoked only in a signed-in dashboard session at api.regsn.app, never with an API key, so there is nothing for an SDK to wrap.

End to end

scan_and_read.py


from regsn import RegSn
 
client = RegSn()  # reads REGSN_API_KEY
 
result = client.scans.create(
    jurisdictions=["UK", "EU"],
    areas=["AML / KYC"],
    horizon=12,
)
 
# Deterministic envelope shape regardless of sync/async path:
snap = client.snapshots.get(result["snapshot_id"])
print(snap["data"]["executive_narrative"])
 
job = client.exports.create(
    snapshot_id=result["snapshot_id"],
    provider="internal-pdf",
    artifact_type="pdf",
)
print(job["status_url"])

Envelope shapes. A fast sync scan returns the envelope flat under "snapshot"; when create had to poll, "snapshot" is the full GET /v1/snapshots/{id} body (envelope nested under "data"). Re-fetching by snapshot_id, as above, always gives the nested shape.

Retries, idempotency, timeouts

Every POST gets an auto-generated UUID Idempotency-Key unless you pass idempotency_key — the SDK’s own retries can never duplicate a scan or export.
Up to 3 retries on network errors, 5xx, and 429. Retry-After is honoured, capped at 60 seconds per wait, with exponential backoff and jitter otherwise.
Requests time out after timeout_s (default 180 s).

Errors

Failures raise RegSnError:


from regsn import RegSn, RegSnError
 
client = RegSn()
try:
    client.scans.create(jurisdictions=["UK"], areas=["Payments"], horizon=6)
except RegSnError as err:
    print(err.status)      # e.g. 402
    print(err.code)        # e.g. 'budget_exhausted'
    print(err.request_id)  # 'req_…' — quote this in support requests
    print(err.body)        # full problem-details document

SDK-generated codes (no HTTP status): network_error, retry_exceeded, scan_failed (from wait when a scan ends failed), wait_timeout. Everything else is the API’s own code.