API docs by Redocly

Water Resources Modeling API (1.8.0)

Download OpenAPI specification:

NEER: support@neer.ai

REST API for running water resources simulations (SWMM, EPANET, HEC-RAS) on demand.

Features

  • Secure API key authentication
  • On-demand simulation execution
  • Simple file upload and download
  • Real-time simulation status tracking
  • Support for SWMM 5.2.4, EPANET 2.3.3, and HEC-RAS 6.6

Authentication

All endpoints except /, /health, and /openapi.yaml require a Bearer token in the Authorization header:

Authorization: Bearer <token>

Visit https://aip.neer.ai/user/keys or https://aip.neer.ai/teams//?tab=keys for API key provisioning.

Info

Informational endpoints

API information

Returns basic information about the API, including documentation links and available endpoints

Responses

Response samples

Content type
application/json
{
  • "name": "Water Resources Modeling API",
  • "version": "1.0.0",
  • "contact": {
    },
  • "documentation": {},
  • "endpoints": {
    }
}

OpenAPI specification

Returns the raw OpenAPI specification for this API in YAML format

Responses

Response samples

Content type
application/json
Example
{
  • "error": "simulation not found"
}

Health check

Returns the health status of the API server

Responses

Response samples

Content type
application/json
{
  • "status": "healthy"
}

Simulations

Water resources simulation management

List simulations

Retrieves a list of simulations accessible to the authenticated user or team. Results can be filtered by simulation type.

Authorizations:
bearerAuth
query Parameters
type
string (SimulationType)
Enum: "swmm" "epanet" "hec_ras"
Example: type=swmm

Filter by simulation type

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create and run a new simulation

Creates a new simulation and submits it for execution.

For HEC-RAS simulations, hec_ras_plan_number is supported, along with optional floodplain controls:

  • generate_floodplain_maps (boolean)
  • depth_threshold (number, feet)

Choose your content type based on your input method:

application/json - For remote files (HTTPS or S3 URIs)

  • Provide file location via input_file_uri field
  • No file upload needed

multipart/form-data - For local file uploads

  • Upload file directly via file field

Input file methods:

  1. HTTPS URL (JSON only) - Publicly accessible HTTPS URL Example: https://example.com/models/stormwater.inp
  2. S3 URI (JSON only) - S3 object URI (must be publicly accessible) Example: s3://my-bucket/models/project.zip
  3. Local File Upload (multipart only) - Direct file upload to API Best for local development and ad-hoc testing
Authorizations:
bearerAuth
Request Body schema:
required
type
required
string (SimulationType)
Enum: "swmm" "epanet" "hec_ras"

Type of water resources simulation:

  • swmm: Storm Water Management Model (version 5.2.4)
  • epanet: Water distribution network modeling (version 2.3.3)
  • hec_ras: HEC-RAS river analysis (version 6.6)
label
string

Human-readable label for the simulation

input_file_uri
string <uri>

URI to the input file. Supported schemes:

  • s3://bucket/path/to/file.inp - S3 object
  • https://example.com/file.inp - HTTPS URL

If omitted and using multipart/form-data, a file can be uploaded directly.

hec_ras_plan_number
string

HEC-RAS plan number to execute. Required when type is hec_ras. Identifies which plan within the HEC-RAS project archive to run.

generate_floodplain_maps
boolean

Optional for hec_ras simulations. When true, floodplain map artifacts are generated.

depth_threshold
number <double> >= 0

Optional for hec_ras simulations. Minimum depth (in feet) used when generating floodplain outputs.

preprocess
boolean

Optional for hec_ras simulations. When true, preprocessing steps are run before the simulation executes.

source_model_id
string or null <uuid>

Optional. UUID of the HydraulicModel this simulation was launched from (Console-initiated sims). Persisted on the simulation row so a model's full simulation history can be retrieved by source_model_id. Has no effect on engine execution. Ignored when null.

source_layer_id
string or null <uuid>

Optional. UUID of the specific child Layer of a HydraulicModel that triggered this simulation, when run directly from a layer in the Console object panel. Like source_model_id, this is metadata only — the engine ignores it.

data_json_uri
string <uri>

Optional. S3 URI of an editable non-spatial overlay (data.json) produced by the Console UI. When set, the task-runner downloads this overlay and merges it onto input_file_uri (the immutable source .inp) before running the engine. Spatial sections are preserved verbatim from the source; only non-spatial sections (patterns, curves, options, controls, …) are replaced. When omitted, the task-runner uses input_file_uri directly, preserving the legacy raw-.inp API path unchanged.

