REST API

Everything the console and astra do goes through one HTTP API, served by the console at https://console.astralyx.cloud/api/v1, in JSON. This page explains how to authenticate, how to reach a workspace's runs, machines and data on a cluster, the conventions, and lists every endpoint with examples. Errors are described in Errors.

Base URL

Part	URL	Scope
Console API	https://console.astralyx.cloud/api/v1	Accounts, organisations, members, workspaces, clusters, usage, alerts, audit
A workspace on a cluster	https://console.astralyx.cloud/api/v1/orgs/{org}/workspaces/{ws}/clusters/{cluster}/api/{path}	The workspace's runs, workers, machines, drives, credentials, endpoints and the rest, on one cluster, as you

{org}, {ws} and {cluster} are short names, as in the console's addresses (/o/{org}/w/{ws}/…). On Astraeus Cloud the cluster's short name is usually default; the workspace's Settings lists the clusters it has access to.

In the examples below:

$ export ASTRA_URL=https://console.astralyx.cloud
$ export ASTRA_TOKEN=ast_pat_…
$ export WS="$ASTRA_URL/api/v1/orgs/acme/workspaces/vision/clusters/lab-a/api"

Authentication

Method	How	For
Personal API token	Authorization: Bearer ast_pat_…	Scripts, CI. Create one under Account & tokens; see API tokens.
CLI session	Authorization: Bearer ast_sess_… from astra login (device flow) or POST /auth/login with "mode": "token"	astra; 30 days.
Browser session	The astraeus_session cookie	The console; 12 hours. Requests that change anything must also send the header X-Astraeus-Client (any value), or they fail with 403 CSRF.

A token acts as its owner, with their roles everywhere. To get a CLI session token with a password (rate-limited, see Limits):

$ curl -sS -X POST "$ASTRA_URL/api/v1/auth/login" -H "Content-Type: application/json" \
    -d '{"email": "[email protected]", "password": "…", "mode": "token"}'
{"access_token":"ast_sess_…","token_type":"Bearer","expires_in":2592000}

Check who you are:

$ curl -sS "$ASTRA_URL/api/v1/me" -H "Authorization: Bearer $ASTRA_TOKEN"
{"id":"0192…","email":"[email protected]","name":"Ada","operator":null,
 "orgs":[{"id":"0192…","slug":"acme","name":"Acme Research","role":"admin"}]}

A workspace on a cluster

/api/v1/orgs/{org}/workspaces/{ws}/clusters/{cluster}/api/{path} acts on the cluster as you, inside the workspace, with your workspace role. The workspace must have access to the cluster (404 NOT_BOUND otherwise).

• Names are the workspace's own. Write train, not ws-3f9a1c07b2e4.train: names in the path, in the job, name and task query parameters, in match=task: and match=volume: series matchers, and in request bodies are the workspace's, and responses (including streams) give them back the same way. A name containing . is refused (400 INVALID_NAME).
• Everything stays in the workspace. Every reference in a body must name an object of the workspace (403 NAMESPACE_FORBIDDEN otherwise), and listings show only the workspace's objects.
• Machines are those of the workspace's pools. Listings of machines and GPUs show only them; any other machine is 404 NODE_NOT_FOUND.
• namespaces/<anything> reads the workspace's terms on the cluster, for example GET $WS/namespaces/self.
• Responses carry Cache-Control: no-store.

Limit	Value
Request body	16 MiB
JSON response	256 MiB (503 RESPONSE_TOO_LARGE beyond: narrow the request)

Conventions

Resources and names

Resources have the shape:

{
  "metadata": {"name": "train", "labels": {"team": "vision"}},
  "spec": { "…": "…" },
  "status": {"state": "Running", "reason": "All workers running", "…": "…"}
}

You create a resource by POSTing metadata and spec; Astraeus owns status. You never write the namespace.

Collections have product names and API names; both are accepted, and responses use the API's field names (task_template, requested_resources):

