JSON-RPC 2.0 over WebSocket

Connect third-party tooling to FreeCORE 15.1 using JSON-RPC 2.0, alongside the inherited WebSocket protocol.

FreeCORE 15.1 accepts JSON-RPC 2.0 over WebSocket in addition to the message-based WebSocket protocol inherited from TrueNAS CORE 13.3.

Use it to connect third-party tooling that speaks JSON-RPC 2.0, such as monitoring applications. The existing protocol is unchanged: the FreeCORE web interface, midclt and existing clients keep speaking it.

Endpoints

Point a JSON-RPC client at /api/current. The autodetection on /websocket exists so that a client that only knows the older path still works.

Authenticate

Call an authentication method before anything else. FreeCORE accepts:

• auth.login_with_api_key — an API key created under Settings > API Keys.
• auth.login — user name and password.
• auth.token — an existing session token.

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

A successful reply carries "result": true. Any other call before authentication returns an error rather than data.

FreeCORE does not provide auth.login_ex. A client that requires it cannot be supported by configuration; it needs a fallback to one of the methods above.

Call a method

{"jsonrpc": "2.0", "id": 2, "method": "system.info", "params": []}

Method names, parameters and results are FreeCORE's own — the same ones the inherited protocol and the REST API expose. This feature is protocol compatibility, not API parity with a different product: a method that FreeCORE does not implement is not reachable over JSON-RPC either.

Only positional parameters are accepted. params must be an array or absent; an object is rejected with -32602.

Batch requests are not supported. An array at the top level is rejected with -32600.

Subscribe to events

{"jsonrpc": "2.0", "id": 3, "method": "core.subscribe", "params": ["reporting.realtime"]}

The server then sends collection_update notifications until the client calls core.unsubscribe with the subscription id returned by core.subscribe. core.set_options is also available.

Errors

Standard JSON-RPC codes are used for protocol problems: -32700 invalid JSON, -32600 invalid request, -32601 unknown method, -32602 invalid parameters, -32603 internal error.

Two implementation-defined codes carry the rest:

Related

• API Reference