From 959109fc15130fc129bc0c82a35ebf612e452660 Mon Sep 17 00:00:00 2001 From: David White Date: Thu, 20 Aug 2026 10:11:16 +0100 Subject: [PATCH] docs(api): mark the retired app-control routes deprecated, and correct the appstats payload Five endpoints changed in FluxOS and the spec still documents the old behaviour. This is the contract third parties build against, so it is wrong on the day the release lands. /apps/apppause and /apps/appunpause are removed. Docker reports a paused container as running, so a paused app stayed listed as healthy: the load balancer kept routing to a server whose processes were frozen and could never answer, and monitoring showed a flat line with no explanation. Nothing could release one either. appstop/appstart replace them. /apps/startmonitoring and /apps/stopmonitoring are removed. The node monitors every app it runs, for the CPU throttling loop, so there was nothing for a caller to turn on or off - and one told "success" by stopmonitoring would have believed monitoring had stopped while it was still running. All four still answer, in band at HTTP 200 with code 410, so an existing caller learns why rather than failing blind. They are marked deprecated with the real error body as the example rather than deleted, because a caller looking the endpoint up should find the explanation. /apps/appmonitorstream is the one that is genuinely gone - the route no longer exists, so it returns a plain 404. Documented as such, and pointed at /apps/appmonitor. That trips redocly's operation-2xx-response warning, which is accurate: the endpoint cannot return a 2xx any more, and documenting one that cannot happen would be worse than the warning. /apps/appstats published the FULL raw dockerode object as its example. The node now keeps only the values a consumer reads and drops the rest before it reaches the wire, so that example advertised eleven fields that no longer exist: percpu_usage, usage_in_kernelmode, usage_in_usermode, throttling_data, max_usage, failcnt, pids_stats, num_procs, storage_stats, preread, read, and the container id and name. Replaced with the shape the endpoint actually returns, and the description now names what was dropped - including that percpu_usage is gone, so a consumer using docker's documented "fall back to the length of percpu_usage when online_cpus is 0" trick has to read online_cpus directly. disk_stats is documented properly while here: status is success, partial or error, and a partial reading is a floor rather than a total - charting one as a real value shows a drop that did not happen. docs/index.html rebuilt with the same redocly 2.0.8 the lockfile pins, since the built site is what GitHub Pages serves. NOTE: /apps/appmonitor, which this now points callers at, has no entry in this spec at all. Worth adding, but not in a deprecation change. Co-Authored-By: Claude Opus 5 (1M context) --- docs/index.html | 54 +++++++---- fluxapi.yaml | 251 +++++++++++++++++++++++++----------------------- 2 files changed, 167 insertions(+), 138 deletions(-) diff --git a/docs/index.html b/docs/index.html index 5e5a2ba..994a05a 100644 --- a/docs/index.html +++ b/docs/index.html @@ -388,11 +388,15 @@ .lkmdtA:focus{outline:auto #1d8127;}/*!sc*/ .ifAHvq{display:block;border:0;width:100%;text-align:left;padding:10px;border-radius:2px;margin-bottom:4px;line-height:1.5em;cursor:pointer;color:#d41f1c;background-color:rgba(212,31,28,0.07);}/*!sc*/ .ifAHvq:focus{outline:auto #d41f1c;}/*!sc*/ +.kQCDrg{display:block;border:0;width:100%;text-align:left;padding:10px;border-radius:2px;margin-bottom:4px;line-height:1.5em;cursor:pointer;color:#d41f1c;background-color:rgba(212,31,28,0.07);cursor:default;}/*!sc*/ +.kQCDrg:focus{outline:auto #d41f1c;}/*!sc*/ +.kQCDrg::before{content:"—";font-weight:bold;width:1.5em;text-align:center;display:inline-block;vertical-align:top;}/*!sc*/ +.kQCDrg:focus{outline:0;}/*!sc*/ .oZuve{display:block;border:0;width:100%;text-align:left;padding:10px;border-radius:2px;margin-bottom:4px;line-height:1.5em;cursor:pointer;color:#1d8127;background-color:rgba(29,129,39,0.07);cursor:default;}/*!sc*/ .oZuve:focus{outline:auto #1d8127;}/*!sc*/ .oZuve::before{content:"—";font-weight:bold;width:1.5em;text-align:center;display:inline-block;vertical-align:top;}/*!sc*/ .oZuve:focus{outline:0;}/*!sc*/ -data-styled.g120[id="sc-jIDBmd"]{content:"lkmdtA,ifAHvq,oZuve,"}/*!sc*/ +data-styled.g120[id="sc-jIDBmd"]{content:"lkmdtA,ifAHvq,kQCDrg,oZuve,"}/*!sc*/ .fBhAXU{vertical-align:top;}/*!sc*/ data-styled.g123[id="sc-eJvlPh"]{content:"fBhAXU,"}/*!sc*/ .kjrVcG{font-size:1.3em;padding:0.2em 0;margin:3em 0 1.1em;color:#333333;font-weight:normal;}/*!sc*/ @@ -432,7 +436,7 @@ -
logo
API docs by Redocly
logo
API docs by Redocly
4. Configure API Headers " class="sc-eVqvcJ sc-fszimp kIppRw drqpJr">

Explorer API - Blockchain data and statistics

https://explorer.runonflux.io/apps/apprestart

Network Statistics API - Real-time network metrics

-
https://stats.runonflux.io/apps/apprestart

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": "Flux App fluxFoldingAtHome successfully restarted."
}

