Queries & mutations
Domain query and mutation factories for the Gateway API — miners, pools, actions, site, and more
TanStack Query and mutation factories for Gateway API resources — miners, pools,
containers, actions, site status, and device history. Each factory returns a
query key and fetcher (or mutation key and mutation function) ready to pass to
useQuery / useMutation. For the lower-level fetcher, URL, and query-client
building blocks these factories are built on, see Query helpers.
Package
@tetherto/mdk-ui-foundation
Queries & mutations
@tetherto/mdk-ui-foundation
Import the public APIs on this page from @tetherto/mdk-ui-foundation.
ACTION_WRITE_INVALIDATE_PREFIXES
Query-key prefixes refreshed after any action write (submit / vote / cancel). A write can change pool configs, miner assignments, the aggregated pools and the actions queue, so all four refresh together.
Constant
readonly [readonly ["auth", "configs", "pool"], readonly ["auth", "miners"], readonly ["auth", "pools"], readonly ["auth", "actions"]]actionsQuery
GET /auth/actions — pending/voting actions list (the review-tray source). Array params serialize comma-separated.
Function
(client: QueryClient, params: ActionsParams = {}, fetcher: Fetcher = runtimeFetcher(client)) => { queryKey: readonly ["auth", "actions", ActionsParams]; queryFn: ({ signal }?: QueryFnContext) => Prom…addThingCommentMutation
TanStack Mutation factory for POST /auth/thing/comment — add a device comment. Requires the comments:write permission; the backend stamps the author from the session token.
Constant
(client: QueryClient, fetcher?: Fetcher) => { mutationKey: ResourceKey; invalidates: ResourceKey[]; mutationFn: (payload: ThingCommentBody) => Promise<unknown>; }authTokenMutation
TanStack Mutation factory for POST /auth/token. Used by useTokenPolling to refresh the session token every 250 s.
Function
(client: QueryClient, fetcher: Fetcher = runtimeFetcher(client)) => { mutationKey: readonly ["auth", "token"]; mutationFn: (body?: AuthTokenRequest) => Promise<AuthTokenResponse>; }cancelActionsMutation
DELETE /auth/actions/:type/cancel?ids=<comma> — cancel pending actions. Arguments ride in the query string, so no body is sent.
Constant
(client: QueryClient, fetcher?: Fetcher) => { mutationKey: ResourceKey; invalidates: ResourceKey[]; mutationFn: (payload: CancelActionsPayload) => Promise<unknown>; }containerPoolStatsQuery
GET /auth/pools/stats/containers — per-container override counts.
Function
(client: QueryClient, fetcher: Fetcher = runtimeFetcher(client)) => { queryKey: readonly ["auth", "pools", "stats", "containers"]; queryFn: ({ signal }?: QueryFnContext) => Promise<ContainerPoolStat[…containerSettingsQuery
Convenience wrapper around globalDataQuery pinned to type=containerSettings — per-model container thresholds/parameters. Verified live: the response is a flat ContainerSettingsEntry[], not the per-Kernel envelope.
Function
(client: QueryClient, options: { model?: string; overwriteCache?: boolean } = {}, fetcher: Fetcher = runtimeFetcher(client)) => { queryKey: readonly ["auth", "global", "data", GlobalDataParams]; quer…deleteThingCommentMutation
TanStack Mutation factory for DELETE /auth/thing/comment — remove an existing device comment (body.id identifies it; the schema still requires the full body on delete).
Constant
(client: QueryClient, fetcher?: Fetcher) => { mutationKey: ResourceKey; invalidates: ResourceKey[]; mutationFn: (payload: ThingCommentBody) => Promise<unknown>; }editThingCommentMutation
TanStack Mutation factory for PUT /auth/thing/comment — edit an existing device comment (body.id identifies it).
Constant
(client: QueryClient, fetcher?: Fetcher) => { mutationKey: ResourceKey; invalidates: ResourceKey[]; mutationFn: (payload: ThingCommentBody) => Promise<unknown>; }extDataQuery
TanStack Query factory for GET /auth/ext-data. Generic in the response row type so adapters can pin the result to a typed envelope (see minerpoolStatsQuery for the canonical narrowing). query is a JSON-stringified provider-specific s…
Function
(client: QueryClient, params: ExtDataParams, fetcher: Fetcher = runtimeFetcher(client)) => { queryKey: readonly ["auth", "ext-data", ExtDataParams]; queryFn: ({ signal }?: QueryFnContext) => Promise<…featureConfigQuery
TanStack Query factory for GET /auth/featureConfig — deployment feature flags, including the multi-site mode switch. Note the camelCase path: there is no /auth/feature-config route (a kebab-case request falls through to the SPA fallbac…
Function
(client: QueryClient, fetcher: Fetcher = runtimeFetcher(client)) => { queryKey: readonly ["auth", "featureConfig"]; queryFn: ({ signal }?: QueryFnContext) => Promise<FeatureConfigResponse>; }globalConfigQuery
TanStack Query factory for GET /auth/global-config — the global system config document. Shape is deployment-specific (not yet captured live), so callers narrow via the generic.
Function
(client: QueryClient, fetcher: Fetcher = runtimeFetcher(client)) => { queryKey: readonly ["auth", "global-config"]; queryFn: ({ signal }?: QueryFnContext) => Promise<TConfig>; }globalDataQuery
TanStack Query factory for GET /auth/global/data. Generic in the row type — see containerSettingsQuery for the canonical narrowing.
Function
(client: QueryClient, params: GlobalDataParams, fetcher: Fetcher = runtimeFetcher(client)) => { queryKey: readonly ["auth", "global", "data", GlobalDataParams]; queryFn: ({ signal }?: QueryFnContext)…historyLogQuery
TanStack Query factory for GET /auth/history-log. logType is required ('alerts' | 'info').
Function
(client: QueryClient, params: HistoryLogParams, fetcher: Fetcher = runtimeFetcher(client)) => { queryKey: readonly ["auth", "history-log", HistoryLogParams]; queryFn: ({ signal }?: QueryFnContext) =>…listRacksQuery
TanStack Query factory for GET /auth/list-racks. type (worker type, e.g. miner / container) is required — the backend 400s with ERR_TYPE_INVALID without it. Response is the per-Kernel nested envelope.
Function
(client: QueryClient, params: ListRacksParams, fetcher: Fetcher = runtimeFetcher(client)) => { queryKey: readonly ["auth", "list-racks", ListRacksParams]; queryFn: ({ signal }?: QueryFnContext) => Pr…listThingsQuery
TanStack Query factory for GET /auth/list-things. query and fields are Mongo-style selectors passed as already-stringified JSON.
Function
(client: QueryClient, params: ListThingsParams = {}, fetcher: Fetcher = runtimeFetcher(client)) => { queryKey: readonly ["auth", "list-things", ListThingsParams]; queryFn: ({ signal }?: QueryFnContex…liveActionsQuery
GET /auth/actions?queries=… — polls all action types in a single request using the multi-type query format. Returns the typed response map { voting, ready, executing, done }.
Function
(client: QueryClient, queries: ActionTypeQuery[] = [ { type: 'voting', opts: { reverse: true, limit: LIVE_ACTIONS_LIMIT } }, { type: 'ready', opts: { reverse: true, limit: LIVE_ACTIONS_LIMIT } }, { t…minerpoolStatsQuery
Convenience wrapper around extDataQuery pinned to type=minerpool and query={"key":"stats"}. Returns the canonical MinerpoolExtDataEntry[][] envelope so the pool counts hook can _head(_head(...)) without casts.
Function
(client: QueryClient, fetcher: Fetcher = runtimeFetcher(client)) => { queryKey: readonly ["auth", "ext-data", ExtDataParams]; queryFn: ({ signal }?: QueryFnContext) => Promise<MinerpoolExtDataEntry[]…minersQuery
GET /auth/miners — miners with their assigned poolConfig (Miner Explorer rows). filter / fields / sort are JSON-stringified selectors. Returns the paginated MinersResponse envelope.
Function
(client: QueryClient, params: MinersParams = {}, fetcher: Fetcher = runtimeFetcher(client)) => { queryKey: readonly ["auth", "miners", MinersParams]; queryFn: ({ signal }?: QueryFnContext) => Promise…pduLayoutQuery
TanStack Query factory for GET /auth/pdu-layout — the static PDU socket grid for a container type. The backend sources it from the container worker's pduGridLayout config keyed by the exact type string, and 400s with `ERR_PDU_LAYOUT_NO…
Function
(client: QueryClient, params: PduLayoutParams, fetcher: Fetcher = runtimeFetcher(client)) => { queryKey: readonly ["auth", "pdu-layout", PduLayoutParams]; queryFn: ({ signal }?: QueryFnContext) => Pr…poolBalanceHistoryQuery
GET /auth/pools/:pool/balance-history — per-pool revenue/hashrate history for the chart view.
Function
(client: QueryClient, pool: string, params: PoolBalanceHistoryParams = {}, fetcher: Fetcher = runtimeFetcher(client)) => { queryKey: readonly ["auth", "pools", string, "balance-history", PoolBalanceH…poolConfigForDeviceQuery
GET /auth/pools/config/:minerId — pool config + override count for a single device/miner.
Function
(client: QueryClient, minerId: string, fetcher: Fetcher = runtimeFetcher(client)) => { queryKey: readonly ["auth", "pools", "config", string]; queryFn: ({ signal }?: QueryFnContext) => Promise<PoolCo…poolConfigsQuery
GET /auth/configs/pool — raw pool configurations. The shape the devkit usePoolConfigs transform consumes.
Function
(client: QueryClient, fetcher: Fetcher = runtimeFetcher(client)) => { queryKey: readonly ["auth", "configs", "pool"]; queryFn: ({ signal }?: QueryFnContext) => Promise<PoolConfigEntry[]>; }poolsQuery
GET /auth/pools — aggregated pools (hashrate / workers / balance / revenue). Feeds the Dashboard pool panel.
Function
(client: QueryClient, fetcher: Fetcher = runtimeFetcher(client)) => { queryKey: readonly ["auth", "pools"]; queryFn: ({ signal }?: QueryFnContext) => Promise<PoolsResponse>; }siteQuery
TanStack Query factory for GET /auth/site — the configured site label.
Function
(client: QueryClient, fetcher: Fetcher = runtimeFetcher(client)) => { queryKey: readonly ["auth", "site"]; queryFn: ({ signal }?: QueryFnContext) => Promise<SiteResponse>; }siteStatusLiveQuery
GET /auth/site/status/live?overwriteCache=true — composite live site-status snapshot (hashrate / power / efficiency / miner, alert & pool counts). Polled on a short interval by useSiteStatusLive; overwriteCache bypasses the server-si…
Function
(client: QueryClient, fetcher: Fetcher = runtimeFetcher(client)) => { queryKey: readonly ["auth", "site", "status", "live"]; queryFn: ({ signal }?: QueryFnContext) => Promise<SiteStatusLive>; }submitActionMutation
POST /auth/actions/voting — submit a single staged action. The backend exposes a fixed voting path, so the client-only type field is stripped from the body; the remaining fields (query, action, params, rackType, …) form the r…
Constant
(client: QueryClient, fetcher?: Fetcher) => { mutationKey: ResourceKey; invalidates: ResourceKey[]; mutationFn: (payload: VotingActionPayload) => Promise<unknown>; }submitBatchActionMutation
POST /auth/actions/voting/batch — submit a batch of staged actions in one request. Expects the SubmitBatchActionsPayload body ({ batchActionsPayload, batchActionUID, suffix? }).
Constant
(client: QueryClient, fetcher?: Fetcher) => { mutationKey: ResourceKey; invalidates: ResourceKey[]; mutationFn: (payload: SubmitBatchActionsPayload) => Promise<unknown>; }tailLogMultiQuery
TanStack Query factory for GET /auth/tail-log/multi — the batched variant of tail-log (keys is a comma-separated list of stat-* keys). Returns the same per-worker nested envelope as tailLogQuery, one series per requested key.
Function
(client: QueryClient, params: TailLogMultiParams, fetcher: Fetcher = runtimeFetcher(client)) => { queryKey: readonly ["auth", "tail-log", "multi", TailLogMultiParams]; queryFn: ({ signal }?: QueryFnC…tailLogQuery
TanStack Query factory for GET /auth/tail-log. Returns the raw nested response shape (Array<Array<TailLogEntry>>) — callers unwrap with _head(response) (or a typed select projection).
Function
(client: QueryClient, params: TailLogParams, fetcher: Fetcher = runtimeFetcher(client)) => { queryKey: readonly ["auth", "tail-log", TailLogParams]; queryFn: ({ signal }?: QueryFnContext) => Promise<…thingConfigQuery
TanStack Query factory for GET /auth/thing-config — a thing type's config document (Settings tab). Both params are required by the backend schema. Response shape is worker-specific, so callers narrow via the generic.
Function
(client: QueryClient, params: ThingConfigParams, fetcher: Fetcher = runtimeFetcher(client)) => { queryKey: readonly ["auth", "thing-config", ThingConfigParams]; queryFn: ({ signal }?: QueryFnContext)…userInfoQuery
GET /auth/userinfo — current authenticated user's profile. Used to resolve the caller's email for partitioning live actions into "mine vs others".
Function
(client: QueryClient, fetcher: Fetcher = runtimeFetcher(client)) => { queryKey: readonly ["auth", "userinfo"]; queryFn: ({ signal }?: QueryFnContext) => Promise<UserInfoResponse>; }voteActionMutation
PUT /auth/actions/voting/:id/vote — approve or reject a pending action.
Constant
(client: QueryClient, fetcher?: Fetcher) => { mutationKey: ResourceKey; invalidates: ResourceKey[]; mutationFn: (payload: VoteActionPayload) => Promise<unknown>; }