Calling the API

Clusterra does not ship a dedicated CLI — the HTTP API is the interface. This page collects the curl recipes most teams need on day one.

Authentication

Browser sessions use an httpOnly cookie set by POST /v1/auth/callback after the Google OIDC handshake, so they are not useful for scripts. For automation, grab a session cookie from your browser's dev tools and set it in a curl jar:

COOKIE="clusterra_session=<paste-from-browser>"
API="https://api-use1.clusterra.cloud"

curl -H "Cookie: $COOKIE" "$API/v1/users/me"

A first-class service-account flow (machine-to-machine tokens) is on the roadmap. Talk to us if you need it before then.

List your clusters

curl -H "Cookie: $COOKIE" "$API/v1/clusters"

Returns a { clusters: [...], total: N } envelope where each item has id, name, state, and connection_state.

Submit a job

CID=clusXXXX

curl -X POST -H "Cookie: $COOKIE" -H "Content-Type: application/json" \
  "$API/v1/clusters/$CID/jobs/submit" \
  -d '{
    "script": "#!/bin/bash\nsrun hostname",
    "job": {
      "name": "hello",
      "nodes": "1",
      "current_working_directory": "/mnt/efs",
      "environment": ["PATH=/usr/bin:/bin"]
    }
  }'

Submit from a template

# List templates
curl -H "Cookie: $COOKIE" "$API/v1/templates"

# Get parameter schema for one
curl -H "Cookie: $COOKIE" "$API/v1/templates/gromacs-mdrun"

# Submit
curl -X POST -H "Cookie: $COOKIE" -H "Content-Type: application/json" \
  "$API/v1/clusters/$CID/jobs/submit" \
  -d '{
    "template_id": "gromacs-mdrun",
    "params": { "input_tpr": "shared/md.tpr", "ntomp": 4 }
  }'

Tail a running job

JOB=12345

# One-shot snapshot
curl -H "Cookie: $COOKIE" "$API/v1/clusters/$CID/jobs/$JOB/output"

# Live tail (Server-Sent Events)
curl -N -H "Cookie: $COOKIE" \
  "$API/v1/clusters/$CID/jobs/$JOB/output/stream"

Cancel a job

curl -X DELETE -H "Cookie: $COOKIE" \
  "$API/v1/clusters/$CID/jobs/$JOB"

Upload a file

# 1. Get a presigned PUT URL
curl -X POST -H "Cookie: $COOKIE" -H "Content-Type: application/json" \
  "$API/v1/clusters/$CID/storage/presigned-url" \
  -d '{ "filename": "input.pdb", "location": "data" }'
# => { "upload_url": "https://...", "key": "...", "expires_in": 3600 }

# 2. PUT the file directly to S3 — does NOT go through Clusterra.
curl -X PUT -T ./input.pdb "$UPLOAD_URL"

Query Slurm directly

All read-only Slurm endpoints are proxied, so you can talk to slurmrestd without a JWT of your own. A few you are likely to use:

# All jobs
curl -H "Cookie: $COOKIE" "$API/v1/clusters/$CID/jobs"

# All nodes (including idle ones Karpenter is about to consolidate)
curl -H "Cookie: $COOKIE" "$API/v1/clusters/$CID/nodes"

# Scheduler diagnostics
curl -H "Cookie: $COOKIE" "$API/v1/clusters/$CID/stats"

# OpenMetrics — scrape from Prometheus
curl -H "Cookie: $COOKIE" "$API/v1/clusters/$CID/metrics/jobs"

See the API reference for the full list.