Skip to main content
Andromeda exposes two HTTP APIs. Both take and return JSON, and both authenticate you with the same bearer token. Each API serves its OpenAPI 3.1 document at /openapi.json and a browsable version at /docs. The pages here cover the subset of endpoints a cluster user needs. Everything else in those documents is either internal or not yet documented for customers.

​
Endpoints

​
Making requests

The examples use the andromeda CLI, which signs you in and attaches your token to each request. See Authentication to set it up. andromeda call takes the API name, the HTTP method, and the path:
Flags go before the API name. The CLI stops reading flags at the first positional argument, so a flag placed after the path is an error:
On a 2xx response the CLI writes the response body to standard output and exits 0. It does not print the status or headers. On any other status it writes one line to standard error and exits 1:
The CLI does not follow redirects. A 3xx is reported the same way as an error. To call the APIs from your own HTTP client, send Authorization: Bearer <access token>. The authentication guide explains which tokens are accepted.

​
Identifiers

A cluster has one ID, and both APIs use it. You also type it as part of your SSH login name.

​
Organization in the request

Every read is scoped to one organization. Business puts the organization in the path. Platform takes it as a query parameter for cluster routes and in the path for organization routes. The query parameter has two names: The parameter is required when you call as a person, even where the OpenAPI document marks it optional. Without it, Platform returns 400 with code invalid_organization, or 422 where the document marks it required.

​
Field names

Business uses snake_case throughout. Platform uses camelCase, except for /ssh-access and /machines, which use snake_case. Each reference page shows the exact field names.

​
Pagination

Platform lists are ordered by ID and take limit (1 to 200, default 50) and after (an ID). When more items exist, the response carries a token. Pass it as after to get the next page. The token is nextPageToken on /clusters and next_page_token on /machines. It is absent on the last page.
The Business lists on these pages return every item in one response.

​
Retrying writes

Business write endpoints take two headers: If a request fails in transit, send it again with the same key and body. A replay returns 200 with the same result as the first success, which is 201 when the request created something. Reusing a key with a different body returns 409 with code idempotency_mismatch. Your permissions are checked again on every replay. The Platform PUT endpoints on these pages replace a whole document. Sending the same document twice leaves the same result, so they take no idempotency header.

​
Versioning

Paths carry no version. Each API’s OpenAPI document states its current version in info.version.