{"openapi":"3.1.0","info":{"title":"Flock API","version":"0.1.0","description":"A hand-curated backyard/common bird identification and reference guide covering 50+ North American, Indian and Brazilian species: field marks, habitat, behavior, song descriptions, feature-based matching, similar-species look-alikes, region/habitat listings, an attracting guide, and a birding glossary.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://flock.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/flock/docs"},"termsOfService":"https://connectorbay.com/flock/terms"},"servers":[{"url":"https://flock.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/flock/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/bird_info":{"post":{"operationId":"bird_info","summary":"Full profile for one bird: common and scientific name, size, key field marks, habitat, behavior, song/","description":"Full profile for one bird: common and scientific name, size, key field marks, habitat, behavior, song/\n    call description, region(s), and a conservation note if notable. Use for \"tell me about the Blue Jay\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"Common or scientific name.","examples":["American Robin","Indian Peafowl","Turdus migratorius"],"minLength":1,"title":"Name","type":"string"}},"required":["name"],"title":"bird_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/bird_search":{"post":{"operationId":"bird_search","summary":"Keyword search across bird name, field marks, habitat, colors and behavior. Use for \"which birds have a","description":"Keyword search across bird name, field marks, habitat, colors and behavior. Use for \"which birds have a\n    red crest\", \"birds found near wetlands\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Keyword to search across name, field marks, habitat, colors and behavior.","minLength":1,"title":"Query","type":"string"}},"required":["query"],"title":"bird_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/identify_by_features":{"post":{"operationId":"identify_by_features","summary":"Given loose descriptive filters (approximate size, colors seen, habitat, region), returns the best-","description":"Given loose descriptive filters (approximate size, colors seen, habitat, region), returns the best-\n    matching candidate birds ranked by how many filters they satisfy and how well colors overlap — real\n    multi-field scoring against the structured dataset, not a single lookup. Use for \"what bird is this: small\n    yellow bird at a backyard feeder\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"size":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Approximate size category: tiny, small, medium, or large.","title":"Size"},"colors":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Colors observed, e.g. ['red', 'black'].","title":"Colors"},"habitat":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Habitat type, e.g. urban/backyard, wetland, forest, grassland/open country, scrub/edge, coastal, farmland, mountain/foothill.","title":"Habitat"},"region":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"North America, India, Brazil, or Widespread.","title":"Region"}},"title":"identify_by_featuresArguments","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/birds_by_region":{"post":{"operationId":"birds_by_region","summary":"Lists birds commonly found in a region: North America, India, Brazil, or Widespread (species common","description":"Lists birds commonly found in a region: North America, India, Brazil, or Widespread (species common\n    across all three). Use for \"what birds might I see in my backyard in Brazil\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"North America, India, Brazil, or Widespread.","title":"Region","type":"string"}},"required":["region"],"title":"birds_by_regionArguments","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/birds_by_habitat":{"post":{"operationId":"birds_by_habitat","summary":"Lists birds commonly found in a given habitat type. Use for \"what birds live in wetlands\", \"forest","description":"Lists birds commonly found in a given habitat type. Use for \"what birds live in wetlands\", \"forest\n    birds\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"habitat":{"description":"urban/backyard, wetland, forest, grassland/open country, scrub/edge, coastal, farmland, or mountain/foothill.","title":"Habitat","type":"string"}},"required":["habitat"],"title":"birds_by_habitatArguments","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/similar_species":{"post":{"operationId":"similar_species","summary":"Other birds in the dataset commonly confused with a given one, and the key distinguishing features","description":"Other birds in the dataset commonly confused with a given one, and the key distinguishing features\n    between them (hand-authored per bird, where a well-known look-alike exists). Use for \"how do I tell a crow\n    from a raven\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"Common or scientific name of a bird in the dataset.","minLength":1,"title":"Name","type":"string"}},"required":["name"],"title":"similar_speciesArguments","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/birdsong_description":{"post":{"operationId":"birdsong_description","summary":"The onomatopoeic/descriptive call and song description for a bird, standalone for convenience. Use for","description":"The onomatopoeic/descriptive call and song description for a bird, standalone for convenience. Use for\n    \"what does a Northern Cardinal sound like\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"Common or scientific name.","minLength":1,"title":"Name","type":"string"}},"required":["name"],"title":"birdsong_descriptionArguments","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/attracting_guide":{"post":{"operationId":"attracting_guide","summary":"Practical tips for attracting and supporting backyard birds — feeder types, food, water, native plants","description":"Practical tips for attracting and supporting backyard birds — feeder types, food, water, native plants\n    — general reference content, optionally focused on one region's common species. Use for \"how do I attract\n    birds to my yard\", \"how do I attract hummingbirds\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"North America, India, or Brazil; omit for general tips only.","title":"Region"}},"title":"attracting_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/birdwatching_glossary":{"post":{"operationId":"birdwatching_glossary","summary":"Definitions of common birding terms (field mark, molt, raptor, passerine, migratory vs. resident, brood","description":"Definitions of common birding terms (field mark, molt, raptor, passerine, migratory vs. resident, brood\n    parasite, ...). Use for \"what's a passerine\", \"what does migratory 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":"birdwatching_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/random_bird":{"post":{"operationId":"random_bird","summary":"A random bird from the dataset — good for a \"bird of the day\" style prompt. Use for \"give me a random","description":"A random bird from the dataset — good for a \"bird of the day\" style prompt. Use for \"give me a random\n    bird\", \"bird of the day\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"seed":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Optional seed for a reproducible pick.","title":"Seed"}},"title":"random_birdArguments","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}}}}