Mould Detect Data API

GETTING STARTEDAuthentication

Every endpoint except GET /health requires an API key, sent in the x-api-key request header. Keys look like wk_live_<32 characters>. There is no OAuth, no bearer token, and no query-string key — only the header.

# every authenticated request carries this header
x-api-key: wk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API keys are issued directly to integration partners — request one through your Mould Detect contact. Each key carries a daily request quota; exceeding it returns 429 until the UTC day rolls over. Only a SHA-256 hash of your key is ever stored server-side, so keep the plaintext safe — it cannot be recovered, only re-issued.

GETTING STARTEDAI agents & MCP

Building with an AI assistant or your own agents? Mycelium Network puts this API behind a remote MCP server at https://mcp.moulddetect.ai/mcp, so Claude, ChatGPT, Cursor, Codex and any MCP client can call the mould growth index, forecasts, weather history, river flood and air-quality endpoints as tools, plus a mould check for photos. Keys are self-service and free during the beta, and every result carries the Copernicus credits this reference describes.

# Claude Code: one command, then ask in plain language
claude mcp add --scope user --transport http mould-detect https://mcp.moulddetect.ai/mcp \
  --header "Authorization: Bearer $MYCELIUM_KEY"

GETTING STARTEDConventions

GETTING STARTEDErrors & status codes

Errors use one consistent envelope on every endpoint — a JSON body with error: true and a human-readable reason:

{ "error": true, "reason": "invalid parameter 'latitude': input should be less than or equal to 90" }

Error reasons are safe to surface in logs — they never contain AWS identifiers, internal ARNs, or account IDs.

GETTING STARTEDQuickstart

A two-day Sydney forecast, temperatures + precipitation + weather code:

curl -s -H "x-api-key: wk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://data.moulddetect.ai/v1/daily?latitude=-33.8688&longitude=151.2093&forecast_days=2&daily=temperature_2m_max,temperature_2m_min,precipitation_sum,weather_code&timezone=auto"

{
  "latitude": -33.8688, "longitude": 151.209,
  "timezone": "Australia/Sydney", "utc_offset_seconds": 36000,
  "model": "gfs", "run": "2026-07-20T06Z",
  "daily": {
    "time":                ["2026-07-20", "2026-07-21"],
    "temperature_2m_max":  [16.1, 18.2],
    "temperature_2m_min":  [12.3, 9.1],
    "precipitation_sum":   [0.0, 0.0],
    "weather_code":        [0, 3]
  },
  "daily_units": { "temperature_2m_max": "°C", "precipitation_sum": "mm", … }
}

ENDPOINTDaily forecast

The core feed: daily aggregates for any point — up to 7 past days, today, and up to 7 forecast days — bucketed to local calendar days. Past days are served from each day's own model run; forecast days (including today) come from the latest run. The top-level run field always reports the latest run id.

Query parameters

Response body

Second model: ECMWF, and model=best (ADR-0004 item 4)

ECMWF IFS 0.25° is a second forecast model, ingested from ECMWF Open Data (00Z/12Z runs, 3-hourly steps). Its stored horizon is 6 days (144h) — shorter than GFS's 7 — because the open-data feed only publishes 3-hourly steps out to 144h; model=ecmwf with forecast_days beyond 6 returns a clean 400 naming the horizon. A handful of ECMWF variables (gust, downward shortwave radiation, precipitation type) are not always present in the open-data feed; when one is missing for a run it is recorded in that run's manifest as missing_variables and the corresponding daily.<variable> values are null, not an error.

model=best picks, per local day, whichever model's run is fresher and covers that day — ECMWF is preferred when both cover the day and its run is not more than 6h older than GFS's; any day beyond ECMWF's 6-day horizon always falls back to GFS. Each day also gets a model_agreement confidence signal:

ENDPOINTCurrent conditions

A single lightweight reading for the current moment — the model sample at-or-immediately-before now, plus today's high/low. Built for polling clients like Theme Clock: it is cacheable and supports conditional requests (see Caching).

