HTTP API

The CLI and the web app use this API; so can anything that speaks HTTP. Every route is under https://rrun.041.io/api/v1 and takes and returns JSON.

Authentication

Send a credential as a Bearer token:

curl -H "Authorization: Bearer $O41_RRUN_API_KEY" https://rrun.041.io/api/v1/jobs

An organization API key (ak_…) acts in its organization. It can use the job routes below, not the ones marked person.
A signed-in person's token (as the CLI's login gets) names its organization with the x-o41-organization header.

Errors are a 4xx or 5xx status with {"error": "<code>", "message": "…"}.

Jobs

Route	Does
`HEAD /bundles/:sha256`	200 when the bundle is stored, 404 when not
`PUT /bundles/:sha256`	Upload a bundle: the `.tar.gz` body, at most 95 MiB
`POST /offers`	`{resources, limit?}` → `{offers, errors}`, cheapest first
`POST /jobs`	Create a job → 201 and the job
`GET /jobs?limit&before&active`	Jobs, newest first → `{jobs, next}`; `active=1` hides ended jobs
`GET /jobs/:id?wait=<s>`	The job; `wait` (up to 25) holds the answer until it ends
`GET /jobs/:id/logs?after&limit&wait=<s>`	Log lines after `after` → `{lines, next, status, done, expired}`
`GET /jobs/:id/telemetry?from&to&points`	Samples over a range → `{samples, from, to, expired}`
`POST /jobs/:id/cancel`	Cancel → the job
`GET /machines?all=1`	Machines; `all=1` adds terminated ones
`PATCH /machines/:id`	`{enabled}`: turn a reserved machine on or off → the machine
`PATCH /clouds/:cloud[/:name]`	`{gpu?, cpu?}`: an account's switches, or every account's of a cloud → `{clouds}`
`GET /whoami`	`{orgId, userId, credential}`

A job is created from a bundle uploaded first, by its sha256:

{
  "name": "train",
  "command": "./train.sh",
  "bundleSha256": "<64 hex characters>",
  "resources": {
    "gpus": [
      { "model": "RTX5090", "count": 1 },
      { "model": "RTX5080", "count": 4 },
      { "model": "H200", "count": 8 }
    ],
    "minRamGb": 64,
    "minCpus": 0,
    "minDiskGb": 50,
    "minVramGb": 0,
    "spot": true,
    "clouds": [],
    "maxPricePerHour": 0,
    "minCuda": ""
  },
  "image": "",
  "env": { "DATASET": "small" },
  "secrets": { "HF_TOKEN": "hf_…" },
  "timeoutSeconds": 0,
  "keepSeconds": 300,
  "queueSeconds": 1800,
  "restarts": 10,
  "placement": "any"
}

gpus lists the acceptable shapes, any one of which will do; gpus: [] asks for a machine without a GPU. clouds takes clouds ("vast", every account of it) and cloud accounts ("vast/lab-b"); [] means every connected account. maxPricePerHour: 0 means no limit, timeoutSeconds: 0 never. restarts may be left out for 10; 0 never restarts. placement may be left out for any (a free reserved machine first, else a cloud); reserved takes only reserved machines and refuses image and clouds, cloud never takes one. The job carries restarts, placement and its attempt, and once placed its cloud and account (vast/default, or reserved). The bundle is a gzipped tar of the folder.

Log reads continue from next: pass it as after on the next call. With wait, an empty read is held up to that many seconds (at most 25) for new lines. done is true once the job is over and every line has been read.

Settings (person)

Route	Does
`POST /machines`	`{name}`: register a reserved machine → 201 `{id, key, command, machine}`; the key is shown once
`DELETE /machines/:id`	Delete a machine now, or remove a reserved one and revoke its key
`GET /clouds`	Connected cloud accounts with their `gpu` and `cpu` switches
`PUT /clouds/:cloud/:name`	Connect the account `<cloud>/<name>`; the body is its credentials
`DELETE /clouds/:cloud/:name`	Remove an account's credentials → 204
`GET /storage`	Where logs go
`PUT /storage`	`{endpoint, bucket, region, prefix, accessKeyId, secretAccessKey}`
`DELETE /storage`	Back to rrun's own bucket
`GET /api-keys`	`{apiKeys}`
`POST /api-keys`	`{name}` → the key with its `secret`, shown once
`DELETE /api-keys/:id`	Revoke → 204
`GET /audit?limit`	`{entries}`

Feedback

POST /feedback needs no credential, so a report gets through when signing in is what broke. Send {"kind": "bug" | "feedback", "message", "replyTo"?, "context"?}; replyTo is an email address or an http(s) URL. It answers 201 with {id, surface, receivedAt}, and 429 after ten reports a minute from one address.

Outside `/api/v1`

Route	Does
`GET /install.sh`	The installer for `o41-rrun`
`GET /install-server.sh`	Installs the agent on a reserved machine; `sh -s uninstall` removes it
`GET /cli/manifest.json`	The current release: its version and each platform's SHA-256
`GET /cli/:platform`	The current `o41-rrun` binary, gzipped
`GET /cli/:version/:platform`	One release's binary, gzipped
`GET /.well-known/openid-configuration`	rrun's OIDC issuer, for keyless Google Cloud
`GET /.well-known/jwks.json`	Its signing keys

Platforms are linux-x64, linux-arm64, darwin-x64 and darwin-arm64.