OpenSS Local Engine API

A local integration surface

The OpenSS Local Engine API is an authenticated REST API served by the OpenSS process on your Mac. It connects a desktop or localhost browser interface to capture, OCR, chat, provider configuration, history and selected account-backed operations.

Contract at a glance

The supported workflow

1. 01
   Start the engine

   Run openss gui or launch the desktop app. The engine binds to 127.0.0.1 and chooses an available port.

2. 02
   Check compatibility

   Call GET /api/version before using protected routes. This exposes desktopVersion, engineVersion and apiVersion without account data.

3. 03
   Exchange the launch token

   Send the launch token supplied by the local launch flow to POST /api/session/exchange. Keep the returned session token in memory.

4. 04
   Capture locally

   Call POST /api/screenshots/capture. The engine captures a supported window, runs OCR and returns a temporary screenshot ID.

5. 05
   Stream an answer

   POST the screenshot ID and an instruction to /api/chat/stream, then consume delta events until the final done event.

6. 06
   Release the resource

   Delete the screenshot with DELETE /api/screenshots/{screenshot_id} when the analysis is finished. The engine also expires temporary captures after 30 minutes.

What else is exposed

• System: /api/ping, /api/version and authenticated /api/health.
• Providers and models: /api/providers, /api/providers/status, /api/providers/validate, /api/providers/key, /api/models and /api/models/default.
• Chat and history: /api/chat, /api/chat/stream, /api/chat/cancel, /api/chats and /api/history.
• Settings and diagnostics: /api/settings, /api/doctor, /api/diagnostics and capture or permission settings.
• Meetings: a proxy surface under /api/meetings for account-backed meeting workflows; it is outside this quickstart.

Implementation source

The reference is maintained from the FastAPI server and Pydantic request schemas in OpenSS/src/openss/gui/server.py and OpenSS/src/openss/gui/schemas.py. When source and an older example disagree, the current engine behavior is authoritative.