API#

Everything the console does in Hesperus goes through the same REST API as Astraeus, at https://console.astralyx.cloud/api/v1, in JSON. This page maps the Hesperus endpoints and who may call them; every endpoint, with its bodies and examples, is in the Hesperus API reference. Authentication, conventions and the error format are in the API Reference overview.

Base URLs#

Scope	URL
A workspace on a cluster	`https://console.astralyx.cloud/api/v1/orgs/{org}/workspaces/{ws}/clusters/{cluster}/api` — written `$API` below
A workspace	`https://console.astralyx.cloud/api/v1/orgs/{org}/workspaces/{ws}` — written `$CONSOLE` below

Authenticate with Authorization: Bearer <API token> (create one under Account → API tokens). Names in paths and bodies are local to your workspace: dev, not the namespace. Below, <org>, <workspace> and <cluster> stand for yours (as in the console's address), and ast_pat_… for your token:

$ export ASTRAEUS_TOKEN=ast_pat_…
$ export CONSOLE="https://console.astralyx.cloud/api/v1/orgs/<org>/workspaces/<workspace>"
$ export API="$CONSOLE/clusters/<cluster>/api"

Roles#

Who	May
viewer	List and read notebooks, runtimes, the limits per person and the presets. Nothing that runs code: no opening, starting, connecting.
editor, admin	Create, change and delete notebooks; open them; create runtimes and environments; start, stop and delete any runtime of the workspace.
The runtime's owner, its members, workspace admins (all editors or admins)	SSH into it, open its IDE and its apps, name its apps.
The runtime's owner, workspace admins	Share it (its members).
admin	Set the limits per person; make a runtime for someone else (`for`); make one that never stops when idle (`idle_timeout_minutes: 0`).

A notebook's Jupyter Server is every editor's: any editor may open any notebook of the workspace.

Endpoints#

Method and path (below `$API` unless said)	What
`GET /notebooks` · `POST /notebooks`	List notebooks; create one `{metadata, spec}`.
`GET`, `PUT`, `DELETE /notebooks/{name}`	One notebook; change its `spec`; delete it (the file stays on the drive).
`POST /notebooks/{name}/open`	Open it: your runtime for it, started if need be → `{notebook, runtime, reused}`.
`GET /notebook-runtimes`	Runtimes, newest first. Filters: `?notebook=`, `?state=`, `?started_by=user:<id>`.
`POST /notebook-runtimes`	Create a runtime or an environment `{metadata, spec, for?}` and start it.
`GET`, `DELETE /notebook-runtimes/{name}`	One runtime; delete it with its run (its drive keeps the files).
`POST /notebook-runtimes/{name}/stop` · `…/start`	Stop it (its GPUs are freed); start it again (a new run).
`POST /notebook-runtimes/{name}/ssh-certificates`	Sign your Ed25519 public key `{public_key}`: a certificate valid 8 hours for this runtime.
`GET /notebook-runtimes/{name}/ssh-sessions`	Its last 50 SSH sessions, newest first.
`GET /interactive/{task}/tcp/2222`	A WebSocket carrying one SSH connection to the runtime (its `ssh.tcp_path`).
`PUT /notebook-runtimes/{name}/members`	Share it: `{members: ["user:<id>"]}`, replacing the list.
`PUT /notebook-runtimes/{name}/apps`	Name its apps: `{apps: [{name, port}]}`, replacing the list.
`POST /notebook-runtimes/{name}/access`	Whether you may reach its IDE (no `port`) or an app's `port`, and where. The console asks it for you.
`GET`, `PUT /notebook-limits/default`	The workspace's limits per person.
`GET /notebook-images`	The presets, `{items, default}`.
`POST $CONSOLE/clusters/{cluster}/runtime-links`	A link into a runtime's IDE or an app `{runtime, port?, path?}` → `{url, origin, expires_at}`: used once, within 60 seconds.

Members by e-mail

The API names people as user:<id>. astra env share and the console take an e-mail; with the API, find the id in GET $CONSOLE/members (user_id).

Examples#

Make an environment with one GPU, then list who connected to it:

$ curl -fsS -X POST "$API/notebook-runtimes" -H "Authorization: Bearer $ASTRAEUS_TOKEN" \
    -H 'content-type: application/json' \
    -d '{"metadata": {"name": "dev"}, "spec": {"kind": "shell", "image": "pytorch", "resources": {"gpus": {"count": 1}}}}' \
    | jq '{state: .status.state, reason: .status.reason, ssh}'
{
  "state": "Pending",
  "reason": "Started by user:7c1e2f4a-93b0-4d51-a6f2-0e8d3b9c1a55",
  "ssh": {"user": "root", "port": 2222, "home": "/content/home/root", "workdir": "/content"}
}
$ curl -fsS "$API/notebook-runtimes/dev/ssh-sessions" -H "Authorization: Bearer $ASTRAEUS_TOKEN" \
    | jq -r '.items[] | [.user, .client, .started_at, .duration_seconds] | @tsv'
user:7c1e2f4a-93b0-4d51-a6f2-0e8d3b9c1a55   astra   2026-10-02T09:14:03.112Z    1834

Give a runtime a credential as a variable (the console and astra do not offer this; the credential hf must exist in the workspace):

$ curl -fsS -X POST "$API/notebook-runtimes" -H "Authorization: Bearer $ASTRAEUS_TOKEN" \
    -H 'content-type: application/json' \
    -d '{"metadata": {"name": "hf-dev"}, "spec": {"kind": "shell", "image": "huggingface", "resources": {"gpus": {"count": 1}},
         "credentials": [{"credential": "hf", "key": "token", "env": "HF_TOKEN"}]}}' > /dev/null

Jupyter Server through a runtime#

A notebook's runtime serves Jupyter Server's REST API at its status.proxy_path, reached below $API without /v1; the machine adds the runtime's token. Editors and admins may use it:

$ TASK=$(curl -fsS "$API/notebook-runtimes/<runtime>" -H "Authorization: Bearer $ASTRAEUS_TOKEN" | jq -r .status.task)
$ curl -fsS "$API/interactive/$TASK/proxy/api/contents/notebooks" -H "Authorization: Bearer $ASTRAEUS_TOKEN" \
    | jq -r '.content[].path'
notebooks/mnist.ipynb

Here <runtime> is a notebook's runtime that is Ready (its name is in the notebook's status.last_runtime).

Errors#

Every code, with its message, is in Limits and errors.