Responses

Request samples

Content type
Example
{}

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "user_id": "usr-123",
  • "team_id": "team-456",
  • "project_id": "proj-789",
  • "label": "Storm water analysis",
  • "type": "swmm",
  • "version": "5.2.4",
  • "context": {
    },
  • "status": "pending",
  • "created_at": "2026-01-17T10:30:00Z",
  • "started_at": "2026-01-17T10:31:00Z",
  • "ended_at": "2026-01-17T10:35:00Z"
}

Get simulation details

Retrieves detailed information about a specific simulation

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

Simulation ID (UUID)

Responses

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "user_id": "usr-123",
  • "team_id": null,
  • "project_id": "proj-456",
  • "label": "Storm water analysis",
  • "type": "swmm",
  • "version": "5.2.4",
  • "context": {
    },
  • "status": "running",
  • "created_at": "2026-01-17T10:30:00Z",
  • "started_at": "2026-01-17T10:31:00Z",
  • "ended_at": null
}

List simulation files

Retrieves all files associated with a simulation, including input files, output files, reports, and other simulation artifacts.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

Simulation ID (UUID)

Responses

Response samples

Content type
application/json
[]

Download all simulation files as ZIP

Downloads all files associated with a simulation as a single ZIP archive. Files that cannot be retrieved are silently skipped.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

Simulation ID (UUID)

Responses

Response samples

Content type
application/json
Example
{
  • "error": "missing authorization header"
}

Get simulation logs

Retrieves logs for a simulation with pagination and sorting support. By default, logs are ordered by timestamp in descending order (newest first).

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

Simulation ID (UUID)

query Parameters
limit
integer [ 1 .. 500 ]
Default: 50
Example: limit=25

Maximum number of logs to return (default 50, max 500)

offset
integer >= 0
Default: 0

Number of logs to skip for pagination (default 0)

sort
string
Default: "desc"
Enum: "asc" "desc" "ascending" "descending"
Example: sort=desc

Sort order by timestamp (default desc for newest first)

Responses

Response samples

Content type
application/json
{
  • "logs": [
    ],
  • "total": 15,
  • "limit": 25,
  • "offset": 0,
  • "has_more": false
}

Model Generation

Async model generation jobs for HEC-RAS, SWMM, and EPANET

Create a model generation job

Submits an async job to generate a water resources model (HEC-RAS, SWMM, or EPANET) from geospatial data. Returns a job record with status: pending and a job ID that can be used to poll for progress via GET /models/generate/{id}.

Authorizations:
bearerAuth
Request Body schema: application/json
required
software
required
string (ModelSoftware)
Enum: "hec_ras" "swmm" "epanet" "gis_tool" "report"

Modeling software or tool type:

  • hec_ras: HEC-RAS river analysis
  • swmm: Storm Water Management Model (EPA SWMM)
  • epanet: Water distribution network (EPANET)
  • gis_tool: GIS processing tool (terrain, hydrology, vector, raster)
  • report: Automated hydrology / modeling report generation (PDF/DOCX)
project_name
required
string

Human-readable project name

build_type
string (BuildType)
Enum: "brownfield" "greenfield"
  • brownfield: Existing infrastructure — user provides existing network layers
  • greenfield: New network design from scratch
huc_id
string

HUC watershed identifier for the study area

object (BoundingBox)

Geographic bounding box in WGS84 coordinates

units
string
Default: "US"

Unit system (US or SI), defaults to US

dem_resolution
integer
Default: 10

DEM resolution in meters (default 10)

tool_name
string

GIS tool function name (required when software = gis_tool). Available tools: compute_slope, compute_aspect, compute_hillshade, compute_curvature, compute_twi, fill_sinks, compute_flow_direction, compute_flow_accumulation, extract_streams, compute_stream_order, delineate_watershed, delineate_subwatersheds, clip_vector, buffer_vector, dissolve_vector, merge_vectors, simplify_vector, reproject_vector, spatial_join, vector_overlay, resample_raster, reproject_raster, clip_raster, reclassify_raster, zonal_statistics, raster_algebra, generate_contours

object

Parameters for the GIS tool (required when software = gis_tool). Each tool has its own parameters. File paths can be S3 URIs or HTTPS URLs.

user_dem_url
string <uri>

