API reference

Derived from the code: Edge crates/tenms-edge/src/{server,session,elevenlabs,limits}.rs, protocol crates/tenms-proto/src/protocol.rs, control plane crates/tenms-control/src/{api,licenses,auth,reads,customers,error,validate,accounts,session,keys,plans,usage}.rs. The ElevenLabs bridge protocol is documented in full in ElevenLabs bridge; only its HTTP surface is repeated here.

• Edge WebSocket protocol
• Edge HTTP endpoints
• Control-plane HTTP API
• Data types

Authentication tokens

Bearer header: Authorization: Bearer <token>. Edge streams also accept ?token=<token> (browsers cannot set WebSocket headers). A request that carries a bearer token is authenticated by the token alone; cookies are only consulted without one. Self-serve API keys (POST /v1/keys) are ordinary license tokens.

Edge WebSocket protocol

GET /v1/stream upgraded to WebSocket. Binary messages carry audio; text messages carry JSON control and events.

Binary messages

Limits: binary messages ≤ 256 KiB (max_message_bytes), larger closes the connection; the reference buffer holds at most 1000 ms ahead of the mic (newest samples dropped).

Client → server JSON

Text messages ≤ 16 KiB (message_too_large error otherwise; the session continues).

Focus profiles

ready.focus_profile echoes the profile in use (only when Focus is enabled); the call summary’s processing.algorithmic_delay_ms is the measured end-to-end delay of that profile. The ElevenLabs bridge accepts stt and listening only. Details and measurements: Integration guide.

Server → client JSON

at_ms is stream time at the end of the frame that raised the event.

Error codes (error events)

Close codes

A client that does not read for 10 s is disconnected without a close handshake.

Pacing

Caller audio may arrive at up to 1.5 × real time after an initial 5 s allowance. Beyond that Edge stops reading the socket until the client is back within budget (no error). The summary’s duration_ms is the processed audio, clamped to wall_time × factor + burst.

Edge HTTP endpoints

Upgrade refusals (both streams)

Body {"error": "<code>", "message": "..."}.

/v1/elevenlabs/stream takes ?focus_profile=stt|listening (default stt: the caller audio goes to ElevenLabs’ recogniser; an unknown value, listening_mini or listening_pro is 400 bad_request) and adds: 400 missing_agent_id / invalid_agent_id; 403 agent_not_allowed (agent not in elevenlabs_agents) / no_modules; 503 elevenlabs_not_configured (no ELEVENLABS_API_KEY). In-call tenms_error codes are in ElevenLabs bridge.

Control-plane HTTP API

Base: https://app.tenms.cloud. Edge: wss://edge.tenms.cloud. JSON in and out; request bodies may be gzip-compressed; responses are compressed when the client accepts it. Every request times out after 30 s (408).

Errors

{"error": {"code": "unauthorized", "message": "license revoked"}}

Note the shape differs from Edge ({"error": "<code>"}).

Endpoints

Session-token errors: 403 if the caller is itself a session token; 401 if the license is revoked or expired; 400 for ttl_secs: 0 or unknown fields. ttl_secs is capped at the server’s session-token TTL (300 s).

GET /v1/calls query: since (unix ms, default now − 7 days, clamped to the retention floor), before + before_id (keyset cursor from the previous page), cause (none|audio|transcription|llm|failed = not none), region (unknown matches null), source, limit (1-500, default 50). Values not on the region/source allowlists return an empty page.

Accounts, sessions and CSRF

• Signup: approval (default) creates a pending account that an admin approves (POST /v1/signups/{id}/approve: creates the customer, or links an existing one with customer_id, and sets its plan, default trial) or rejects; open approves at once with the trial plan; closed refuses (403). No email is sent: tell approved partners yourself.
• Validation: email (ASCII, ≤ 254, stored lower-case), password 10-256 characters, company 1-200, use_case 1-2000; unknown fields → 400; bodies > 16 KiB → 413.
• Enumeration-safe answers: signup is 202 with the same body whether or not the email exists; login is 401 invalid email or password for unknown emails, wrong passwords and rejected accounts. A pending account with the right password gets a session that can only read /v1/account (everything else 403 account is pending approval).
• Rate limits (per replica, fixed windows): signup 10/hour per client IP and 3/hour per email; login 30/15 min per client IP and 10/15 min per email → 429 + Retry-After.
• Cookies: __Host-tenms_session (HttpOnly) and __Host-tenms_csrf (readable by the page), both Secure; SameSite=Lax; Path=/, Max-Age = session lifetime.
• Every cookie-authenticated POST (keys, logout) needs X-CSRF-Token equal to the CSRF cookie and to the session’s token (also returned by /v1/login and /v1/account), and an Origin (or Referer) equal to an allowed origin. Signup and login check the origin too. Bearer callers are not subject to these checks.

Plan

{name: "trial"|"partner", modules, max_sessions, ttl_days, elevenlabs_agents, listening_pro, monthly_minutes}

PlanLimits = {modules?, elevenlabs_agents?, max_sessions?, ttl_days?, listening_pro?}. listening_pro is recorded and shown but not enforced (license tokens have no profile claim yet). Customers that predate self-serve have no plan (null) and cannot create keys.

KeyRequest

