Programmable watershed modeling

One Platform. Three Doors.

SWATGenX is infrastructure you can drive from code: a Python package on PyPI, a REST model-generation API, and a public Model Context Protocol server for AI agents — the same data, the same models, and the same fair-use quotas behind every door.

pip install swatgenx Connect an AI agent Get API key

swatgenx on PyPI
MCP server for AI agents
REST jobs for SWAT+ packages
Same pipeline as the web app

Humans

swatgenx.com

Python

pip install swatgenx

AI agents

swatgenx.com/mcp

SWATGenX

25,000+ USGS gauges
NHDPlus HR · PRISM · gSSURGO
SWAT+ · MODFLOW 6
Groundwater & PFAS inventories

→ calibrated, validated models

Choose your door

Everything the website can do is backed by an API — and now there are three ways in. Python users install the swatgenx package from PyPI. Scripts and pipelines call the REST API directly. And AI agents connect to the public Model Context Protocol server, where the platform's datasets and model factory appear as callable tools.

All three doors open onto the same infrastructure: 25,000+ USGS gauges, the national groundwater and PFAS inventories, and SWAT+ / MODFLOW 6 model generation with published, validated calibration results — under the same accounts and fair-use quotas as the web app.

Python: pip install swatgenx

The official Python client is dependency-light and needs no account for public data. Browse the example-model catalog with calibration metrics, query wells and PFAS records, then — with a free API key — order a brand-new model and pull the finished ZIP straight to your disk.

pip install swatgenx

# Public data — no account needed
import swatgenx as sg

models = sg.catalog(state="FL", calibrated_only=True)
len(models)                      # 17 calibrated Florida models

sg.calibration("01451800")
# {'mode': 'engineer', 'cal_daily_nse': 0.642,
#  'val_daily_nse': 0.748, 'validated_split': True, ...}

sg.groundwater_at(40.602, -75.471)   # nearest well + lithology
sg.pfas_stations(huc8="0405")        # PFAS monitoring inventory

swatgenx on PyPI

MCP: the door for AI agents

SWATGenX runs a public, read-first Model Context Protocol server. Add it to Claude or any MCP client as a streamable-HTTP server and the platform becomes a set of callable tools — no scraping, no glue code. Public-data tools work for everyone; ordering and downloads use your API key (sent as the X-SWATGenX-Api-Key header), under the same quotas as every other door. Agents that hit a limit are told exactly how their user can upgrade.

Endpoint

https://www.swatgenx.com/mcp    (transport: streamable HTTP)

Also advertised to agents in this site's llms.txt.

Tool	What it does	Needs
search_swat_models	Browse the example-model catalog (state, size, calibration status)	guest
get_model_calibration	Calibration + held-out validation NSE / PBIAS for one model	guest
query_groundwater	Nearest wells + lithology from the 28.8M-interval national inventory	guest
query_pfas	National PFAS monitoring inventory by state / analyte	guest
request_model	Preview what SWATGenX would build for a gauge or HUC12 outlet	guest
get_access_info	The access ladder + your current tier	guest
order_model	Order a real SWAT+ build (fair-use allocations apply)	API key
get_order_status	Track a build order to completion	API key
list_my_models	List your build orders	API key
download_model	Mint a 24 h pull link; your agent saves the ZIP locally	API key

Model-generation entry points

USGS gage

Generate a SWAT+ model for a gage-centered watershed using site_no.

HUC12 outlet

Generate a SWAT+ model from a selected WBD HUC12 outlet watershed.

HUC8 basin

Generate a whole-basin SWAT+ model for an eight-digit HUC8 watershed. Available on Pro.

Why this API matters

Every request uses the same SWATGenX model-generation pipeline: NHDPlus-HR hydrography, national weather, land cover, soils, crop, terrain, and optional water-use inputs assembled into a downloadable SWAT+ project structure.

REST: direct HTTP requests

Prefer raw HTTP? Choose the watershed type, copy the request, and replace the identifier with your USGS gage, HUC12 outlet, or HUC8 code. Full polling and download examples are available on GitHub.

Sample requests.post body

import os
import requests

