API docs by Redocly

Water Resources Modeling API (1.0.0)

Download OpenAPI specification:

NEER: support@neer.ai License: MIT

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 and EPANET 2.3.3

Authentication

All endpoints (except /health) require a Bearer token in the Authorization header:

Authorization: Bearer <token>

Visit https://aip.neer.ai/user/api-keys for API key provisioning.

Health

Health check endpoints

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 on AWS ECS.

Supports two content types:

  • application/json: JSON request body
  • multipart/form-data: Form data with optional file upload

Input files can be provided via:

  1. S3 URI in input_file_uri field
  2. HTTPS URL in input_file_uri field
  3. File upload via multipart form (automatically uploaded to S3)
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 (not yet supported)
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.

Responses

Request samples

Content type
Example
{
  • "type": "swmm",
  • "label": "Storm water analysis - Jan 2026",
  • "input_file_uri": "s3://bucket/input/model.inp"
}

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",
  • "completed_at": "2026-01-17T10:35:00Z",
  • "ended_at": null
}

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",
  • "completed_at": null
}

Run a simulation with existing ID

Runs a simulation using an existing simulation ID. The simulation must be in a pending state. Only the simulation owner (user or team) can run it.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Simulation ID (UUID)

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 (not yet supported)
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.

Responses

Request samples

Content type
{
  • "type": "swmm",
  • "label": "Storm water runoff analysis - January 2026",
  • "input_file_uri": "s3://neeraip-simulations-dev/input/model.inp"
}

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",
  • "completed_at": "2026-01-17T10:35:00Z",
  • "ended_at": null
}