HTTP Endpoints

Base URL: http://<host>:7200

---

POST /rpc — JSON-RPC Gateway

All automation commands (except SSE streaming) go through this endpoint.

POST /rpc HTTP/1.1
Content-Type: application/json

{"jsonrpc":"2.0","method":"<method>","params":[...],"id":1}

Response	Condition
HTTP 200 + JSON result	Success
HTTP 200 + JSON error object	JSON-RPC error
HTTP 204	Method returned no value

---

GET /events — Server-Sent Events

Real-time push stream for incoming messages, delivery receipts, join progress, and Privitty events.

GET /events HTTP/1.1
Accept: text/event-stream

Example event:

data: {"type":"IncomingMsg","account_id":1,"chat_id":7,"msg_id":42}

• Keepalive : ping comment every 15 seconds
• event: lag emitted if the client falls behind

Full event list: SSE Events

---

GET /health — Liveness Probe

curl -s http://127.0.0.1:7200/health

{
  "status": "ok",
  "service": "privitty-edged",
  "version": "0.1.0"
}

Used by Docker HEALTHCHECK, Kubernetes probes, and load balancers.

---

POST /auth — Viewer Authentication

Binds a privitty-viewer session. Requires the device fingerprint (SHA-256 of MAC + machine-id).

POST /auth HTTP/1.1
Content-Type: application/json

{"device_fingerprint":"<sha256-hex>"}

Success (200):

{"token":"a3f1c9…","expires_in":3600}

Error (403):

{"error":"Device fingerprint mismatch"}

Only one viewer session is active at a time.

---

GET /stream/:msg_id — Secure File Stream

Decrypts a .prv attachment and streams plaintext bytes. Requires a valid Bearer token from /auth.

GET /stream/42 HTTP/1.1
Authorization: Bearer <token>

Status	Condition
200	File streamed (Content-Type detected by magic bytes)
401	Missing, expired, or invalid token
404	Message or file not found
500	Decryption failed

The file is never written to disk in plaintext on the server.

---

CORS

CORS headers are disabled by default. Enable with the --cors daemon flag for web-based HMI frontends:

command: ["--listen", "0.0.0.0:7200", "--accounts", "/var/lib/privitty", "--cors"]