HTTP API: Add endpoints to manage and query connection status

[brianegge]

Summary

The HTTP Remote Control API currently supports button presses, styling, variables, and surface rescanning, but has no endpoints to manage or query connection status.

Use Case

In automated/headless environments (e.g., Companion running as a container on a server), it's useful to programmatically check whether a module connection is active and trigger a reconnect without opening the web UI.

For example, after restarting ProPresenter on a remote machine, there's no HTTP API way to:

1. Check if the Companion module has reconnected
2. Trigger a reconnect if it hasn't
3. List all connections and their current status (connected/disconnected/error)

The only option today is to open the web UI and manually interact with the Connections page.

Proposed Endpoints

Endpoint	Method	Description
/api/connections	GET	List all connections with their current status
/api/connections/:id/status	GET	Get status of a specific connection
/api/connections/:id/reconnect	POST	Trigger a reconnect for a specific connection
/api/connections/:id/enable	POST	Enable a connection
/api/connections/:id/disable	POST	Disable a connection

Environment

• Companion v4.2 running as a container (ghcr.io/bitfocus/companion/companion)
• Managing connections to ProPresenter, ATEM, X32, PTZ cameras
• HTTP API is enabled with http_api_enabled: true

[brianegge]

Update: Found the root cause of our disconnection — it wasn't a missing API feature, just a port mismatch. But the debugging experience reinforces the need for this feature request.

Debugging without connection management APIs

After restarting ProPresenter, Companion showed the module as disconnected. With no HTTP API to query connection status or view error details, we had to:

1. Check container logs (no errors logged — the module just went silent after loading config)
2. Verify TCP connectivity from inside the container (succeeded)
3. Manually probe all ProPresenter listening ports to discover the REST API had moved from port 50490 to 50242

With the proposed /api/connections/:id/status endpoint, we could have immediately seen the connection error and diagnosed the port mismatch without needing shell access to the container.

Root cause

ProPresenter's REST API port changed (50490 → 50242), likely after a ProPresenter update. The Companion module connected at the TCP level but the protocol handshake failed silently — port 50490 speaks the legacy stage display protocol, not HTTP/REST.

[Julusian]

I'm not opposed to these endpoints, it just requires someone to do it.

I suspect a /api/connections/:id/reconnect endpoint isn't possible in the current system, we don't have a way to tell modules to do this currently. Instead we expect them to attempt to keep a connection open at all times. Maybe there could be a a /restart endpoint though as a shortcut for disabling and enabling the connection. While heavier, this is probably safer than asking a module to reconnect anyway, if they need to be told to reconnect then their connection management could well be flawed.

With the proposed /api/connections/:id/status endpoint, we could have immediately seen the connection error and diagnosed the port mismatch without needing shell access to the container.

What did the connections page inside of Companion show? Or the module debug log (accessible from that page)?

I'm not opposed to adding a /api/connections/:id/status endpoint, but it will almost certainly directly mirror the data we already show inside of companion. Getting any more detail out of modules will require them to opt into that, meaning it likely wont happen for most modules, I don't expect many modules to implement it until asked, and even then the details will likely not be useful for much debugging.

the REST API had moved from port 50490 to 50242

tbh both those port numbers look pretty suspicious to me. Firmly in the range of the ephemeral ports, so if they are correct then it could be that pro-presenter changed what port they use, or the one in use could have clashed with a short-lived connection so the application switched to a different port.

[brianegge]

ProPresenter uses ports in the ephemeral range. I had their old 'remote control' API and updated it to their REST API. The logs in companion were confusing and the destination port was open.

I was using Claude to troubleshoot the issue, though I didn't try to have it use the browser. Eventually, it fixed it by updating the sqlite database:

podman unshare sqlite3 /home/ubuntu/companion-data/v4.2/db.sqlite "UPDATE connections SET value = json_set(value, '$.config.port', 50242) WHERE id = 'sFxBbbDJeSfgpNA6-s4';" 2>&1 && podman unshare sqlite3 /home/ubuntu/companion-data/v4.2/db.sqlite "SELECT json_extract(value, '$.config.port') FROM connections WHERE id='sFxBbbDJeSfgpNA6-s4';"

[peternewman]

Shouldn't this be linked to/closed by #4048 @Julusian ? It seems @claw-explorer was clever enough to link to the issue, but managed to tag it as Implements rather than closes, hence it's still unlinked and open... 🤦