{"openapi":"3.1.0","info":{"title":"eBird (BYOK) API","version":"0.1.0","description":"eBird (BYOK) lets an AI assistant read your own eBird data through the eBird API with a key you supply (eBird API key). Read-only: 11 tools (recent_observations, recent_notable_observations, recent_species_observations, nearby_observations, nearest_species_observations, historic_observations, list_hotspots, nearby_hotspots, get_hotspot_info, get_region_info, list_subregions). The BYOK key travels...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-ebird.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-ebird/docs"},"termsOfService":"https://connectorbay.com/byok-ebird/terms"},"servers":[{"url":"https://byok-ebird.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-ebird/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/recent_observations":{"post":{"operationId":"recent_observations","summary":"List the most recent observation of each bird species in a region (up to 30 days back). Use for \"What birds were seen re","description":"List the most recent observation of each bird species in a region (up to 30 days back). Use for \"What birds were seen recently in New York state\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region_code":{"description":"eBird region code: a country (US), state or province (US-NY), county (US-NY-109) or a hotspot location id (L99381).","maxLength":30,"title":"Region Code","type":"string"},"back":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":14,"description":"How many days back to look, 1 to 30.","title":"Back"},"cat":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only this taxonomic category, for example species.","title":"Cat"},"hotspot":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to use only observations from hotspots.","title":"Hotspot"},"max_results":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Return at most this many observations (1 to 10000).","title":"Max Results"},"species_locale":{"anyOf":[{"maxLength":8,"type":"string"},{"type":"null"}],"default":"en","description":"Language code for common names, for example en or es.","title":"Species Locale"}},"required":["region_code"],"title":"recent_observationsArguments","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/recent_notable_observations":{"post":{"operationId":"recent_notable_observations","summary":"List recent notable (rare or unusual) bird observations in a region (up to 30 days back). Use for \"Which rare birds were","description":"List recent notable (rare or unusual) bird observations in a region (up to 30 days back). Use for \"Which rare birds were reported in California this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region_code":{"description":"eBird region code: a country (US), state or province (US-NY), county (US-NY-109) or a hotspot location id (L99381).","maxLength":30,"title":"Region Code","type":"string"},"back":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":14,"description":"How many days back to look, 1 to 30.","title":"Back"},"hotspot":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to use only observations from hotspots.","title":"Hotspot"},"max_results":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Return at most this many observations (1 to 10000).","title":"Max Results"},"detail":{"anyOf":[{"enum":["simple","full"],"type":"string"},{"type":"null"}],"default":"simple","description":"simple for a subset of fields, full for all.","title":"Detail"}},"required":["region_code"],"title":"recent_notable_observationsArguments","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/recent_species_observations":{"post":{"operationId":"recent_species_observations","summary":"List recent observations of one species in a region, one per location (up to 30 days back). Use for \"Where was a Canada ","description":"List recent observations of one species in a region, one per location (up to 30 days back). Use for \"Where was a Canada Goose seen recently in New York\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region_code":{"description":"eBird region code: a country (US), state or province (US-NY), county (US-NY-109) or a hotspot location id (L99381).","maxLength":30,"title":"Region Code","type":"string"},"species_code":{"description":"eBird species code, usually six letters, for example cangoo for Canada Goose.","maxLength":20,"title":"Species Code","type":"string"},"back":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":14,"description":"How many days back to look, 1 to 30.","title":"Back"},"hotspot":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to use only observations from hotspots.","title":"Hotspot"},"max_results":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Return at most this many observations (1 to 10000).","title":"Max Results"}},"required":["region_code","species_code"],"title":"recent_species_observationsArguments","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/nearby_observations":{"post":{"operationId":"nearby_observations","summary":"List recent bird observations within a radius (up to 50 km) of coordinates, newest first by default. Use for \"What birds","description":"List recent bird observations within a radius (up to 50 km) of coordinates, newest first by default. Use for \"What birds have been seen near 42.46,-76.51 in the last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"lat":{"description":"Latitude, -90 to 90, to two decimal places.","maximum":90,"minimum":-90,"title":"Lat","type":"number"},"lng":{"description":"Longitude, -180 to 180, to two decimal places.","maximum":180,"minimum":-180,"title":"Lng","type":"number"},"dist":{"anyOf":[{"maximum":50,"minimum":0,"type":"integer"},{"type":"null"}],"default":25,"description":"Search radius in kilometres, 0 to 50.","title":"Dist"},"back":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":14,"description":"How many days back to look, 1 to 30.","title":"Back"},"hotspot":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to use only observations from hotspots.","title":"Hotspot"},"max_results":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Return at most this many observations (1 to 10000).","title":"Max Results"},"sort":{"anyOf":[{"enum":["date","species"],"type":"string"},{"type":"null"}],"default":"date","description":"Order by date (most recent first) or species (taxonomic).","title":"Sort"}},"required":["lat","lng"],"title":"nearby_observationsArguments","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/nearest_species_observations":{"post":{"operationId":"nearest_species_observations","summary":"Find the nearest places where a species was seen recently, from coordinates. Use for \"Where is the nearest recent Barn S","description":"Find the nearest places where a species was seen recently, from coordinates. Use for \"Where is the nearest recent Barn Swallow sighting to 42.46,-76.51\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"species_code":{"description":"eBird species code, usually six letters, for example cangoo for Canada Goose.","maxLength":20,"title":"Species Code","type":"string"},"lat":{"description":"Latitude, -90 to 90, to two decimal places.","maximum":90,"minimum":-90,"title":"Lat","type":"number"},"lng":{"description":"Longitude, -180 to 180, to two decimal places.","maximum":180,"minimum":-180,"title":"Lng","type":"number"},"back":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":14,"description":"How many days back to look, 1 to 30.","title":"Back"},"dist":{"anyOf":[{"maximum":50,"minimum":0,"type":"integer"},{"type":"null"}],"default":25,"description":"Search radius in kilometres, 0 to 50.","title":"Dist"},"hotspot":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to use only observations from hotspots.","title":"Hotspot"},"max_results":{"anyOf":[{"maximum":3000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Return at most this many observations (1 to 3000).","title":"Max Results"}},"required":["species_code","lat","lng"],"title":"nearest_species_observationsArguments","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/historic_observations":{"post":{"operationId":"historic_observations","summary":"List the birds seen in a region on a past date, one observation per species. Use for \"What birds were seen in New York o","description":"List the birds seen in a region on a past date, one observation per species. Use for \"What birds were seen in New York on 2024-05-17\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region_code":{"description":"eBird region code: a country (US), state or province (US-NY), county (US-NY-109) or a hotspot location id (L99381).","maxLength":30,"title":"Region Code","type":"string"},"year":{"description":"Year, 1800 to the present.","maximum":2100,"minimum":1800,"title":"Year","type":"integer"},"month":{"description":"Month number, 1 to 12.","maximum":12,"minimum":1,"title":"Month","type":"integer"},"day":{"description":"Day of the month, 1 to 31.","maximum":31,"minimum":1,"title":"Day","type":"integer"},"hotspot":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to use only observations from hotspots.","title":"Hotspot"},"max_results":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Return at most this many observations (1 to 10000).","title":"Max Results"},"rank":{"anyOf":[{"enum":["mrec","create"],"type":"string"},{"type":"null"}],"default":"mrec","description":"mrec for the latest observation of the day, create for the first added.","title":"Rank"}},"required":["region_code","year","month","day"],"title":"historic_observationsArguments","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_hotspots":{"post":{"operationId":"list_hotspots","summary":"List the birding hotspots of a region, optionally only those visited in the last N days. Use for \"Which birding hotspots","description":"List the birding hotspots of a region, optionally only those visited in the last N days. Use for \"Which birding hotspots are in Tompkins County, New York\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region_code":{"description":"eBird region code: a country (US), state or province (US-NY), county (US-NY-109) or a hotspot location id (L99381).","maxLength":30,"title":"Region Code","type":"string"},"back":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only hotspots visited within this many days, 1 to 30.","title":"Back"},"fmt":{"anyOf":[{"const":"json","type":"string"},{"type":"null"}],"default":"json","description":"Response format; json is required here.","title":"Fmt"}},"required":["region_code"],"title":"list_hotspotsArguments","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/nearby_hotspots":{"post":{"operationId":"nearby_hotspots","summary":"List birding hotspots within a radius (up to 500 km) of coordinates. Use for \"Which birding hotspots are near 42.46,-76.","description":"List birding hotspots within a radius (up to 500 km) of coordinates. Use for \"Which birding hotspots are near 42.46,-76.51\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"lat":{"description":"Latitude, -90 to 90, to two decimal places.","maximum":90,"minimum":-90,"title":"Lat","type":"number"},"lng":{"description":"Longitude, -180 to 180, to two decimal places.","maximum":180,"minimum":-180,"title":"Lng","type":"number"},"dist":{"anyOf":[{"maximum":500,"minimum":0,"type":"integer"},{"type":"null"}],"default":25,"description":"Search radius in kilometres, 0 to 500.","title":"Dist"},"back":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only hotspots visited within this many days, 1 to 30.","title":"Back"},"fmt":{"anyOf":[{"const":"json","type":"string"},{"type":"null"}],"default":"json","description":"Response format; json is required here.","title":"Fmt"}},"required":["lat","lng"],"title":"nearby_hotspotsArguments","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_hotspot_info":{"post":{"operationId":"get_hotspot_info","summary":"Get the name, coordinates, country and region of one hotspot by its location id. Use for \"Give me the details of hotspot","description":"Get the name, coordinates, country and region of one hotspot by its location id. Use for \"Give me the details of hotspot L99381\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"loc_id":{"description":"eBird hotspot location id such as L99381 (private locations are not found).","maxLength":20,"title":"Loc Id","type":"string"}},"required":["loc_id"],"title":"get_hotspot_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/get_region_info":{"post":{"operationId":"get_region_info","summary":"Get the name, type, parent regions and bounding box of an eBird region code. Use for \"What region is the eBird code CA-B","description":"Get the name, type, parent regions and bounding box of an eBird region code. Use for \"What region is the eBird code CA-BC-GV\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region_code":{"description":"eBird region code: a country (US), state or province (US-NY), county (US-NY-109) or a hotspot location id (L99381).","maxLength":30,"title":"Region Code","type":"string"},"region_name_format":{"anyOf":[{"enum":["detailed","detailednoqual","full","namequal","nameonly","revdetailed"],"type":"string"},{"type":"null"}],"default":"full","description":"Name style: detailed, detailednoqual, full, namequal, nameonly or revdetailed.","title":"Region Name Format"}},"required":["region_code"],"title":"get_region_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/list_subregions":{"post":{"operationId":"list_subregions","summary":"List the sub-regions (states or counties) of a country or region with their codes. Use for \"What are the county codes in","description":"List the sub-regions (states or counties) of a country or region with their codes. Use for \"What are the county codes in Nevada\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region_type":{"description":"Type of sub-region to list: country, subnational1 or subnational2.","enum":["country","subnational1","subnational2"],"title":"Region Type","type":"string"},"parent_region_code":{"description":"Country or state code, or 'world'; for example US-NV or US.","maxLength":30,"title":"Parent Region Code","type":"string"},"fmt":{"anyOf":[{"const":"json","type":"string"},{"type":"null"}],"default":"json","description":"Response format; json is required here.","title":"Fmt"}},"required":["region_type","parent_region_code"],"title":"list_subregionsArguments","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}}}}