API docs by Redocly

Water Resources Modeling API (1.1.4)

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, 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": {
    },
  • "license": {},
  • "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.

An additional hec_ras_plan_number field is required for HEC-RAS simulations.

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.

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
}

Re-run an existing simulation

Re-runs an existing simulation with updated parameters or a new input file. Only the simulation owner (user or team) can update 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 (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.

Responses

Request samples

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

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

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
}