API Reference

Authentication

Get AWS Cognito Configuration

Endpoint

GET api/v1/security/cognito

Example

curl -X GET https://<ip>:<port>/api/v1/security/cognito

Responses

200 OK

{
    "enabled": true,
    "region": "<region>",
    "userPoolID": "<user-pool-id>",
    "clientID": "<client-id>",
    "identityPoolID": "<identity-pool-id>",
    "adminGroups": "<admin groups list>"
}

Enable AWS Cognito

Endpoint

PUT api/v1/security/cognito

Request body

{
    "region": "<region>", 
    "userPoolID": "<user-pool-id>",
    "clientID": "<client-id>",
    "identityPoolID": "<identity-pool-id>",
    "adminGroups":"<admin-groups>", 
    "accessKey": "<access-key>", 
    "secretKey": "<secret-key>", 
    "token":"<access-token>"
}

Example

curl -X PUT https://<ip>:<port>/api/v1/security/cognito \ 
        -H "Content-Type: application/json" \ 
        -d '{"region": "<region>", "userPoolID": "<user-pool-id>", "clientID": "<client-id>", "identityPoolID": "<identity-pool-id>", "adminGroups":"<admin-groups>", "accessKey": "<access-key>", "secretKey": "<secret-key>", "token":"<access-token>"}'

Responses

200 OK

{
    "region": "<region>", 
    "userPoolID": "<user-pool-id>",
    "clientID": "<client-id>",
    "identityPoolID": "<identity-pool-id>",
    "adminGroups":"<admin-groups>", 
    "accessKey": "<access-key>", 
    "secretKey": "<secret-key>", 
    "token":"<access-token>"
}

422 Invalid input

{
    "statusCode": 422,
    "errorCode": 1003,
    "message": "Invalid argument"
}

Disable AWS Cognito

Endpoint
- Delete api/v1/security/cognito

Example

curl -X DELETE https://<ip>:<port>/api/v1/security/cognito \ -H "Content-Type: application/json" \ -H "Authorization: bearer <access-token>"

Responses
- 200 OK
```
                                    
```
  href="#__codelineno-7-1">{ "addr": "https://0.0.0.0:8081", "id": "<id>", "staticFolder": "mmabWeb", "log": { "file": "/var/log/memverge/mmab.log", "level": "debug", "maxSizeMB": 10, "maxBackups": 10 }, "security": { "certFile": "server.crt", "keyFile": "server.pem", "cognito": { "enabled": false, "userPoolID": "us-west-1_xxx", "identityPoolID": "", "clientID": "<client-id>", "adminGroups": [ "admin" ] } }, "ckpt": { "ckptMode": "iterative", "ckptInterval": "15m", "diagnosisMode": false }, "node": { "heartbeat": "30s", "ttl": "5m0s" }, "job": { "diskType": "gp3", "diskSizeGB": 120 } }
- 403 Not privileged
```
{
    "statusCode": 403,
    "errorCode": 2005,
    "message": "User is not privileged, only admin can disable cognito",
    "fields": {
        "adminGroups": [
        "admin"
        ],
        "groupsInToken": null
    }
}
```

Checkpoint Configuration

For checkpoint configurations details (keys, values, definitions), see here.

Get Checkpoint Configuration

Endpoint
- GET api/v1/config

Example

curl -X GET https://<ip>:<port>/api/v1/config

Responses

200 OK

{
    "addr": "https://0.0.0.0:8081",
    "id": "1e6c7914-9f0a-497f-96a8-de9abc41bd2e",
    "staticFolder": "mmabWeb",
    "security": {
        "certFile": "/etc/memverge/mmab/server.crt",
        "keyFile": "/etc/memverge/mmab/server.pem",
        "cognito": {
        "enabled": false,
        "userPoolID": "",
        "identityPoolID": "",
        "clientID": "",
        "adminGroups": [
            "admin"
        ]
        }
    },
    "ckpt": {
        "ckptMode": "iterative",
        "ckptImagePath": "/mmc-checkpoint",
        "ckptInterval": "1h0m0s",
        "ckptFiles": null,
        "IRMapScanPaths": null,
        "rootFSDiff": true,
        "tcpClose": true
    },
    "node": {
        "heartbeat": "30s",
        "ttl": "5m0s"
    },
    "job": {
        "ebsPerJob": true,
        "customTags": {
        "owner": "engineer"
        },
        "ebsMountPath": "/mnt/mmab",
        "diskType": "gp3",
        "diskSizeGB": 120,
        "diskThroughputMB": 125
    }
}