Product name	Path (alias)	API path
Runs	/runs	/jobs
Workers	/workers	/tasks
Machines	/machines	/nodes
Drives	/drives	/datavolumes
Mounts	/mounts	/datavolume-claims
Data sources	/data-sources	/connectors
Credentials	/credentials	/external-secrets
Schedules	/schedules	/cronjobs
Replica groups	/replica-groups	/scaling-groups
Reservations	/reservations	/node-reservations

The alias is accepted in the first path segment, in the second after metrics/ (/metrics/workers/{name}) and in the third after nodes/{name}/ (/machines/{name}/workers).

Lists

A listing answers {"items": [ … ]} with every matching object; listings under a workspace's cluster path are not paginated. Common query parameters:

Parameter	Applies to	Description
state	most collections	Only objects in this state.
labelSelector	most collections	key=value,key2=value2: only objects with all these labels.
order	most collections	asc (default) or desc.
sort_by	workers	created_at, started_at, finished_at, name, updated_at.
job, node	workers	Only the workers of a run, or on a machine.
watch	watchable collections	true or 1: a watch stream instead of a list; see Watch.

Console listings that grow without bound (events, audit) are paged with before and limit; see Events and audit.

Times, sizes and statuses

• Times are RFC 3339, in UTC.
• Sizes are in bytes (memory_bytes), durations in seconds (time_limit_seconds) unless the field name says otherwise.
• POST that creates answers 201 Created with the object; DELETE answers 204 No Content (or 202 Accepted when deletion continues in the background, as for namespaces).

Watch

GET $WS/<collection>?watch=true answers a stream of server-sent events instead of a list. Each data: line is a JSON event:

{"type": "MODIFIED", "name": "train", "object": { "metadata": {"name": "train"}, "spec": {}, "status": {"state": "Running"} }, "revision": 88213}

Field	Description
type	ADDED, MODIFIED, DELETED or ERROR.
name	The object's name.
object	The whole object; absent for DELETED and ERROR.
revision	A number that increases with every change, to order events.
message	With ERROR: why the watch ended.

• The stream opens with every current object as ADDED, then follows changes. A burst of writes to one object becomes one event per state you can see.
• state and labelSelector filter a watch as they filter a list. Only the workspace's objects are sent.
• A comment line is sent every 15 s to keep the connection open.
• A client that falls behind receives ERROR: list again, then watch again.

Watchable collections: jobs, tasks, nodes, cronjobs, external-secrets, endpoints, scaling-groups, connectors, datavolumes (and their aliases), plus models, deployments and agents.

$ curl -sSN "$WS/runs?watch=true" -H "Authorization: Bearer $ASTRA_TOKEN"
data: {"type":"ADDED","name":"train","object":{…},"revision":88190}

data: {"type":"MODIFIED","name":"train","object":{…},"revision":88213}

Console API endpoints

Paths are relative to /api/v1. "Admin" means organisation owner or admin; see Roles and permissions.

Accounts

Method and path	Who	Description
POST /auth/signup	anyone	{"email", "password", "name"}; always 202 (a taken address is told by e-mail).
POST /auth/verify-email	anyone	{"token"} from the e-mail.
POST /auth/login	anyone	{"email", "password", "mode"}; sets the session cookie, or with "mode": "token" returns a CLI session token.
POST /auth/logout	signed in	Ends the current session.
POST /auth/forgot-password	anyone	{"email"}; always 202.
POST /auth/reset-password	anyone	{"token", "password"}; ends every session.
POST /auth/device	anyone	Starts a CLI sign-in: device_code, user_code, verification_uri, verification_uri_complete, expires_in (600), interval (5).
POST /auth/device/approve	signed in	{"user_code"}.
POST /auth/device/token	anyone	{"device_code"}; returns the token once approved.
GET /auth/providers	anyone	Google and GitHub sign-in offered here.
GET /auth/sso/{org}/start	anyone	Starts an organisation's SSO sign-in (?redirect_to=/path).
GET /me	signed in	You, and your organisations with your role.
POST /me/password	signed in	{"current", "new"}; ends your other sessions.
GET, POST /me/tokens; DELETE /me/tokens/{id}	signed in	Your API tokens.
POST /invitations/accept	signed in	{"token"}.

