{
  "name": "oceansong",
  "description": "Real-time cetacean acoustic monitoring — 7 live hydrophone streams, 4 ML detection models, automatic recording with bioacoustic denoising.",
  "version": "2.0.0",
  "api_base": "https://api.oceansong.live",
  "docs": "https://api.oceansong.live/docs",
  "openapi": "https://api.oceansong.live/openapi.json",
  "websocket": "wss://api.oceansong.live/ws",
  "dashboard": "https://oceansong.live",
  "auth": "none",
  "rate_limits": {
    "note": "No formal rate limits. Be reasonable — this runs on a single server.",
    "recommended_polling": "10s for status, 30s for events"
  },

  "endpoints": {
    "summary": {
      "method": "GET",
      "path": "/summary",
      "description": "Quick situation report: streams online, total detections, active species, latest event. Start here.",
      "output_shape": {
        "streams_online": "int",
        "streams_total": "int",
        "total_detections": "int",
        "active_species": ["string"],
        "active_models": ["string"],
        "latest_detection": "event | null"
      }
    },
    "highlights": {
      "method": "GET",
      "path": "/highlights",
      "description": "Top detections and activity breakdown over a time window.",
      "params": {
        "hours": "int (default 24) — time window",
        "top": "int (default 5) — number of top detections"
      },
      "output_shape": {
        "period_hours": "int",
        "total_events": "int",
        "species_breakdown": {"species_name": "count"},
        "stream_breakdown": {"stream_id": "count"},
        "top_detections": ["event"],
        "latest_event": "event | null"
      }
    },
    "status": {
      "method": "GET",
      "path": "/status",
      "description": "Full telemetry for all streams: connection state, buffer levels, per-model scores, detection counts.",
      "output_shape": {
        "status": "string",
        "streams": [{
          "stream_id": "string",
          "connected": "bool",
          "buffer_seconds": "float",
          "last_scores": {"model_name": "float"},
          "last_detection": "ISO timestamp | null",
          "detections_1h": "int",
          "detections_24h": "int",
          "detections_7d": "int",
          "top_species": "string | null"
        }]
      }
    },
    "events": {
      "method": "GET",
      "path": "/events",
      "description": "Paginated detection events, newest first. Filterable.",
      "params": {
        "species": "humpback | orca | blue_whale | sperm_whale",
        "stream": "stream_id",
        "since": "ISO timestamp",
        "before": "ISO timestamp (for pagination)",
        "limit": "int (default 10, max 1000)"
      },
      "output_shape": {
        "events": ["event"],
        "has_more": "bool"
      }
    },
    "clip": {"method": "GET", "path": "/clips/{event_id}", "description": "Original FLAC audio"},
    "clip_mp3": {"method": "GET", "path": "/clips/{event_id}/mp3", "description": "MP3 for playback"},
    "clip_denoised": {"method": "GET", "path": "/clips/{event_id}/denoised", "description": "Denoised FLAC (ESP biodenoising)"},
    "clip_denoised_mp3": {"method": "GET", "path": "/clips/{event_id}/denoised/mp3", "description": "Denoised MP3"},
    "spectrogram": {"method": "GET", "path": "/spectrograms/{event_id}", "description": "Spectrogram PNG image"}
  },

  "event_shape": {
    "id": "int",
    "timestamp": "ISO 8601",
    "stream_id": "string",
    "species": "string (comma-separated if multiple)",
    "confidence": "float 0-1",
    "duration_seconds": "float | null",
    "has_denoised": "bool",
    "clip_path": "string (internal)",
    "spectrogram_path": "string (internal)"
  },

  "streams": {
    "orcasound-pt": {"name": "Port Townsend, WA", "models": ["humpback", "orca"], "depth": "surface"},
    "orcasound-sunset": {"name": "Sunset Bay, WA", "models": ["humpback", "orca"], "depth": "surface"},
    "orcasound-nsjc": {"name": "N. San Juan Channel, WA", "models": ["humpback", "orca"], "depth": "surface"},
    "orcasound-mast": {"name": "MaST Center, WA", "models": ["humpback", "orca"], "depth": "surface"},
    "orcasound-andrews": {"name": "Andrews Bay, WA", "models": ["humpback", "orca"], "depth": "surface"},
    "mbari-mars": {"name": "Monterey Bay, CA", "models": ["humpback", "blue_whale", "sperm_whale"], "depth": "900m"},
    "simres": {"name": "Saturna Island, BC", "models": ["humpback", "orca"], "depth": "surface"}
  },

  "species_info": {
    "humpback": {"model": "Google TF Hub humpback_whale/1", "threshold": 0.90, "peak_season": "Jun-Oct"},
    "orca": {"model": "orcAI (ETH Zurich)", "threshold": 0.50, "peak_season": "Jun-Sep (SRKW), year-round (Bigg's)", "note": "Trained on Icelandic orcas — may miss PNW populations"},
    "blue_whale": {"model": "MBARI ResNet50 A-call", "threshold": 0.70, "peak_season": "Jul-Oct"},
    "sperm_whale": {"model": "Spectrogram click train detector", "threshold": 0.70, "peak_season": "year-round at MBARI"}
  },

  "recommended_queries": {
    "quick_check": "GET /summary",
    "todays_best": "GET /highlights?hours=24&top=5",
    "this_weeks_activity": "GET /highlights?hours=168&top=10",
    "orca_watch": "GET /events?species=orca&limit=20",
    "mbari_deep_ocean": "GET /events?stream=mbari-mars&limit=20",
    "high_confidence_only": "GET /events?limit=50 (then filter client-side for confidence > 0.95)",
    "download_best_clip": "GET /highlights?hours=24&top=1, then GET /clips/{id}/denoised/mp3"
  },

  "common_workflows": [
    {
      "name": "Daily monitoring report",
      "steps": [
        "GET /summary — check streams online, latest detection",
        "GET /highlights?hours=24 — species breakdown, top detections",
        "For each top detection: GET /spectrograms/{id} to visually inspect"
      ]
    },
    {
      "name": "Investigate specific species",
      "steps": [
        "GET /events?species=orca&limit=20 — recent orca events",
        "GET /clips/{id}/denoised/mp3 — listen to denoised audio",
        "GET /spectrograms/{id} — visual inspection"
      ]
    },
    {
      "name": "Compare streams",
      "steps": [
        "GET /status — get all streams with detection counts",
        "Compare detections_24h across streams",
        "Drill into active stream: GET /events?stream={id}&limit=10"
      ]
    },
    {
      "name": "Download dataset",
      "steps": [
        "GET /events?species=humpback&limit=1000 — get all humpback events",
        "For each event: GET /clips/{id} for FLAC, GET /clips/{id}/denoised for clean version",
        "GET /spectrograms/{id} for visual labels"
      ]
    }
  ]
}