HTTP & WebSocket

POST /api/cli/command

Create an access token in account settings and send it as a Bearer token. Never put it in a URL or client-side storage. The CLI authorization-code flow uses a one-use code and PKCE; browser cookies are not bearer tokens.

curl --request POST http://localhost:8080/api/cli/command \
  --header "Authorization: Bearer $BIBLEIT_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"command":"PING"}'

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8

OK pong=true

A valid dispatched command returns HTTP 200 with text/plain protocol output, including domain ERR responses. Missing or invalid tokens return 401; a missing username returns 403; invalid commands and SSH-only subscriptions return 400. Inspect both HTTP status and the response envelope.

WebSocket /ws?live=<id>

Connect to /ws?live=LIVE_ID for viewer events, using the Live cookie when a secret is required. A push command additionally requires a valid browser session, live.update, and access to that Live. Text command frames are limited to 4 KiB. Successful pushes return push_result; failures return error with a code.

{"type":"push","reference":{"translation":"WEB","book":19,"chapter":23,"verse":1}}

{
  "type": "push_result",
  "live": "demoLive01",
  "verse": {
    "translation": "web", "book": "Psalms",
    "chapter": 23, "verse": 1,
    "reference": "Psalms 23:1",
    "text": "The LORD is my shepherd; I shall lack nothing.",
    "publisher_id": "demo-account", "sequence": 1,
    "translations": [{
      "translation": "web", "book": "Psalms",
      "chapter": 23, "verse": 1,
      "reference": "Psalms 23:1",
      "text": "The LORD is my shepherd; I shall lack nothing."
    }]
  }
}

{"type":"error","live":"demoLive01","code":"invalid_reference"}
{"type":"clear","live":"demoLive01"}
{"type":"paused","live":"demoLive01"}
{"type":"closed","live":"demoLive01"}