API reference

Health Check

Path:

GET /health

Response:

{
  "status": "UP"
}

List jobs

Returns a list of the most recent jobs

Path:

GET /jobs

Query Params:

• page - page number (default: 1)
• size - page size (default: 10 min:1 max:20)
• q - full text search query

Response

{
  "items": [
    {
      "id": "c5873550dad7439e85ac781168e6e124",
      "name": "sample job",
      "state": "COMPLETED",
      "createdAt": "2023-08-21T21:52:07.751041Z",
      "startedAt": "2023-08-22T01:52:07.765393Z",
      "completedAt": "2023-08-22T01:52:12.900569Z"
    }
    ...
  ],
  "number": 1,
  "size": 4,
  "totalPages": 1
}

Get Job Details

Path:

GET /jobs/<JOB ID>

Response:

{
  "id": "9d7d7184b8f244249c5f5d8b4074f72e",
  "name": "my job",
  "state": "COMPLETED",
  "createdAt": "2023-09-05T01:33:08.413605Z",
  "startedAt": "2023-09-05T01:33:08.414339Z",
  "completedAt": "2023-09-05T01:33:14.167127Z",
  "tasks": [
    {
      "name": "my first task",
      "run": "echo hello world",
      "image": "alpine:3.18.3"
    },
    ...
  ],
  "execution": [
    {
      "id": "aa76535bc23649ca9403e636e377aca3",
      "jobId": "9d7d7184b8f244249c5f5d8b4074f72e",
      "position": 1,
      "name": "my first task",
      "state": "COMPLETED",
      "createdAt": "2023-09-05T01:33:08.414192Z",
      "scheduledAt": "2023-09-05T01:33:08.414378Z",
      "startedAt": "2023-09-05T01:33:08.414574Z",
      "completedAt": "2023-09-05T01:33:08.699749Z",
      "run": "echo hello world",
      "image": "alpine:3.18.3",
      "queue": "default",
      "nodeId": "93a1cd11800741e6863d1adef3bc3d18"
    },
    ...
  ],
  "position": 4,
  "taskCount": 3
}

Submit a job

Submit a new job to be scheduled for execution

Path:

POST /jobs

Headers:

Content-Type:text/yaml

Body:

The job definition represented in YAML

Example:

curl -X POST "http://localhost:8000/jobs" \
     -H "Content-Type: text/yaml" \
     -d \
'
name: sample job
tasks:
  - name: sample task
    image: ubuntu:mantic
    run: echo hello world
'

Or using JSON:

Headers:

Content-Type:application/json

Body:

The job definition represented in JSON

Example:

curl -X POST "http://localhost:8000/jobs" \
     -H "Content-Type: application/json" \
     -d \
'{
  "name": "hello job",
  "tasks": [{
     "name": "say hello",
      "image": "ubuntu:mantic",
      "run": "echo -n hello world\n"
  }]
}'

Cancel a running job

Path:

PUT /jobs/<JOB ID>/cancel

Response:

Success:

HTTP 200

{
  "status": "OK"
}

Failure:

400 Bad Request

{
  "message": "job in not running"
}

Restart a failed/cancelled job

Path:

PUT /jobs/{job id}/restart

Response:

Success:

HTTP 200

{
  "status": "OK"
}

Failure:

400 Bad Request

{
  "message": "job is COMPLETED and can not be restarted"
}

List nodes

Returns a list of all active nodes in the cluster.

Path:

GET /nodes

Response:

[
  {
    "id": "V2CjY4HYEaUCtTZziuJh6M",
    "name": "Coordinator",
    "startedAt": "2024-06-15T19:51:51.111662-04:00",
    "cpuPercent": 17.977528051675314,
    "lastHeartbeatAt": "2024-06-15T23:51:51.226284Z",
    "status": "UP",
    "hostname": "some-host-1",
    "version": "0.1.87"
  },
  {
    "id": "2C2LtZRhktaieM768LQpbP",
    "name": "Worker",
    "startedAt": "2024-06-15T23:51:50.995903Z",
    "cpuPercent": 9.952276537355232,
    "lastHeartbeatAt": "2024-06-15T23:51:51.135511Z",
    "queue": "x-2C2LtZRhktaieM768LQpbP",
    "status": "UP",
    "hostname": "some-host-2",
    "version": "0.1.87"
  }
]

List queues

Returns a list of all queues used by the broker.

Path:

GET /nodes

Response:

[
  {
    "name": "default",
    "size": 12,
    "subscribers": 3,
    "unacked": 3
  },
  {
    "name": "jobs",
    "size": 0,
    "subscribers": 1,
    "unacked": 0
  },
  {
    "name": "logs",
    "size": 0,
    "subscribers": 1,
    "unacked": 0
  },
  ...
]