Query parameters

{
  "timezone": "Australia/Sydney", "model": "gfs",
  "run_id": "2026-07-20T06Z", "sample_time_utc": "2026-07-20T09:00:00+00:00",
  "temperature_2m": 13.7, "relative_humidity_2m": 74.8,
  "wind_speed_10m": 13.2, "wind_gusts_10m": 25.2, "weather_code": 0,
  "temperature_2m_max": 16.1, "temperature_2m_min": 12.3,
  "units": { "temperature_2m": "°C", "wind_speed_10m": "km/h", … }
}

ENDPOINTHistorical daily

Historical daily weather from the ERA5-Land reanalysis archive — including soil-moisture layers the forecast feed doesn't carry. Aggregated to local-time days. Australia region (v1)

Query parameters

Each day also carries a data_completeness fraction (0–1); fully-missing days are omitted from the arrays entirely.

Attribution

ENDPOINTFlood forecast

River-discharge forecast and flood severity from the Global Flood Awareness System (GloFAS). The requested point is snapped to the nearest real river cell — the highest-upstream-area cell in a 5×5 (±0.1°) window — because a naïve nearest-cell lookup misses rivers. Australia region (v1)

Query parameters

Response body

ENDPOINTSite layers & dampness prior

Static site layers — elevation, slope, aspect, topographic wetness index (TWI), soil texture, land cover, and distance to coast/water — from a one-off build onto a 0.002° (~200 m) master grid (ADR-0004 item 3, "Site Passport"), plus a documented site-dampness-prior heuristic gauge. Australia region (v1)

Query parameters

No days/units/timezone parameter — a static-layer lookup is a single point-in-time read (nearest master-grid cell, no interpolation), not a time series.

Response body

Mould Atlas groups: water, coast, built (ADR-0009)

When FEATURE_ATLAS_PLACE is on and the Mould Atlas place store has been built, the body also carries three more groups from a second static store on the same 0.002° grid, plus atlas_layers_version (also on GET /health as atlas_place_version). Otherwise these keys are absent (not null) and the body and ETag are exactly the ones above. Within a group, a key is null when the value is unknown for the cell.

ENDPOINTHazard layers: fire and cyclone

Fire and tropical-cyclone hazard history near a point, read from precomputed rasters (Mould Atlas, ADR-0009). fire: satellite fire detections within 5 km, last burned date, optional smoke load, and the rain that has fallen since the last fire. cyclone: tropical cyclones within 100 km over 10 and 30 years. Each block carries its own as_of and attribution. fire: Australia region (v1) cyclone: global

Query parameters

No days/units/timezone parameter. The value is for the nearest grid-cell centre (no interpolation); every date is an ISO UTC date and the one rainfall figure is millimetres.

Response body

Top level: latitude, longitude, and fire and/or cyclone. A block is omitted when its feature flag is off. A block that cannot be produced is {"available": false, "reason": ...}: "outside_region" (with regions, the regions the store covers, for example a point outside Australia on fire) or "hazard_layers_unavailable".

ENDPOINTMould Growth Index

A daily 0–6 mould growth index, computed from 3-hourly temperature and relative humidity: up to 30 days of ERA5-Land history joined to up to 7 days of GFS forecast, for a chosen material sensitivity class. This is the published VTT mould growth model (Hukka & Viitanen 1999; improved/parameterized by Ojanen et al. 2010) — the model used in building-physics practice and WUFI/Delphin tooling, transparent and material-aware enough for hygienists to cite and labs to compare against a microscope read. Australia region (v1, ERA5-Land coverage)

Query parameters

No timezone/units parameter: timezone is always resolved automatically (the same lookup /v1/astro uses), and the index itself has no metric/imperial variant.

Response body

Plain-language scale

How this is worked out — the model