Property description:
- addr - address of the server
- id - should not be changed
- staticFolder - the location of the web frontend folder, should not be changed
- security - security settings
  - certFile - location of the certificate file
  - keyFile - location of the private key file
  - cognito - cognito related settings
    - enabled - enable cognito authentication or not
    - userPoolID - user pool ID in Cognito
    - identityPoolID - the identity pool ID in Cognito
    - clientID - ID of the client for this application, must be a single page application(SPA)
    - adminGroups - users in these groups are treated as administrators
- ckpt - checkpoint settings
  - ckptMode - checkpoint mode, can be iterative or none
  - ckptImagePath - path of the folder to store checkpoint image
  - ckptInterval - interval between checkpoints
  - ckptFiles - extra files to copy during checkpointing
  - IRMapScanPaths - paths to scan for IR map
  - rootFSDiff - whether to include the root filesystem in the checkpoint
  - tcpClose - whether to close all TCP connections
- node - worker node settings
  - heartbeat - interval between heartbeats
  - ttl - time to live for a node
- job - per job settings
  - ebsPerJob - whether to create a new EBS volume for each job
  - ebsMountPath - the mount path of the EBS volume
  - diskType - the type of the EBS volume
  - diskSizeGB - the size of the EBS volume
  - diskThroughputMB - the throughput of the EBS volume in MB

Set Checkpoint Configuration

Endpoint
- PUT api/v1/configKV
Request body

Change specific configuration value with body:
```
{"kvMap": {"<key>":"<value>"}}
```
You can specify multiple keys and values in the same map.

Use the full path of the configuration key such as "node.ttl" Use the string version of the value, e.g.
- "5m" for 5 minutes.
- "true" for true
- "500" for 500
When setting string array values, use , to separate them, e.g.
```
{"kvMap": {"security.cognito.adminGroups":"admin,root"}}
```
When setting string maps, use : to separate key and value. use , to separate pairs, e.g.
```
{"kvMap": {"job.customTags": "owner:name,team:engineer"}}
```
Responses

Same as GET request.

Metrics Reporting

Get Metrics Reporting Summary

Endpoint
- GET api/v1/metrics/summary

Request body

{
    "start": 2025-01-01T00:00:00Z,  //optional; type = time.time
    "end": 2025-01-07T23:59:59Z     //optional; type = time.time
}

Example

GET /api/v1/metrics/summary?start=2025-01-01T00:00:00Z&end=2025-01-07T23:59:59Z

Responses

200 OK

{
    "items": {
        "jobSubmitted": [
        {
            "id": "jobSubmitted",
            "point": {
            "time": "2025-01-01T12:00:00Z",
            "value": 150.0
            },
            "metaData": {
            "queueName": "queue1"
            }
        }
        ],
        "runtime": [
        {
            "id": "runtime",
            "point": {
            "time": "2025-01-02T12:00:00Z",
            "value": 300.5
            },
            "metaData": {
            "queueName": "queue1"
            }
        }
        ], 
        "spotProtection": [
        {
            "id": "spotProtection",
            "point": {
            "time": "2025-01-02T12:00:00Z",
            "value": 3
            },
            "metaData": {
            "queueName": "queue1"
            }
        }
        ],
        "timeSaved": [
        {
            "id": "timeSaved",
            "point": {
            "time": "2025-01-02T12:00:00Z",
            "value": 120.5
            },
            "metaData": {
            "queueName": "queue1"
            }
        }
        ]
    }
}

