Overview
Embed live AI roleplay calls and pull scored-call data into your own product.
Athos lets your reps practice live sales calls against AI personas — and automatically transcribes and scores each one. This documentation is for engineers integrating Athos into their own product.
What you get
Browser SDK
@useathos/sdk runs a live roleplay call in your frontend. The voice transport is fully
managed — your code only ever works with the Athos SDK.
REST API
Seven endpoints under /api/external/v1. Your backend creates agencies, registers reps,
mints sessions and reads scored calls by agency and by rep.
Webhook
A signed call.scored webhook fires as soon as a call reaches its outcome — scored or not.
OpenAPI spec
Import into Postman or generate a client. The machine-readable contract for the REST API and the call.scored webhook.
How it fits together
A roleplay call flows through three surfaces — your backend, the browser SDK, and the Athos API — and finishes with a webhook back to your backend:
┌─────────────────┐ ┌──────────────────────┐
│ Your backend │ ──(1) POST /v1/session ──────────▶ │ Athos API │
│ (holds API key)│ ◀──────── { token } ────────────── │ │
└────────┬────────┘ └──────────┬───────────┘
│ (2) hand token to the browser │
▼ │
┌─────────────────┐ │
│ Your frontend │ ─(3) AthosRoleplay.create({ token, drillKey })│ live roleplay call
│ (@useathos/sdk) │ session.connect() ───────────────────▶ │ (persona speaks)
└─────────────────┘ │
│ (4) call is scored
┌─────────────────┐ ▼
│ Your backend │ ◀──(5) POST call.scored (signed) ────────── │
│ (webhook URL) │ ──(6) GET /v1/calls/:callId ───────────────▶ │ full score + transcript
└─────────────────┘ └──────────────────────┘- Your backend exchanges its API key for a short-lived session token (
POST /v1/session). - You hand that token to the browser.
- The SDK redeems it and starts the live call — the AI persona speaks to your rep.
- When the call ends, Athos transcribes and scores it.
- Athos sends your backend a signed
call.scoredwebhook. - Your backend fetches the full score + transcript with
GET /v1/calls/:callId.
Two kinds of credentials
Your backend holds a secret, long-lived API key. The browser gets a short-lived session token your backend mints with it, good for one call. The browser never sees the API key. See Authentication.