Luxor PlatformAPI DocumentationCommanderAgents

Get agents

Returns a paginated list of Commander agents with optional filtering by site and status.

GET
/v2/commander/agents

Authorization

LuxorAPIKey
authorization<token>

Use your API key here.

In: header

Query Parameters

site_id?string
Formatuuid
status?string

Value in

  • "enabled"
  • "disabled"
sort_by?string

Value in

  • "name"
  • "created_at"
  • "last_seen_at"
sort_order?string
Default"asc"

Value in

  • "asc"
  • "desc"
page_number?integer
Range1 <= value
Default1
page_size?integer
Range1 <= value
Default25

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/v2/commander/agents"
{  "agents": [    {      "id": "1d786ea1-9400-4566-94be-d5f400e0490b",      "name": "blocklab-agent-001",      "site_id": "b0a5fad8-1234-5678-9abc-def012345678",      "status": "enabled",      "version": "v0.20.0",      "plan": "pro",      "scan_ranges": [        {          "type": "ip_range",          "value": "10.206.0.1-100"        }      ],      "firmware_credentials": [        {          "firmware": "Bitmain",          "username": "root",          "password_set": true        }      ],      "miners_count": 512,      "last_seen_at": "2026-04-20T10:15:00Z",      "created_at": "2025-11-02T09:30:00Z",      "url": "/v2/commander/agents/1d786ea1-9400-4566-94be-d5f400e0490b"    }  ],  "pagination": {    "page_number": 1,    "page_size": 1,    "item_count": 0,    "previous_page_url": null,    "next_page_url": null  }}
{  "statusCode": 400,  "code": "FST_ERR_VALIDATION",  "error": "Bad Request",  "message": "body/end_date Required"}
{  "statusCode": 403,  "code": "7",  "error": "Forbidden",  "message": "[permission_denied] site_id does not belong to this workspace"}

Create action

Creates a bulk miner action (execution plan) such as reboot, sleep, wake up, or configuration changes. 'Change Temperature Control' requires at least one params.temp_control field, temperatures are in degrees Celsius, and fields a miner model doesn't support are ignored. Thresholds sent together are checked server-side and rejected with 400 if out of order: chip target, hot and dangerous must ascend, and water-inlet hot and startup must not exceed water-inlet dangerous. Its fields dispatch as three groups — the ATM group (enabled, startup_minutes, post_ramp_minutes, minimum_profile, maximum_profile, temperature_buffer, chip_temperature_buffer, water_inlet_temperature_buffer), the power group (minimum_power) and the threshold group (everything else) — and a request spanning more than one produces one Action Log entry per group, of which the response returns one; find the siblings with GET /v2/commander/actions. Every 'Change Temperature Control' request requires the same subscription entitlement as 'Change ATM Settings' (403 otherwise). Both 'Change ATM Settings' and 'Change Temperature Control' can appear as a response action_type, because the two share a downstream step type: an ATM request may read back as 'Change Temperature Control'. Remote commands: 'Install Firmware' (alias 'Install LuxOS'), 'Update Firmware' (alias 'Update LuxOS'), 'Uninstall Custom Firmware' and 'Retrieve Firmware Logs' take no params; 'Retrieve Firmware Logs' targets exactly one LuxOS or Antminer miner. 'Power Configuration' (alias 'Change Mining Profile') requires params.power_settings, one entry per firmware in the selection (offline miners included): luxos takes power_target (500-8000 W) and optional power_limit and minimum_power (minimum_power <= power_target <= power_limit); antminer and whatsminer take profile_step (-1, 0 or 1); fluxos takes power_target or profile_step, not both. 'Run LuxOS Command' requires params.luxos_command with a command and its parameters, as the web form offers them (* = required; values are strings; board_id, fan speeds, min_fans and delay_secs are integers): autotunerset (enabled* true|false); disableboard and enableboard (board_id* >= 0); fanset (speed -1-100, min_speed, max_speed and power_off_speed 0-100, min_fans >= 0); hashboardoptsset (overtemp_auto_recovery true|false, no_pic_protection_mode shutdown_all_boards|shutdown_failing_board); immersionswitch (immersion_mode* on|off); ledset (led* red|green, mode* on|off|blink|auto); netset (dhcp true|false, hostname, ipaddress, netmask, gateway, dnsservers); reboot (board_id* >= 0, delay_secs >= 0); resetminer (none); tempctrlset (target_temp, hot_temp, dangerous_temp). Other parameters are rejected. disableboard, enableboard, immersionswitch, ledset and reboot send the values positionally in that order, the rest as key=value. 'Blink Miner LED' requires params.led_mode: BLINK to start, AUTO to stop. For Install Firmware, Update Firmware, Uninstall Custom Firmware, Power Configuration, Run LuxOS Command and Blink Miner LED, if any online miner in miner_ids cannot run the command on its firmware, the request is rejected with 400 and nothing is sent; offline miners are allowed. A 503 means compatibility could not be checked and nothing was sent; the request can be retried. Firmware commands, Run LuxOS Command and Power Configuration need the matching subscription entitlement (403 otherwise).

Create agent

Provisions a new Commander agent. The caller provides the agent secret.