API Types

Type definitions for API requests and responses.

Types

`ActionsParams`

Free-form query parameters for GET /auth/actions. Array values are serialized comma-separated (e.g. ?status=VOTING,APPROVED).

type ActionsParams = Record<string, unknown>

`ActionTypeQuery`

One entry in the queries array sent to GET /auth/actions?queries=….

type ActionTypeQuery = { type: 'voting' | 'ready' | 'executing' | 'done' | string opts?: { reverse?: boolean; limit?: number; [key: string]: unknown } }

`AggregatedPool`

Aggregated pool row from GET /auth/pools (hashrate / workers / balance / revenue / summary). Feeds the Dashboard pool panel, not the Pools list.

type AggregatedPool = { name?: string hashrate?: number workers?: number balance?: number revenue?: number [key: string]: unknown }

`AlertSeverity`

Severity literal expected by the ActiveIncidentsCard row component.

type AlertSeverity = 'critical' | 'high' | 'medium'

`AuthTokenRequest`

Request body for POST /auth/token. The token endpoint refreshes the session and (optionally) downgrades the role set.

type AuthTokenRequest = { roles?: string[] ttl?: number ips?: string[] scope?: string }

`AuthTokenResponse`

Response from POST /auth/token.

type AuthTokenResponse = { token: string }

`CancelActionsPayload`

Arguments for DELETE /auth/actions/:type/cancel?ids=<comma>.

type CancelActionsPayload = { /** Action type URL segment (e.g. `voting`). */ type: string ids: Array<string | number> }

`ContainerPoolStat`

Per-container override-count row from GET /auth/pools/stats/containers.

type ContainerPoolStat = { container: string overriddenConfig?: number [key: string]: unknown }