Organisations and people

Method and path	Who	Description
GET, POST /orgs	signed in	Your organisations; create one ({"slug", "name"}): you become its owner.
GET, PATCH, DELETE /orgs/{org}	member; admin (PATCH); owner (DELETE)	Read with your role and limits; rename ({"name"}); delete.
GET /orgs/{org}/members	member	Members with role and since.
PUT, DELETE /orgs/{org}/members/{user}	admin (or yourself, to leave)	Set a role ({"role"}); remove.
GET, POST /orgs/{org}/invitations; DELETE /orgs/{org}/invitations/{id}	admin	Pending invitations; invite ({"email", "role"}); revoke.
GET, PUT, DELETE /orgs/{org}/sso	admin	Single sign-on settings.
GET /orgs/{org}/audit	admin	The audit log (before, limit).

Workspaces

Method and path	Who	Description
GET, POST /orgs/{org}/workspaces	member (yours); admin (all; create)	{"slug", "name"}.
GET, PATCH, DELETE /orgs/{org}/workspaces/{ws}	workspace member; workspace admin (PATCH); admin (DELETE)	With its clusters and terms.
GET /orgs/{org}/workspaces/{ws}/members	workspace member	People and roles.
PUT, DELETE /orgs/{org}/workspaces/{ws}/members/{user}	workspace admin (or yourself)	{"role"}: admin, editor, viewer, auditor.
GET, POST /orgs/{org}/workspaces/{ws}/clusters	workspace member; admin (POST)	Cluster access and terms; give access. See quotas.
PATCH, DELETE /orgs/{org}/workspaces/{ws}/clusters/{cluster}	admin	New terms; remove access (deletes everything there).
POST /orgs/{org}/workspaces/{ws}/connect	admin	Give access to the organisation's only cluster, or Astraeus Cloud, with no limits.
ANY /orgs/{org}/workspaces/{ws}/clusters/{cluster}/api/{path}	workspace member	The workspace on that cluster: see A workspace on a cluster and its endpoints.
GET /orgs/{org}/workspaces/{ws}/runs (also /jobs)	workspace member	Runs on every cluster, from events: cluster, name, state, reason, updated_at, deleted_at. ?state=, ?deleted=true.
GET /orgs/{org}/workspaces/{ws}/events	workspace member	Events (kind, name, before, limit).
GET, PUT /orgs/{org}/workspaces/{ws}/events-retention	workspace member; workspace admin (PUT)	{"days": n or null}.
GET, POST /orgs/{org}/workspaces/{ws}/templates; DELETE …/templates/{id}	workspace member; editor (write)	Run templates: {"name", "description", "spec"}.

Clusters and machines

Method and path	Who	Description
GET /orgs/{org}/clusters	member	The organisation's clusters: Astraeus Cloud and any dedicated cluster.
POST /orgs/{org}/hosted-cluster	admin	Use Astraeus Cloud.
GET /orgs/{org}/clusters/{cluster}/machines (also /nodes)	admin	Every machine of the cluster the organisation may see.
DELETE /orgs/{org}/clusters/{cluster}/nodes/{node}	admin	Remove a machine.
POST …/nodes/{node}/cordon, …/uncordon	admin	Stop or resume new work on a machine.
PUT …/nodes/{node}/placement	admin	{"pool", "site", "rack", "fabric"}.
PUT, DELETE …/nodes/{node}/data-location	admin	Where the machine keeps data: {"path", "max_bytes"}.
POST …/nodes/{node}/gpus/{gpu}/clear-fault	admin	Put a repaired GPU back.
POST …/nodes/{node}/upgrade	admin	{"version"}.
GET /orgs/{org}/clusters/{cluster}/version	member	The cluster's Astraeus release (the version machines' agents should match).
POST /orgs/{org}/clusters/{cluster}/enrollment-tokens	admin	{"labels", "ttl_seconds"}; returns the token and the install command.
GET /orgs/{org}/clusters/{cluster}/reservations	member	Reservations of the cluster's machines, with the workspaces they are for.
POST /orgs/{org}/clusters/{cluster}/reservations; DELETE …/reservations/{name}	admin	Reserve machines (by name or pool) for workspaces or maintenance; remove a reservation.
GET, PUT /orgs/{org}/clusters/{cluster}/prices	member; admin (PUT)	The price table.
GET /orgs/{org}/clusters/{cluster}/events	admin	The cluster's machine events.

