FluxOS API Reference

Essential API endpoints for monitoring, automation, and building tools on top of the Flux network.

15 min read

apifluxosendpointsmonitoring

FluxOS API for Node Operators

Every Flux node exposes a comprehensive REST API on port 16127 (HTTP) and 16128 (HTTPS). This API allows you to query node status, manage applications, access blockchain data, and perform administrative tasks. Understanding the API is essential for building monitoring tools, automation scripts, and integration with Fluxme.io.

API Architecture

•Base URL: `http://NODE_IP:16127/` (direct node) or `https://api.runonflux.io/` (load-balanced gateway)
•Response format: All responses return JSON with a `status` field ("success" or "error") and a `data` field
•Caching: Most GET endpoints are cached (30s–1 day depending on the endpoint)
•Authentication: Public endpoints require no auth. Protected endpoints use a signed message challenge-response flow

Access Levels

Level	Who	Example Endpoints
Public	Anyone	/flux/info, /apps/listrunningapps, /daemon/getblockcount
User	Logged-in users	/benchmark/getstatus, /id/loggedsessions
FluxNode Owner	Collateral holder	/flux/restart, /daemon/wallet endpoints
FluxTeam	Flux team members	/flux/updateflux, /flux/daemondebug
AppOwner	App deployers	/apps/appstart, /apps/applog, /apps/appexec

Essential Endpoints for Monitoring

Common Node Monitoring Queries

# Node info (tier, version, connections, uptime)
curl -s http://NODE_IP:16127/flux/info | jq .data

# Node tier
curl -s http://NODE_IP:16127/flux/nodetier | jq .data

# FluxOS version
curl -s http://NODE_IP:16127/flux/version | jq .data

# Benchmark results
curl -s http://NODE_IP:16127/daemon/getbenchmarks | jq .data

# Running apps on this node
curl -s http://NODE_IP:16127/apps/listrunningapps | jq .data

# Resource usage
curl -s http://NODE_IP:16127/apps/fluxusage | jq .data

# System uptime
curl -s http://NODE_IP:16127/flux/systemuptime | jq .data

# ArcaneOS detection
curl -s http://NODE_IP:16127/flux/isarcaneos | jq .data

# Geolocation
curl -s http://NODE_IP:16127/flux/geolocation | jq .data

# Connected peers
curl -s http://NODE_IP:16127/flux/connectedpeers | jq .data

Blockchain & Network Endpoints

Blockchain & Network Queries

# Current block height
curl -s https://api.runonflux.io/daemon/getblockcount | jq .data

# Network info
curl -s https://api.runonflux.io/daemon/getnetworkinfo | jq .data

# FluxNode count
curl -s https://api.runonflux.io/daemon/getfluxnodecount | jq .data

# Node status
curl -s http://NODE_IP:16127/daemon/getfluxnodestatus | jq .data

# Address balance
curl -s https://api.runonflux.io/explorer/balance/YOUR_ADDRESS | jq .data

Application Management

App Management Queries

# All global app specifications
curl -s https://api.runonflux.io/apps/globalappsspecifications | jq .data

# Specific app specification
curl -s https://api.runonflux.io/apps/appspecifications/APP_NAME | jq .data

# App locations (which nodes run it)
curl -s https://api.runonflux.io/apps/location/APP_NAME | jq .data

# Calculate app price
curl -s -X POST https://api.runonflux.io/apps/calculatefiatandfluxprice \
  -H "Content-Type: application/json" \
  -d '{"cpu": 0.5, "ram": 1000, "hdd": 10, "instances": 3}' | jq .data

Stats API (Network-Wide)

The Stats API at stats.runonflux.io provides aggregated data for all nodes. It supports projection queries for efficient partial data retrieval:

Stats API Projections

# All node data (large response ~50MB+)
curl -s https://stats.runonflux.io/fluxinfo | jq .data | head

# Only locked resources per node
curl -s "https://stats.runonflux.io/fluxinfo?projection=apps.resources" | jq .data[0]

# Only benchmark data per node
curl -s "https://stats.runonflux.io/fluxinfo?projection=benchmark" | jq .data[0]

# Only running container images
curl -s "https://stats.runonflux.io/fluxinfo?projection=apps.runningapps.Image" | jq .data[0]

The Stats API /fluxinfo endpoint returns data for ALL nodes on the network (10,000+). The full response is very large. Always use projections when you only need specific fields.