Pause app

This will pause the fluxapp. AppOwnerAbove

+
https://stats.runonflux.io/apps/apprestart

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": "Flux App fluxFoldingAtHome successfully restarted."
}

Pause app (REMOVED) Deprecated

Removed. Docker reports a paused container as running, so a paused app stayed listed as healthy: the load balancer kept routing to a server whose processes were frozen and which could never answer, and monitoring showed a flat line with no explanation. Nothing could release one either.

+

Use /apps/appstop instead, and /apps/appstart to bring it back. The route still answers, with the error below, so an existing caller learns why rather than failing blind. AppOwnerAbove

Authorizations:
ZelID
query Parameters
container
required
string
Example: container=fluxFoldingAtHome

Name/Id of app

Responses

Network Statistics API - Real-time network metrics

-
https://stats.runonflux.io/apps/apppause

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": "Flux App fluxFoldingAtHome successfully paused."
}

Unpause app

This will unpause the Flux application. AppOwnerAbove

+
https://stats.runonflux.io/apps/apppause

Response samples

Content type
application/json
{
  • "status": "error",
  • "data": {
    }
}

Unpause app (REMOVED) Deprecated

Removed alongside /apps/apppause. Use /apps/appstart to start a stopped application. The route still answers, with the error below, so an existing caller learns why rather than failing blind. AppOwnerAbove

Authorizations:
ZelID
query Parameters
container
required
string
Example: container=fluxFoldingAtHome

Name/Id of app

Responses

Network Statistics API - Real-time network metrics

-
https://stats.runonflux.io/apps/appunpause

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": "Flux App fluxFoldingAtHome successfully unpaused."
}

List of running processes

https://stats.runonflux.io/apps/appunpause

Response samples

Content type
application/json
{
  • "status": "error",
  • "data": {
    }
}

List of running processes

Display the running processes of a container. AppOwnerAbove

Authorizations:
ZelID
query Parameters
container
required
string
Example: container=fluxFoldingAtHome

Name/Id of app

@@ -7058,8 +7064,14 @@

4. Configure API Headers

" class="sc-eVqvcJ sc-fszimp kIppRw drqpJr">

Explorer API - Blockchain data and statistics

https://explorer.runonflux.io/apps/appinspect

Network Statistics API - Real-time network metrics

-
https://stats.runonflux.io/apps/appinspect

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

App stats based on resource usage

Returns containers resource usage. AppOwnerAbove

+
https://stats.runonflux.io/apps/appinspect

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

App stats based on resource usage

Returns the container's resource usage.

+

The payload is a NARROWED subset of docker's stats object, not the raw object. The node samples every app it runs and keeps only the values a consumer reads; the rest is dropped before it reaches the wire. Fields that used to appear here and no longer do: percpu_usage, usage_in_kernelmode, usage_in_usermode, throttling_data, max_usage, failcnt, pids_stats, num_procs, storage_stats, preread, read, and the container id and name.

+

Two consequences worth knowing. memory_stats.stats carries inactive_file only, reported under that cgroup v2 name whichever key it was read from. And percpu_usage is gone, so a consumer using docker's documented "fall back to the length of percpu_usage when online_cpus is 0" trick must read online_cpus directly.

