Skip to main content
WhisprDesk

Local API

Applies to WhisprDesk 1.9.0 · Updated 2026-11-16

WhisprDesk includes a local API so other apps and scripts on your Mac can request transcriptions and listen for new dictations. It only accepts connections from your own Mac and is protected by a token that only you can see. Transcription through the API always runs locally, never in the cloud.

Find your endpoint and token

Where: WhisprDesk > Settings > Integrations > External App Gateway

  1. Open the WhisprDesk app: click its icon in the Dock (or open it from your Applications folder). If WhisprDesk is running but you don't see its window, click the WhisprDesk icon in the menu bar at the top right of your screen and choose Open WhisprDesk.
  2. Click the gear button at the top right of the window to open Settings.
  3. Click Integrations.
  4. The page explains what the gateway is for, under What is this for?, with examples and the steps to connect an app. Below it, find External App Gateway. It shows Running while the app is open.
  5. Next to Endpoint, click Copy URL. This is the address other apps use. In the examples below it appears as <gateway-address>; replace it with what you copied.
  6. Next to Auth token, click Show token or Copy token. In the examples it appears as <your-token>.
  7. To replace the token, click Rotate token and confirm. Any app using the old token must be updated.

Always copy the endpoint from the app rather than typing it, because it can change if another app is using the usual one. Share the token only with apps you trust, and treat it like a password. The gateway only accepts connections from apps on this Mac, never from other computers. The API starts with WhisprDesk and is always on while the app is running.

Authentication

Send your token in a header:

Authorization: Bearer <your-token>

For /v1/events, you can pass ?token=<your-token> instead if your client cannot set headers.

Endpoints

Method and path Token needed What it does
GET /v1/status No Confirms the API is running and returns the app version
GET /v1/capabilities No Lists available local engines and limits
POST /v1/transcribe Yes, and an active license or trial Transcribes an audio file you send
GET /v1/history?limit=N Yes Returns recent saved transcripts (default 20, up to 200)
GET /v1/events Yes A live event stream. A transcription event fires each time a dictation is saved to Your Transcripts.

Check that it is running

Where: Terminal on your Mac. Copy <gateway-address> and <your-token> from WhisprDesk > Settings > Integrations > External App Gateway first.

curl http://<gateway-address>/v1/status

Transcribe an audio file through the API

Where: Terminal on your Mac. Copy <gateway-address> and <your-token> from WhisprDesk > Settings > Integrations > External App Gateway first.

Send the raw audio bytes as the request body with an audio Content-Type. Do not use a multipart form or JSON.

curl -X POST "http://<gateway-address>/v1/transcribe?language=en" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: audio/wav" \
  --data-binary @recording.wav

The response includes the text, the engine and model used, and the duration.

Options (query parameters):

  • provider=whisper or provider=parakeet. By default it follows your local engine setting.
  • language=<code>, for example en.

Accepted Content-Types: audio/wav, audio/mpeg, audio/mp4, audio/x-m4a, audio/webm, audio/ogg, audio/flac, audio/aac, and application/octet-stream. Maximum size is 25 MB.

Which model the API uses

Where: WhisprDesk > Models > Speech to text > On this Mac

  • Whisper: always uses the Base model, whichever Whisper model you chose in Models > Speech to text. Download Base first, otherwise the request fails:
    1. Open the WhisprDesk app: click its icon in the Dock (or open it from your Applications folder).
    2. Click the Models tab at the top of the window, then click Speech to text.
    3. Click the On this Mac tab, then the OpenAI Whisper tab.
    4. Click Download on Base. You don't need to click Use this model for the API.
  • Parakeet: uses Parakeet TDT 0.6B, which must be downloaded.

API transcriptions are not saved to Your Transcripts.

Limits and errors

Code Meaning
401 Missing or wrong token
402 No active license or trial
413 File larger than 25 MB
415 Unsupported Content-Type
422 No speech detected
429 Too many requests (60 per minute, 10,000 per day)
500 Transcription failed. Check that the model is downloaded.
503 Engine not available

Good to know

  • /v1/events and /v1/history only include dictations saved to Your Transcripts. With Data Retention off, they receive nothing new.
  • Web pages can only call the API when they are served from your own Mac.