Cluster facts and the Base Load book¶

Three read only routes answer what an agent asks right after /api/whoami: what this Kubernetes cluster is, how to connect to it, and what Base Load it can hold.

Route	What it serves
`GET /api/k8s/cluster`	the cluster's facts: GPU shape, market posture, storage, endpoints
`GET /api/k8s/cluster/kubeconfig`	the cluster's kubeconfig, by token (below)
`GET /api/k8s/reservations`	the Base Load book: rate sheet, availability by size, your blocks

Contract: GET /api/k8s/openapi.json.

Every route takes an org API token and resolves the cluster the way the limit price read does: a token bound to a Kubernetes cluster reads its own; an org wide token resolves when the organization holds one Kubernetes cluster and otherwise passes ?cluster=<name> or gets a 409 ambiguous-cluster. A token bound to a VM cluster is refused with 422 bad-request. A cluster outside your organization is a 404, the same as one that does not exist.

The cluster's facts¶

curl -H "Authorization: Bearer $NC_TOKEN" \
  https://nationalcompute.com/api/k8s/cluster

Field	Meaning
`cluster`, `kind`, `status`	the name, `k8s`, and the platform's status word (`ready` for a usable cluster)
`market`	`true` when the cluster trades on the market; `false` for a fixed cluster the platform sizes
`nodes`, `gpus`	the nodes and GPUs the cluster holds right now
`gpus_per_node`	the node to GPU conversion every bid uses
`cpu_worker`	`true` when the cluster carries a CPU worker
`shared_volume`	`true` when a shared volume is bound to the cluster
`nccl_env`	the environment the platform injects for high performance networking on this cluster, as `{VAR: value}`; `null` when there is none
`gpu_vendor`	which vendor's runtime the nodes carry, so you pick the matching manifests
`gpu_model`	the GPU class the cluster's island sells, what a limit price buys. `null` while the platform has not set one
`base_load_offered`	`true` when Base Load is sold for clusters where this one runs
`kubeconfig_url`	the kubeconfig download on this API, `GET /api/k8s/cluster/kubeconfig?cluster=<name>`, with your token (below). Signing in is the device code flow the kubeconfig triggers
`api_url`, `ingress_url`, `ingress_port`	the API server and the workload ingress endpoint, or `null` where the platform does not derive them for this cluster. The kubeconfig carries the API server regardless
`island_stale`	`null` while the platform hears the island's heartbeat; `{since}` once it has lost the island, and every node read then shows the last snapshot (island staleness)
`feed_error`, `feed_age_s`	the last error of the platform's pull of the node health feed (`null` when the last pull landed), and the data age of what that feed serves in seconds: the time since the newest landed pull plus the platform's cache age at that pull (`null` when no pull has ever landed)

A 404 right after a cluster is created means its record has not landed yet. Retry.

The kubeconfig¶

curl -fsSL -H "Authorization: Bearer $NC_TOKEN" \
  "https://nationalcompute.com/api/k8s/cluster/kubeconfig?cluster=<name>" \
  -o ~/.kube/<name>.yaml

GET /api/k8s/cluster/kubeconfig answers the cluster's kubeconfig as application/yaml: a public client and the cluster's certificate, no secret inside. The first kubectl call prints the device code sign in link a person approves. The cluster resolves like every read here, from the token's binding or ?cluster=. Another organization's cluster can never answer, whatever its name. When your own organization carries one name on two clusters, the read answers 409 ambiguous-cluster and the platform team resolves it.

Status	Meaning
`409 cluster-not-ready`	the cluster is still building
`503 station-unavailable`	the island cannot publish the file right now. Retry

On the MCP server the same read is a grid_api path answering JSON with the YAML inside.

The public onboarding path at access.nationalcompute.com resolves a bare name without a token. When more than one cluster carries the name it answers 409 ambiguous-cluster and points here.

The Base Load book¶

curl -H "Authorization: Bearer $NC_TOKEN" \
  https://nationalcompute.com/api/k8s/reservations

The response is what the console's Burst Capacity page shows under Base Load, read only:

offered is false when no rates are posted where the cluster runs. checkout_open is false while self serve buying is closed there.
rates is the posted sheet, USD per GPU-hour keyed by size in GPUs and then by term in days. days lists the posted terms.
sizes[] is the size matrix: each entry's chips, nodes, whether it is available now, else sold_out_until as an epoch second (null when no live block's end would free it).
reservations[] is the cluster's own book: blocks that are live, and blocks that ended or were cancelled within 30 days, each with id (the block's handle), nodes, chips, rate_usd_per_gpu_hr, starts_at and ends_at (epoch seconds), and status (scheduled, active, ended, cancelled).
deposit_cap_ucredits is the deposit rule's cap in microcredits (1,000,000 = $1): a purchase needs the smaller of the block's price and this figure on the balance.

Buying is a console action (Base Load). This API has no purchase route, and neither does the MCP server, where the book is a grid_api path.