Time step 3 h. Growth requires temperature 0–50 °C and relative humidity at or above a critical threshold RHcrit(T) — a cubic in temperature down to 80% (very sensitive/sensitive materials) or 85% (medium resistant/resistant) at 20 °C and above. Above that threshold, the index grows at a material- and history-dependent rate that slows as it approaches a material- and humidity-dependent ceiling (Mmax). Below the threshold (or outside 0–50 °C), it declines on a fixed 6 h / 24 h schedule, scaled by a material "stickiness" factor (Cmat). Every constant is from Ojanen et al. 2010's parameterization; see api/mould_index.py's module docstring for the exact constants table and both references. The index is clamped to [0, 6] throughout.

References

Hukka, A. & Viitanen, H. (1999). "A mathematical model of mould growth on wooden material." Wood Science and Technology 33, 475–485. — Ojanen, T., Viitanen, H., Peuhkuri, R., Lähdesmäki, K., Vinha, J. & Salminen, K. (2010). "Mold growth modeling of building structures using sensitivity classes of materials." Buildings XI, ASHRAE.

ENDPOINTAstronomy

Sun and moon astronomy for any point, computed locally with Astral — no ingest, no ephemeris file (ADR-0004 item 1). Sunrise, sunset, civil dawn/dusk, solar noon, daylight hours, moon phase/illumination/rise/set, for up to 31 local calendar days starting today — enough to cover a whole lunar cycle (the mean synodic month is 29.53 days) in one request.

Query parameters