URL to user-provided DEM raster (overrides default data source)

user_boundary_url
string <uri>

URL to user-provided study area boundary (GeoJSON or shapefile)

user_streams_url
string <uri>

URL to user-provided stream network layer

user_landcover_url
string <uri>

URL to user-provided land cover raster

user_soils_url
string <uri>

URL to user-provided soils data layer

user_roads_url
string <uri>

URL to user-provided roads layer

user_parcels_url
string <uri>

URL to user-provided parcels layer (greenfield builds)

user_buildings_url
string <uri>

URL to user-provided buildings layer (greenfield builds)

sub_type
string (ModelSubType)
Enum: "1d" "2d" "1d2d"

HEC-RAS model dimensionality (required when software is hec_ras):

  • 1d: One-dimensional analysis
  • 2d: Two-dimensional analysis
  • 1d2d: Combined 1D/2D analysis
design_storms
Array of strings

Design storm return periods (HEC-RAS), e.g. ["100yr", "500yr"]

xs_spacing_ft
number <double>

Cross-section spacing in feet (HEC-RAS 1D)

xs_half_width_ft
number <double>

Cross-section half-width in feet (HEC-RAS 1D)

xs_sample_interval_ft
number <double>

DEM sample interval along cross-sections in feet (HEC-RAS 1D)

xs_max_points
integer

Maximum points per cross-section (HEC-RAS 1D)

cell_size_default_ft
number <double>

Default 2D mesh cell size in feet (HEC-RAS 2D)

cell_size_channel_ft
number <double>

Channel zone 2D mesh cell size in feet (HEC-RAS 2D)

cell_size_urban_ft
number <double>

Urban zone 2D mesh cell size in feet (HEC-RAS 2D)

stream_source
string

Source dataset for stream network (HEC-RAS)

road_breakline_mode
string

How roads are used as breaklines in terrain (HEC-RAS)

storm_duration_hr
number <double>

Storm duration in hours (HEC-RAS)

precip_distribution_type
string

Precipitation distribution type (HEC-RAS)

user_breaklines_url
string <uri>

URL to user-provided terrain breaklines (HEC-RAS)

user_cross_sections_url
string <uri>

URL to user-provided cross-section geometry (HEC-RAS 1D)

user_structures_url
string <uri>

URL to user-provided hydraulic structures (HEC-RAS)

user_mannings_url
string <uri>

URL to user-provided Manning's n roughness polygons (HEC-RAS)

user_flow_data_url
string <uri>

URL to user-provided flow data (HEC-RAS)

burn_culverts
boolean

Burn culverts into the terrain DEM (HEC-RAS)

culvert_depth_ft
number <double>

Culvert burn depth in feet (HEC-RAS)

user_culvert_lines_url
string <uri>

URL to user-provided culvert centerlines (HEC-RAS)

auto_inflow_bc
boolean

Automatically generate upstream inflow boundary conditions (HEC-RAS)

min_inflow_drainage_area_sqmi
number <double>

Minimum drainage area (sq mi) for auto-inflow BC (HEC-RAS)

inflow_bc_line_width_ft
number <double>

Width in feet of generated inflow BC lines (HEC-RAS)

user_inflow_csv_url
string <uri>

URL to user-provided inflow hydrograph CSV (HEC-RAS)

user_bc_lines_url
string <uri>

URL to user-provided boundary condition lines (HEC-RAS)

user_downstream_stage_url
string <uri>

URL to user-provided downstream stage time series (HEC-RAS)

user_rating_curve_url
string <uri>

URL to user-provided downstream rating curve (HEC-RAS)

downstream_bc
string

Downstream boundary condition type, e.g. normal_depth, stage, rating_curve (HEC-RAS)

downstream_slope
number <double>

Downstream channel slope for normal depth BC (HEC-RAS)

downstream_stage_ft
number <double>

Fixed downstream stage in feet (HEC-RAS)

rainfall_source
string

Source for rainfall data (SWMM)

design_storm_type
string

Design storm type (SWMM)

storm_duration_hrs
number <double>
Default: 24

Storm duration in hours (SWMM), defaults to 24

storm_return_years
Array of integers

Return period years for design storms (SWMM)

subcatchment_method
string
Default: "auto"

Subcatchment delineation method (SWMM), defaults to auto

user_junctions_url
string <uri>

URL to user-provided junction nodes (SWMM brownfield)

user_outfalls_url
string <uri>

