One system.
Four ways in.

Request and response envelopes

{
  "id": "client-generated-id",
  "method": "query",
  "resource": "current-show",
  "parameters": { "limit": 50 },
  "callbackURL": "https://automation.example/sybilsight/result",
  "callbackHeaders": { "X-Request": "client-generated-id" }
}

method is one of discover, query, action, schedule, poll, subscribe, or unsubscribe. Query requests set resource; action requests set action. IDs are echoed unchanged.

{
  "type": "integration_response",
  "requestId": "client-generated-id",
  "ok": true,
  "result": { /* resource or action result */ },
  "timestamp": "2026-07-31T18:45:00.000Z"
}

Failures set ok: false and include error.code, error.message, and optional structured error.details. Additive fields may appear; integrations should ignore fields they do not recognize.

Queryable resources

Controllable actions

Actions are deliberately limited to app-owned, automation-safe controllers. They do not expose bearer tokens, saved credentials, raw Keychain records, arbitrary filesystem access, or unrestricted process execution.

Cloud endpoint

wss://api.sybilsight.com/glasses-ws

Local endpoint

ws://127.0.0.1:8766/v1/ws

Envelope

{ "type": "…" }

Liveness

ping every 15 seconds

Connect to the cloud channel

Derive the socket from the configured backend by converting https to wss (or http to ws) and replacing the path with /glasses-ws. The iOS client sends these query items:

wss://api.sybilsight.com/glasses-ws?token=CORE_TOKEN&livekit=true&udpEncryption=true

Connect to the local universal channel

The loopback socket is designed for a trusted utility or agent on the same device. Pass the Integration API token in the socket query, then exchange the universal request and response envelopes from the shared contract. The listener binds only to 127.0.0.1.

ws://127.0.0.1:8766/v1/ws?token=ssapi_REDACTED

→ request
{ "id": "shows-1", "method": "query", "resource": "shows" }

← response
{ "type": "integration_response", "requestId": "shows-1", "ok": true, "result": [ … ] }

Send { "method": "subscribe" } to receive pushed integration_event frames, and { "method": "unsubscribe" } to stop them. Request execution events include the source, request ID, method, resource or action name, success state, and timestamp.

{
  "type": "display_event",
  "view": "text",
  "packageName": "com.example.integration",
  "durationMs": 5000,
  "layout": {
    "text": "The spectator chose the seven of hearts."
  }
}

Client → cloud messages

Binary frames carry encoded microphone audio when the negotiated UDP path is not yet ready. The client prefers UDP after registration and probe acknowledgement.

Cloud → client messages

Recovery behavior

Socket failures, malformed incoming envelopes, missed pongs, and server connection errors trigger reconnect. The delay follows an exponential curve with a one-second floor, a 60-second cap, and jitter. A valid connection_ack resets the curve. Manual disconnect cancels recovery.

# Query running apps
curl "http://127.0.0.1:8766/v1/query/running-apps" \
  -H "Authorization: Bearer $SYBILSIGHT_API_TOKEN"

# Fire the next show cue
curl -X POST "http://127.0.0.1:8766/v1/actions/show/control" \
  -H "Authorization: Bearer $SYBILSIGHT_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"command":"go"}'

Local routes

Requests are capped at 1 MiB. Responses use the universal envelope, include Cache-Control: no-store, and return 401 for a missing or invalid token. CORS preflight is supported for a same-device browser utility, but bearer authentication is still required.

Existing cloud client API

Older cloud resources commonly use { "success": true, "data": … }; newer v2 photo and managed-stream resources return their payload directly. Follow the shape shown for the endpoint.

Core cloud resources

Apps and settings

Photos and managed streams

Feedback, incidents, and account lifecycle

Routine HTTP integrations

For performer-configured web services, a routine can send or receive data without using the cloud client endpoints above:

• Default output: an HTTP(S) output sends { "value": "…" } as JSON with POST.
• GET output: prefix the template with get ; Sybil Sight removes the prefix and fetches the resolved URL.
• Reusable integrations: Settings → Integrations can poll a configured URL, extract a chosen JSON key or bare response, and optionally write with JSON or form encoding.
• Substitution: {value} and configured field placeholders are percent-encoded before insertion.

# JSON POST
https://example.com/reveal
# body: {"value":"seven of hearts"}

# Plain GET with encoded substitution
get https://example.com/reveal/{value}

# initialize
{ "jsonrpc": "2.0", "id": 1, "method": "initialize",
  "params": { "protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": { "name": "stage-agent", "version": "1" } } }

# tools/call
{ "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": { "name": "sybilsight_query",
    "arguments": { "resource": "tasks" } } }

initialize, notifications/initialized, ping, tools/list, and tools/call are implemented. Tool results contain both text JSON and structuredContent, so an MCP client can inspect fields without reparsing display text.

Pre-registered Siri phrases

Apple limits each app to ten pre-registered App Shortcuts. The standard Sybil Sight build uses the curated set below; every other action remains available in the Shortcuts editor.

Universal automation actions

Parameters JSON accepts the same object used by WebSocket and Web API calls. For example, choose Control SybilSight, select Show Control, and pass { "command": "go" }. This keeps new catalog actions usable from Shortcuts without adding a bespoke intent for every parameter combination.

iOS 27 Siri and system discovery