Timezone is always resolved automatically (the same tzfpy lookup /v1/daily's timezone=auto uses) — there is no timezone or units parameter; none of the response fields have a metric/imperial variant.

Response body

ENDPOINTAir quality forecast

CAMS global atmospheric-composition forecast — seven pollutants (PM2.5, PM10, O3, NO2, SO2, CO, and an HCHO VOC proxy), three-hourly, up to 5 days ahead. The requested point is snapped to the nearest grid cell on the dataset's native 0.4° grid — no interpolation, same convention as /v1/flood. Every value is banded against the WHO 2021 Air Quality Guideline (see Bands below). Australia region (v1)

Also carries uv_index (ADR-0004 §2) — the CAMS UV biologically effective dose × 40 — banded against the WHO UV-Index scale (see Bands below). Present in now/hourly/daily and the top-level uv_banding field only when the run has it and FEATURE_UV is on; older runs and FEATURE_UV=off both omit it cleanly (no key, not a null).

Query parameters

Response body

curl -s -H "x-api-key: wk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://data.moulddetect.ai/v1/air?latitude=-33.8688&longitude=151.2093&days=2"

{
  "location": { "lat": -33.8688, "lon": 151.2093 },
  "model": "cams-global", "run": "2026-08-04T00",
  "units": { "pm2_5": "ug/m3", …, "uv_index": "index" },
  "guideline": "who-2021-multiples", "uv_banding": "who-uv-index",
  "voc_proxy": "hcho",
  "attribution":
    "Generated using Copernicus Atmosphere Monitoring Service information 2026",
  "now": {
    "time": "2026-08-04T09:00Z",
    "pm2_5": { "value": 8.4, "band": "good" },
    "pm10": { "value": 14.2, "band": "good" },
    "uv_index": { "value": 6.4, "band": "high" },
    …
  },
  "hourly": {
    "time": ["2026-08-04T06:00Z", "2026-08-04T09:00Z", …],
    "pm2_5": [7.9, 8.4, …], … 6 more species, "uv_index": [5.1, 6.4, …]
  },
  "daily": {
    "date": ["2026-08-04", "2026-08-05"],
    "pm2_5_max": [9.6, 11.1], "pm2_5_mean": [8.1, 9.4], …,
    "uv_index_max": [9.0, 8.5], "uv_index_mean": [4.2, 3.9]
  }
}

Bands — WHO-2021-multiples, and WHO UV-Index

Each pollutant species is banded against its WHO 2021 Air Quality Guideline reference level: good ≤ 1× reference, fair ≤ 2×, poor ≤ 4×, very_poor above 4×. HCHO has no WHO ambient guideline, so it uses a separate, clearly-labelled heuristic instead of a multiple.

uv_index (source: CAMS UV biologically effective dose × 40, ADR-0004 §2) uses a separate scheme, "who-uv-index" — the WHO UV-Index exposure categories, banded on the value rounded to the nearest whole UV-Index unit:

ENDPOINTSpecialists directory

An Australia-wide directory of 4,525 mould and building specialists — plumbers, building inspectors, remediators, occupational hygienists, mycology labs and cleaners. Resolves a typed suburb, typed postcode, typed region name, or device geolocation to one of 84 ABS SA4 regions and returns its specialists, filtered and sorted. Full architecture, the offline geocoding pipeline, and the partitioning rationale: docs/specialists-api.html and docs/adr/0003-specialists-directory-partitioning.md.

Query parameters

Exactly one location path is used per request, in a fixed resolution order: region > postcode > suburb (+ state) > lat/lon. Supplying more than one uses the highest-precedence one; supplying none returns 400.

Response body

Sort order, in order of precedence: approved first, then pending_review, then the rest; then based_here before service_area; then distance_km ascending when lat/lon was given, else google_rating descending; then name. So an approved specialist leads even in a region it only services, and among equally-vetted companies a local one outranks a visiting one.

curl -s -H "x-api-key: wk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://data.moulddetect.ai/v1/specialists?suburb=Parramatta&state=NSW&category=Mould%20Testing&limit=5"

{
  "query": { "suburb": "Parramatta", "state": "NSW", "category": "Mould Testing", "limit": 5 },
  "resolved": {
    "region_slug": "sydney-parramatta", "region_name": "Sydney - Parramatta",
    "state": "NSW", "match_type": "suburb",
    "centroid": { "latitude": -33.8034, "longitude": 151.0016 }
  },
  "count": 3, "limit": 5, "offset": 0,
  "specialists": [ { "id": "mds-02931", "name": "…", "coverage": "based_here", "categories": ["Mould Testing"], … } ]
}

ENDPOINTSpecialists regions

The full region catalogue — every ABS SA4 that has at least one specialist, with its slug, name, state(s) and a category summary. Built for app pickers and typeahead widgets rather than for resolving a single search.

Response body

{ "regions": [
  { "slug": "sydney-inner-west", "name": "Sydney - Inner West", "state": "NSW",
    "states": ["NSW"], "count": 7,
    "centroid": { "latitude": -33.88071, "longitude": 151.11907 },
    "categories": ["Cleaning", "Plumbing"] }, …
] }

ENDPOINTHealth

Liveness plus data freshness — no API key required. Reports the latest run and its age, so you can monitor whether ingest is current. Also serves GET /openapi.json (the machine-readable OpenAPI schema) for codegen and Postman import.

{ "status": "ok", "model": "gfs", "latest_run": "2026-07-20T06Z", "age_seconds": 10800,
  "ecmwf_latest_run": null }

ecmwf_latest_run (ADR-0004 item 4) is the latest ingested ECMWF run id, or null when FEATURE_ECMWF is off or no ECMWF run has been ingested yet — same graceful-absence pattern as history_latest_complete_date and air_latest_run.

ADR-0009 adds three more fields, each null while its feature flag is off or its store has not been built: atlas_place_version (the Mould Atlas place-layers build version behind GET /v1/site's water/coast/built groups), hazard_fire_as_of and hazard_cyclone_as_of (the data date of the newest GET /v1/hazard build for each block). Ask /health before relying on a hazard block being fresh.

REFERENCEDaily variables

Pass any subset in daily= (comma-separated). Omitting daily returns the full base set. Every opt-in variable below is only returned when named explicitly, and never changes the default response.

REFERENCEWeather codes

The weather_code field follows the WMO 4677 convention (the same family Open-Meteo and many clients use). Common values:

REFERENCECaching & conditional requests

Every data endpoint returns a Cache-Control header and a strong ETag. To poll cheaply, store the ETag and send it back as If-None-Match: an unchanged resource returns 304 Not Modified with no body and no quota-relevant payload.

# 1) first call returns an ETag header:  ETag: "a1b2c3d4e5f6..."
# 2) poll conditionally — 304 if nothing changed:
curl -s -H "x-api-key: wk_live_…" -H 'If-None-Match: "a1b2c3d4e5f6..."' \
  "…/v1/now?latitude=-33.8688&longitude=151.2093" -o /dev/null -w "%{http_code}\n"

How long should a client cache?

The header above is a floor, not a recommendation — a client can hold data longer based on how often the upstream source actually changes:

TOOLINGTesting with Postman

Postman is the fastest way to explore the API interactively. There are two ways in.

Option A — import the OpenAPI schema (recommended)

The API self-describes at /openapi.json. Postman turns that into a ready collection with every endpoint and parameter pre-filled.

1. In Postman: Import → Link, paste https://data.moulddetect.ai/openapi.json, and import. Postman generates a collection from the live schema.
2. Open the collection's Variables and set baseUrl to the base URL above.
3. Add the API key once, at the collection level (next section), so every request inherits it.

Option B — a minimal collection by hand

Prefer to hand-roll it? Create a collection, add these two variables, then add one request per endpoint using {{baseUrl}} in the URL.

Set the key once, collection-wide

On the collection's Authorization tab, choose type API Key, with:

Leave each request's auth as Inherit auth from parent and the header is added automatically. Storing the key as a secret variable keeps it out of exported collection files.

A starter collection (paste into a new .json, then Import → File)

{
  "info": { "name": "Weather-API v1",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" },
  "auth": { "type": "apikey", "apikey": [
    { "key": "key",   "value": "x-api-key" },
    { "key": "value", "value": "{{apiKey}}" },
    { "key": "in",    "value": "header" } ] },
  "variable": [
    { "key": "baseUrl", "value": "https://data.moulddetect.ai" } ],
  "item": [
    { "name": "Daily forecast", "request": { "method": "GET", "url":
      "{{baseUrl}}/v1/daily?latitude=-33.8688&longitude=151.2093&forecast_days=3" } },
    { "name": "Current conditions", "request": { "method": "GET", "url":
      "{{baseUrl}}/v1/now?latitude=-33.8688&longitude=151.2093" } },
    { "name": "Flood forecast", "request": { "method": "GET", "url":
      "{{baseUrl}}/v1/flood?latitude=-27.47&longitude=153.03" } },
    { "name": "Health", "request": { "method": "GET", "url": "{{baseUrl}}/health" } }
  ]
}

TOOLINGClient patterns

There is no SDK to install — it's plain HTTPS/JSON, so any HTTP client works. Three idioms worth adopting:

• Respect the units block. Read units / daily_units from the response rather than hard-coding °C/km/h — a client that flips units=imperial then stays correct automatically.
• Poll /v1/now conditionally. Cache the ETag and send If-None-Match; treat 304 as "no change", which keeps a clock or widget cheap and within quota.
• Cache per grid cell, not per place-name. Every request snaps to a grid cell — forecast 0.25° (≈ 25 km), history 0.1° (≈ 10 km), flood 0.05° (≈ 5 km, snapped to the river network). Round the request coordinates to the endpoint's grid resolution and use that, plus the query params that affect the payload (units, timezone, granularity, variable list), as the cache key. Nearby suburbs and localities then collapse into a single upstream request per TTL window instead of one each.

// JavaScript (fetch) — conditional /v1/now poll
const r = await fetch(`${base}/v1/now?latitude=-33.87&longitude=151.21`, {
  headers: { 'x-api-key': key, ...(etag && { 'If-None-Match': etag }) }
});
if (r.status === 304) return cached;        // unchanged
etag = r.headers.get('ETag');
const data = await r.json();