API

Spec

The full OpenAPI 3.1 description is available at the /v1/openapi.json endpoint. Drop it into Swagger UI, Stoplight, Redocly, or your preferred SDK generator.

Base URL: https://api.classeve.com

Authentication

All paid endpoints require an access token in the Authorization header. Sign in through the desktop or mobile app, or via classeve.com/auth.

Authorization: Bearer eyJhbGciOiJIUzI1NiI...

Tokens are validated server-side with algorithm whitelisting and explicit issuer and audience checks. Missing or invalid tokens return 401; expired tokens return 401 with code: TOKEN_EXPIRED.

Health + status

# Liveness probe
curl https://api.classeve.com/v1/health/live

# Readiness — checks all upstream dependencies
curl https://api.classeve.com/v1/health/ready

# Latest version metadata for desktop "Check for updates"
curl https://api.classeve.com/v1/version

Account + usage

# Get your full profile + plan + usage aggregates
curl https://api.classeve.com/v1/me \
  -H "Authorization: Bearer $TOKEN"

# GDPR data export — full JSON of profile + transcripts
curl https://api.classeve.com/v1/account/export \
  -H "Authorization: Bearer $TOKEN" \
  -o my-lven-data.json

# GDPR right to erasure
curl -X DELETE https://api.classeve.com/v1/account \
  -H "Authorization: Bearer $TOKEN"

# Server-side logout (revokes refresh token globally)
curl -X POST https://api.classeve.com/v1/auth/logout \
  -H "Authorization: Bearer $TOKEN"

Billing

Checkout is handled client-side via Paddle.js — there is no server-side checkout endpoint. The billing portal is available via:

# Open the billing portal
curl -X POST https://api.classeve.com/v1/customer-portal \
  -H "Authorization: Bearer $TOKEN"

Transcription (Lven Cloud only)

curl -X POST https://api.classeve.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@recording.wav"

Server-side transcription endpoint used by the Lven Cloud build. Returns the transcribed text — the server selects the model, clients cannot override it. Each successful transcription increments the daily quota attached to your Cloud subscription tier.

Lven Instant — the flagship on-device build — does not use this endpoint. Transcription runs entirely inside the app on your machine, and the only API call the Instant build makes is the subscription-status check via /v1/me.

Errors

All error responses are JSON with shape { error: string, code?: string, request_id: string }. Stable codes: TRIAL_NOT_STARTED, TRIAL_EXPIRED, QUOTA_EXCEEDED, ALREADY_PREMIUM, TRIAL_ALREADY_USED, TRIAL_ALREADY_ACTIVE.

Every response includes an X-Request-Id header you can quote in support tickets — we correlate it back to logs.

Rate limits

IP rate limit: 60 requests per minute per IP.

Per-user daily quota: 1,000 for Premium, 100 for Trial, 0 for Free (start a trial or subscribe to unlock).