{"openapi":"3.1.0","info":{"title":"Reef API","version":"0.1.0","description":"A fully local aquarium stocking and fish-care reference toolkit: species profiles for 36 freshwater and saltwater fish, a compatibility checker, stocking and tank-volume calculators, water-parameter guides, a nitrogen-cycling explainer, aquarium plant care, and a glossary.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://reef.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/reef/docs"},"termsOfService":"https://connectorbay.com/reef/terms"},"servers":[{"url":"https://reef.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/reef/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/fish_species_info":{"post":{"operationId":"fish_species_info","summary":"Full care profile for one of 36 common freshwater and saltwater aquarium species: minimum tank size,","description":"Full care profile for one of 36 common freshwater and saltwater aquarium species: minimum tank size,\n    temperament, water-parameter targets (pH/temperature), diet, and a care-level rating. Use for \"what does a\n    betta need\", \"tell me about neon tetras\". General guidance only — always research a specific species'\n    needs before purchase.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"Common or scientific name.","examples":["Betta","Neon Tetra","Yellow Tang"],"minLength":1,"title":"Name","type":"string"}},"required":["name"],"title":"fish_species_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/fish_search":{"post":{"operationId":"fish_search","summary":"Search the species reference by keyword across name, category (freshwater/saltwater), temperament,","description":"Search the species reference by keyword across name, category (freshwater/saltwater), temperament,\n    behavior tags, diet and notes. Use for \"peaceful schooling fish\", \"saltwater beginner fish\", \"algae\n    eaters\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Keyword to search across name, category, temperament, tags, diet and notes.","minLength":1,"title":"Query","type":"string"}},"required":["query"],"title":"fish_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/compatibility_check":{"post":{"operationId":"compatibility_check","summary":"Checks a list of species against each other for known-incompatible pairings: aggressive-vs-peaceful","description":"Checks a list of species against each other for known-incompatible pairings: aggressive-vs-peaceful\n    temperament clashes, fin-nippers paired with long-finned species, territorial species that generally need\n    their own tank, and freshwater/saltwater mismatches. Matches each species' own temperament/tag data —\n    genuine pairwise logic, not a static list of bad pairs. Use for \"can I keep a betta with tiger barbs\",\n    \"is my stocking list compatible\". Does not know your tank's size or decor — always research further\n    before stocking.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"species_list":{"description":"Two or more species names to check against each other.","examples":[["Betta","Tiger Barb"],["Neon Tetra","Cherry Barb","Corydoras"]],"items":{"type":"string"},"minItems":2,"title":"Species List","type":"array"}},"required":["species_list"],"title":"compatibility_checkArguments","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/stocking_calculator":{"post":{"operationId":"stocking_calculator","summary":"Applies the commonly-cited \"one inch of adult fish per gallon\" rule of thumb to a tank size and a","description":"Applies the commonly-cited \"one inch of adult fish per gallon\" rule of thumb to a tank size and a\n    stocking list of {name, quantity} entries. Use for \"is 20 gallons enough for 8 neon tetras and 6\n    corydoras\". This is a deliberately oversimplified guideline for small community freshwater fish only — it\n    ignores bioload, filtration capacity, adult body shape, and aggression/territoriality. Always research\n    further, and run compatibility_check, before finalizing a stocking plan.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"tank_gallons":{"description":"Tank size in US gallons.","exclusiveMinimum":0,"title":"Tank Gallons","type":"number"},"species_list":{"description":"Stocking list, each {\"name\": str, \"quantity\": int}.","examples":[[{"name":"Neon Tetra","quantity":8},{"name":"Corydoras","quantity":6}]],"items":{"additionalProperties":true,"type":"object"},"title":"Species List","type":"array"}},"required":["tank_gallons","species_list"],"title":"stocking_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/tank_size_calculator":{"post":{"operationId":"tank_size_calculator","summary":"Computes real US gallons (and liters) from tank dimensions in inches: cubic inches (L x W x H) / 231 =","description":"Computes real US gallons (and liters) from tank dimensions in inches: cubic inches (L x W x H) / 231 =\n    US gallons. Use for \"how many gallons is a 36x18x18 tank\". Actual water volume is somewhat less once\n    substrate, decor and headspace below the rim are accounted for.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"length_in":{"description":"Inside length, in inches.","exclusiveMinimum":0,"title":"Length In","type":"number"},"width_in":{"description":"Inside width, in inches.","exclusiveMinimum":0,"title":"Width In","type":"number"},"height_in":{"description":"Inside (water-line) height, in inches.","exclusiveMinimum":0,"title":"Height In","type":"number"}},"required":["length_in","width_in","height_in"],"title":"tank_size_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/water_parameter_guide":{"post":{"operationId":"water_parameter_guide","summary":"Target pH, temperature and hardness ranges for common aquarium setup types (community freshwater","description":"Target pH, temperature and hardness ranges for common aquarium setup types (community freshwater\n    tropical, goldfish/coldwater, African cichlid, planted tank, reef saltwater, fish-only saltwater). Use for\n    \"what pH does a reef tank need\", \"water parameters for African cichlids\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"setup_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"community_freshwater_tropical | goldfish_coldwater | african_cichlid | planted_tank | reef_saltwater | fish_only_saltwater. Omit to list all.","title":"Setup Type"}},"title":"water_parameter_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/cycling_guide":{"post":{"operationId":"cycling_guide","summary":"Explains the nitrogen cycle (ammonia to nitrite to nitrate), the bacteria that drive it, a typical","description":"Explains the nitrogen cycle (ammonia to nitrite to nitrate), the bacteria that drive it, a typical\n    fishless-cycling timeline (commonly cited at 4-6 weeks), and practical tips for cycling a new tank safely.\n    Use for \"how does the nitrogen cycle work\", \"how long does it take to cycle a tank\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"cycling_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/plant_care_guide":{"post":{"operationId":"plant_care_guide","summary":"Care needs for common aquarium plants (Java fern, Anubias, Amazon sword, Java moss, Vallisneria,","description":"Care needs for common aquarium plants (Java fern, Anubias, Amazon sword, Java moss, Vallisneria,\n    Cryptocoryne): light, CO2 and substrate needs, growth rate and difficulty. Use for \"how do I care for java\n    fern\", \"does anubias need CO2\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A specific plant to look up; omit to list all.","examples":["Java Fern","Anubias","Amazon Sword"],"title":"Name"}},"title":"plant_care_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/aquarium_glossary":{"post":{"operationId":"aquarium_glossary","summary":"Definitions of common aquarium-hobby terms (nitrogen cycle, biological filtration, live rock,","description":"Definitions of common aquarium-hobby terms (nitrogen cycle, biological filtration, live rock,\n    quarantine tank, fishless cycling, ammonia/nitrite/nitrate, GH/KH, specific gravity, bioload, ...). Use\n    for \"what's a quarantine tank\", \"what does KH mean\".","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":"aquarium_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}}}}