Local API Server

HyperWhisper includes an optional HTTP server. The server listens on 127.0.0.1 only, and the network cannot reach it. When the server starts, it writes a discovery file with the port and a bearer token. MCP wrappers, benchmark scripts, and Shortcuts read this file. You do not copy the credentials anywhere. The server is off by default. You turn it on one time in Settings. It stays on across restarts.

Turn on the server

macOS
Windows
Linux

Open Settings → API Server.
Set the toggle to on. The status line then shows the bound address and the last four characters of your bearer token.

When the server runs, the panel shows three tabs on macOS and Windows: Connection, MCP setup, and cURL. Linux shows the same content as one list.

Connection tab

The Connection tab shows the current values that you need to make requests to the server.

Field	What it shows
Port	The port that the server listens on. The Copy button copies the port to the clipboard.
Bearer token	Hidden by default. Click Reveal to show the full value. Click Copy to copy the token. Click the regenerate button to make a new token (see the next section).
Port file	The full path of the discovery file. The Show button opens the file in Finder (macOS) or Explorer (Windows). Linux shows the path in a read-only field that you can copy.

If an error occurs after the server starts (for example, the port is already in use), an orange warning appears below these fields.

Bearer token

Every request except GET /health must include the bearer token:

Authorization: Bearer <token>

HyperWhisper makes the token the first time the server starts. macOS keeps the token in the Keychain. Windows keeps the token in a DPAPI-protected file at %LOCALAPPDATA%\HyperWhisper\local-api-token.bin. Linux keeps the token in an owner-only file at $XDG_DATA_HOME/hyperwhisper/local-api-token. The token stays the same across restarts. You do not update your scripts each time. To make a new token, click the regenerate button. This button is a circular arrows icon on macOS, a rotate button on Windows, and a Regenerate button on Linux. The previous token stops immediately. Update each MCP client and each script that cached the old token. These clients and scripts can read the new value from the discovery file.

MCP setup tab

The MCP setup tab shows the configuration to paste into your MCP client. The bridge reads the discovery file when it starts. Thus no port and no token appear in the client configuration.

{
  "mcpServers": {
    "hyperwhisper": {
      "command": "npx",
      "args": ["-y", "@hyperwhisper/mcp"]
    }
  }
}

The Copy button copies the full block. For step-by-step instructions for Cursor, Claude Desktop, and Claude Code, read the MCP setup guide.

The Linux app shows this same block, but the @hyperwhisper/mcp bridge does not read the Linux discovery file yet. The bridge looks for the macOS path on every platform that is not Windows, so on Linux it reports HYPERWHISPER_NOT_RUNNING. Until the bridge adds the Linux path, call the endpoints directly with the cURL snippet below.

cURL tab

The cURL tab shows shell commands that contain your current port and token.

macOS
Windows
Linux

When the server runs, the snippet contains your current values:

PORT=<your port>
TOKEN=<your token>
curl -s http://127.0.0.1:$PORT/health | jq .
curl -s -H "Authorization: Bearer $TOKEN" "http://127.0.0.1:$PORT/models" | jq .

If the server does not run, the snippet reads the values from the discovery file:

PORT=$(jq -r .port ~/Library/Application\ Support/HyperWhisper/local-api.json)
TOKEN=$(jq -r .token ~/Library/Application\ Support/HyperWhisper/local-api.json)
curl -s http://127.0.0.1:$PORT/health | jq .
curl -s -H "Authorization: Bearer $TOKEN" "http://127.0.0.1:$PORT/models" | jq .

When the server runs, the snippet contains your current values:

$PORT = <your port>
$TOKEN = "<your token>"
curl http://127.0.0.1:$PORT/health
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:$PORT/models

If the server does not run, the snippet reads the values from the discovery file:

$discovery = Get-Content "$env:LOCALAPPDATA\HyperWhisper\local-api.json" | ConvertFrom-Json
$PORT = $discovery.port
$TOKEN = $discovery.token
curl http://127.0.0.1:$PORT/health
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:$PORT/models

Linux always reads the values from the discovery file:

DISCOVERY="${XDG_DATA_HOME:-$HOME/.local/share}/hyperwhisper/local-api.json"
PORT="$(jq -r .port "$DISCOVERY")"
TOKEN="$(jq -r .token "$DISCOVERY")"
curl "http://127.0.0.1:$PORT/health"
curl -H "Authorization: Bearer $TOKEN" "http://127.0.0.1:$PORT/models"

The snippet needs jq. Install it with sudo apt install jq if the command is not available.

