http://127.0.0.1:4649 by default. All endpoints are under /api unless noted otherwise.
Plugin UI pages should use
window.freestyle.api() instead of calling these endpoints directly. The bridge handles authentication and sandboxing automatically. See the SDK reference.Health and diagnostics
| Method | Path | Description |
|---|---|---|
GET | /api/health | Health check. Returns { "status": "ok", "name": "freestyle" }. |
GET | /api/device-id | Return the anonymous telemetry device id: { "deviceId": "..." }. |
POST | /api/telemetry | Record a renderer-side product event. Body: { event, properties? }. Honors the telemetry opt-out and DO_NOT_TRACK. |
POST | /api/client-error | Report a renderer crash/error for local logging (and PostHog when telemetry is on). Body: { message, stack?, source?, context? }. |
Settings
| Method | Path | Description |
|---|---|---|
GET | /api/settings | List all settings as a { key: value } map. |
GET | /api/settings/:key | Get a single setting by key. |
PUT | /api/settings/:key | Upsert a setting. Per-key validation for cleanup_intensity, cleanup_custom_prompt, plugins, and disabled_plugins. |
DELETE | /api/settings/:key | Delete a setting. |
Models
| Method | Path | Description |
|---|---|---|
GET | /api/models/available | List all available models — cloud registry, curated catalog, and local whisper/MLX/LLM. |
GET | /api/models/configured | List user-configured models from DB (voice + LLM), ordered by type and default status. |
POST | /api/models/configured | Add or upsert a model configuration. Body: { provider, model_id, model_name, type, is_default? }. |
PUT | /api/models/configured/:id/default | Set a model config as the default for its type. |
DELETE | /api/models/configured/:id | Delete a model configuration. |
Transcription
| Method | Path | Description |
|---|---|---|
POST | /api/transcribe | Main transcription endpoint. Accepts audio as multipart form data or raw binary. Transcribes via configured voice provider and optionally runs LLM cleanup. Headers: x-app-context (JSON), x-audio-duration-ms, x-skip-post-process. |
POST | /api/post-process | Run LLM cleanup on text independently. Body: { text, appContext?, language? }. |
Dictionary
Post-transcription text replacements. Say the key, get the value.| Method | Path | Description |
|---|---|---|
GET | /api/dictionary | List entries with pagination and search. Query: limit, offset, search, orderBy. |
GET | /api/dictionary/all | Get all entries ordered by key length DESC (for matching). |
GET | /api/dictionary/:id | Get a single entry. |
POST | /api/dictionary | Create an entry. Body: { key, value }. Returns 409 on duplicate key. |
PUT | /api/dictionary/:id | Update an entry. |
DELETE | /api/dictionary/:id | Delete an entry. |
POST | /api/dictionary/export | Export as JSON. Body: { type: "json" }. |
POST | /api/dictionary/import | Import entries. Body: array of { key, value }. Uses INSERT OR IGNORE, returns { imported, skipped }. |
Vocabulary
Recognition bias terms — help the speech model hear specific words correctly.| Method | Path | Description |
|---|---|---|
GET | /api/vocabulary | List terms with pagination and search. |
GET | /api/vocabulary/all | Get all terms ordered by length DESC (for ASR injection). |
GET | /api/vocabulary/:id | Get a single term. |
POST | /api/vocabulary | Create a term. Body: { term, notes? }. Returns 409 on duplicate. |
PUT | /api/vocabulary/:id | Update a term. |
DELETE | /api/vocabulary/:id | Delete a term. |
POST | /api/vocabulary/export | Export as JSON. Body: { type: "json" }. |
POST | /api/vocabulary/import | Import terms. Body: array of { term, notes? }. Returns { imported, skipped }. |
Formats
Output formatting rules matched by the app you’re typing in.| Method | Path | Description |
|---|---|---|
GET | /api/formats | List format rules with pagination and search. |
GET | /api/formats/:id | Get a single format rule. |
GET | /api/formats/match | Context-aware format matching. Query: context. Returns matching rule or null. User rules take priority over defaults. |
POST | /api/formats | Create a format rule. Body: { app_pattern, label, instructions }. |
PUT | /api/formats/:id | Update a format rule. |
DELETE | /api/formats/:id | Delete a format rule. |
POST | /api/formats/reset | Reset to defaults. Deletes all user-created rules. |
History
| Method | Path | Description |
|---|---|---|
GET | /api/history | List transcription history with pagination, search, date filtering, and sort. Query: limit, offset, search, start_date, end_date, orderBy. |
GET | /api/history/stats | Aggregate stats: total sessions, duration, tokens, cost, words, today’s stats. Optional date range. |
GET | /api/history/:id | Get a single history entry. |
DELETE | /api/history/:id | Delete a single history entry. |
DELETE | /api/history | Clear all transcription history. |
Plugins
| Method | Path | Description |
|---|---|---|
POST | /api/plugins/reload | Reload server-side plugin registry. Re-reads settings and re-runs setup(). |
GET | /api/plugins/catalog | Return the plugin catalog from the cloud registry. |
POST | /api/plugins/install | Install a plugin from npm. Body: { npmName, version? }. Downloads, stages atomically, adds specifier, and reloads. |
POST | /api/plugins/uninstall | Uninstall a plugin. Body: { specifier }. Removes package and specifier. |
POST | /api/plugins/check-updates | Check for updates against npm. Body: { plugins: [{ name, currentVersion }] }. |
Auth (Freestyle Cloud)
| Method | Path | Description |
|---|---|---|
GET | /api/auth/status | Current auth status and user info. |
POST | /api/auth/device/code | Request a device authorization code for Freestyle Cloud sign-in. |
POST | /api/auth/device/token | Poll for device token. On success, sets session and applies cloud defaults. |
POST | /api/auth/sign-out | Sign out from Freestyle Cloud. |
Cloud usage
| Method | Path | Description |
|---|---|---|
GET | /api/usage | Fetch Freestyle Cloud usage and balance. Requires active cloud session. |
Local models (Whisper)
| Method | Path | Description |
|---|---|---|
GET | /api/whisper/status | Full local Whisper status: binary availability, server state, model statuses, definitions. |
POST | /api/whisper/models/:model/download | Start downloading a Whisper model. |
POST | /api/whisper/models/:model/cancel | Cancel an in-progress download. |
DELETE | /api/whisper/models/:model | Delete a downloaded model. |
POST | /api/whisper/server/start | Start the local Whisper server. Body: { modelId? }. |
POST | /api/whisper/server/stop | Stop the local Whisper server. |
Local models (MLX ASR)
Apple Silicon only.| Method | Path | Description |
|---|---|---|
GET | /api/mlx-asr/status | Full MLX ASR status: platform support, Python availability, model statuses, setup hints. Query: refresh=1 to re-probe. |
POST | /api/mlx-asr/models/:model/download | Start downloading an MLX model. |
POST | /api/mlx-asr/models/:model/cancel | Cancel an in-progress download. |
DELETE | /api/mlx-asr/models/:model | Delete a downloaded model. |
POST | /api/mlx-asr/server/start | Start the local MLX ASR server. Body: { modelId? }. |
POST | /api/mlx-asr/server/stop | Stop the local MLX ASR server. |