API reference

Base URL https://whisper.thundera.eu. JSON in, JSON out.

Authentication

Send the thundera_token cookie (browser), Authorization: Bearer <access token> (native), or X-API-Key: sk_sus_… (organization key). Tokens come from auth.thundera.eu; native clients refresh with POST https://auth.thundera.eu/api/v1/auth/refresh.

Errors

Errors are {"error": "CODE", "message": "..."} with the matching HTTP status: 400 BAD_REQUEST, 401 UNAUTHORIZED, 403 FORBIDDEN, 404 NOT_FOUND, 413 PAYLOAD_TOO_LARGE, 429 (rate limit). Authenticated request bodies are limited to 2 MB.

Public

Method	Path	Auth	Description
`GET`	`/api/v1/health`	none	Health check.
`GET`	`/api/plans`	none	Whisper plans, proxied from the central catalogue (also `/api/v1/plans`). Cached 60 s.
`GET`	`/api/v1/updates/macos`	none	macOS update manifest with verified size and SHA-256.
`GET`	`/api/v1/updates/macos/file`	none	macOS update artifact (`no-store`).
`GET`	`/api/v1/updates/windows`	none	Windows update manifest.
`GET`	`/api/v1/updates/windows/file`	none	Windows update artifact.

Account and usage

Method	Path	Auth	Description
`GET`	`/api/v1/auth/me`	user	Current user from the token.
`GET`	`/api/v1/usage`	user	`{words_used, word_limit, plan_tier, reset_date}`.
`GET`	`/api/v1/downloads`	user	Available client downloads.
`GET`	`/api/v1/downloads/file?platform=macos\|windows\|ios\|android`	user	Download a client. `400` without `platform`, `404` if none.

Dictation

Method	Path	Auth	Description
`GET`	`/api/v1/stream`	user	WebSocket upgrade for streaming dictation (see below).
`POST`	`/api/v1/polish`	user	Body `{text, source_language, target_language, tone, developer_mode, naming_convention, custom_vocab[]}`. Returns `{text, polished, source_language, target_language, translated}`. On any model failure returns the raw text with `polished:false`.
`POST`	`/api/v1/transcribe`	user	Body `{audio (base64, ≤ 25 MB), language, tone}`. Batch transcription plus cleanup.

WebSocket protocol

Client → server:

{"type":"control","action":"start","language":"en","mode":"dictation"}
{"type":"audio","data":"<base64-pcm>","sequence":1}
{"type":"control","action":"command_mode","selected_text":"text to transform"}
{"type":"control","action":"stop"}
{"type":"heartbeat"}

Server → client: session, transcript (text, is_final, sequence), command_result (original, transformed, preview), heartbeat, error (code such as QUOTA_EXCEEDED).

Dictionary, snippets, notes

Method	Path	Auth	Description
`GET`	`/api/v1/vocabulary`	user	List terms (paginated).
`POST`	`/api/v1/vocabulary`	user	`{term, pronunciation_hint, category}`.
`PUT`	`/api/v1/vocabulary/{id}`	user	Update a term.
`DELETE`	`/api/v1/vocabulary/{id}`	user	Delete a term.
`GET`	`/api/v1/snippets`	user	List snippets (paginated).
`POST`	`/api/v1/snippets`	user	`{trigger_phrase, expansion_text, category}`.
`PUT`	`/api/v1/snippets/{id}`	user	Update a snippet.
`DELETE`	`/api/v1/snippets/{id}`	user	Delete a snippet.
`GET`	`/api/v1/notes`	user	List notes.
`POST`	`/api/v1/notes`	user	`{title?, text}`.
`PATCH`	`/api/v1/notes/{id}`	user	Partial update `{title?, text?}`.
`DELETE`	`/api/v1/notes/{id}`	user	Delete a note.

Settings

Method	Path	Auth	Description
`GET / PUT`	`/api/v1/settings`	user	User settings (tone, language, translation).
`GET / PUT`	`/api/v1/settings/developer`	user	Developer mode and naming convention.
`PUT`	`/api/v1/settings/hipaa`	user	HIPAA mode switch.
`GET / POST`	`/api/v1/settings/apps`	user	Per-application settings.
`PUT / DELETE`	`/api/v1/settings/apps/{appId}`	user	Update or remove one application’s settings.

Organizations (admin role)

Method	Path	Auth	Description
`GET`	`/api/v1/org/settings`	org admin	Organization settings.
`PUT`	`/api/v1/org/settings/hipaa`	org admin	`{hipaa_mode: bool}`.
`GET / POST`	`/api/v1/org/members`	org admin	List or invite `{email, role}`.
`DELETE`	`/api/v1/org/members/{userId}`	org admin	Remove a member.
`GET / POST`	`/api/v1/org/api-keys`	org admin	List or create `{name}` (key shown once).
`DELETE`	`/api/v1/org/api-keys/{id}`	org admin	Revoke a key.
`GET / PUT`	`/api/v1/admin/polish/status`	system admin	Read or set the AI-cleanup kill switch `{enabled: bool}`.

Example: polish a transcript

curl -X POST https://whisper.thundera.eu/api/v1/polish \
  -H "X-API-Key: $WHISPER_KEY" -H "Content-Type: application/json" \
  -d '{"text":"um so the meeting is uh at three","tone":"concise"}'