{"openapi":"3.1.0","info":{"title":"Gauge API","version":"0.1.0","description":"A US river/stream gauge and flood-stage connector reading live from USGS Water Services: current conditions, site search, daily history, percentile context, station metadata, a parameter glossary and unit conversion.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://gauge.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/gauge/docs"},"termsOfService":"https://connectorbay.com/gauge/terms"},"servers":[{"url":"https://gauge.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/gauge/docs"},"security":[{},{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/current_conditions":{"post":{"operationId":"current_conditions","summary":"The latest reading from one USGS monitoring site for every parameter it currently reports — typically","description":"The latest reading from one USGS monitoring site for every parameter it currently reports — typically\n    streamflow (cfs) and gage height (ft), sometimes also water temperature, dissolved oxygen, pH and more —\n    each with its own observation timestamp. Use for \"what's the current flow on the Potomac\", \"how high is\n    the river at site 01646500 right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_id":{"description":"USGS site number, e.g. '01646500' (Potomac River near Washington, DC).","examples":["01646500"],"title":"Site Id","type":"string"}},"required":["site_id"],"title":"current_conditionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/multi_site_snapshot":{"post":{"operationId":"multi_site_snapshot","summary":"Current streamflow, gage height and water temperature for several USGS sites at once, in a single","description":"Current streamflow, gage height and water temperature for several USGS sites at once, in a single\n    upstream call (USGS's API accepts a comma-separated site list natively). Use for \"compare flow at these\n    three gauges\", \"check all my usual river sites\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_ids":{"description":"2-10 USGS site numbers.","examples":[["01646500","01638500"]],"items":{"type":"string"},"maxItems":10,"minItems":1,"title":"Site Ids","type":"array"}},"required":["site_ids"],"title":"multi_site_snapshotArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/find_sites":{"post":{"operationId":"find_sites","summary":"Find USGS monitoring sites by state or county. Give a site's number to current_conditions or","description":"Find USGS monitoring sites by state or county. Give a site's number to current_conditions or\n    site_info. Use for \"find stream gauges in Colorado\", \"what USGS sites are in Fairfax County, VA\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter USPS state code, e.g. 'VA'.","examples":["VA","CA"],"title":"State"},"county":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"5-digit county FIPS code (state+county), e.g. '51059' for Fairfax County, VA. Overrides state if both are given.","title":"County"},"site_type":{"default":"ST","description":"ST=stream, LK=lake/reservoir, SP=spring, GW=well, ES=estuary, AT=atmosphere, WE=wetland.","title":"Site Type","type":"string"},"max_results":{"default":100,"maximum":500,"minimum":1,"title":"Max Results","type":"integer"}},"title":"find_sitesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/sites_near":{"post":{"operationId":"sites_near","summary":"USGS monitoring sites within an approximate radius of a coordinate, nearest first. The search box is","description":"USGS monitoring sites within an approximate radius of a coordinate, nearest first. The search box is\n    computed from simple planar math (not exact geodesics), which is fine at this scale but means the\n    'radius' is approximate, especially at high latitudes. Use for \"any stream gauges near me\", \"USGS sites\n    near 38.9, -77.1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"latitude":{"maximum":90,"minimum":-90,"title":"Latitude","type":"number"},"longitude":{"maximum":180,"minimum":-180,"title":"Longitude","type":"number"},"radius_miles":{"default":25,"description":"Search radius. USGS's bounding-box query caps how large an area can be searched at once, so this is limited.","maximum":75,"minimum":1,"title":"Radius Miles","type":"number"},"site_type":{"default":"ST","description":"ST=stream, LK=lake/reservoir, SP=spring, GW=well.","title":"Site Type","type":"string"},"max_results":{"default":50,"maximum":200,"minimum":1,"title":"Max Results","type":"integer"}},"required":["latitude","longitude"],"title":"sites_nearArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/historical_daily_values":{"post":{"operationId":"historical_daily_values","summary":"Recent daily-mean values for one USGS site and parameter (default: streamflow) — one value per","description":"Recent daily-mean values for one USGS site and parameter (default: streamflow) — one value per\n    calendar day going back up to a year, from USGS's daily-values service. Use for \"show the last 30 days\n    of flow on the Potomac\", \"daily gage height for the past two weeks\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_id":{"description":"USGS site number.","examples":["01646500"],"title":"Site Id","type":"string"},"days":{"default":30,"maximum":365,"minimum":1,"title":"Days","type":"integer"},"parameter_cd":{"default":"00060","description":"Parameter code; default 00060 (streamflow). 00065 = gage height.","title":"Parameter Cd","type":"string"}},"required":["site_id"],"title":"historical_daily_valuesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/flow_stats_context":{"post":{"operationId":"flow_stats_context","summary":"How today's reading at a site compares to that calendar day's historical percentiles (10th, 25th,","description":"How today's reading at a site compares to that calendar day's historical percentiles (10th, 25th,\n    50th/median, 75th, 90th) computed by USGS from its full period of record — \"is this river running high\n    or low for late September\". Not every site/parameter combination has published statistics; this tool\n    says so plainly rather than guessing. Use for \"is the Potomac running high for this time of year\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_id":{"description":"USGS site number.","examples":["01646500"],"title":"Site Id","type":"string"},"parameter_cd":{"default":"00060","description":"Parameter code; default 00060 (streamflow). Percentile statistics are published mainly for streamflow.","title":"Parameter Cd","type":"string"}},"required":["site_id"],"title":"flow_stats_contextArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/site_info":{"post":{"operationId":"site_info","summary":"A USGS monitoring station's metadata: name, coordinates, altitude, drainage area, county/state,","description":"A USGS monitoring station's metadata: name, coordinates, altitude, drainage area, county/state,\n    site type and time zone. No current readings — use current_conditions for those. Use for \"what river is\n    site 01646500 on\", \"how big is the watershed above this gauge\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_id":{"description":"USGS site number.","examples":["01646500"],"title":"Site Id","type":"string"}},"required":["site_id"],"title":"site_infoArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/parameter_glossary":{"post":{"operationId":"parameter_glossary","summary":"Glossary of USGS parameter codes — what each five/six-digit code measures and in what unit (00060","description":"Glossary of USGS parameter codes — what each five/six-digit code measures and in what unit (00060\n    streamflow, 00065 gage height, 00010 water temperature, and others actually seen on tested sites). Use\n    for \"what does parameter code 00065 mean\", \"what units is streamflow in\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A specific USGS parameter code, e.g. '00060'. Omit to list all covered codes.","title":"Code"}},"title":"parameter_glossaryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/unit_convert":{"post":{"operationId":"unit_convert","summary":"Convert between flow units (cfs/cms/gpm) or length units (ft/m, mi/km) — useful because USGS always","description":"Convert between flow units (cfs/cms/gpm) or length units (ft/m, mi/km) — useful because USGS always\n    reports in US customary units (cfs, ft). Use for \"convert 500 cfs to cubic meters per second\", \"how many\n    feet is 2 meters of gage height\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"value":{"description":"The number to convert.","title":"Value","type":"number"},"from_unit":{"description":"cfs, cms, gpm, ft, m, mi or km.","examples":["cfs"],"title":"From Unit","type":"string"},"to_unit":{"description":"cfs, cms, gpm, ft, m, mi or km.","examples":["cms"],"title":"To Unit","type":"string"}},"required":["value","from_unit","to_unit"],"title":"unit_convertArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}