Reference
API reference
The seven External API endpoints, auth, and the OpenAPI spec.
The External API is seven endpoints under a single base URL.
Base URL: https://app.useathos.ai/api/external/v1
Paths in these docs are written /v1/…: POST /v1/session means
POST https://app.useathos.ai/api/external/v1/session. Path parameters are written :name.
Endpoints
| Method & path | Auth | CORS | Purpose |
|---|---|---|---|
POST /v1/agencies | API key | ❌ | Create or rename an agency under your own id — the first roster call. |
POST /v1/agents | API key | ❌ | Register an agent into an existing agency. |
GET /v1/agents | API key | ❌ | Look agents up by any handle, or page the roster. |
POST /v1/session | API key | ❌ | Mint a session token for the SDK. |
POST /v1/roleplay/session | Session token | ✅ | Redeem a token and start a call. Called by the SDK, not you. |
GET /v1/calls | API key | ❌ | List scored calls (cursor-paginated). |
GET /v1/calls/:callId | API key | ❌ | Get full call detail (transcript + score). |
The six API-key endpoints are server-to-server and reject cross-origin requests. Only the SDK's redeem endpoint accepts browser (CORS) requests. See Authentication.
Conventions
- Auth: bearer token —
Authorization: Bearer <api-key-or-token>. - Success: returns the resource JSON directly (no envelope).
- Errors:
{ "error": { "code", "message", "requestId" } }. Branch oncode— see error codes. - Request id: every response from a v1 endpoint carries
X-Athos-Request-Id. Quote it in support tickets. - Rate limits: none are enforced in v1. Poll
GET /v1/callson a schedule rather than in a tight loop; thecall.scoredwebhook is the notification. If limits are introduced they will answer429with aRetry-Afterheader — handle that status now and nothing changes later. - Versioning: the path is pinned to
/v1. Breaking changes ship under a new version;/v1stays available for at least six months past any successor.@useathos/sdkfollows semver: a breaking change to its public surface is a major release.
OpenAPI spec
The full machine-readable contract is published as an OpenAPI 3.1 document:
Point any OpenAPI generator at it for a typed client:
npx @openapitools/openapi-generator-cli generate \
-i https://docs.useathos.ai/openapi.yaml \
-g typescript-fetch -o ./athos-client