API Reference

The Hub API is a Fastify HTTP server. All endpoints are under /api/.

Authentication

The auth resolver tries internal key, JWT cookie, JWT bearer, then API key, in that order. Whichever matches sets request.auth = { userId? | apiKeyId?, satelliteId?, tenantId, role, isPlatformAdmin }. API keys are SHA-256 hashed in storage; the raw key is shown once at creation. Satellite-scoped keys are minted by registration (POST /api/satellites returns apiKey) and rotated via POST /api/satellites/:id/rotate-api-key hub 0.32.5; they carry role=member and a satellite_id FK so they can be revoked individually.

Authorization hub 0.70: every route declares the action it performs in the permissions registry (packages/shared/src/permissions.ts), and one guard applies the action's rule before the route runs: 401 when no one is signed in; 403 when the role, or the kind of caller, is not allowed (an API key where a person must act, a satellite's key outside the routes declared for it); 404 when the team or the item the route names is out of reach; 400 when a body must name its team and does not. The role counts in the team the action concerns (the item's own team, or the team the request names), whichever team the caller has active. The Auth column below gives the minimum role; Settings and permissions lists every action.

Login security:

• Rate limiting: max 20 attempts per IP per 15 minutes (429)
• Account lockout: 5 failed attempts locks for 15 minutes (423)
• Last login timestamp + IP recorded on success
• Hub admin status resolved from DB on every request (not from stale JWT)

Auth

*Gated by hub settings (allow_self_registration, allow_tenant_creation)

Detections

Query params for GET /detections:

• tenantId — filter by tenant
• satelliteId — filter by satellite
• species — filter by species code
• speciesSearch — search by common or scientific name (ILIKE)
• minConfidence — minimum confidence threshold
• verificationStatus — pending_review, confirmed, rejected, unverified
• sortBy — sort field: date (default), confidence, species
• sortDir — sort direction: asc or desc (default)
• limit, offset — pagination
• start, end: time window (ISO, end exclusive); all time when absent
• includeTentative: true to include detections still waiting on the temporal-aggregation rule
• withCount — set to false to skip the multi-second COUNT(*) over the visibility-filtered table when the caller doesn't need pagination (Dashboard recent-detections, Verification queue). When false, total is null in the response

Response: { detections: [...], total: number | null, aggregation }. Each detection includes an is_first_of_season boolean flag indicating whether it was the first observation of that species in the current season for the tenant. aggregation maps the team of each tentative detection listed to its rule: {enabled, count, windowMinutes, confidenceHigh, retentionHours} (retentionHours is null while the hub's retention is off, since nothing then deletes them).

Sessions

Query params for GET /sessions:

• tenantId — filter by tenant
• satelliteId — filter by satellite
• filter — session type: with-detections, empty, or omit for all
• sortBy — sort field: date (default), duration, detections, species, chunks
• sortDir — sort direction: asc or desc (default)
• limit, offset — pagination

Response: { sessions: [...], total: number }

Query params for GET /sessions/timeline:

• tenantId — filter by tenant
• satelliteId — filter by satellite
• from, to — ISO 8601 time range boundaries

Sessions are groups of consecutive audio chunks separated by a gap of 5 minutes or more. Each session includes its start/end time, chunk count, and detection summary.

Satellites

Device rule hub 0.51. Every mutating satellite route is authorized against the device's own team, never the caller's active one: hub admin; or admin+ in that team; or the member who registered the device (registered_by) while the team's device_policy is members. A device's own satellite-scoped key may rename, rotate its key and push its config, nothing else. A device with no registrant is team-owned and admin-managed. Unknown or invisible devices answer 404, visible but not manageable ones 403.

PUT /satellites/:id/config body:

• configLocked: boolean (admins of the satellite's team only: "Only admins can change its settings")
• overrides: object with nullable fields: filter_enabled, filter_min_rms, yamnet_min_bird_prob, outbox_soft_size_mb, outbox_hard_size_mb, outbox_max_age_hours, heartbeat_interval_sec, drop_amphibian_at_satellite, drop_insect_at_satellite, drop_anthropogenic_at_satellite, drop_human_voice_at_satellite, drop_other_animal_at_satellite, device_inference. null follows the team (which follows the hub).

Config resolution: one rule for every setting, from the settings registry: the satellite's own value, else its team's, else the hub's, else the built-in default, with a lock at the hub or the team ending the walk there. See Settings and permissions.

Audio

Alerts

Export

Stats

Every count below, the exports above and the PDF report cover the detections the Detections page lists: promoted, one row per stitched call, in the categories the team shows hub 0.78.0.

Species

Webhooks

Webhook delivery is an alert-channel type; manage channels via /alert-rules/channels and see webhooks.md for payloads and X-BirdNet-Signature verification. The former standalone /webhooks routes were removed in hub 0.37.2.

Alert Rules

Trigger types: detection (on new detection matching conditions), absence (no activity for N minutes), trend (species diversity or detection count drop/increase)

Alert Channels

Channel types: email (SMTP), slack (Block Kit), telegram (Bot API), google_chat (Cards v2), discord (rich embeds), webhook (generic with HMAC)

Scheduled Exports

Formats: csv, json, ebird, inaturalist Schedule: cron expression (e.g. 0 6 * * 1 for weekly Monday 6am) Delivery: via alert channel (email attachment or webhook POST)

Calibration hub 0.30

Per-(tenant, model) isotonic-regression confidence calibration. Inputs: confirmed/rejected verification votes. Output: a monotonic mapping from raw confidence buckets to calibrated probabilities, stored in confidence_calibration (migration 069).

GET /detections already decorates each row with calibrated_confidence (bulk-loaded once per request); single-detection callers read it directly from the row, not from this endpoint.

Mobile Releases

Workers

Settings

Tenants

Admin (hub admins only)

User list query params: ?search=, ?status=active|blocked, ?tenantId=

Audit Log

All audit log entries include the real client IP address (via X-Forwarded-For, with trustProxy enabled on Fastify).

Each route that changes something declares the entries it writes (config.audit, hub 0.72+) and writes them through request.audit(), which records who acted, from which address, and in which team; a team's entries also feed its activity page. The list below is generated from services/audit.ts and the audit log page's labels.

user

admin

member

device

detection

auth

field_note

satellite

WebSocket

Connect to /ws/events?tenantId=<id> for real-time events (signed in; a socket stays within its team, hub admins excepted).

Live listening: ?listenSatelliteId=<id> at connection, or a {"type":"live-start","satelliteId":"<id>"} message, streams that satellite's microphone. It needs member or above in the satellite's own team, which must be the socket's team (hub 0.64.5; before, the client named the team and a member of another team could join the session). Any team the client sends is ignored.

Event types:

• detection — new bird detected (species, confidence, satellite, rare flag)
• alert — system alert (rare species, satellite offline, etc.)

Toast format: Rare species notifications show translated names (primary + secondary languages).

System

Response includes:

• Services: each registered instance (API, dispatcher, web, workers, satellites) with status, version, uptime, memory usage, IP address, and service-specific details (e.g., per-worker job stats: processed, succeeded, failed, avg duration)
• Infrastructure: PostgreSQL, Redis, MQTT, MinIO connectivity and status
• Data summary: detection counts, inference queue stats, species image totals, tenant and user counts

Service instances are discovered via Redis service registry (birdnet:registry:{service}:{instanceId}, 30s TTL).

Health