API reference

Armada has two APIs: gRPC, which armadactl and the client libraries use, and REST (HTTP with JSON), for most of the same operations from scripts or languages without a gRPC client. This page shows you how to call the REST API, and where to find the definitions for both.

Before you start

You need an Armada installation: a laptop install (Getting started), or a team installation (an Armada that your platform team runs for many users). You also need its API addresses:

Call the REST API

Every REST path starts with /v1, unless your platform team has added a prefix. (Lookout's own API, at localhost:30000/api/v1, is a different API used by the web UI.)

Step 1. Create a queue

curl -X POST http://localhost:30001/v1/queue \
  -H 'Content-Type: application/json' \
  -d '{"name": "api-demo", "priorityFactor": 1}'

Check it:

curl http://localhost:30001/v1/queue/api-demo

Success: creating returns {}, and the check returns the queue as JSON, starting {"name":"api-demo","priorityFactor":1,....

Wait about 10 seconds before the next step: Armada checks for new queues every 10 seconds.

Step 2. Submit a job

curl -X POST http://localhost:30001/v1/job/submit \
  -H 'Content-Type: application/json' \
  -d '{
    "queue": "api-demo",
    "jobSetId": "rest-1",
    "jobRequestItems": [{
      "namespace": "default",
      "podSpec": {
        "restartPolicy": "Never",
        "containers": [{
          "name": "hello",
          "image": "alpine:3.21",
          "command": ["sh", "-c", "echo hello from REST"],
          "resources": {
            "requests": {"cpu": "100m", "memory": "64Mi"},
            "limits": {"cpu": "100m", "memory": "64Mi"}
          }
        }]
      }
    }]
  }'

Success: it returns the new job's ID:

{"jobResponseItems":[{"jobId":"<job-id>"}]}

The job follows the same rules as any Armada job: by default, each container's limits must equal its requests, but your platform team can allow higher limits (the server's submission.maxOversubscriptionByResourceRequest). See Submitting jobs.

Step 3. Check the job's state

curl -X POST http://localhost:30001/v1/job/status \
  -H 'Content-Type: application/json' \
  -d '{"jobIds": ["<job-id>"]}'

Success: after about 30 seconds:

{"jobStates":{"<job-id>":3}}

Run it a few times to see the job move along. In testing it went 5 (straight after submitting, before Armada had recorded it), then 0, 7, 2 and 3.

States are returned as numbers. 3 means the job succeeded:

Step 4. Clean up

curl -X DELETE http://localhost:30001/v1/queue/api-demo

Success: it returns {}.

Logging in

A laptop install has no login. On a team installation, send your login in the Authorization header with every request, the same way the gRPC API receives it:

# A token from your login provider
curl -H "Authorization: Bearer <token>" https://<your-armada-rest-address>/v1/queue/<queue>

# Or a username and password, if your installation uses them
curl -u <user>:<password> https://<your-armada-rest-address>/v1/queue/<queue>

Without credentials you get HTTP 401 (Request could not be authenticated ...); without the right permission, HTTP 403 with the same message armadactl shows. /health needs no login.

REST endpoints

Request and response fields are described in the OpenAPI specification, which your installation also serves at <rest-address>/swagger.json. It lists the /v1/node/... paths, which REST doesn't serve, and leaves out the scheduler report paths, which are in pkg/api/schedulerobjects/api.swagger.json.

Cancelling or preempting all the jobs on one node or executor is only in the gRPC API (the Node and Executor services, or armadactl cancel and armadactl preempt with node or executor). The /v1/node/... and /v1/executor... paths in the API definitions return HTTP 404, because the REST API doesn't serve them.

The gRPC API

The gRPC API is defined in Protocol Buffers files in pkg/api. The services you're most likely to use:

You can generate a client for any language that supports gRPC from these files. For Python, Go, Java, Scala, .NET and Rust, use the ready-made client libraries instead.

Troubleshooting