API docs by Redocly

Water Resources Modeling API (1.11.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.1.15–5.2.4, EPANET 2.2–2.3.3, and HEC-RAS 6.6–7.0.1

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"
}

Engines

Supported simulation engine types and versions

List supported engines

Returns all supported simulation engine types, their available versions, and the default version for each.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

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)
  • use_existing_results (boolean) — reuse results already in the package rather than recomputing

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

Field ordering (multipart only): the upload body is consumed as a stream, so all form fields must be sent before the file field. type in particular decides how the file is handled and is read from the stream before the file itself. Standard clients (curl -F, browser FormData, Go's multipart.Writer) preserve the order you add fields, so putting file last is enough. A file field arriving before type is rejected with 400.

Maximum upload size: uploads are limited to 5 GiB by default (MAX_UPLOAD_BYTES), for every engine. Exceeding it returns 413.

No upload is held in server memory. A HEC-RAS archive is passed to the engine untouched and streams straight to S3. A SWMM or EPANET archive is unpacked first, but it is spooled to disk and its entries are streamed out one at a time.

Two smaller limits apply inside an archive. Its extracted contents are bounded by the same 5 GiB ceiling, which a compressed archive can otherwise far exceed, and it may hold at most 10,000 entries. The input file itself is limited to 1 GiB (MAX_BUFFERED_UPLOAD_BYTES), because it is validated as a whole and searched for references to the other files, so it is the one entry that must be read into memory. That limit also applies to a bare .inp uploaded on its own, and to JSON request bodies.

For models above these limits, use POST /uploads to get presigned URLs, transfer the file directly to S3, then pass the returned input_file_uri here. An input_file_uri that already points into the API's own bucket is referenced in place rather than being copied through the server, so files of any size work by that route.

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 (supported versions: 5.1.15, 5.2.1, 5.2.2, 5.2.3, 5.2.4)
  • epanet: Water distribution network modeling (supported versions: 2.2, 2.3, 2.3.1, 2.3.2, 2.3.3)
  • hec_ras: HEC-RAS river analysis (supported versions: 6.6, 7.0.1)
engine_version
string

Optional engine version to use for the simulation. Must be a version supported by the chosen type. Defaults to the latest stable version for each engine type when omitted.

Supported versions per engine:

  • swmm: 5.1.15, 5.2.1, 5.2.2, 5.2.3, 5.2.4 (default: 5.2.4)
  • epanet: 2.2, 2.3, 2.3.1, 2.3.2, 2.3.3 (default: 2.3.3)
  • hec_ras: 6.6, 7.0.1 (default: 7.0.1)
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"
}

Uploads

Presigned direct-to-S3 uploads for model files above the request size limit

Start a presigned upload

Returns presigned URLs that let a client upload a model file directly to S3, bypassing the API's request size limit entirely. The file's bytes never pass through the API, so the upload is bounded by S3 rather than by server memory or load balancer timeouts. Use this for any file too large for a multipart/form-data upload to POST /simulations.

The response mode tells you how to transfer the file:

single (files under 5GB) — send one PUT to the single URL in parts[0].url with the file as the body. No completion call is needed.

multipart (files 5GB and over) — split the file into chunks of exactly part_size bytes (the final chunk may be smaller) and PUT each one to its matching URL in parts. S3 returns an ETag header for each part; collect them and call POST /uploads/complete.

Either way, once the upload is finished, pass the returned input_file_uri as input_file_uri to POST /simulations. The API references the object in place — it is never copied through the server.

URL lifetime: URLs expire at expires_at (6 hours after issue). Treat that as an upper bound, not a guarantee — when the API runs with temporary credentials (an ECS task role in production), presigned URLs stop working as soon as those credentials expire, which can be sooner. If part uploads start returning 403 partway through a transfer, call POST /uploads/abort and start a new upload rather than retrying.

Authorizations:
bearerAuth
Request Body schema: application/json
required
filename
required
string

Original file name. Only the base name is used, and it is sanitised; the storage key is chosen by the server.

size
required
integer <int64> <= 68719476736

Exact size of the file in bytes. Required, because the number of presigned part URLs is derived from it.

Limited to 64 GiB by default (configurable per deployment via MAX_PRESIGNED_UPLOAD_BYTES); a larger value is rejected with 400.

Responses

Request samples

Content type
application/json
{
  • "filename": "hecras-model.zip",
  • "size": 8800000000
}

Response samples

Content type
application/json
Example
{}

Complete a multipart upload

Assembles the parts of a multipart upload into a single object. Required only for mode: multipart; single uploads are complete as soon as the PUT succeeds.

Send every part you uploaded, with the ETag S3 returned in the response header for that part. Parts must be ordered by part_number.

The upload key must belong to the calling API key's user or team.

Authorizations:
bearerAuth
Request Body schema: application/json
required
key
required
string

The key returned by POST /uploads

upload_id
required
string

The upload_id returned by POST /uploads

required
Array of objects

One entry per uploaded part, ordered by part number

Responses

Request samples

Content type
application/json
{
  • "key": "uploads/team-abc/9f8e7d/hecras-model.zip",
  • "upload_id": "2~Xy9...",
  • "parts": [
    ]
}

Response samples

Content type
application/json
{
  • "key": "uploads/team-abc/9f8e7d/hecras-model.zip",
  • "input_file_uri": "s3://neeraip-simulations-prod/uploads/team-abc/9f8e7d/hecras-model.zip",
  • "size": 8800000000
}

Abort a multipart upload

Discards an unfinished multipart upload and the parts already transferred, so they stop accruing storage charges. Use this when a large upload is cancelled or fails partway through.

The upload key must belong to the calling API key's user or team.

Authorizations:
bearerAuth
Request Body schema: application/json
required
key
required
string
upload_id
required
string

Responses

Request samples

Content type
application/json
{
  • "key": "uploads/team-abc/9f8e7d/hecras-model.zip",
  • "upload_id": "2~Xy9..."
}

Response samples

Content type
application/json
Example
{
  • "code": "BAD_REQUEST",
  • "message": "type is required"
}