Resources and actions conform to AppEntity and IndexedEntity, have stable identifiers and searchable summaries, and are proactively indexed with Core Spotlight at app startup. The generic Query and Control intents accept those entities directly, while the curated App Shortcuts provide natural-language entry phrases. On iOS 27, the universal intents explicitly target the main app process so they can reach the live app model. Together these hooks give Siri a discoverable entity/action graph in addition to every existing typed intent.

Sybil Sight’s show-control and mentalism concepts are a custom domain, so the app uses custom App Intents and indexed entities for the universal catalog. Apple App Schemas should be adopted only when an action semantically matches an Apple-defined domain; declaring a mismatched system schema would make Siri behavior less reliable.

All Shortcuts actions

Start a routine with pre-filled anchors

The Start Routine action accepts a main value, an anchor to open immediately, and newline- or semicolon-separated name=value pairs. Only slots declared by the routine are accepted.

name=Sarah Jane
city=Hilo
sign=Scorpio

The action returns true when delivered, or false with a performer-readable reason such as “routine is not armed,” so the Shortcut can branch safely.

Universal API routes

sybilsight://api/query/current-show?requestId=show-1

sybilsight://api/action/show.control?command=go&requestId=go-1

sybilsight://api/query/tasks\
?callback=stageutility%3A%2F%2Fsybilsight-result\
&requestId=tasks-1

The route is api/query/{resource} or api/action/{dot-separated-action}. Query items are type-inferred as Boolean, number, JSON, or string. A percent-encoded parameters JSON object can supply nested values and overrides same-name scalar query items.

When callback or callbackURL is present, Sybil Sight opens that URL with requestId, ok=1|0, and either result or error. The result/error value is a Base64-encoded universal response JSON document.

Complete envelope route

For nested parameters, schedules, polls, or a client-generated callback envelope, encode the universal request JSON as Base64URL (replace + with -, / with _, and omit padding):

sybilsight://api/request?payload=BASE64URL_ENCODED_REQUEST_JSON

Compact legacy links

sybilsight://peek?value=seven%20of%20hearts&seconds=5
sybilsight://shows/go
sybilsight://notify?text=Your%20next%20table%20is%20ready

Peeks and display

Apps, assistant, and translation

Shows and routines

sybilsight://routine/8F4A0000-0000-0000-0000-0000000000C2\
?value=Scorpio\
&anchor=birthday\
&set.city=Hilo\
&set.name=Sarah%20Jane

The token is generated by a routine’s App link start trigger. The routine must be armed, unknown set. keys are ignored, and anchor names match case-insensitively.

Navigation routes

These routes bring the app to a screen: home, settings, glasses, assistant, terminal, mirror, mirror/fullscreen, mirror/display-regions, miniapps/gallery, degrees/actors, and degrees/wikipedia. Links received during launch or onboarding are parked and replayed after the authenticated home screen is ready.

On demand versus scheduled

curl -X POST "http://127.0.0.1:8766/v1/polls" \
  -H "Authorization: Bearer $SYBILSIGHT_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "Current task watcher",
    "resource": "tasks",
    "intervalSeconds": 5,
    "changedOnly": true,
    "callbackURL": "https://automation.example/sybilsight/task"
  }'

Schedule object

A schedule contains a nested universal request, an ISO 8601 runAt, optional interval and run count, optional callback URL and headers, and a name. For convenience, schedule creation also accepts top-level action and parameters. Poll creation accepts top-level resource and query parameters.

{
  "method": "schedule.create",
  "parameters": {
    "name": "Keep captions ready",
    "action": "captions.start",
    "parameters": {},
    "runAt": "2026-07-31T23:00:00Z",
    "intervalSeconds": 900,
    "repeatCount": 4
  }
}

Callback delivery

Any immediate Web, WebSocket, App Intent, MCP, schedule, or poll request can carry callbackURL and optional callbackHeaders. Sybil Sight sends the universal response as an application/json POST with a 15-second timeout. Only HTTPS URLs, or HTTP on 127.0.0.1, localhost, or ::1, are accepted. URLs with embedded credentials are rejected.

Custom headers are forwarded except Host, Content-Length, Transfer-Encoding, and Proxy-*. A 2xx response marks delivery successful. Delivery success/failure appears in the event stream, while callback URLs are redacted in stored events.

Encoding

All WebSocket and Web API text payloads are UTF-8 JSON. URL-scheme query values and routine URL substitutions must be percent-encoded. In particular, encode spaces, ampersands, hashes, percent signs, slashes inside path values, and any user-provided text.

Identifiers

Package names are stable reverse-DNS strings such as com.sybilsight.peek_text. Routine App-link tokens and request IDs are opaque: copy them exactly and do not derive meaning from them.

Action versus navigation

Control links such as shows/go, peek/clear, and brightness are action-only and intentionally leave the performer on the current screen. Screen routes replace or extend the app’s navigation path.

Errors and retries

Local API failures use a stable machine-readable error code such as invalid_request, unknown_resource, unknown_action, missing_argument, not_found, or app_unavailable. Cloud Web API requests accept any 2xx response as transport success, then validate the endpoint’s response shape. A cloud response indicating NO_ACTIVE_SESSION causes one session recovery attempt and one request retry. WebSocket reconnect is automatic and bounded; callers should not add an aggressive retry loop.

Versioning

The universal contract reports apiVersion: "1.0" through discovery. Ignore additive JSON fields you do not understand, preserve opaque identifiers, and discover capabilities at startup. For cloud compatibility, also check /api/client/min-version. Validate critical show workflows against the exact app build you will perform with.