• Bind. Loopback by default (daemon.http_host/ http_port, default 127.0.0.1:7060). Never expose it publicly — put it behind a TLS reverse proxy or a tunnel if the caller is remote.
• Auth. Header X-API-Key on every endpoint except /health, /metrics, /stats and /dashboard. The key comes from STROWGER_API_KEY; an empty key disables auth (dev only).
• JSON everywhere. Request and response bodies are JSON.
• Idempotence. POST /calls carries a client-supplied call_id; a known id returns 409. Generating unique ids is the client's job — there is no retry inside strowger.
• Secrets. Any api_key/password sent in a payload is write-only — scrubbed from storage, never returned, never logged.

{
  "backend": "gemini", "model": "…",
  "objectives": "…", "first_message": "…", "language": "fr",
  "tools": [ … ], "proxy_url": "http://…/proxy",
  "proxy_tools": [ … ],
  "callback_url": "http://…/callback?token=…",
  "recording": false,
  "agent_id": "…"
}

DID matching (multi-format)

A route's did accepts three forms, compared after normalising to digits only (+, spaces, dots, dashes and URI params dropped):

Deterministic resolution: exact > longest suffix > *. Two patterns identical after normalisation are rejected at validation time.

At the end of every call (outbound, or inbound that was answered), strowger POSTs to the supplied callback_url. No auth header is added — put your secret in the URL. Delivery is 10 attempts with backoff; every attempt is logged regardless of outcome, and the callback is replayed from its append-only journal on failure. The CDR audit trail is kept independently in its own on-disk journal, so a failed callback never loses the CDR.

{
  "call_id": "…", "direction": "outbound|inbound",
  "status": "completed|failed|no_answer|busy|rejected",
  "sip_code": 486,
  "destination": "…", "caller_id": "…", "agent_id": "…",
  "trunk": "ovh-prod", "backend": "gemini", "model": "…",
  "cdr": { /* full CDR, see below */ },
  "transcription": "…", "tool_results": [ … ],
  "recording": {                     // present if recording=true
    "urls": { "mixed": "http://…/recordings/{call_id}/mixed.wav?token=…",
              "in": "…", "out": "…" },
    "expires_at": "…"                // 24 h retention (configurable), then purge
  }
}

Recording URLs are tokenised and expire — download the WAV before expires_at; past that, the file is purged. Tokens are loaded once from SQLite at startup and authenticated from an in-memory projection afterwards.

Every finished call produces a CDR, available through two channels: the end-of-call callback above (recommended), and a daily journal — .journal files on disk, JSON Lines format, under data_dir/cdr/. Newer CDRs are not stored in SQLite and no CSV export is produced (the historical SQLite tables/functions remain only for migration compatibility). There is no HTTP endpoint to read historical CDRs — GET /calls/:id only ever returns active calls and answers 404 once the call has ended.

released_by values: caller · callee · api · watchdog_rtp · watchdog_silence · session_timer · shutdown · max_duration.

An endpoint is a SIP relationship with an operator or PBX. Two modes: REGISTER (credentials) or IP-auth (register: false — no credentials, the host enters the allowlist and the OPTIONS keepalive becomes the liveness signal).

password is write-only: never returned, never logged. [[trunk]] entries from the TOML coexist with API-created ones (source: "config", modifiable only by editing the file); a name conflict between the two is a startup error.

The routing counterpart of /endpoints: provision inbound DID routes by API, with no TOML reload and no restart — an upsert or delete is visible to the very next inbound INVITE. API routes persist in strowger.db and reload at boot; [[inbound_route]] entries from the file coexist (source: "config", immutable via the API).

Config/API merge. On an exact (trunk, normalised did) collision, the API route wins — the config route is hidden (shadowed: true in the GET) and reappears if the API route is deleted. Any other pattern collision (different trunks) is refused 409 at write time; if it only appears at boot (file edited afterwards), the API route still wins, with a warning logged. A route's trunk does not need to exist yet at PUT time; it only matters for the 503 refusal when that endpoint is deactivated (drain).

