Local API Overview

​

Discovery file

macOS:   ~/Library/Application Support/HyperWhisper/local-api.json
Windows: %LOCALAPPDATA%\HyperWhisper\local-api.json

{
  "port": 39201,
  "pid": 12345,
  "started_at": "2026-06-02T13:57:46Z",
  "api_version": 1,
  "app_version": "2.36.0",
  "token": "9YH8r0Z1u3Xl..."
}

​

Authentication

Authorization: Bearer <token>

​

Response envelope

{ "ok": true, "...": "..." }

{
  "ok": false,
  "error": {
    "code": "MODEL_NOT_INSTALLED",
    "message": "Whisper large-v3 is not installed.",
    "hint": "Use /models to list installed models, or install via the app."
  }
}

• 400 for malformed JSON
• 401 for a missing or invalid bearer token
• 403 for a rejected Host/Origin header. This is a DNS-rebinding guard on every route, including /health.

​

Request limits

{
  "ok": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Request exceeds the configured limit."
  }
}

• macOS applies the request limit to every route that reads a body, and always answers with the HTTP 200 envelope. It applies the audio limit to audio_base64 and to a file path. For audio_base64 the limit is out of reach, because the request limit refuses the payload first; for a file path it is reachable, and a file above 48 MiB gets Audio exceeds the configured upload limit. macOS accepts no multipart request. So a file path is how you transcribe audio between 37.5 MiB and 48 MiB on macOS.
• Linux applies both limits, and both are reachable. It applies the audio limit to a multipart audio part and to a file path as well as to audio_base64. A file path above 48 MiB gets the same refusal here as on macOS. Only /transcribe answers with the HTTP 200 envelope. On the other routes, the web server stops the body itself and returns a bare 413 with no envelope.
• Windows applies both limits, and both are reachable. The request limit applies to every route that reads a body — POST /transcribe, POST /post-process, POST /modes and PATCH /modes/{id} — and each one answers with the HTTP 200 envelope. The audio limit applies to the decoded bytes of audio_base64 and to a file path, so a file path above 48 MiB is refused here and on Linux but accepted on macOS. Windows accepts no multipart request. Older Windows builds used neither value. Their web server kept its own default of 30,000,000 bytes (approximately 28.6 MiB), the refusal arrived as HTTP 400 with the message Invalid JSON body — which a client could not tell from malformed JSON — and there was no audio limit at all. Read the code and the message, and keep your client tolerant of both answers if it must support older builds.

​

Endpoints

​

Next: MCP