> ## Documentation Index
> Fetch the complete documentation index at: https://docs.andromeda.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Cluster API calls are made as a signed-in person with an OIDC bearer token. There are no API keys, and service-account tokens are refused (Business returns 401, Platform returns 403).
> Platform takes the organization as the query parameter businessOrgId on most cluster routes, but as organizationId on /clusters/{clusterId}/ssh-access and /clusters/{clusterId}/kubeconfig.
> The Business API uses snake_case. The Platform API uses camelCase, except /ssh-access and /machines, which use snake_case.
> Business write requests need Idempotency-Key and Audit-Reason headers.
> Storage capacity can grow but cannot shrink, including disk and PVC resizing. Each purchase adds capacity.
> A cluster's storage can be Ceph, WEKA, or both, or NFS on its own. The Ceph quota, the purchased bytes, and Slurm's default 100 GiB shared-volume request are three different quantities.
> Organization permissions cover every cluster the organization owns. A Kubernetes resource grant shares one cluster or namespace, possibly with someone outside the organization, and lets them read that cluster and fetch its kubeconfig. A grant does not give Slurm SSH, Slurm configuration, or organization storage inventory access. Slurm SSH requires organization membership and clusters.ssh.
> The SSH login name is <cluster-id>.<username>. The gateway supports shells, commands, SFTP (including modern scp), and forwarding to loopback ports on the login node. Legacy scp and rsync need their programs on the login node. Remote forwarding and non-loopback destinations are refused.
> Use POST /me/ssh-keys for personal key registration. POST /organizations/{orgID}/ssh-keys is a deprecated alias and requires no membership. Read the preferred shell from GET /me as user.login_shell; update it with PUT /me/login-preferences.
> GET /clusters/{clusterId}/ssh-access returns 200 with ready and reason, even when access is not ready. ready: true does not mean compute nodes or Slurm accounting are ready. To confirm a key or shell change reached a cluster, require observation_current: true and compare ssh_key_set_generation with generation from GET /me/ssh-keys, and shell with user.login_shell from GET /me.
> Adding or removing a login account restarts the cluster's login nodes, Slurm controller, and accounting service, then its compute nodes one at a time; jobs running on a restarting node end. An account is added or removed when a person with an active key gains or loses SSH access, or a person with SSH access registers their first key or revokes their last. Other key changes and shell changes restart no nodes.

# Storage

> Read the storage backends and capacity of your organization's clusters, and how to add capacity.

<Warning>
  Storage capacity can grow but cannot shrink, even if your data would fit in less. This applies to cluster storage
  and to resizing disks and Kubernetes volumes.
</Warning>

On a Slurm cluster, configured shared storage backs `/home` and `/shared` on the login and compute nodes. Ceph and
NFS can provide that shared filesystem. The inventory also reports WEKA when configured. See
[Connect over SSH](/clusters/ssh#files-and-storage).

## Increase storage capacity

Each storage purchase adds to the cluster's capacity rather than setting a new total.

The `purchase` object below and `storage.purchase` in [cluster options](/api-reference/platform/clusters#read-cluster-options)
give the Business API route for buying more storage for a cluster. Purchases made there go through the usual quote
and purchase checks.

## Backends and capacity

* A cluster can have Ceph, WEKA, or both. NFS is used on its own.
* `unknown` means the cluster has not reported whether that backend is configured. Read again later.
* `purchasedRawBytes` is the total storage purchased, not the space used or available. `configuredQuotaBytes` is the
  Ceph quota the cluster has applied. The two can differ for a short time after a purchase.
* Only Ceph entries have quota fields; their absence on WEKA and NFS entries does not mean zero capacity. For NFS
  readiness, read `storage.ready` from [cluster options](/api-reference/platform/clusters#read-cluster-options).
* Slurm's shared volume requests 100 GiB when no size is set. That request is separate from the purchased capacity
  and the Ceph quota.

## Read organization storage

```http theme={null}
GET /organizations/{orgId}/storage
```

**API:** Platform. **Permission:** `clusters.read` in the organization. If you only have a grant for one cluster, read
that cluster's [options](/api-reference/platform/clusters#read-cluster-options) instead.

Returns one entry per cluster the organization owns, including clusters with no storage. The list is not paginated.

### Parameters

| Name | In | Type | Required | Description |
| - | - | - | - | - |
| `orgId` | path | string | yes | Organization ID. |

### Response

| Field | Type | Description |
| - | - | - |
| `items[].clusterId` | string | Cluster ID. |
| `items[].clusterName` | string | Cluster name. |
| `items[].lifecycleState` | string | The cluster's lifecycle state. See [the cluster object](/api-reference/platform/clusters#the-cluster-object). |
| `items[].state` | string | `available`, `unavailable`, or `unknown`, as for [cluster options](/api-reference/platform/clusters#read-cluster-options). |
| `items[].reason` | string, optional | Why `state` is not `available`. |
| `items[].observedAt` | timestamp, optional | When the cluster was last observed. |
| `items[].backends[].type` | string | `ceph`, `weka`, or `nfs`. Ceph and WEKA can coexist; NFS excludes both. |
| `items[].backends[].configured` | string | `configured`, `not_configured`, or `unknown`. |
| `items[].backends[].configuredQuotaBytes` | integer, optional | The Ceph quota the cluster reports, in bytes. Absent for WEKA and NFS. |
| `items[].backends[].purchasedRawBytes` | integer, optional | Total bytes of active storage purchases, on the Ceph entry. Not the space used or available. |
| `items[].backends[].ready` | condition, optional | Ceph readiness. See [conditions](/api-reference/platform/clusters#read-cluster-options). |
| `items[].backends[].purchase` | object, optional | How to buy more storage for this cluster, as in [cluster options](/api-reference/platform/clusters#read-cluster-options). On the Ceph entry of an active or provisioning cluster. |

### Example

```sh theme={null}
andromeda call platform GET "/organizations/$ORG_ID/storage" |
  jq -r '.items[] | .clusterName as $c | .backends[]
    | [$c, .type, .configured, (.configuredQuotaBytes // "not reported")] | @tsv'
```

```text theme={null}
training-h200	ceph	configured	1000000000000
training-h200	weka	not_configured	not reported
training-h200	nfs	not_configured	not reported
```

### Errors

| Status | Code | When |
| - | - | - |
| 403 | `forbidden` | You lack `clusters.read` in the organization. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.