{"openapi":"3.1.0","info":{"title":"Grotto API","version":"0.1.0","description":"A fully local caving/speleology reference and safety connector: cave formation types, a speleothem reference, caving safety fundamentals, equipment basics, cave wildlife/ecology (bats and white-nose syndrome), minimal-impact conservation ethics, caving disciplines, and a glossary.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://grotto.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/grotto/docs"},"termsOfService":"https://connectorbay.com/grotto/terms"},"servers":[{"url":"https://grotto.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/grotto/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/cave_formation_type_info":{"post":{"operationId":"cave_formation_type_info","summary":"How a major cave type forms and where it's found — limestone/karst (solutional) caves, lava tubes,","description":"How a major cave type forms and where it's found — limestone/karst (solutional) caves, lava tubes,\n    sea caves, and ice/glacier caves. Use for \"how do lava tubes form\", \"what is a karst cave\", \"how do sea\n    caves form\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"A cave formation type's name or alias.","examples":["limestone cave","karst","lava tube","sea cave","ice cave"],"title":"Name","type":"string"}},"required":["name"],"title":"cave_formation_type_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/speleothem_info":{"post":{"operationId":"speleothem_info","summary":"One cave mineral formation (speleothem)'s description and how it forms — stalactite, stalagmite,","description":"One cave mineral formation (speleothem)'s description and how it forms — stalactite, stalagmite,\n    column, soda straw, flowstone, draperies/curtains, helictite, cave popcorn, rimstone, or cave pearl.\n    Use for \"what is a stalactite\", \"how do helictites form\", \"what's the difference between a stalactite\n    and a stalagmite\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"A speleothem (cave formation) name or alias.","examples":["stalactite","stalagmite","flowstone","soda straw","helictite"],"title":"Name","type":"string"}},"required":["name"],"title":"speleothem_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/speleothem_search":{"post":{"operationId":"speleothem_search","summary":"Search all speleothems in this connector's data by partial name, alias, or description text. Use for","description":"Search all speleothems in this connector's data by partial name, alias, or description text. Use for\n    \"which cave formations grow upward\", \"formations that form from dripping water\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Partial name, alias, or a word from a speleothem's description.","minLength":1,"title":"Query","type":"string"}},"required":["query"],"title":"speleothem_searchArguments","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/safety_fundamentals_guide":{"post":{"operationId":"safety_fundamentals_guide","summary":"Core caving safety fundamentals — never cave alone (the buddy system, group of four or more), leave","description":"Core caving safety fundamentals — never cave alone (the buddy system, group of four or more), leave\n    a trip plan and return time with someone outside the cave, carry at least three independent light\n    sources per person, wear a helmet, dress for cold and abrasion, match the trip to the group's training,\n    and check flood risk before entering. General safety information, not a substitute for hands-on\n    training. Use for \"how many lights do I need caving\", \"what's the buddy system in caving\", \"caving\n    safety basics\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"safety_fundamentals_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/equipment_guide":{"post":{"operationId":"equipment_guide","summary":"Core caving equipment — helmet, headlamp plus backup lights, clothing and footwear, gloves and","description":"Core caving equipment — helmet, headlamp plus backup lights, clothing and footwear, gloves and\n    knee/elbow pads, first aid and signaling gear, and vertical (SRT) gear — one item or the full list. Use\n    for \"what gear do I need for caving\", \"how many light sources should I carry\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"item":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"helmet | headlamp_and_backup_lights | clothing_and_footwear | gloves_and_kneepads | first_aid_and_signaling | vertical_gear. Omit to list all.","title":"Item"}},"title":"equipment_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/bat_and_wildlife_guide":{"post":{"operationId":"bat_and_wildlife_guide","summary":"Cave wildlife and ecology, centered on white-nose syndrome — the real, well-documented fungal","description":"Cave wildlife and ecology, centered on white-nose syndrome — the real, well-documented fungal\n    disease (Pseudogymnoascus destructans) that has killed millions of North American bats since 2006 —\n    why cavers must not disturb hibernating bat colonies or posted closures, gear-decontamination guidance,\n    and general cave ecology (troglobites, troglophiles, trogloxenes, and the role of bat guano in the cave\n    food web). Use for \"what is white-nose syndrome\", \"why shouldn't I disturb bats in a cave\", \"what is a\n    troglobite\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"bat_and_wildlife_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/conservation_ethics_guide":{"post":{"operationId":"conservation_ethics_guide","summary":"Minimal-impact caving principles: take only pictures and leave only footprints, never touch","description":"Minimal-impact caving principles: take only pictures and leave only footprints, never touch\n    speleothems (skin oils halt or discolor their growth), protect cave water from contamination, respect\n    wildlife and seasonal closures, and minimize your party's overall footprint. Use for \"why shouldn't I\n    touch cave formations\", \"leave no trace caving\", \"cave conservation rules\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"conservation_ethics_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/caving_types_guide":{"post":{"operationId":"caving_types_guide","summary":"The three main caving disciplines — horizontal/general caving, vertical/rope (SRT) caving, and cave","description":"The three main caving disciplines — horizontal/general caving, vertical/rope (SRT) caving, and cave\n    diving. Cave diving is explicitly flagged as requiring specialized certification (NSS-CDS or NACD\n    training) well beyond ordinary open-water scuba, never something to attempt casually. Use for \"what's\n    vertical caving\", \"do I need certification to cave dive\", \"what's the difference between caving and cave\n    diving\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"horizontal | vertical | cave_diving. Omit to list all three.","title":"Type"}},"title":"caving_types_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/caving_glossary":{"post":{"operationId":"caving_glossary","summary":"Definitions of core caving and speleology terms — speleology, karst, speleothem, sump, breakdown,","description":"Definitions of core caving and speleology terms — speleology, karst, speleothem, sump, breakdown,\n    pitch, squeeze, guano, troglobite, troglophile, trogloxene, grotto, wild cave, and spelunker. Use for\n    \"what does sump mean\", \"what's a troglobite\", \"what's a grotto in caving\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"term":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A specific caving term to look up; omit to list all.","examples":["speleology","karst","sump","breakdown"],"title":"Term"}},"title":"caving_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}}}}