The endpoint behind strowger-cli register (see the CLI reference). Two payload shapes:

// Commercial licence issued in advance
{ "key": "…" }

// Demo — light identification, keyless
{ "company": "…", "contact_name": "…", "email": "…", "phone": "…" }

On success, the daemon returns the activated licence: license_id, customer, state, expires_at, max_concurrent_calls, max_trunks, max_call_seconds.

Strowger provides built-in tools natively intercepted by the daemon:

• end_call ({"reason": "string"}) — Cleanly hangs up the active call with a reason.
• transfer_call ({"destination": "string"}) — Initiates an agent call transfer to the specified destination (E.164 phone number or SIP URI). Destination is checked against the fail-closed allow/deny policy configured in [transfer].

Transfer CDR Fields: When a call is transferred, the end-of-call callback and CDR reflect the outcome:

• released_by: Set to "transferred" on successful transfer.
• transfer_mode: "refer" or "hairpin".
• transfer_target: The sanitized destination URI or phone number.
• In hairpin mode, two linked CDRs are produced (one per leg) with correlated call group identifiers.

The daemon serves its own observability — nothing to install:

• GET /health — liveness: the process is alive. Returns 200 with status: "ok" or "degraded" in the body (degraded = licence in refusal, or every configured trunk unusable). Returns 503 only when the whole SIP plane is down (trunks configured, none usable) — a binary signal for a load balancer, distinct from a mere licence degradation (which stays 200).
• GET /ready — readiness, separate from liveness: can this node actually carry traffic. Checks four components, 200 if all pass, else 503 with per-check detail (checks[].name/ok/detail): db (background SELECT 1 probe every 2 s), disk (recording volume has ≥ 500 MiB free, skipped if recording is off), rtp_ports (at least one free RTP port pair), sip_registration (at least one usable trunk, if trunks are configured). Use this to gate load-balancer/k8s rotation, not /health.
• GET /stats — structured JSON: registrations by state, active calls, TTFT (p95), RTP loss, playout underruns, dispositions.
• GET /dashboard — a standalone, auto-refreshing HTML page reading /stats.
• GET /metrics — Prometheus format, series prefixed strowger_. Beyond business metrics, it exposes saturation signals that precede collapse: strowger_rtp_ports_available/_total (media capacity), strowger_http_requests_active + strowger_http_overload_rejections_total (HTTP pressure), strowger_event_loop_lag_ms_last/_max (Tokio event-loop lag), strowger_open_fds and strowger_rss_bytes (OS resources, Linux — compare against the systemd unit's LimitNOFILE/ MemoryMax), plus strowger_db_queue_depth, strowger_db_group_commits_total, strowger_db_group_commit_jobs_total, strowger_db_group_commit_failures_total, strowger_callback_backlog and strowger_api_keys_inflight.
• GET /trunks — per-trunk registration, expiry, liveness, calls in progress.

• Caller-ID and the French MAN mechanism (since 2026-01). The presented CLI must be a number native to the emitting trunk. Presenting another operator's number gets the call cut before it reaches the callee (attestation C of the number authentication mechanism, ≈ STIR/SHAKEN). On an OVH trunk, keep the default (the identity is the trunk's own number) unless you have a validated native CLI.
• Disjoint RTP ranges. If another softswitch runs on the same box, keep separate RTP port ranges (strowger defaults to 20002-40001). A collision disguises itself as mass "no answer".
• RTP watchdog. A call with no inbound RTP for rtp_timeout_secs (default 30 s) is hung up (released_by=watchdog_rtp). Set it to 0 per call to disable — e.g. for a destination that never sends media.
• Session timers (RFC 4028). If the carrier requires Session-Expires, strowger honours it UAS-side (refresh + BYE at expiry if not renewed, released_by=session_timer). A Session-Expires < 90 gets 422 Min-SE: 90; Require: 100rel (PRACK) gets 420 (unsupported in v1).
• Inbound webhook is on the critical path. Keep it under a few hundred ms; past webhook_timeout_secs the call is rejected (486).