+

disk_stats.status is success when every mount was measured, partial when some could not be (an unmeasured list is then included) and error when the reading failed outright. A partial reading is a floor, not a total - charting one as a real value shows a drop that did not happen. AppOwnerAbove

https://docs.docker.com/engine/api/v1.40/#operation/ContainerStats
Authorizations:
ZelID
query Parameters
appname
required
string
Example: appname=fluxdibi-UND

App name

Responses

Network Statistics API - Real-time network metrics

-
https://stats.runonflux.io/apps/appstats

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "pids_stats": { },
  • "blkio_stats": {
    },
  • "num_procs": 0,
  • "storage_stats": { },
  • "cpu_stats": {
    },
  • "precpu_stats": {
    },
  • "memory_stats": {
    },
  • "name": "/fluxdibi-UND",
  • "id": "1e2f681c8a356c0af561bcefb3a85b8dbe690487598a004fef1c4a65001e0078",
  • "networks": {
    }
}

Container changes

https://stats.runonflux.io/apps/appstats

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Container changes

4. Configure API Headers " class="sc-eVqvcJ sc-fszimp kIppRw drqpJr">

Explorer API - Blockchain data and statistics

https://explorer.runonflux.io/apps/applogpolling/{appname}

Network Statistics API - Real-time network metrics

-
https://stats.runonflux.io/apps/applogpolling/{appname}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Stream application monitoring data

Get real-time streaming monitoring data for an application. AppOwnerAbove

+
https://stats.runonflux.io/apps/applogpolling/{appname}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Stream application monitoring data (REMOVED) Deprecated

Removed, and unlike the other retired endpoints this one no longer exists at all - the route is gone, so a request returns a plain HTTP 404 rather than an in-band explanation.

+

Poll /apps/appmonitor/{appname} instead. The node samples every application it runs on its own schedule and keeps a rolling window, so a poll returns the same data the stream did without holding a connection open. AppOwnerAbove

Authorizations:
ZelID
path Parameters
appname
required
string
Example: electrumxtest

Name of the application

-

Responses

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Start application monitoring

Start monitoring for a specific application. AppOwnerAbove

+
https://stats.runonflux.io/apps/reconstructhashes

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Start application monitoring (NO LONGER HAS ANY EFFECT) Deprecated

Removed. The node monitors every application it runs, for the CPU throttling loop, so there is nothing for a caller to turn on. The route still answers, with the error below, so an existing caller is not told "success" for something that did not happen. AppOwnerAbove

Authorizations:
ZelID
path Parameters
appname
required
string
Example: electrumxtest

Name of the application to monitor

Responses

Network Statistics API - Real-time network metrics

-
https://stats.runonflux.io/apps/startmonitoring/{appname}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Stop application monitoring

Stop monitoring for a specific application. AppOwnerAbove

+
https://stats.runonflux.io/apps/startmonitoring/{appname}

Response samples

Content type
application/json
{
  • "status": "error",
  • "data": {
    }
}

Stop application monitoring (NO LONGER HAS ANY EFFECT) Deprecated

Removed alongside /apps/startmonitoring. Monitoring is not optional - the node needs it for every app it runs - so a caller told "success" here would believe monitoring had stopped while it was still running. The route answers with the error below instead. AppOwnerAbove

Authorizations:
ZelID
path Parameters
appname
required
string
Example: electrumxtest

Name of the application

query Parameters
deletedata
boolean
Default: false
4. Configure API Headers " class="sc-eVqvcJ sc-fszimp kIppRw drqpJr">

Explorer API - Blockchain data and statistics

https://explorer.runonflux.io/apps/stopmonitoring/{appname}

Network Statistics API - Real-time network metrics

-
https://stats.runonflux.io/apps/stopmonitoring/{appname}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get public key for app operations

https://stats.runonflux.io/apps/stopmonitoring/{appname}

Response samples

Content type
application/json
{
  • "status": "error",
  • "data": {
    }
}

Get public key for app operations

Get the public key used for application operations. User

Authorizations:
ZelID
Request Body schema: application/json
required
message
string

Message to sign

@@ -10109,7 +10123,7 @@

4. Configure API Headers

" class="sc-eVqvcJ sc-fszimp kIppRw drqpJr">

Network Statistics API - Real-time network metrics

https://stats.runonflux.io/ioutils/fileupload