Local API

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 > Integrations > External App Gateway

Open the WhisprDesk app: click its icon in the Dock (or open it from your Applications folder).
Click Integrations in the sidebar.
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. 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 History items (default 20, up to 200)
`GET /v1/events`	Yes	A live event stream. A `transcription` event fires each time a dictation is saved to History.

Check that it is running

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

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

Transcribe a file

Where: Terminal on your Mac. Copy <gateway-address> and <your-token> from WhisprDesk > 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 > Settings > Transcription > Local tab

Whisper: always uses the Base model, whichever Whisper model you picked in Settings. 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 Settings at the bottom of the sidebar, then click Transcription.
3. Click the Local tab, then the OpenAI Whisper tab.
4. Click Download on Base.
Parakeet: uses Parakeet TDT 0.6B, which must be downloaded.

API transcriptions are not saved to History.

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 History. With Data Retention off, they receive nothing new.
Web pages can only call the API when they are served from your own Mac.