> ## 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.

# Errors

> The error body, every error code the cluster endpoints return, and how to handle each.

A failed request returns a non-`2xx` status and a JSON body:

```json theme={null}
{
  "code": "invalid_state",
  "message": "resource state conflicts with the operation",
  "retryable": false
}
```

| Field | Type | Meaning |
| - | - | - |
| `code` | string | Stable, machine-readable reason. Branch on this and the HTTP status. |
| `message` | string | Human-readable description. Its wording can change; do not parse it. |
| `retryable` | boolean | `true` when sending the same request again later may succeed. |

If `retryable` is `false`, change something before sending the request again: the request, your permissions, or the
state of the resource. If it is `true`, retry with exponential backoff and a deadline. For a write, keep the same
`Idempotency-Key` and body when you retry (see [Retrying writes](/api-reference/overview#retrying-writes)).

One endpoint differs. [`POST /organizations/{orgID}/ssh-keys`](/api-reference/business/ssh-keys) reports its own errors with
`error` in place of `message`, for example `{"error": "conflict", "code": "invalid_state", "retryable": false}`.
`code` and `retryable` mean the same thing. Its authentication and schema errors use the standard body.

## Validation errors

When a parameter fails the request schema before the endpoint runs, both APIs return `422` with code
`invalid_request`. An example is a `limit` above 200.

## Codes

These are the codes the endpoints in this reference return. The OpenAPI documents list more, for endpoints
not covered here.

| Status | Code | API | Meaning | What to do |
| - | - | - | - | - |
| 400 | `invalid_request` | both | The body or a header is malformed or missing. | Fix the request. |
| 400 | `invalid_organization` | Platform | The organization query parameter is missing. | Add `businessOrgId` or `organizationId`; see [Organization in the request](/api-reference/overview#organization-in-the-request). |
| 400 | `invalid_cluster` | Platform | The cluster ID is not a UUID. | Use the `id` from a cluster list. |
| 400 | `invalid_pagination` | Platform | `after` is not a valid ID. | Pass the token from the previous page unchanged. |
| 400 | `invalid_scheduler_config` | Platform | A Slurm setting failed validation. | See [Slurm configuration](/api-reference/platform/scheduler#validation). |
| 401 | `unauthorized` | both | No token or an expired token. Business also returns this for a service-account token. | Run `andromeda auth login`. See [Authentication](/clusters/authentication). |
| 403 | `forbidden` | both | You lack the permission the endpoint needs. Platform also returns this for a service-account token. | Ask an organization owner or admin; see [Permissions](/clusters/permissions). |
| 404 | `not_found` | both | The resource does not exist, or it is not in the organization you named. | Check the ID and organization. |
| 409 | `invalid_state` | both | The resource is not in a state that allows the request. | Read the resource. Each endpoint page says what causes this. |
| 409 | `idempotency_mismatch` | Business | The `Idempotency-Key` was already used with a different body. | Use a new key for a new operation. |
| 422 | `invalid_request` | both | A parameter failed schema validation. | Fix the parameter named in `message`. |
| 503 | `service_unavailable`, `integration_unavailable` | both | A dependency is temporarily unavailable. `retryable` is `true`. | Retry with backoff. |
| 503 | `customer_kubernetes_login_not_configured` | Platform | This environment does not offer Kubernetes sign-in. | Contact [Andromeda Support](/support). |


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