{"openapi":"3.1.0","info":{"title":"Ripple API","version":"0.1.0","description":"A swimming pool water-chemistry reference and calculator: CDC/industry-verified ideal ranges, a real-geometry pool volume calculator, a general chemical dosing estimator, chemical-mixing safety warnings, troubleshooting, a testing-method reference, shock-treatment and seasonal guides, and a glossary — all local.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://ripple.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/ripple/docs"},"termsOfService":"https://connectorbay.com/ripple/terms"},"servers":[{"url":"https://ripple.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/ripple/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/ideal_range_reference":{"post":{"operationId":"ideal_range_reference","summary":"CDC/industry-verified ideal (and acceptable) ranges for pH, free chlorine, total alkalinity, cyanuric","description":"CDC/industry-verified ideal (and acceptable) ranges for pH, free chlorine, total alkalinity, cyanuric\n    acid, and calcium hardness, one parameter or the full set, each with why it matters and its source. Use for\n    \"what should pool pH be\", \"ideal free chlorine range\", \"what's a good cyanuric acid level\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"parameter":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"ph | free_chlorine | total_alkalinity | cyanuric_acid | calcium_hardness. Omit for all five.","title":"Parameter"}},"title":"ideal_range_referenceArguments","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/pool_volume_calculator":{"post":{"operationId":"pool_volume_calculator","summary":"Real pool volume in gallons and liters for a rectangular, circular, or oval pool, from its dimensions in","description":"Real pool volume in gallons and liters for a rectangular, circular, or oval pool, from its dimensions in\n    feet — handles a uniform depth or a shallow/deep-end pair (averaged). Use for \"how many gallons is my\n    16x32 pool with a 3 to 8 foot slope\", \"volume of a 24-foot round pool\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"shape":{"description":"rectangular | circular | oval","title":"Shape","type":"string"},"dimensions":{"additionalProperties":{"type":"number"},"description":"Dimensions in feet. Rectangular/oval: length_ft, width_ft, plus depth_ft (uniform) or shallow_depth_ft + deep_end_depth_ft. Circular: diameter_ft (or radius_ft), plus depth_ft or the shallow/deep pair.","examples":[{"deep_end_depth_ft":8,"length_ft":32,"shallow_depth_ft":3,"width_ft":16},{"depth_ft":4.5,"diameter_ft":24}],"title":"Dimensions","type":"object"}},"required":["shape","dimensions"],"title":"pool_volume_calculatorArguments","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/chemical_dosing_estimator":{"post":{"operationId":"chemical_dosing_estimator","summary":"A general, non-authoritative estimate of how much of a common chemical it takes to move one water-chemistry","description":"A general, non-authoritative estimate of how much of a common chemical it takes to move one water-chemistry\n    parameter from its current value to a target value, using standard per-10,000-gallon dosing figures —\n    always framed as a starting estimate: add gradually, retest before adding more, and follow the product\n    label. Use for \"how much chlorine to raise free chlorine by 2 ppm in a 15000 gallon pool\", \"how much\n    muriatic acid to lower my pH from 7.8 to 7.4\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"pool_gallons":{"description":"Total pool volume in US gallons.","exclusiveMinimum":0,"title":"Pool Gallons","type":"number"},"parameter":{"description":"ph | free_chlorine | total_alkalinity | cyanuric_acid | calcium_hardness","title":"Parameter","type":"string"},"current_value":{"description":"The parameter's current tested value.","title":"Current Value","type":"number"},"target_value":{"description":"The parameter's desired value.","title":"Target Value","type":"number"}},"required":["pool_gallons","parameter","current_value","target_value"],"title":"chemical_dosing_estimatorArguments","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/mixing_safety_warnings":{"post":{"operationId":"mixing_safety_warnings","summary":"The critical pool-chemical safety rules, verified against CDC guidance: never mix chlorine products with","description":"The critical pool-chemical safety rules, verified against CDC guidance: never mix chlorine products with\n    each other or with acid (toxic gas risk), always add chemical to water rather than water to chemical, store\n    incompatible chemicals separately and ventilated, and more — plus what to do if someone is exposed. Use\n    for \"can I mix bleach and muriatic acid\", \"is it safe to combine pool shock with algaecide\", \"how should I\n    store pool chemicals\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"mixing_safety_warningsArguments","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/troubleshooting_guide":{"post":{"operationId":"troubleshooting_guide","summary":"Troubleshooting for cloudy water, algae, a strong chlorine smell, and eye/skin irritation — including","description":"Troubleshooting for cloudy water, algae, a strong chlorine smell, and eye/skin irritation — including\n    the common myth-correction that a strong smell or irritated eyes usually mean too little effective chlorine\n    (combined chlorine/chloramines) or a pH problem, not \"too much chlorine\". Use for \"why is my pool cloudy\",\n    \"how do I get rid of algae\", \"why does my pool smell so strongly of chlorine\", \"why do my eyes sting after\n    swimming\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"issue":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"cloudy_water | algae | chlorine_smell | eye_skin_irritation. Omit to list all.","title":"Issue"}},"title":"troubleshooting_guideArguments","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/testing_method_guide":{"post":{"operationId":"testing_method_guide","summary":"Compares test strips, liquid (DPD) test kits, and digital meters/photometers for testing pool water —","description":"Compares test strips, liquid (DPD) test kits, and digital meters/photometers for testing pool water —\n    accuracy, best use case, and testing-frequency guidance for each, per CDC guidance. Use for \"test strips vs\n    liquid chlorine test\", \"most accurate way to test pool water\", \"how often should I test my pool\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"testing_method_guideArguments","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/shock_treatment_guide":{"post":{"operationId":"shock_treatment_guide","summary":"What 'shocking' a pool means (breakpoint chlorination), when it's typically done, and the general","description":"What 'shocking' a pool means (breakpoint chlorination), when it's typically done, and the general\n    approach and safety notes. Use for \"what does it mean to shock a pool\", \"when should I shock my pool\",\n    \"how long after shocking can I swim\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"shock_treatment_guideArguments","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/seasonal_guide":{"post":{"operationId":"seasonal_guide","summary":"General guidance for opening or closing a pool seasonally — the typical steps and what to watch for.","description":"General guidance for opening or closing a pool seasonally — the typical steps and what to watch for.\n    Use for \"how do I open my pool for summer\", \"steps to close my pool for winter\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"topic":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"opening | closing. Omit for both.","title":"Topic"}},"title":"seasonal_guideArguments","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/pool_glossary":{"post":{"operationId":"pool_glossary","summary":"Definitions of common pool water-chemistry terms (free chlorine, combined chlorine/chloramines, cyanuric","description":"Definitions of common pool water-chemistry terms (free chlorine, combined chlorine/chloramines, cyanuric\n    acid, total alkalinity, Langelier Saturation Index, breakpoint chlorination, DPD test, and more). Use for\n    \"what is combined chlorine\", \"what does the Langelier index mean\", \"what's a DPD test\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"term":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A specific term to look up; omit to list all.","title":"Term"}},"title":"pool_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}}}}