eave developer docs

Authentication

Machine API calls use an API key as a Bearer token (or X-API-Key). Portal sessions use HttpOnly cookies and are never valid as API credentials.

Authorization: Bearer eave_sk_sand_…

• eave_sk_sand_… — sandbox (no real SMS / family alerts)
• eave_sk_live_… — live (requires organization live access)
• Create and revoke keys in the developer portal after signing in
• OpenAPI: GET /openapi.json on the API host

POST /api/v1/classify

Classify a transcript snippet. Primary sandbox endpoint.

curl -X POST "$API/api/v1/classify" \
  -H "Authorization: Bearer $EAVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Please buy Google Play cards and read me the codes.","use_ai":true,"depth":"fast"}'

{
  "ok": true,
  "environment": "sandbox",
  "session_id": "…",
  "use_ai": true,
  "depth": "fast",
  "is_scam": true,
  "confidence": 0.91,
  "reason": "…",
  "tactics": ["gift_card"],
  "call_state": { },
  "model": "…",
  "alerted": false,
  "timings": { "triage": 210, "fast_model": 1840, "total": 2090 }
}

use_ai (default true):

• true — embedding triage + LLM (counts toward AI quota)
• false — keyword/rules only, free and fast (model: "rules", includes keyword_hits). Useful for A/B testing without burning quota.

depth (default "fast", ignored when use_ai is false):

• "fast" — embedding triage plus one fast-model pass. Typically 2–4 seconds and one AI call of quota.
• "thorough" — adds a full-model second opinion when the fast pass looks suspicious or uncertain. Both models must agree before a scam is reported, which cuts false positives but costs roughly 10–25 seconds and a second AI call. Allow at least a 70-second client timeout.

Every AI response carries a timings object of per-stage milliseconds (triage, fast_model, full_model, total) so you can see where the wall-clock went.

Sandbox vs live

• Sandbox keys are scoped to classify only (no ingest/monitor). They never send real Twilio SMS or ntfy family alerts.
• Live keys are off by default; contact us for production volume.
• HTTP rate limits: sandbox ~30 rpm, live ~120 rpm (enforced per key).
• Paid AI caps (separate from HTTP rpm): sandbox defaults ~100 LLM calls/day and ~1000/month, plus embedding and STT second budgets. Library/keyword skips do not count. Live /ws/monitor audio meters STT seconds before each Deepgram/Whisper call; exhausted STT sends a {"type":"quota","resource":"stt"} frame and stops calling STT. See ai_quota on classify responses and ai_quotas on GET /api/v1/me.

Advanced endpoints

• POST /api/ingest — finished call / recording classification
• WS /ws/monitor — live PCM audio stream (device / companion apps)
• Omi marketplace uses a separate webhook path

Errors

• 401 — missing/invalid key
• 403 — live disabled or missing scope
• 422 — text too short / invalid body
• 429 — HTTP rate limited, or AI quota exhausted (ai_quota_exceeded)

Open developer portal Platform overview