SWATGenX Model Creation API — generate SWAT+ models for 25,000+ USGS stations, WBD outlet HUC12 catalog watersheds, or any HUC8, based on High Resolution National Hydrographical database (NHDPlus HR).

Public Jupyter notebook + small Python helpers for the SWATGenX API at https://www.swatgenx.com.

Fastest path: open notebooks/01_simple_station_model.ipynb in JupyterLab — set your API key and USGS station ID (site_no), run all cells, wait until the task shows SUCCESS, then use the email download link or the web dashboard to fetch files. (The API does not stream the ZIP back in one synchronous call; see the notebook intro.)

For outlet HUC12 catalog watersheds, run python examples/create_model_by_outlet_huc12.py (set SWATGENX_EXAMPLE_OUTLET_HUC12 to a 12-digit outlet from Watershed Explorer). For HUC8 whole-basin or other requests flows, see examples/ and docs/.

Repository: github.com/SWATGenX/SWATGenX_API

Access model — free for research use

API keys are tied to your user account, and the same access rules apply as in the web app:

• A free account covers SWAT+ builds for USGS stations and outlet-HUC12 watersheds (up to 15 contributing HUC12 subbasins per model) under fair-use allocations.
• Extended access — HUC8 whole-basin builds, calibration/validation, higher throughput — is granted on request, free of charge (short justification; request in-app or via info@swatgenx.com). No capability on the platform is sold.
• Cloud calibration runs on dedicated AWS compute: you pay only the actual AWS cost (pass-through, shown as an estimate before you launch — no platform fee).

The API returns explicit 403 codes when a request exceeds your current allocation; the codes and how to raise your allocation are documented in docs/subscription_tiers.md.

What SWATGenX exposes

SWATGenX offers authenticated HTTP APIs to queue SWAT+ model builds from national datasets:

Entry	HTTP	Notes
USGS streamgage / station	POST /api/model-settings	JSON body includes site_no (and optional resolutions). Optional booleans extract_wq_data, extract_pesticide_data, extract_pfas_data bundle observed water-quality / pesticide / PFAS records (snapped to your model channels) into the model package.
HUC8 watershed	POST /api/model-settings-huc8	Extended access required for whole-basin orders (granted on request, free).
Outlet HUC12 (WBD catalog watershed)	POST /api/model-settings/explorer-watershed	JSON body includes outlet_huc12 (12 digits). Same tier rules as station builds for contributing HUC12 count; see docs/subscription_tiers.md.
Durable orders	GET /api/model-orders	Active QUEUED_APP / DISPATCHING / RUNNING rows.
Queue health	GET /api/model-orders/health	Redis-backed slot snapshot (slots.in_use, slots.limit).
Celery task row	GET /api/task_status/<task_id>	Progress while a build runs.
Cancel queued order	POST /api/model-orders/<order_id>/cancel	Queued durable orders only.
Stop in-flight build	POST /api/model_task/<task_id>/cancel	Revokes the Celery task when still cancelable.

Downloads of completed workspaces are typically issued via email links (token-based GET /download_model/<token>) or the signed-in web app (/download/...). See docs/api_reference.md.

Quick start (JupyterLab — recommended)

git clone https://github.com/SWATGenX/SWATGenX_API.git
cd SWATGenX_API
python3 -m venv .venv && . .venv/bin/activate
pip install jupyterlab requests
export SWATGENX_API_KEY='sgx_…'
jupyter lab notebooks/01_simple_station_model.ipynb

CLI alternative: pip install -r requirements.txt then python examples/create_model_by_usgs_station.py and/or python examples/create_model_by_outlet_huc12.py.

Layout

Path	Purpose
notebooks/01_simple_station_model.ipynb	Main user story: station ID + API key → submit → poll → download guidance.
examples/*.py	Minimal requests scripts: station, explorer-watershed (outlet HUC12), HUC8, polling, cancel, download helpers.
docs/	Authentication, tiers, endpoint table.
example_outputs/	Screenshots when you publish.
requirements.txt	requests only (add jupyterlab locally for the notebook).
.env.example	Variable names only — never commit real keys.

Website

Use SWATGenX Developer API for the public website overview: programmatic SWAT+ generation by USGS station, HUC8, or /api/model-settings/explorer-watershed (outlet HUC12), with links back to this GitHub repo and the example-model catalog.

Security

• Never commit .env, API keys (sgx_…), or GitHub tokens to this public repository.
• Revoke any token that was ever pasted into chat, logs, or a committed file.