Discovery file

When the server starts, it writes a JSON file. MCP wrappers and scripts read the port and the token from this file. You do not put these values in your code.

macOS
Windows
Linux

~/Library/Application Support/HyperWhisper/local-api.json

HyperWhisper creates the file with chmod 600. Only your user account can read the file.

%LOCALAPPDATA%\HyperWhisper\local-api.json

The NTFS ACL permits access from your Windows user account only. This is equivalent to chmod 600.

$XDG_DATA_HOME/hyperwhisper/local-api.json

This is normally ~/.local/share/hyperwhisper/local-api.json.HyperWhisper writes the file atomically, then checks that only your user account can read it. If the check fails, the server stops itself instead of leaving a readable token on disk. The status line then reports local_api.discovery.

The file has this structure:

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

The server deletes the file when it stops correctly. If you force-quit HyperWhisper, the file can stay on disk until the next start. The next start writes new values over the old file.

If you see Connection refused and the discovery file is present, the file records an old port. Set the Local API switch to off, then set it to on again. The server writes a new file.

Port

The server has no fixed port. At the first start, it asks the operating system for a free port. It then keeps that port and uses the same port at each later start. Thus a script that holds the port in its code continues to operate across restarts. If the kept port is not free at a later start, for example because a different program took it, the server does not fail. It asks the operating system for a new free port and writes the new port into the discovery file. To make a script that always finds the server, read the port from the discovery file.

Linux is different. It gives you a Preferred port box, and the default is 51671. HyperWhisper tries that port first. If the port is taken, it asks the operating system for any free loopback port instead, and it writes the port that it really got into the discovery file. Set the box to 0 to always ask for a free port.The Port row below the box shows the port that the server actually bound, which can be different from your preferred port. Read the discovery file, not the box.

Request timeout

A /transcribe or a /post-process call is slow. A large local model, or a slow cloud model, needs 30 to 90 seconds, and sometimes more. On macOS, the server allows 10 minutes for one request. On Windows, the server sets no limit on the time of one request. Set the timeout of your own HTTP client higher than its default value. Many clients apply a short default timeout. Such a client reports a failure while the transcription is still in progress.

Available endpoints

Method	Path	Auth	Purpose
GET	`/health`	None	Server identity and status.
GET	`/models`	Required	Model catalog.
GET	`/modes`	Required	List saved Modes.
POST	`/modes`	Required	Create a Mode.
GET	`/modes/{id}`	Required	Fetch one Mode.
PATCH	`/modes/{id}`	Required	Partial-field update.
DELETE	`/modes/{id}`	Required	Delete a Mode.
POST	`/transcribe`	Required	Transcribe an audio file. If you give a `file` path instead of `audio_base64`, the path must be inside your recordings folder. The server rejects all other paths.
POST	`/post-process`	Required	Rewrite text with a preset prompt or a custom prompt.
GET	`/recordings/search`	Required	Substring search across past transcripts.
GET	`/recordings/{id}`	Required	Single transcript row.
GET	`/recordings`	Required	Windows only — undocumented alias for `/recordings/search`.

The OpenAPI reference gives the full request and response schemas.

The two platforms are different in three ways. On macOS, GET /models accepts the ?kind= and ?installed_only= query parameters to filter the catalog. Windows ignores these parameters and always returns the full catalog.macOS also examines the Host and Origin headers on each request. macOS returns 403 for a request that is not a true loopback call. This check protects you against DNS-rebinding attacks from a browser tab. Windows does not make this check.Windows accepts and returns five more mode fields than macOS: localEngine, localParakeetModel, localPostProcessingModel, customVocabulary, and providerType. These fields hold the Windows settings that have no macOS equivalent. macOS ignores these keys when you send them, and never returns them.

Next steps

MCP setup guide — connect HyperWhisper to Cursor, Claude Desktop, or Claude Code as an agent tool.
API overview — authentication, response envelope, and error codes.

Getting Started

Plans & Billing

Transcription & Models

The Interface

Features

Settings

Privacy & Security

Developer & API

Troubleshooting

Windows

Turn on the server

Connection tab

Bearer token

MCP setup tab

cURL tab

Discovery file

Port

Request timeout

Available endpoints

Next steps

​Turn on the server

​Connection tab

​Bearer token

​MCP setup tab

​cURL tab

​Discovery file

​Port

​Request timeout

​Available endpoints

​Next steps

Turn on the server

Connection tab

Bearer token

MCP setup tab

cURL tab

Discovery file

Port

Request timeout

Available endpoints

Next steps