Usage, alerts and streams

Method and path	Who	Description
GET /orgs/{org}/usage	member	Usage and cost (start, end); see Usage.
GET /orgs/{org}/alerts	admin	Channels, rules, the last 50 deliveries, and the alert names.
POST /orgs/{org}/alerts/channels; DELETE …/channels/{id}; POST …/channels/{id}/test	admin	See Alerts.
POST /orgs/{org}/alerts/rules; PATCH, DELETE …/rules/{id}	admin
GET, POST /orgs/{org}/event-streams; PATCH, DELETE …/{id}; POST …/{id}/test	admin	See Event streams.

Eos, Anemoi and Hesperus have further console endpoints (deployments shared between workspaces, the model library, the marketplace, guardrails); see their documentation.

Examples

Give a workspace access to a cluster with a quota:

$ curl -sS -X POST "$ASTRA_URL/api/v1/orgs/acme/workspaces/vision/clusters" \
    -H "Authorization: Bearer $ASTRA_TOKEN" -H "Content-Type: application/json" \
    -d '{"cluster": "lab-a", "quota": {"gpus": 16}, "node_selector": {"pool": "h100"}}'
{"cluster":"lab-a","namespace":"ws-3f9a1c07b2e4"}

List the workspace's runs on every cluster:

$ curl -sS "$ASTRA_URL/api/v1/orgs/acme/workspaces/vision/runs?state=Running" \
    -H "Authorization: Bearer $ASTRA_TOKEN"
{"items":[{"cluster":"lab-a","name":"train","state":"Running","reason":"All workers running","updated_at":"2026-10-01T08:02:10.553Z","deleted_at":null}]}

Workspace endpoints on a cluster

Paths are relative to a workspace's cluster path ($WS). Product aliases work everywhere (/runs for /jobs). The role each needs is in Roles and permissions.

Runs and workers

Method and path	Description
GET /jobs	Runs. state, labelSelector, order, watch.
POST /jobs	Create a run: {"metadata": {"name"}, "spec": {…}}; see Run specification. Unknown fields are refused (400 UNKNOWN_FIELD).
GET /jobs/{name}	One run.
DELETE /jobs/{name}	Delete a run; its workers stop.
GET /jobs/{name}/external-accesses	The run's external access endpoints.
GET /tasks	Workers. job, node, state, labelSelector, order, sort_by, watch.
GET /tasks/{name}	One worker; includeHistory=false leaves out its transitions (default true).
DELETE /tasks/{name}	Delete a worker.
POST /tasks/{name}/stop	Stop a worker: {"reason"} (optional).
POST /tasks/{name}/requeue	Put a worker back in the queue: {"reason"} (optional).
GET /tasks/{name}/logs	{"logs": "…"} from its machine; tail (default 1000, at most 10000).
GET /tasks/{name}/activity	Its outbound activity from its machine; limit (default 500, at most 2000), since (RFC 3339).
GET /tasks/{name}/trace	Its tool-call trace (agent runs).
ANY /tasks/{name}/proxy/{path}	Reach a port of the worker, over the connection its machine opened.

