Zum Hauptinhalt springen

HTTP API

FreezeText provides a local HTTP API for automation and integration with other applications. The API must be enabled in settings under API.

Setup

  1. Open Settings → API
  2. Enable Enable API server
  3. Optional: Generate an API token for authentication
  4. The server is available at http://localhost:9876

Authentication

If an API token is configured, every request must include the token as a Bearer token in the Authorization header:

Authorization: Bearer <your-token>

Endpoints

Capture & OCR

EndpointMethodDescription
/statusGETServer status, version, history count
/captureGET/POSTStart text capture
/capture/cancelPOSTCancel ongoing capture
/capture/regionPOSTCapture and OCR a specific screen region
/ocrPOSTPerform OCR on a provided image
/ocr/languagesGET/PUTGet/update OCR languages

History

EndpointMethodDescription
/historyGETList all entries (filter by color, sorting)
/history/search?q=GETFull-text search in history
/historyPOSTAdd new entry
/history/:idGETGet single entry
/history/:idPUTUpdate entry text
/history/:idDELETEDelete entry
/historyDELETEClear all entries
/history/:id/screenshotGETGet entry screenshot
/history/export/jsonGETExport history as JSON
/history/export/csvGETExport history as CSV

Settings & UI

EndpointMethodDescription
/settingsGET/PUTGet/update settings
/hotkeyGET/PUTGet/update hotkey
/hotkey/resetPOSTReset hotkey to default
/preferencesGET/POSTOpen preferences window (optional tab parameter)
/sidebarGETSidebar visibility state
/sidebar/showPOSTShow sidebar
/sidebar/hidePOSTHide sidebar
/sidebar/togglePOSTToggle sidebar visibility
/aboutGET/POSTShow About window
/onboardingGET/POSTShow onboarding wizard

Screenshots & Windows

EndpointMethodDescription
/windowsGETList all visible FreezeText windows
/screenshotGETCapture FreezeText windows as PNG
/screenGETFull screen capture as PNG
/sidebar/screenshotGETCapture sidebar as PNG
/displaysGETList all connected displays
/permissionsGETPermission status (Screen Recording, Accessibility)

Mouse & Keyboard (requires Accessibility permission)

EndpointMethodDescription
/mouse/positionGETCurrent mouse position
/mouse/movePOSTMove mouse cursor
/mouse/clickPOSTPerform mouse click
/mouse/dragPOSTPerform drag operation
/keyboard/typePOSTType text character by character
/keyboard/keyPOSTPress single key
/keyboard/hotkeyPOSTPress key combination

Miscellaneous

EndpointMethodDescription
/legal/:typeGETLegal texts (impressum, terms, privacy, accessibility)
/logsGET/DELETEGet/clear logs
/docsGETSwagger UI documentation
/openapi.jsonGETOpenAPI specification
/quitPOSTQuit application

Example

# Start text capture via API
curl http://localhost:9876/capture

# Get history
curl http://localhost:9876/history

# With authentication
curl -H "Authorization: Bearer my-token" \
     http://localhost:9876/history