Organized module-by-module for direct application integration.

Overview

How to read the API

The API is arranged upstream-to-downstream. Materials and operating data support scenario selection. Scenario selection drives source models. Source models generate release information for dispersion, fire, explosion, and effect modules. Those outputs then support hazard-analysis workflows and map-facing application layers.

materials -> scenario -> source -> dispersion/effects -> hazard evaluation

Module

Materials

Material records provide upstream physical properties, toxicological data, flammability information, and reactivity screening inputs. These records are packaged as registry data rather than embedded directly in model code.

Module

Health and Industrial Hygiene

These routes support concentration conversion, exposure screening, probit evaluation, TWA calculations, ventilation screening, and occupational-style interpretations that often sit beside consequence models in applications.

Symbol meaning and units

Module

Scenario and Source Models

This family converts inventory, geometry, pressure, temperature, and failure assumptions into release rate, release duration, total released mass, and phase-state information. Realistic-case, worst-case, and conservative analysis are first-class API choices.

Symbol meaning and units

Module

Dispersion

Dispersion routes transform source-term outputs into concentration fields, threshold-distance screens, isopleths, and map-ready payloads. Continuous releases, puff releases, and dense-gas screening are separated so applications can choose the proper release interpretation.

Symbol meaning and units

Module

Fire and Explosion

These routes convert flammable releases into ignition, fire, explosion, blast, and BLEVE screening outputs. They are structured so applications can chain flammability, source, ignition, and damage calculations without collapsing everything into one call.

Symbol meaning and units

Module

Effects and Toxic Criteria

Effect models convert concentration, radiation, or overpressure into consequence metrics such as fatality probability, burn probability, and dose-response curves. Toxic criteria endpoints provide the threshold values these downstream calculations are typically compared against.

Symbol meaning and units

Module

Prevention, Reactivity, and Relief

These modules support inerting, static electricity screening, area classification, relief selection and sizing, and reactivity screening so teams can connect consequence outputs back to design and safeguard decisions.

Symbol meaning and units

Module

Hazard Evaluation

Hazard-evaluation routes are meant to consume the physical outputs of upstream models rather than stand alone as isolated templates. This keeps scenario-based workflows anchored to the same source, dispersion, and effect assumptions used elsewhere in the API.

Integration Contracts

POST endpoint families, expected JSON, and governing formulas

These tables are designed as implementation contracts. Each row shows the expected top-level JSON shape and the primary physics relation the endpoint family applies.

Scenario and source controllers

Dispersion controllers

Fire, explosion, and effects controllers

Prevention, reactivity, relief, and hazard controllers

GIS, visualization, and sign controllers

POST JSON templates

Use these templates as controller-level payload contracts.

Service solver template
{
  "model_type": "gaussian_plume",
  "inputs": {
    "...": "model-specific input fields"
  }
}

Model calculate template
{
  "inputs": { "...": "model input fields" },
  "constants": { "constant.name": 123.0 }
}

GIS scenario evaluation template
{
  "scenario_type": "leak",
  "source": { "latitude": 0.0, "longitude": 0.0, "label": "Source" },
  "receptors": [
    { "id": "r1", "latitude": 0.0, "longitude": 0.0, "label": "Receptor 1" }
  ],
  "model_id": "dispersion.gaussian_puff_ground",
  "inputs": { "...": "scenario/model inputs" },
  "constants": { "constant.name": 123.0 }
}

GIS impact-zones template
{
  "scenario_type": "fire",
  "source": { "latitude": 0.0, "longitude": 0.0, "label": "Source" },
  "asset": { "...": "asset fields" },
  "criteria": [
    { "label": "Primary ring", "threshold": 12.5, "unit": "kW/m^2" },
    { "label": "Awareness ring", "threshold": 4.0, "unit": "kW/m^2" }
  ],
  "constants": { "fire.default_radiative_fraction": 0.35 }
}

Sign analysis template
{
  "observed_text": "High pressure gas pipeline",
  "site_context": "roadside corridor",
  "topography": "urban",
  "stability_class": "D",
  "wind_speed_m_s": 3.0
}

Analytical Reference

Analytical formulas used across the API

This section collects the main screening equations surfaced by the current endpoint families. These are intentionally visible so downstream applications can show the mathematical basis directly in the user interface.

The symbol definitions above apply to these summary formulas as well. In practice, the API expects request payloads to use the units listed in the symbol tables for each module section so the fitted coefficients and empirical constants remain unambiguous.

Provenance

Constants and physical meaning

Deep Safety keeps shared constants and starter screening defaults in packaged JSON registries. The intention is to make hard-coded assumptions explicit and inspectable.