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
- 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.
- Click the gear button at the top right of the window to open Settings.
- Click Integrations.
- 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.
- 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. - Next to Auth token, click Show token or Copy token. In the examples it appears as
<your-token>. - 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=whisperorprovider=parakeet. By default it follows your local engine setting.language=<code>, for exampleen.
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:
- Open the WhisprDesk app: click its icon in the Dock (or open it from your Applications folder).
- Click the Models tab at the top of the window, then click Speech to text.
- Click the On this Mac tab, then the OpenAI Whisper tab.
- 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/eventsand/v1/historyonly 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.