# Cluster facts and the Base Load book

Three read only routes answer what an agent asks right after
[`/api/whoami`](https://docs.nationalcompute.com/authentication.md#discovering-what-a-token-can-address):
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](#the-kubeconfig)) |
| `GET /api/k8s/reservations` | the Base Load book: rate sheet, availability by size, your blocks |

Contract: [`GET /api/k8s/openapi.json`](https://nationalcompute.com/api/k8s/openapi.json).

Every route takes an org API token and resolves the cluster the way the
[limit price read](https://docs.nationalcompute.com/api/k8s-bid.md) 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

```sh
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](https://docs.nationalcompute.com/kubernetes.md#the-cluster-cpu-worker) |
| `shared_volume` | `true` when a [shared volume](https://docs.nationalcompute.com/kubernetes.md#the-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](https://docs.nationalcompute.com/market.md#base-load-capacity) 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](#the-kubeconfig)). 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](https://docs.nationalcompute.com/api/k8s-cluster-pages.md#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

```sh
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](https://docs.nationalcompute.com/api/mcp.md#grid_api-paths)
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

```sh
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](https://docs.nationalcompute.com/market.md#base-load-capacity)).
This API has no purchase route, and neither does the MCP server, where
the book is a [`grid_api` path](https://docs.nationalcompute.com/api/mcp.md#grid_api-paths).