Remote Servers

Multi-server management - add, connect, and proxy to peer panels.

All endpoints below are mounted under /api. Authentication: Authorization: Bearer <token> unless noted as public.

Endpoint count: 3

Endpoints

Method	Path	Handler	Guards
DELETE	/api/remote-servers/:id	deleteRemoteServer	RequirePermission(db, "administrative_operations"), RequirePlugin(db, "multi-panel")
PUT	/api/remote-servers/:id	updateRemoteServer	RequirePermission(db, "administrative_operations"), RequirePlugin(db, "multi-panel")
POST	/api/remote-servers/:id/check	checkRemoteServerHealth	RequirePermission(db, "administrative_operations"), RequirePlugin(db, "multi-panel")

Source

Handlers for this section live in api/routes/handlers_*.go in the StarkOne source. Each handler binds its request body with gin.ShouldBindJSON(&req) and responds with the standard envelope:

{ "data": { ... } }

On error:

{ "error": { "code": "string", "message": "string" } }

Reference

DELETE /api/remote-servers/:id

Removes a remote server record from the local panel's remote_servers table.

Guards: RequirePermission(db, "administrative_operations"), RequirePlugin(db, "multi-panel")

Path parameters

Name	Type	Description
id	integer	Numeric ID of the remote server row to delete.

Response - 200 OK

{ "data": { "message": "Server removed" } }

Errors

Status	Code	Meaning
404	-	No remote server matched the given id (zero rows affected). The error object carries only message: "Server not found".
500	-	The DELETE query failed; message contains the underlying database error.

Side effects

• Deletes the matching row from the remote_servers table (DELETE FROM remote_servers WHERE id = ?).

Example

curl -X DELETE https://panel.example.com:2087/api/remote-servers/1 \
  -H "Authorization: Bearer $TOKEN"

PUT /api/remote-servers/:id

Updates one or more fields (name, URL, API key) of an existing remote server; only non-empty fields in the body are changed.

Guards: RequirePermission(db, "administrative_operations"), RequirePlugin(db, "multi-panel")

Path parameters

Name	Type	Description
id	integer	Numeric ID of the remote server row to update.

Request body

{
  "name": "string (optional)",
  "url": "string (optional)",
  "api_key": "string (optional)"
}

Field	Type	Required	Description
name	string	no	New display name. Applied only if non-empty.
url	string	no	New panel URL. Applied only if non-empty. A trailing / is stripped, and if it lacks an http:///https:// scheme, https:// is prepended.
api_key	string	no	New API key/bearer token used to authenticate to the remote panel. Applied only if non-empty.

No field carries binding:"required"; the body itself must be valid JSON. At least one of the three fields must be non-empty or the request is rejected.

Response - 200 OK

{ "data": { "message": "Server updated" } }

Errors

Status	Code	Meaning
400	-	Body failed to bind as JSON; message contains the bind error.
400	-	All fields were empty - message: "No fields to update".
404	-	No remote server matched the given id (zero rows affected); message: "Server not found".
500	-	The dynamically built UPDATE query failed; message contains the database error.

Side effects

• Updates the matching row in remote_servers, setting only the provided columns (name, url, and/or api_key).

Example

curl -X PUT https://panel.example.com:2087/api/remote-servers/1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Edge Node", "url": "https://node1.example.com:2087"}'

POST /api/remote-servers/:id/check

Performs a live health check against the stored remote server by calling its /health endpoint, measures latency, and persists the result.

Guards: RequirePermission(db, "administrative_operations"), RequirePlugin(db, "multi-panel")

Path parameters

Name	Type	Description
id	integer	Numeric ID of the remote server to probe.

Response - 200 OK

{
  "data": {
    "status": "online",
    "latency_ms": 42,
    "server_version": "1.2.3",
    "last_error": ""
  }
}

Field	Type	Description
status	string	"online" if the remote /health returned HTTP 200, otherwise "offline".
latency_ms	integer	Round-trip time of the health request in milliseconds.
server_version	string	Version parsed from the remote response's data.version field; empty if unavailable.
last_error	string	Error detail when offline (transport error or HTTP <code>); empty when online.

Errors

Status	Code	Meaning
404	-	No remote server matched the given id; message: "Server not found".

A failed health probe still returns 200 OK with status: "offline" and a populated last_error; it does not produce an error status code.

Side effects

• Issues an outbound GET <url>/health request (10s timeout, TLS verification disabled) with Authorization: Bearer <stored api_key>.
• Updates the remote_servers row, setting status, last_check (to datetime('now')), last_error, and server_version.

Example

curl -X POST https://panel.example.com:2087/api/remote-servers/1/check \
  -H "Authorization: Bearer $TOKEN"