Protocol overview

The S3 Lens application protocol is a revisioned, typed JSON-RPC 2.0 protocol. Revision 1 is the current revision. It is shared by the browser, desktop shell, first-party TypeScript client, and third-party consumers.

Endpoints

Route	Purpose
GET /rpc	Upgrade to the preferred WebSocket transport.
POST /rpc	Send one stateless JSON-RPC request or notification over HTTP.
GET /healthz	Process liveness probe.
GET /readyz	Listener readiness probe.
/transfers/{ticket}	Redeem a single-use Object download or upload ticket.

Batch requests are not supported. WebSocket text frames and HTTP request bodies each contain exactly one complete JSON-RPC message. WebSocket binary frames are rejected.

Initialize a WebSocket

Every WebSocket must begin with initialize. Other requests sent before a successful initialization receive -32600 Invalid Request; pre-initialization notifications are discarded because notifications cannot receive errors.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolRevision": 1,
    "clientInfo": {
      "name": "example-client",
      "version": "1.0.0"
    },
    "capabilities": {}
  }
}

A successful result confirms the negotiated revision and returns server, Workspace, and capability information:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolRevision": 1,
    "serverInfo": {
      "name": "s3lens-server",
      "version": "0.0.0"
    },
    "workspace": {
      "id": "default",
      "displayName": "Default Workspace"
    },
    "capabilities": {
      "batchRequests": false,
      "streamingTransfers": true,
      "apiKeys": false,
      "objectCopy": true
    }
  }
}

Treat identity strings as diagnostic and presentation metadata. Provider IDs, Bucket names, cursors, Object keys, version IDs, upload IDs, and transfer URLs are opaque values; send them back unchanged.

HTTP fallback

HTTP calls are stateless and do not require prior initialization. They use the same typed dispatcher and response envelopes as WebSockets.

curl --fail \
  --header 'content-type: application/json' \
  --data '{"jsonrpc":"2.0","id":2,"method":"server/ping","params":{}}' \
  http://127.0.0.1:8085/rpc

Notifications omit id and never receive a JSON-RPC response. server/ping is the only revision 1 method with meaningful notification semantics. Its successful HTTP notification response is 204 No Content.

When an authenticated server enables API Keys, native applications can attach an issued s3l_ak_… credential as Authorization: Bearer … on HTTP requests or the WebSocket upgrade. The server revalidates a WebSocket credential before every frame, so revocation and expiration take effect without reconnecting. API Key management methods require an interactive browser or native session and reject API Key credentials.

Typical client flow

1. Connect to /rpc over WebSocket.
2. Send initialize with protocolRevision: 1.
3. Call provider/list and let the user select a configured Provider.
4. Call bucket/list with that Provider ID.
5. Call object/list, passing nextCursor back unchanged until it is absent.
6. Use bounded RPC methods for metadata and previews; use transfer tickets for streaming Object bytes.

Continue with the revision 1 reference or errors and transfers.