{name?, modules?, ttl_days?, elevenlabs_agents?, max_sessions?}; every field defaults to the plan’s value and may only narrow it (e.g. ttl_days ≤ the plan’s, agents ⊆ the plan’s). The key is a license: lid = lic_…, sub = the customer, exp ≤ now + ttl_days. KeyView = {license_id, name, token_hint ("tenms1…" + last 6 characters), modules, elevenlabs_agents, max_sessions, created_at, expires_at, revoked_at, last_used_at, status, self_serve}. last_used_at is the last control-plane request authenticated by the key or a session token derived from it (Edge verifies offline and does not report use), written at most every 60 s.

UsageResponse

customer_id   null = all customers (admin)
from, to      "YYYY-MM-DD" (UTC days, inclusive)
plan          "trial" | "partner" | null
totals        {calls, duration_ms, minutes}
daily         [{day, calls, duration_ms, minutes}]          # every day of the window
by_source     [{key, calls, duration_ms, minutes, share}]   # edge, pipecat, livekit, elevenlabs, sdk, ...
by_focus_profile [{key, ...}]                               # stt, listening, listening_mini, listening_pro,
                                                            # unknown (Focus on, not reported), none (Focus off), other
quota         trial only: {plan, period "YYYY-MM", minutes_included, minutes_used, fraction_used, enforced: false}

Served from the usage_daily rollup, which ingest maintains in the same transaction as the dedup insert, so resends never count twice. Minutes are duration_ms / 60000, rounded to 0.01. The trial quota is informational: nothing is blocked when it is exceeded.

Ingest result

{
  "accepted": 2, "duplicates": 1,
  "rejected": [{"index": 3, "call_id": "c4", "reason": "out_of_range"}],
  "results": [
    {"index": 0, "call_id": "c1", "status": "accepted"},
    {"index": 1, "call_id": "c2", "status": "accepted"},
    {"index": 2, "call_id": "c1", "status": "duplicate"},
    {"index": 3, "call_id": "c4", "status": "rejected", "reason": "out_of_range"}
  ],
  "customer_id": "acme"
}

• accepted = queued in memory (at-most-once from here); duplicate = already stored for this customer or repeated in the batch (do not resend); rejected = permanently invalid, except out_of_range (the day has no partition: maintenance failing).
• 422 when nothing in the batch was accepted or duplicate; 503 + Retry-After when the queue is full (nothing queued: resend the whole batch).
• Validation (validate.rs): call_id 1-128 bytes; started_at_ms not more than 1 day in the future and inside retention; duration_ms ≤ 7 days; ≤ 8 modules; ≤ 8 failure reasons of ≤ 200 chars; finite numbers; compute times ≤ 10 s; serialised summary ≤ 8 KiB. Regions / sources outside the server limit / the server limit are stored as other.

StatsResponse

window      {hours, from_ms, to_ms, customer_id, include_test}
totals      {calls, failed, failure_rate, duration_ms, mean_duration_ms}
failure_causes [{cause, calls, share}]
quality     {calls, mos {mean,p10,p50,p90}, snr_db_mean, asr_risk {mean,p50,p90,high_risk_calls,high_risk_share}}
turns       {calls, user_turns, barge_ins, backchannels, ignored_noise, ignored_other_speaker, eot_delay_ms_p50_mean, ...}
processing  {compute_us_p99 {mean,p50,p95,p99,max}}   # distribution across calls of per-call p99
regions     [{region, calls, failed, failure_rate, mean_mos, ...}]
hourly      [{hour_ms, calls, failed, audio, transcription, llm, mean_mos, ...}]

Served from the hourly rollups, never from raw calls. A license token’s stats always include its own test traffic.

Data types

CallSummary

crates/tenms-proto/src/summary.rs:

{
  "call_id": "c1", "started_at_ms": 1793847800519, "duration_ms": 30120,
  "source": "edge", "region": "asia-southeast1-eqsg3a", "modules": ["focus","turn","pulse"],
  "quality": {"mos": 4.16, "snr_db": 30.1, "clipping_ratio": 0, "dropout_ratio": 0,
              "narrowband_ratio": 0, "overlap_ratio": 0.06, "echo_ratio": 0.29,
              "speech_ratio": 0.34, "asr_risk": 0.004},
  "turns": {"user_turns": 4, "barge_ins": 1, "backchannels": 1, "ignored_noise": 0,
            "ignored_other_speaker": 0, "eot_delay_ms_p50": 360, "eot_delay_ms_p95": 610},
  "failure": {"cause": "none", "confidence": 0.6, "reasons": []},
  "processing": {"frames": 3012, "compute_us_p50": 20.9, "compute_us_p99": 102.9,
                 "compute_us_max": 347.6, "algorithmic_delay_ms": 5.0}
}

(Values from python/tests/live_reports/pipecat_daily_latest.json, region illustrative.) quality, turns, failure and region are optional (null when the module was off). focus_profile (optional, omitted when unset) is the Focus profile the call ran with: stt, listening, listening_mini or listening_pro, set by Engine::finish from the engine configuration (absent when Focus is off or the settings are custom). It is a string so older control planes and newer profiles stay compatible; ingest accepts [A-Za-z0-9_.:-]{1,32} and meters unknown names as other. source values in use: edge, elevenlabs, pipecat, livekit, sdk (allowlist: the server limit).

CallBatch

{"customer_id": "acme", "calls": [CallSummary, ...]}

customer_id must match the license’s customer.