URL to user-provided outfall nodes (SWMM brownfield)

user_storage_url
string <uri>

URL to user-provided storage units (SWMM brownfield)

user_conduits_url
string <uri>

URL to user-provided conduit links (SWMM brownfield)

user_pumps_url
string <uri>

URL to user-provided pump links (SWMM brownfield)

user_weirs_url
string <uri>

URL to user-provided weir links (SWMM brownfield)

user_orifices_url
string <uri>

URL to user-provided orifice links (SWMM brownfield)

user_subcatchments_url
string <uri>

URL to user-provided subcatchment polygons (SWMM)

user_raingages_url
string <uri>

URL to user-provided rain gauge locations (SWMM)

default_conduit_roughness
number <double>
Default: 0.013

Default Manning's n for conduits (SWMM), defaults to 0.013

default_conduit_shape
string
Default: "CIRCULAR"

Default conduit cross-section shape (SWMM), defaults to CIRCULAR

default_conduit_diameter
number <double>
Default: 18

Default conduit diameter in inches (SWMM), defaults to 18

infiltration_method
string
Default: "GREEN_AMPT"

Infiltration method for subcatchments (SWMM), defaults to GREEN_AMPT

flow_routing
string
Default: "DYNWAVE"

Flow routing method (SWMM), defaults to DYNWAVE

system_type
string

Stormwater system type (SWMM)

use_rdii
boolean

Enable rainfall-derived inflow and infiltration (SWMM)

precip_distribution
string

Precipitation temporal distribution (SWMM)

precip_quartile
string

SCS precipitation quartile (SWMM)

precip_percentile
string

NOAA precipitation percentile (SWMM)

user_epanet_junctions_url
string <uri>

URL to user-provided junction nodes (EPANET brownfield)

user_reservoirs_url
string <uri>

URL to user-provided reservoirs (EPANET brownfield)

user_tanks_url
string <uri>

URL to user-provided tanks (EPANET brownfield)

user_pipes_url
string <uri>

URL to user-provided pipe links (EPANET brownfield)

user_epanet_pumps_url
string <uri>

URL to user-provided pump links (EPANET brownfield)

user_valves_url
string <uri>

URL to user-provided valve links (EPANET brownfield)

user_demands_url
string <uri>

URL to user-provided demand data (EPANET)

default_pipe_diameter
number <double>
Default: 12

Default pipe diameter in inches (EPANET), defaults to 12

default_pipe_roughness
number <double>
Default: 130

Default Hazen-Williams C roughness coefficient (EPANET), defaults to 130

default_demand_gpm
number <double>
Default: 5

Default node demand in GPM (EPANET), defaults to 5

headloss_formula
string
Default: "H-W"

Headloss formula (EPANET), defaults to H-W

Responses

Request samples

Content type
application/json
Example
{
  • "software": "hec_ras",
  • "project_name": "Austin Creek Flood Study",
  • "sub_type": "2d",
  • "huc_id": "12090205",
  • "design_storms": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440001",
  • "user_id": "usr-123",
  • "team_id": "team-456",
  • "project_name": "Austin Creek Flood Study",
  • "model_type": "hec_ras_2d",
  • "status": "pending",
  • "config": { },
  • "output_uri": "s3://neeraip-models/generated/550e8400-e29b-41d4-a716-446655440001/model.zip",
  • "error": "string",
  • "progress": 45,
  • "current_step": "Generating 2D mesh",
  • "created_at": "2026-01-17T10:30:00Z",
  • "started_at": "2026-01-17T10:31:00Z",
  • "ended_at": "2026-01-17T10:45:00Z"
}

List model generation jobs

Returns all model generation jobs accessible to the authenticated user or team.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get model generation job

Returns the status and details of a specific model generation job.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440001

Model generation job ID (UUID)

Responses

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440001",
  • "user_id": "usr-123",
  • "team_id": "team-456",
  • "project_name": "Austin Creek Flood Study",
  • "model_type": "hec_ras_2d",
  • "status": "pending",
  • "config": { },
  • "output_uri": "s3://neeraip-models/generated/550e8400-e29b-41d4-a716-446655440001/model.zip",
  • "error": "string",
  • "progress": 45,
  • "current_step": "Generating 2D mesh",
  • "created_at": "2026-01-17T10:30:00Z",
  • "started_at": "2026-01-17T10:31:00Z",
  • "ended_at": "2026-01-17T10:45:00Z"
}