{"openapi":"3.1.0","info":{"title":"USGS Water Data (BYOK) API","version":"0.1.0","description":"USGS Water Data (BYOK) lets an AI assistant read your own USGS Water Data data through the USGS Water Data API with a key you supply (USGS Water Data API key). Read-only: 7 tools (list_monitoring_locations, get_monitoring_location, list_time_series_metadata, list_daily_values, list_latest_daily_values, list_latest_continuous_values, list_field_measurements). The BYOK key travels with each...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-usgs-waterdata.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-usgs-waterdata/docs"},"termsOfService":"https://connectorbay.com/byok-usgs-waterdata/terms"},"servers":[{"url":"https://byok-usgs-waterdata.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-usgs-waterdata/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_monitoring_locations":{"post":{"operationId":"list_monitoring_locations","summary":"List USGS monitoring locations (stream gages, wells, lakes) filtered by state, site type, county or HUC, with name, type","description":"List USGS monitoring locations (stream gages, wells, lakes) filtered by state, site type, county or HUC, with name, type, elevation and drainage area. Use for \"Which stream gages does USGS have in Wisconsin\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state_name":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Full state or territory name, for example Wisconsin.","title":"State Name"},"site_type":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Site type name, for example Stream, Well, Lake, Reservoir, Impoundment or Spring.","title":"Site Type"},"county_name":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"County name, for example Dane County.","title":"County Name"},"hydrologic_unit_code":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Hydrologic unit code (HUC) of the watershed.","title":"Hydrologic Unit Code"},"bbox":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Bounding box as west,south,east,north longitude and latitude in degrees, for example -90.2,42.6,-88.7,43.2.","title":"Bbox"},"skip_geometry":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"True to leave out coordinates of each feature (smaller answer).","title":"Skip Geometry"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Maximum features to return (1 to 50).","title":"Limit"}},"title":"list_monitoring_locationsArguments","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/get_monitoring_location":{"post":{"operationId":"get_monitoring_location","summary":"Get one USGS monitoring location by its id: name, type, state, county, elevation and drainage area. Use for \"What is USG","description":"Get one USGS monitoring location by its id: name, type, state, county, elevation and drainage area. Use for \"What is USGS site 02238500\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Monitoring location id, for example USGS-02238500.","maxLength":40,"title":"Id","type":"string"},"skip_geometry":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"True to leave out coordinates of each feature (smaller answer).","title":"Skip Geometry"}},"required":["id"],"title":"get_monitoring_locationArguments","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/list_time_series_metadata":{"post":{"operationId":"list_time_series_metadata","summary":"List which measurements a location records (parameter, statistic, begin and end of the record) to discover what to reque","description":"List which measurements a location records (parameter, statistic, begin and end of the record) to discover what to request next. Use for \"What does USGS site 02238500 measure\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"monitoring_location_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Monitoring location id: agency code, a hyphen and the site number, for example USGS-02238500.","title":"Monitoring Location Id"},"parameter_code":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Five-digit USGS parameter code, for example 00060 for streamflow in cubic feet per second, 00065 for gage height or 00010 for water temperature.","title":"Parameter Code"},"statistic_id":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Statistic code: 00001 maximum, 00002 minimum, 00003 mean.","title":"Statistic Id"},"parameter_name":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Parameter name, for example Discharge.","title":"Parameter Name"},"skip_geometry":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"True to leave out coordinates of each feature (smaller answer).","title":"Skip Geometry"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Maximum features to return (1 to 50).","title":"Limit"}},"title":"list_time_series_metadataArguments","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/list_daily_values":{"post":{"operationId":"list_daily_values","summary":"List daily values (mean, minimum or maximum per day) for a location and parameter over a time range, such as daily mean ","description":"List daily values (mean, minimum or maximum per day) for a location and parameter over a time range, such as daily mean streamflow. Use for \"What was the daily mean streamflow at USGS-02238500 over the last 7 days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"monitoring_location_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Monitoring location id: agency code, a hyphen and the site number, for example USGS-02238500.","title":"Monitoring Location Id"},"parameter_code":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Five-digit USGS parameter code, for example 00060 for streamflow in cubic feet per second, 00065 for gage height or 00010 for water temperature.","title":"Parameter Code"},"statistic_id":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Statistic code: 00001 maximum, 00002 minimum, 00003 mean.","title":"Statistic Id"},"time":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Date, interval or duration to include: 2026-09-01, 2026-09-01T00:00:00Z/2026-09-30T00:00:00Z, '2026-09-01/..' or an ISO 8601 duration such as P7D for the last 7 days.","title":"Time"},"approval_status":{"anyOf":[{"enum":["Approved","Provisional"],"type":"string"},{"type":"null"}],"default":null,"description":"Approved (reviewed) or Provisional (subject to revision).","title":"Approval Status"},"skip_geometry":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"True to leave out coordinates of each feature (smaller answer).","title":"Skip Geometry"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Maximum features to return (1 to 50).","title":"Limit"}},"title":"list_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/list_latest_daily_values":{"post":{"operationId":"list_latest_daily_values","summary":"List the most recent daily value of each time series for a location or parameter. Use for \"What is the latest daily valu","description":"List the most recent daily value of each time series for a location or parameter. Use for \"What is the latest daily value recorded at USGS-02238500\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"monitoring_location_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Monitoring location id: agency code, a hyphen and the site number, for example USGS-02238500.","title":"Monitoring Location Id"},"parameter_code":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Five-digit USGS parameter code, for example 00060 for streamflow in cubic feet per second, 00065 for gage height or 00010 for water temperature.","title":"Parameter Code"},"statistic_id":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Statistic code: 00001 maximum, 00002 minimum, 00003 mean.","title":"Statistic Id"},"approval_status":{"anyOf":[{"enum":["Approved","Provisional"],"type":"string"},{"type":"null"}],"default":null,"description":"Approved (reviewed) or Provisional (subject to revision).","title":"Approval Status"},"skip_geometry":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"True to leave out coordinates of each feature (smaller answer).","title":"Skip Geometry"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Maximum features to return (1 to 50).","title":"Limit"}},"title":"list_latest_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/list_latest_continuous_values":{"post":{"operationId":"list_latest_continuous_values","summary":"List the latest sensor reading (typically every 15 minutes) of each continuous time series for a location or parameter. ","description":"List the latest sensor reading (typically every 15 minutes) of each continuous time series for a location or parameter. Use for \"What is the current gage height at USGS-02238500\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"monitoring_location_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Monitoring location id: agency code, a hyphen and the site number, for example USGS-02238500.","title":"Monitoring Location Id"},"parameter_code":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Five-digit USGS parameter code, for example 00060 for streamflow in cubic feet per second, 00065 for gage height or 00010 for water temperature.","title":"Parameter Code"},"statistic_id":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Statistic code: 00001 maximum, 00002 minimum, 00003 mean.","title":"Statistic Id"},"approval_status":{"anyOf":[{"enum":["Approved","Provisional"],"type":"string"},{"type":"null"}],"default":null,"description":"Approved (reviewed) or Provisional (subject to revision).","title":"Approval Status"},"skip_geometry":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"True to leave out coordinates of each feature (smaller answer).","title":"Skip Geometry"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Maximum features to return (1 to 50).","title":"Limit"}},"title":"list_latest_continuous_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/list_field_measurements":{"post":{"operationId":"list_field_measurements","summary":"List discrete in-person field measurements such as gage height, discharge and groundwater level for a location. Use for ","description":"List discrete in-person field measurements such as gage height, discharge and groundwater level for a location. Use for \"What groundwater level readings were measured at USGS site 425654089200901\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"monitoring_location_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Monitoring location id: agency code, a hyphen and the site number, for example USGS-02238500.","title":"Monitoring Location Id"},"parameter_code":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Five-digit USGS parameter code, for example 00060 for streamflow in cubic feet per second, 00065 for gage height or 00010 for water temperature.","title":"Parameter Code"},"time":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Date, interval or duration to include: 2026-09-01, 2026-09-01T00:00:00Z/2026-09-30T00:00:00Z, '2026-09-01/..' or an ISO 8601 duration such as P7D for the last 7 days.","title":"Time"},"approval_status":{"anyOf":[{"enum":["Approved","Provisional"],"type":"string"},{"type":"null"}],"default":null,"description":"Approved (reviewed) or Provisional (subject to revision).","title":"Approval Status"},"skip_geometry":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"True to leave out coordinates of each feature (smaller answer).","title":"Skip Geometry"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Maximum features to return (1 to 50).","title":"Limit"}},"title":"list_field_measurementsArguments","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}}}}