HTTP API

TypeWhisper includes a local REST API for automation and integration with external tools. In macOS 1.2, this is an advanced surface: documented /v1/* endpoints are intended to remain stable throughout the 1.2 release line. Enable it in Settings > Advanced (default port: 8978).

Note: The API is disabled by default, binds to localhost only, and is designed for local automation rather than public network access.

Check Status

# Check if the API is ready

curl http://localhost:8978/v1/status

{
  "status": "ready",
  "engine": "whisper",
  "model": "openai_whisper-large-v3_turbo",
  "supports_streaming": true,
  "supports_translation": true
}

Transcribe Audio

# Send an audio file for transcription

curl -X POST http://localhost:8978/v1/transcribe \

-F "file=@recording.wav" \

-F "language=en" \

-F "target_language=de"

{
  "text": "Hello, world!",
  "language": "en",
  "duration": 2.5,
  "processing_time": 0.8,
  "engine": "whisper",
  "model": "openai_whisper-large-v3_turbo"
}

Optional Parameters

language - ISO 639-1 code (e.g., en, de). Omit for auto-detection.
task - transcribe (default) or translate (to English, WhisperKit only).
target_language - ISO 639-1 code for translation target language (e.g., de, fr). Used with Apple Translate.

List Models

# Get available models

curl http://localhost:8978/v1/models

{
  "models": [
    {
      "id": "openai_whisper-large-v3_turbo",
      "engine": "whisper",
      "ready": true
    }
  ]
}

History

# Search history

curl "http://localhost:8978/v1/history?q=meeting&limit=10&offset=0"

# Delete a history entry

curl -X DELETE "http://localhost:8978/v1/history?id=<uuid>"

Rules

# List all rules

curl http://localhost:8978/v1/rules

# Toggle a rule on or off

curl -X PUT "http://localhost:8978/v1/rules/toggle?id=<uuid>"

Legacy compatibility: /v1/profiles and /v1/profiles/toggle remain available as aliases for older integrations.

Dictation Control

# Start dictation

curl -X POST http://localhost:8978/v1/dictation/start

# Stop dictation

curl -X POST http://localhost:8978/v1/dictation/stop

# Check dictation status

curl http://localhost:8978/v1/dictation/status

Error Responses

The API returns standard HTTP status codes with a JSON error body:

{
  "error": "No model loaded",
  "code": "MODEL_NOT_LOADED"
}

Common Error Codes

400 - Missing or invalid file input, unsupported audio format, or invalid parameter value.
503 - No model is currently loaded.
500 - Internal transcription error. Check the app's logs or diagnostics export for more detail.