Reference

Endpoint reference

A focused reference for the supported system, session, screenshot and chat routes.

Updated 29 July 2026Local API · v1 contract

On this page

Conventions System and session Screenshots Chat Hosted AI Providers and models History and chat context Core request fields

Conventions

Paths are relative to the dynamically assigned local origin, for example http://127.0.0.1:53142. Unless an endpoint is marked Bootstrap, send X-OpenSS-Session. JSON error responses use the same envelope across the local server.

System and session

GET/api/ping

Check that the process responds.

AuthBootstrap

Response

JSON

{"ok":true}

GET/api/version

Read the desktop, engine and local API versions.

AuthBootstrap

Response

JSON

{"desktopVersion":"0.2.8","engineVersion":"0.2.8","apiVersion":1}

POST/api/session/exchange

Exchange a one-time local launch token for a session token.

AuthBootstrap

Request

JSON

{"launchToken":"<one-time-launch-token>"}

Response

JSON

{"sessionToken":"<session-token>"}

Common errors401 INVALID_LAUNCH_TOKEN

GET/api/health

Read local health, history backend and configured providers.

AuthX-OpenSS-Session

Response

JSON

{"status":"ok","ok":true,"historyBackend":"sqlite","configuredProviders":["openai"]}

Common errors401 INVALID_GUI_SESSION

Screenshots

POST/api/screenshots/capture

Capture a supported target and run local OCR.

AuthX-OpenSS-Session

Request

JSON

{"target":"chrome","fullSlide":false}

Response

JSON

{"screenshotId":"<id>","previewDataUrl":"data:image/png;base64,...","target":"chrome","createdAt":"2026-07-29T12:00:00","ocrText":"..."}

Common errors401 INVALID_GUI_SESSION413 REQUEST_TOO_LARGE400 capture error

DELETE/api/screenshots/{screenshot_id}

Delete a temporary server-owned screenshot.

AuthX-OpenSS-Session

Response

JSON

{"deleted":true}

Common errors404 INVALID_SCREENSHOT_ID

Chat

POST/api/chat

Run a non-streaming local provider request.

AuthX-OpenSS-Session plus provider entitlement when required

Request

JSON

{"message":"Explain this","source":"manual","sessionId":null}

Response

JSON

{"text":"...","provider":"openai","model":"...","sessionId":"...","autocopy":{"mode":"off","kind":null,"text":null}}

Common errors404 INVALID_SCREENSHOT_ID400 SCREENSHOT_REQUIRED

POST/api/chat/stream

Stream incremental model output over Server-Sent Events.

AuthX-OpenSS-Session plus provider entitlement when required

Request

JSON

{"message":"Explain this","source":"manual","screenshotId":null,"sessionId":null}

Response

SSE

text/event-stream; data: {"delta":"..."}\n\ndata: {"done":true,"text":"...","sessionId":"...","autocopy":{...}}

Common errors404 INVALID_SCREENSHOT_ID422 INVALID_REQUEST

POST/api/chat/cancel

Acknowledge cancellation for a request ID.

AuthX-OpenSS-Session

Request

JSON

{"requestId":"request-123"}

Response

JSON

{"cancelled":true,"requestId":"request-123"}

Hosted AI

POST/api/hosted-ai/respond

Proxy an account-authenticated request to OpenSS-hosted AI.

AuthX-OpenSS-Session + X-OpenSS-Account-Token

Request

JSON

{"message":"Explain this","source":"text","modelTier":"mini"}

Response

JSON

{"text":"...","provider":"openss","model":"hosted","sessionId":"...","autocopy":{...}}

Common errors401 ACCOUNT_SIGN_IN_REQUIRED503 HOSTED_AI_UNAVAILABLE

Providers and models

GET/api/providers

List providers, configuration state and masked keys.

AuthX-OpenSS-Session

Response

JSON

{"providers":[{"id":"openai","displayName":"OpenAI","configured":true,"maskedKey":"sk-...","models":[...]}]}

GET/api/models

List supported models and the default model.

AuthX-OpenSS-Session

Response

JSON

{"defaultModel":"...","models":[{"id":"...","supportsVision":true,...}]}

POST/api/models/default

Set the local default model.

AuthX-OpenSS-Session + X-OpenSS-Account-Token when entitlement requires it

Request

JSON

{"model":"<model-id>"}

Response

JSON

{"defaultModel":"<model-id>"}

History and chat context

GET/api/history

List up to 50 recent local sessions.

AuthX-OpenSS-Session

Response

JSON

{"sessions":[{"id":"...","title":"...","lastActive":"..."}]}

GET/api/history/{session_id}

Read messages for a local session.

AuthX-OpenSS-Session

Response

JSON

{"sessionId":"...","messages":[{"role":"user","text":"...","timestamp":"..."}]}

POST/api/chats

Create a local chat record.

AuthX-OpenSS-Session

Request

JSON

{"title":"Research notes"}

Response

JSON

{"chatId":"..."}

Common errors409 HISTORY_DISABLED

Core request fields

Field	Type and limit	Use
launchToken	string, 1–512	One-time bootstrap exchange
target	string or null, max 32	Capture target, for example chrome
fullSlide	boolean	PowerPoint full-slide capture
message	string or null, max 32,000	Current instruction or manual prompt
screenshotId	string or null, max 128	Temporary capture to analyze
sessionId	string or null, max 128	Existing conversation history
modelTier	mini \| luna \| terra \| sol	Hosted model tier when applicable
source	manual \| capture \| voice	How the request originated
chatContext	string or null, max 4,000	Pro-only persistent context path

Contract source: OpenSS/src/openss/gui/server.py and schemas.py.