$ curl -sS -X POST "$WS/runs" -H "Authorization: Bearer $ASTRA_TOKEN" -H "Content-Type: application/json" \
    -d '{"metadata": {"name": "hello"},
         "spec": {"task_template": {"image": "busybox", "command": "echo", "args": ["hi"],
                                    "requested_resources": {"cpu_cores": 1, "memory_bytes": 1073741824}}}}'
$ curl -sS "$WS/workers?job=hello" -H "Authorization: Bearer $ASTRA_TOKEN"
$ curl -sS "$WS/workers/hello-0/logs?tail=100" -H "Authorization: Bearer $ASTRA_TOKEN"
{"logs":"hi\n"}

Schedules and replica groups

Method and path	Description
GET, POST /cronjobs	Schedules. See Schedules.
GET, DELETE /cronjobs/{name}
POST /cronjobs/{name}/pause, /resume, /trigger	Pause, resume, or start a run now.
GET, POST /scaling-groups	Replica groups. See Replica groups and scale to zero.
GET, PUT, DELETE /scaling-groups/{name}
POST /scaling-groups/{name}/pause, /resume, /activate	activate wakes a group scaled to zero.

Services

Method and path	Description
GET, POST /endpoints	Endpoints. See Endpoints.
GET, PUT, DELETE /endpoints/{name}
ANY /endpoints/{name}/proxy/{path}	Reach the endpoint through Astraeus, over the connection its machine opened.

Data and credentials

Method and path	Description
GET, POST /datavolumes	Drives. See Drives.
GET, DELETE /datavolumes/{name}
GET /datavolume-claims	Mounts (read only): which workers use which drives.
GET, POST /connectors	Data sources. See Data sources.
GET, PUT, DELETE /connectors/{name}
GET /connectors/{name}/index, /files, /partitions, /profile, /diff	Its catalog, from the machine that indexed it.
POST /connectors/{name}/reindex, /scan	Index again; scan now.
GET, POST /external-secrets	Credentials: references to secrets resolved on the machines. See Credentials.
GET, DELETE /external-secrets/{name}
POST /external-secrets/{name}/resync	Fetch the secret again.

Machines and GPUs

Method and path	Description
GET /nodes	Machines of the workspace's pools, with their state, capabilities and latest metrics. state, labelSelector, order, watch.
GET /nodes/{name}	One machine.
GET /nodes/{name}/tasks	What holds the machine: GPUs, cores, memory; another workspace's work shows only as taken.
GET /gpus	Every GPU of those machines: machine, model, memory, utilisation, health (Healthy, AtRisk, Faulty, Foreign), and its holder.

Organisation admins manage machines — remove, cordon, label, data location, GPU faults, upgrades, enrollment and reservations — through the cluster endpoints of the console API.

Metrics and usage

Method and path	Description
GET /metrics/range	A series over time: metric, match=<label>:<value> (repeatable), by=<label>,…, agg (sum, avg, max, min; default avg), rate=true, start, end (Unix seconds; default the last hour), step (seconds; default about 240 points, at least 15 s). Run and worker series are the workspace's own.
GET /metrics/catalog	Every series and its labels.
GET /metrics/nodes/{name}	A machine's latest snapshot.
GET /metrics/tasks/{name}, /metrics/tasks/{name}/utilization	A worker's latest metrics and utilisation.
GET /metrics/jobs/{name}	A run's workers' metrics.
GET /metrics/live?node={name}	One-second samples of a machine, as server-sent events, while you stay connected.
GET /usage	Hourly usage: start, end (default the last 30 days). See Usage.

$ curl -sS "$WS/metrics/range?metric=gpu_utilization_ratio&match=task:train-0&agg=max" \
    -H "Authorization: Bearer $ASTRA_TOKEN"

The workspace's terms

Method and path	Description
GET /namespaces/{any name}	The workspace's terms on the cluster: spec.quota, weight, node_selector, max_priority, host_access, and phase.

Events are not served here: read them with GET /orgs/{org}/workspaces/{ws}/events. See Events and audit.

Related

• Errors
• Roles and permissions
• Limits
• Run specification
• CLI