Developer Reference

API Documentation

The Wild Echo API gives you programmatic access to AI-powered biodiversity detection, ecosystem health scoring, and compliance reporting.

Overview

Base URL	`https://api.wildecho.app`
Format	JSON (responses) · multipart/form-data (audio uploads)
Protocol	HTTPS only
Version	v1 (current)

Authentication

Pass your API key in the X-Wild-Echo-Key header with every request that requires auth.

curl -H "X-Wild-Echo-Key: your-api-key" https://api.wildecho.app/api/status

API keys are issued when you subscribe to a plan. Keep your key secure — treat it like a password.

Rate Limits

🌱 Free

3 analyses / day
Demo endpoints only

🚜 Farmer

500 analyses / month
Full API access

🏢 Enterprise

Unlimited
Priority processing

When rate limited, the API returns 429 Too Many Requests with a Retry-After header.

Endpoints

POST /api/demo/analyze

Analyse an audio recording for species detection, ecosystem health scoring, and invasive/threatened species alerts.

Request

Parameter	Type	Required	Description
audio	file	✓	Audio file (MP3, WAV, M4A, OGG, FLAC). Max 50MB.
site_name	string	—	Site identifier for logging
lat	float	—	Latitude (improves accuracy)
lon	float	—	Longitude (improves accuracy)

Example

curl -X POST https://api.wildecho.app/api/demo/analyze \
  -H "X-Wild-Echo-Key: your-api-key" \
  -F "audio=@recording.mp3" \
  -F "site_name=Dandenong Ranges Station"

Response

{
  "status": "ok",
  "site": "Dandenong Ranges Station",
  "duration_seconds": 30,
  "health_score": 71,
  "ecosystem_health": "Good",
  "soundscape_diversity_index": 2.34,
  "dominant_frequency_hz": 4200,
  "detections": [
    {
      "species_common": "Laughing Kookaburra",
      "species_scientific": "Dacelo novaeguineae",
      "confidence": 0.94,
      "is_invasive": false,
      "is_threatened": false
    }
  ],
  "alerts": [],
  "credits": {
    "annual_low": 4200,
    "annual_high": 8800,
    "credit_value": 6500
  }
}

POST /api/insect/analyze

Run the insect detection suite — European wasp, Asian honey bee, varroa mite (bee hive health), fire ant, plague locust, and Queensland fruit fly detection.

Example

curl -X POST https://api.wildecho.app/api/insect/analyze \
  -H "X-Wild-Echo-Key: your-api-key" \
  -F "audio=@hive_recording.wav"

Response

{
  "status": "ok",
  "varroa": {"detected": false, "confidence": 0.12, "hive_status": "healthy"},
  "european_wasp": [{"detected": false, "confidence": 0.04}],
  "asian_honey_bee": {"detected": false, "confidence": 0.08},
  "fire_ant": [{"detected": false, "confidence": 0.02}],
  "locust": [{"detected": false, "confidence": 0.01}],
  "qff": {"detected": false, "confidence": 0.05},
  "cicada": {"detected": true, "confidence": 0.87},
  "cricket": {"detected": true, "confidence": 0.73}
}

GET /api/status

Health check. No authentication required.

curl https://api.wildecho.app/api/status

{"status": "ok", "version": "1.0", "birdnet": "available", "timestamp": "2026-04-20T06:00:00Z"}

GET /api/leaderboard

Community detection leaderboard — top contributors and most detected species across all sites.

curl -H "X-Wild-Echo-Key: your-api-key" https://api.wildecho.app/api/leaderboard

POST /api/report/email

Email a detection report to a specified address.

Request Body (JSON)

{
  "email": "landowner@example.com",
  "species": ["Australian Magpie", "Rainbow Lorikeet"],
  "health_score": 71,
  "site_name": "My Property"
}

GET /api/alerts/threatened

Returns recent threatened species detections across all sites, in reverse chronological order.

curl -H "X-Wild-Echo-Key: your-api-key" https://api.wildecho.app/api/alerts/threatened

{
  "alerts": [
    {
      "species": "Helmeted Honeyeater",
      "epbc_status": "Critically Endangered",
      "confidence": 0.73,
      "site": "Dandenong Ranges",
      "detected_at": "2026-04-14T06:48:00Z"
    }
  ]
}

POST /api/report/epbc

Generate a formatted EPBC compliance report HTML given species detections and property details.

Request Body (JSON)

{
  "property_name": "Greenfield Station",
  "property_address": "123 Station Rd, Traralgon VIC",
  "survey_date": "2026-04-20",
  "surveyor_name": "Kris Smith",
  "gps_coordinates": "-37.8136, 144.9631",
  "property_size_ha": 150,
  "species": [
    {
      "name": "Australian Magpie",
      "scientific": "Gymnorhina tibicen",
      "confidence": 0.94,
      "epbc": "Not listed",
      "type": "native"
    }
  ]
}

Response

{"status": "ok", "report_html": "<!DOCTYPE html>...", "threatened_count": 0}

Code Examples

Python

JavaScript

import requests

API_KEY = "your-api-key"
BASE_URL = "https://api.wildecho.app"

def analyze_audio(filepath, site_name="My Site"):
    with open(filepath, "rb") as f:
        response = requests.post(
            f"{BASE_URL}/api/demo/analyze",
            headers={"X-Wild-Echo-Key": API_KEY},
            files={"audio": f},
            data={"site_name": site_name}
        )
    return response.json()

# Run analysis
result = analyze_audio("dawn_chorus.mp3", "Dandenong Ranges")
print(f"Health score: {result['health_score']}/100")
print(f"Species detected: {len(result['detections'])}")
for sp in result["detections"]:
    pct = round(sp["confidence"] * 100)
    status = "⚠️ THREATENED" if sp["is_threatened"] else "🔴 INVASIVE" if sp["is_invasive"] else "✅ native"
    print(f"  {sp['species_common']} ({pct}%) — {status}")

const API_KEY = "your-api-key";
const BASE_URL = "https://api.wildecho.app";

async function analyzeAudio(file, siteName = "My Site") {
  const formData = new FormData();
  formData.append("audio", file);
  formData.append("site_name", siteName);

  const response = await fetch(`${BASE_URL}/api/demo/analyze`, {
    method: "POST",
    headers: { "X-Wild-Echo-Key": API_KEY },
    body: formData,
  });
  return response.json();
}

// Usage with file input
document.getElementById("audioInput").addEventListener("change", async (e) => {
  const file = e.target.files[0];
  const result = await analyzeAudio(file, "My Property");
  console.log(`Health score: ${result.health_score}/100`);
  result.detections.forEach(sp => {
    const pct = Math.round(sp.confidence * 100);
    console.log(`${sp.species_common}: ${pct}%`);
  });
});

SDKs

Official SDKs are in development. They'll provide typed interfaces, auto-retry, and streaming support.

🐍 Python SDKComing soon

⚡ Node.js SDKComing soon

📊 R PackageComing soon

📱 React NativePlanned

Want early SDK access? Contact us — we're working with pilot partners now.