Get Metrics Reporting Attributes

Endpoint
- GET /api/v1/metric

Responses

200 OK

[
    {
        "name": "Total runtime of jobs",
        "id": "metricDef-runtime.system-total",
        "definition": {
            "id": "metricDef-runtime",
            "description": "Total runtime of jobs",
            "labels": [
                "duration"
            ]
        },
        "object": {
            "id": "system-total",
            "type": "system-total",
            "name": "system-total"
        },
        "levels": [
            {
                "interval": "1m0s",
                "retention": "168h0m0s"
            },
            {
                "interval": "24h0m0s",
                "retention": "18000h0m0s"
            },
            {
                "interval": "30m0s",
                "retention": "2160h0m0s"
            }
        ]
    }
]

Get Metrics Reporting Time-based

Endpoint
- GET /api/v1/metricValue/ObjectID/MetricDefinitionID

Query Parameters:

Parameter	Type	Required	Description
interval	string	No	The interval of the metric values
start	time.Time	No	The start of the time range for metrics
end	time.Time	No	The end of the time range for metrics

Example

GET /api/v1/metricValue/system-total/metricDef-volumeAttachTime?interval=1m&end=2025-03-15T00:00:00Z

Responses

200 OK

{
    "id": "metricDef-volumeAttachTime.system-total",
    "points": [
        {
        "time": "2025-03-13T04:51:00Z",
        "value": 6.741566292
        },
        {
        "time": "2025-03-13T05:40:00Z",
        "value": 6.554704421
        }
    ],
    "metaData": {

    }
}

Logging

Get Logging Configuration

Endpoint

GET api/v1/log/config

Responses

200 OK

{
    "level": "info",
    "maxSizeMB": 10,
    "maxBackups": 10
}

Set Logging Configuration

Endpoint

GET api/v1/log/config
Request Parameters

The request body should contain the properties to change, e.g.

{
  "level": "debug"
}

Responses

Same as the GET request.

Get Management Server Log

Retrieve the latest mmab server log. Note that if you change the log file name in the log config, the path will also be changed to /.log

Endpoint

GET /mmab.log
Responses

A text that contains the content of the log

Get Management Server Access Log

Retrieve the access log of the mmab server. Note that if you change the log file name in the log config, the path will also be changed to /-access.log

Endpoint

GET /mmab-access.log
Responses

A text that contains the content of the log

Get List of Worker Nodes

List the running worker nodes

Endpoint

GET /api/v1/node
Responses

[
  {
    "id": "0e0c7b08-32cc-4737-a2ea-9e2a2bfc7fd1",
    "ips": [
      "172.31.1.234"
    ],
    "hostName": "ip-172-31-1-234.us-west-1.compute.internal",
    "cloud": "aws",
    "arch": "x86_64",
    "cores": 2,
    "cpuModel": "Intel(R) Xeon(R) Platinum 8375C CPU @ 2.90GHz",
    "cpuVendor": "GenuineIntel",
    "memoryInMB": 7638,
    "instance": {
      "zone": "us-west-1a",
      "instanceId": "i-044f3323bfd228fd6",
      "instanceType": "m6i.large",
      "region": "us-west-1",
      "createTime": "2025-03-11T23:05:22Z",
      "payType": "Spot"
    },
    "lastHeartbeat": "2025-03-11T23:12:14.07346093Z"
  }
]

List Worker Node's Log

List available log files of the node. nodeID is the id field we got from the list node response.

Endpoint

GET /api/v1/nodes/nodeID/files
Responses

[
  "/nodes/<nodeID>/var/log/cloud-init-output.log",
  "/nodes/<nodeID>/var/log/memverge/mmrunc.log",
  "/nodes/<nodeID>/var/log/memverge/pagent.log"
]

Get Worker Node's Log

Retrieve the content of the log of the node. Use the path you retrieve from the node files request. e.g.

GET /nodes/<nodeID>/var/log/memverge/mmrunc.log

Endpoint

GET /nodes/nodeID/filePath
Responses

Content of the log file.