API_KEY = os.environ["SWATGENX_API_KEY"]

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "X-SWATGenX-Api-Key": API_KEY,
    "Content-Type": "application/json",
}

# 12-digit WBD outlet HUC12 — catalog watershed from Watershed Explorer
payload = {
    "outlet_huc12": "070500020602",
    "ls_resolution": 250,
    "dem_resolution": 30,
}

r = requests.post(
    "https://www.swatgenx.com/api/model-settings/explorer-watershed",
    headers=headers,
    json=payload,
    timeout=120,
)

print(r.json())

Workflow

Request → build → track → download. Same model-generation engine as the web app — error handling and advanced options are covered in the GitHub examples.

1Get an API key

Create an account and generate an API key from your access page.

2Submit a model request

Send a USGS gage, HUC12 outlet, or HUC8 basin request to the model-generation endpoint.

3Track the build

Poll task and order endpoints while SWATGenX delineates the watershed, assembles model inputs, and builds the SWAT+ package.

4Download the model package

When the job completes, download the ZIP package and continue in SWAT+ Editor or your calibration workflow.

Core API routes

These are the main routes for creating, tracking, and downloading SWAT+ model packages. Full request bodies and examples are maintained in the GitHub repository.

Method	Route	Purpose
POST	/api/model-settings	Create model by USGS station (JSON: site_no)
POST	/api/model-settings/explorer-watershed	Create model by outlet HUC12 catalog watershed (JSON: outlet_huc12)
POST	/api/model-settings-huc8	Create model by whole HUC8 (Pro; JSON: huc8_code)
GET	/api/model-orders	List recent model orders
GET	/api/task_status/<task_id>	Check task progress
POST	/api/download_model/link	Mint a fresh 24 h download link for a model you own
GET	/download_model/<token>	Download completed ZIP

One access ladder, every door

The same four tiers apply whether you arrive by browser, Python, REST, or MCP — and the API tells you (or your agent) exactly what the next tier unlocks when you reach a limit.

Guest

All public data — the example-model catalog with calibration results, the groundwater inventory, and the PFAS inventory — via Python, REST, or MCP. No account.

Member (free)

Order SWAT+ models under fair-use daily allocations and pull-download the models you own. Create an account, mint an API key, done.

Extended access

HUC8 whole-basin builds, coupled SWAT+MODFLOW-6, HUC14 30 m site models, and higher allocations — granted on request via info@swatgenx.com.

Calibration credit

Cloud calibration campaigns on dedicated compute, billed against account credit from your dashboard.

View access levels

Frequently asked

Does SWATGenX have an MCP server?

Yes. SWATGenX runs a public Model Context Protocol (MCP) server at https://www.swatgenx.com/mcp (streamable-HTTP transport). Any MCP client — Claude, or any AI-agent framework — can add it as an HTTP server and call the platform as tools: search the SWAT+ example-model catalog, read calibration and validation results, query the national groundwater and PFAS inventories, and (with an API key) order a SWAT+ model and download it. It is also advertised to agents in the site's llms.txt.

Is there a Python package for SWATGenX?

Yes. Install it with "pip install swatgenx" (https://pypi.org/project/swatgenx/). Public data functions need no account; a free API key adds model ordering and downloads. The package mirrors the REST API and MCP server, under the same fair-use quotas.

What can an AI agent do with SWATGenX?

Through the MCP server, an agent can browse calibrated SWAT+ models, read cal/val NSE and PBIAS, query 28.8 million groundwater lithology intervals and a national PFAS inventory by location, and request a SWAT+/MODFLOW 6 model for any of 25,000+ USGS gauges. Public tools are open to everyone; ordering and downloads use the user's API key and fair-use allocation.

How do the website, Python package, REST API, and MCP server relate?

They are four doors onto the same platform — identical national data, identical SWAT+/MODFLOW 6 model generation, and identical accounts and fair-use quotas. Humans use the website; scripts use the REST API or the swatgenx Python package; AI agents use the MCP server.

GitHub examples & support

Notebooks and scripts show polling, downloads, and tier-aware requests. Review completed SWAT+ examples before submitting jobs. For keys and access updates, use your access page.

GitHub examples Get API key

Model Creation API examples (Jupyter + Python): GitHub.

Home