{"openapi":"3.1.0","info":{"title":"Terra Listens API","description":"Read-only access to your Terra Stations and the bird/tag detections they produce.\n\n**Auth.** Send `Authorization: Bearer <api_key>` on every request. Generate a key from the Developer section in the Terra Listens app on iOS or Android.\n\n**Scope.** Endpoints return data only for stations the authenticating account owns or has been shared into. Accounts with no Terra Station registered get a 403.\n\n**Lookback.** Bird detection history is capped at the most recent 30 days for every caller. Asking for older data is silently floored.\n\n**Rate limit.** 60 requests/min per API key. 429 with `Retry-After` when exceeded.","version":"1.0.0","contact":{"name":"Terra Listens Support","url":"https://terralistens.com/support"},"license":{"name":"Proprietary"}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key issued from the Terra Listens app Developer panel."}},"schemas":{"PublicStation":{"type":"object","description":"A Terra Station the caller has access to.","required":["stationId","alias"],"properties":{"stationId":{"type":"string","example":"0123BA68D74CEA21EE"},"alias":{"type":"string","example":"Backyard Feeder"},"lat":{"type":"number","nullable":true},"lon":{"type":"number","nullable":true},"online":{"type":"boolean"},"lastHeard":{"type":"integer","description":"Unix epoch seconds since last device check-in. 0 if never."},"streaming":{"type":"boolean"},"firmware":{"type":"string","nullable":true},"shared":{"type":"boolean","description":"True if this station was shared with the caller; false if owned."}}},"PublicDetection":{"type":"object","description":"One bird ID emitted by BirdNET on the station.","properties":{"id":{"type":"integer"},"commonName":{"type":"string","example":"Eastern Bluebird"},"scientificName":{"type":"string","example":"Sialia sialis"},"speciesCode":{"type":"string","nullable":true,"example":"easblu"},"confidence":{"type":"number","minimum":0,"maximum":1},"epoch":{"type":"integer","description":"Unix epoch seconds of detection."},"audioUrl":{"type":"string","nullable":true,"description":"3-second audio clip URL. May expire."},"notPredicted":{"type":"integer","description":"0 = real BirdNET prediction, 1 = non-bird category (frog, mammal, etc.) the user has opted in to surfacing."}}},"PublicYardEntry":{"type":"object","description":"One species in the station's yard list, with first-heard date and total count.","properties":{"commonName":{"type":"string"},"scientificName":{"type":"string","nullable":true},"count":{"type":"integer"},"firstDetected":{"type":"integer","description":"Unix epoch seconds of the first detection."},"imageUrl":{"type":"string","nullable":true}}},"PublicTag":{"type":"object","description":"A single radio-tag detection (BLE or UHF) at a station.","properties":{"tagId":{"type":"string"},"technology":{"type":"string","enum":["BLE","UHF"]},"species":{"type":"string","nullable":true},"epoch":{"type":"integer"},"lat":{"type":"number","nullable":true},"lon":{"type":"number","nullable":true},"rssi":{"type":"integer","nullable":true},"stationId":{"type":"string"}}}}},"paths":{"/stations":{"get":{"summary":"List your Terra Stations","tags":["stations"],"description":"All stations the authenticated account owns or has been shared into.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"stations":{"type":"array","items":{"$ref":"#/components/schemas/PublicStation"}}}}}}}}}},"/stations/{stationId}":{"get":{"summary":"Get details for one station","tags":["stations"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"stationId","required":true,"description":"Terra station ID (e.g. `0123BA68D74CEA21EE`)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"A Terra Station the caller has access to.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicStation"}}}}}}},"/stations/{stationId}/detections":{"get":{"summary":"Bird detections for a station","tags":["detections"],"description":"Predicted bird IDs ordered newest first. `days` (default 7, max 30 — server enforces a hard 30-day lookback clamp). Use `species` to filter to one common name.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":30,"default":7},"in":"query","name":"days","required":false},{"schema":{"type":"integer"},"in":"query","name":"sinceEpoch","required":false,"description":"Unix epoch seconds. Floored to 30 days ago if older."},{"schema":{"type":"integer"},"in":"query","name":"untilEpoch","required":false},{"schema":{"type":"integer","minimum":1,"maximum":5000,"default":200},"in":"query","name":"count","required":false},{"schema":{"type":"string"},"in":"query","name":"species","required":false},{"schema":{"type":"string"},"in":"path","name":"stationId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"detections":{"type":"array","items":{"$ref":"#/components/schemas/PublicDetection"}}}}}}}}}},"/stations/{stationId}/yard-list":{"get":{"summary":"Yard-list — first-heard per species","tags":["detections"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"year","required":false,"description":"`all` (default) or a 4-digit year."},{"schema":{"type":"string"},"in":"path","name":"stationId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"yardList":{"type":"array","items":{"$ref":"#/components/schemas/PublicYardEntry"}}}}}}}}}},"/stations/{stationId}/tags":{"get":{"summary":"Radio-tag detections (BLE + UHF) for a station","tags":["tags"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"stationId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"tags":{"type":"array","items":{"$ref":"#/components/schemas/PublicTag"}}}}}}}}}},"/stations/{stationId}/weather":{"get":{"summary":"Current weather at a station","tags":["weather"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"stationId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/stations/{stationId}/status":{"get":{"summary":"Live device status snapshot","tags":["stations"],"description":"Firmware version, wifi, audio levels, GPS, CPU — same fields the iOS Status tab uses.","parameters":[{"schema":{"type":"string"},"in":"path","name":"stationId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}}},"servers":[{"url":"https://api.clearlycrickets.io/api/v1","description":"Production"},{"url":"https://qa.api.clearlycrickets.io/api/v1","description":"QA"}]}