One row of GET /auth/global/data?type=containerSettings (verified live 2026-07-01 — the response is a flat array, not the per-Kernel envelope). thresholds is keyed by threshold type (oilTemperature, tankPressure, waterTemperature…

type ContainerSettingsEntry = { model: string site?: string parameters?: Record<string, unknown> thresholds?: Record<string, ContainerThresholdLevels> }

`ContainerThresholdLevels`

Threshold band for one container parameter. Which levels are present varies per parameter (verified live: oilTemperature carries alert/alarm, waterTemperature carries alarmLow/alarmHigh).

type ContainerThresholdLevels = { criticalLow?: number alarmLow?: number alert?: number normal?: number alarm?: number alarmHigh?: number criticalHigh?: number }

`DeviceAlert`

Single alert record carried on a device under last.alerts. The list-things endpoint returns alerts as nested arrays — see getAlertsForDevices for the canonical extractor.

type DeviceAlert = { uuid?: string name: string description: string message?: string severity: string createdAt: number | string type?: string }

`ExtDataParams`

Query parameters for GET /auth/ext-data — a small key-value gateway the backend exposes for non-tail-log data sources (minerpool, mempool, etc.).

type ExtDataParams = { /** Provider id — e.g. `minerpool`, `mempool`. */ type: string /** JSON-stringified provider-specific filter. */ query?: string }

`FeatureConfigResponse`

Response from GET /auth/featureConfig (note the camelCase path — there is no /auth/feature-config route). Typed loosely: the flag set is deployment-specific. The backend may also return multi-site keys (isMultiSiteModeEnabled, `siteL…

type FeatureConfigResponse = { [key: string]: unknown }

`GlobalDataParams`

Query parameters for GET /auth/global/data. type selects the global data set (e.g. containerSettings); model optionally narrows container settings to one settings-model (bd, mbt, hydro, immersion).

type GlobalDataParams = { type: string model?: string overwriteCache?: boolean }

`HashRateLogEntry`

Narrowed variant where the hashrate aggregate is present. The dashboard chart components default to this attribute when no powerAttribute override is provided.

type HashRateLogEntry = TailLogEntry & { hashrate_mhs_1m_sum_aggr?: number hashrate_mhs_5m_sum_aggr?: number }

`HistoricalAlert`

A single historical alert row returned by GET /auth/history-log?logType=alerts.

type HistoricalAlert = { uuid?: string name: string description: string message?: string severity: string createdAt: number | string code?: string | number /** Owning device, when th…

`HistoryLogParams`

Query parameters for GET /auth/history-log (alerts / info-level history).

type HistoryLogParams = { logType: 'alerts' | 'info' start?: number end?: number limit?: number offset?: number query?: string }

`ListRacksParams`

Query parameters for GET /auth/list-racks. type is the worker type (e.g. miner, container) — omitting it returns ERR_TYPE_INVALID.

type ListRacksParams = { type: string overwriteCache?: boolean }

`ListThingsDevice`

Shape returned by GET /auth/list-things for a single device entry. Fields are typed to the union of what the known field projections request (miner explorer, container units, dashboard). Consumers that project fewer fields still satisfy…

type ListThingsDevice = { id: string type: string status?: string tags?: string[] code?: string rack?: string containerId?: string username?: string address?: string | null err?: stri…

`ListThingsParams`

Query parameters for GET /auth/list-things. query and fields are JSON-stringified Mongo-style selectors.

type ListThingsParams = { type?: string tag?: string status?: number | string query?: string fields?: string limit?: number offset?: number }

`LiveAction`

A single live action returned by the backend voting queue.

type LiveAction = { id: string /** The action verb (e.g. `setupPools`, `registerPoolConfig`). */ action?: string type?: string status?: string /** Email/username of the submitte…

`LiveActionsResponse`

Response shape of GET /auth/actions?queries=… — a one-element array whose single object maps each requested type to its result list.

type LiveActionsResponse = { voting?: LiveAction[] ready?: LiveAction[] executing?: LiveAction[] done?: LiveAction[] [key: string]: LiveAction[] | undefined }

`MinerEntry`

A miner row from GET /auth/miners, carrying its assigned poolConfig. Only the id is guaranteed; the rest is consumed via lodash.get.

type MinerEntry = { id: string [key: string]: unknown }

`MinerpoolExtDataEntry`

Single minerpool ext-data envelope. Backend nests these in Array<Array<…>> (per-pool grouping + per-timestamp grouping), so consumers _head(_head(…)).

type MinerpoolExtDataEntry = { ts?: string stats?: PoolMinerStats[] }

`MinerpoolStatsHistoryEntry`

Single sample from the paginated type=minerpool, key=stats-history ext-data feed used by the multi-series Hash Rate chart. Each entry carries a timestamp and a snapshot of every configured pool's hashrate at that point in time.

type MinerpoolStatsHistoryEntry = { ts: number stats: PoolMinerStats[] }

`MinersParams`

Query parameters for GET /auth/miners. filter, fields, and sort are JSON-stringified Mongo-style selectors; search is free text matched across id / code / serial / mac.

type MinersParams = { filter?: string fields?: string sort?: string search?: string limit?: number offset?: number }

`MinersResponse`

Paginated envelope returned by GET /auth/miners — page data plus site-wide pagination metadata.

type MinersResponse = { data: MinerEntry[] totalCount: number offset: number limit: number hasMore: boolean }

`PduLayoutItem`

One PDU row in the static grid layout. power_w / current_a / offline are absent in the static layout and filled from live pdu_data.

type PduLayoutItem = { pdu: string sockets: PduLayoutSocket[] power_w?: number | string current_a?: number | string offline?: boolean }

`PduLayoutParams`

Query parameters for GET /auth/pdu-layout. type is the full container type string (e.g. container-bd-d40-m56).

type PduLayoutParams = { type: string overwriteCache?: boolean }

`PduLayoutResponse`

Response from GET /auth/pdu-layout (verified live 2026-07-01). The backend sources this from the container worker's pduGridLayout config, keyed by the exact container type, and 400s with ERR_PDU_LAYOUT_NOT_FOUND when no layout is pro…

type PduLayoutResponse = { type: string layout: PduLayoutItem[] }

`PduLayoutSocket`

One socket in a PDU grid. enabled reflects the static layout default; live on/off state comes from the device's pdu_data merge.

type PduLayoutSocket = { socket: string enabled: boolean cooling?: boolean }

`PoolBalanceHistoryEntry`

A single revenue/hashrate sample from GET /auth/pools/:pool/balance-history.

type PoolBalanceHistoryEntry = { ts?: number revenue?: number hashrate?: number /** Settled balance for the bucket (equals `revenue` in the current backend). */ balance?: number [key: string…

`PoolBalanceHistoryParams`

Query parameters for GET /auth/pools/:pool/balance-history. The backend requires both start and end (Unix ms) and rejects the request otherwise; they are typed optional only so a param object can be built incrementally.

type PoolBalanceHistoryParams = { /** Window start (Unix ms). Required by the backend. */ start?: number /** Window end (Unix ms). Required by the backend. */ end?: number range?: '1D' | '1W'…

`PoolBalanceHistoryResponse`

Response envelope for GET /auth/pools/:pool/balance-history — the backend wraps the samples in { log }.

type PoolBalanceHistoryResponse = { log: PoolBalanceHistoryEntry[] }

`PoolConfigEntry`

Raw pool-configuration row from GET /auth/configs/pool. This is the shape the devkit usePoolConfigs transform consumes to build a PoolSummary.

type PoolConfigEntry = { id: string poolConfigName: string description: string poolUrls: PoolConfigUrl[] miners: number containers: number updatedAt: string | number }

`PoolConfigForDeviceResponse`

Response for GET /auth/pools/config/:id — the device's assigned pool config id and the count of miners overriding their container's config.

type PoolConfigForDeviceResponse = { poolConfig: string | null overriddenConfig: number }

`PoolConfigUrl`

A single pool-URL endpoint as stored on a pool configuration. url is a stratum+tcp://host:port string; the devkit usePoolConfigs transform parses it into host/port/role for display.

type PoolConfigUrl = { url: string pool: string workerName?: string workerPassword?: string }

`PoolMinerStats`

Per-pool stats entry returned by GET /auth/ext-data?type=minerpool. Each configured pool (f2pool, ocean, …) contributes one row.

type PoolMinerStats = { poolType?: string /** Subaccount / user the pool worker submits shares under. */ username?: string /** * Pool-reported hashrate in **H/s** (raw hashes per se…

`PoolsResponse`

Response envelope for GET /auth/pools — the aggregated pools list plus a site-wide summary. The backend wraps the array, so consumers must read .pools rather than treating the payload as an array.

type PoolsResponse = { pools: AggregatedPool[] summary: PoolsSummary }

`PoolsSummary`

Site-wide totals returned alongside the pool list by GET /auth/pools.

type PoolsSummary = { poolCount: number totalHashrate: number totalWorkers: number totalBalance: number }

`PowerModeTimelineEntry`

Power-mode timeline entry — carries grouped per-miner mode/status maps keyed by miner id. Consumed by PowerModeTimelineChart.

type PowerModeTimelineEntry = TailLogEntry & { power_mode_group_aggr?: Record<string, string> status_group_aggr?: Record<string, string> }

`Rack`

A single rack entry from GET /auth/list-racks. Typed loosely — the listRacks RPC response shape has not been captured against a live backend yet (staging returned no rack data at verification time).

type Rack = { id?: string name?: string [key: string]: unknown }

`SiteResponse`

Response from GET /auth/site — the configured site label.

type SiteResponse = { site: string }

`SiteStatusAlerts`

Alert counts by severity from the live site-status snapshot.

type SiteStatusAlerts = { critical: number high: number medium: number total: number }

`SiteStatusLive`

Composite live site-status snapshot from GET /auth/site/status/live. Aggregates site-wide hashrate, power, efficiency, miner/alert/pool counts, and the snapshot timestamp (ts, Unix ms). Polled on a short interval.

type SiteStatusLive = { hashrate: SiteStatusMetric power: SiteStatusPower efficiency: SiteStatusMetric miners: SiteStatusMiners alerts: SiteStatusAlerts pools: SiteStatusPools /** S…

`SiteStatusMetric`

A { value, unit } measurement, optionally annotated with a nominal (rated) value and a utilization percentage (value / nominal * 100).

type SiteStatusMetric = { value: number unit: string nominal?: number utilization?: number }

`SiteStatusMiners`

Miner population counts from the live site-status snapshot.

type SiteStatusMiners = { online: number offline: number error: number total: number containerCapacity: number }

`SiteStatusPools`

Pool-side aggregates from the live site-status snapshot.

type SiteStatusPools = { totalHashrate: { value: number; unit: string } activeWorkers: number totalWorkers: number }

`SiteStatusPower`

Power metric from the live site-status snapshot. Like SiteStatusMetric but with an alert message and a hard error flag.

type SiteStatusPower = SiteStatusMetric & { alert?: string error?: boolean }

`SubmitBatchActionsPayload`

Body for POST /auth/actions/voting/batch — a set of staged actions plus a client-generated batchActionUID the backend uses to group them.

type SubmitBatchActionsPayload = { batchActionsPayload: VotingActionPayload[] batchActionUID: string suffix?: string /** Batch-level annotations (e.g. `{ isBackFromMaintenance }` on miner move…

`TailLogEntry`

A single time-bucketed entry from GET /auth/tail-log. Backend returns Array<Array<TailLogEntry>> (outer wrapping is the per-worker grouping — single-site dashboards take _head(response)).

type TailLogEntry = { ts: number /** All other fields are dynamic aggregates requested via `aggrFields`. */ [key: string]: unknown }

`TailLogMultiParams`

Query parameters for GET /auth/tail-log/multi — the batched variant of tail-log. keys is required (comma-separated stat-* keys); the rest mirrors the Fastify schema in miningos-gateway. {todo: update miningos-gateway}

type TailLogMultiParams = { keys: string start?: number end?: number offset?: number limit?: number fields?: string aggrFields?: string aggrTimes?: string overwriteCache?: boolean }

`TailLogParams`

Query parameters for GET /auth/tail-log. Mirrors the Fastify schema in miningos-gateway. aggrFields is a JSON-stringified object describing which aggregate columns to include in each row.

type TailLogParams = { key: string type?: string tag?: string start?: number end?: number offset?: number limit?: number fields?: string aggrFields?: string aggrTimes?: string merg…

`ThingCommentBody`

Body for POST | PUT | DELETE /auth/thing/comment (add / edit / delete a device comment — one Fastify schema covers all three verbs). rackId + thingId + comment are required; id and ts identify an existing comment for edit/delet…

type ThingCommentBody = { rackId: string thingId: string comment: string /** Existing comment id — required when editing or deleting. */ id?: string pos?: string ts?: number }

`ThingConfigParams`

Query parameters for GET /auth/thing-config — both fields are required by the Fastify schema.

type ThingConfigParams = { type: string requestType: string }

`VoteActionPayload`

Body for PUT /auth/actions/voting/:id/vote.

type VoteActionPayload = { id: string | number approve: boolean }

`VotingActionObjectParam`

Object-shaped params[] entry on a voting submission. Pool create/update carry { type: 'pool', data } (+ id for updates); assign-pool carries { poolConfigId, configType: 'pool' }; switchSocket carries { pdu, socket, enabled }; `…

type VotingActionObjectParam = { type?: string id?: string poolConfigId?: string configType?: string data?: Record<string, unknown> [key: string]: unknown }

`VotingActionParam`

A single params[] entry on a voting submission. Positional and action-specific: device actions carry primitives (setPowerMode sends ['sleep'], setLED sends [true], setTankEnabled sends [3, true]), pool/thing actions carry {@l…

type VotingActionParam = string | number | boolean | VotingActionObjectParam

`VotingActionPayload`

Body for POST /auth/actions/:type (default voting). type selects the URL segment and is stripped from the JSON body before posting — the remaining fields (query, action, params, rackType, …) form the request body.

type VotingActionPayload = { /** URL segment under `/auth/actions/:type`. Defaults to `voting`. */ type?: string query?: Record<string, unknown> action?: string params?: VotingActionPara…

API Types

On this page