Use API to manage your resources

You can use the HPC-AI platform's APIs to manage your resources. These APIs provide a comprehensive set of endpoints that allow you to perform various operations on your resources programmatically.

Key Features

Resource Management: Create, read, update, and delete resources through RESTful API endpoints
Authentication: Secure access using authentication tokens
Real-time Operations: Perform operations in real-time with immediate response
Scalability: Handle large-scale resource management efficiently

You can watch the tutorial video or refer to the following documentation to manage your resources via API on HPC-AI.COM.

Getting Started

To begin using the APIs, you'll need to:

Obtain your access token from the platform
Review the available endpoints and their documentation
Start making API calls to manage your resources

Available Endpoints

The platform provides various API endpoints for different resource types and operations.

For detailed information about specific endpoints, please refer to the sections below.

Quickstart Example

Here's a complete example showing how to authenticate and manage instances using the HPC-AI platform APIs:

First, authenticate with the platform to obtain your access token:

curl 'https://www.hpc-ai.com/api/user/login' \
  -H 'content-type: application/json' \
  --data-raw '{"username":"username","password":"password"}'

Response:

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsicGxhdGZvcm0uY29sb3NzYWxhaS5jb20iXSwiZXhwIjoxNzUxNjEyMzUyLCJncm91cCI6WyJhZG1pbiJdLCJpYXQiOjE3NTE1MjU5NTIsImlzcyI6ImhwY2FpdGVjaC5jb20iLCJzdWIiOiIwOGY2ZjI2MS1hNzY2LTQ2M2UtOGJhNC04NWU2YWUzMmY0OTIifQ.i3ZZz2_pUt9dvp6eVK8E6U-F3-C1sq8ZG4NnIpWbXmn09dJZqwDWtAUuQ6itFOMRW_KhIVKMgW5DxcWaNGczdhUsulsMECPhAevdo4dCUuAQuisfVKX0ojwwyX0W5_uAOAJTTTCcdyG6ZzbrC-jUeIfBg8jbVvlRlZj3R2GRRYBEncLAnOFdKA-igl2T7QyRxIUBToXC1PNGFfXq4PXoawJYQFHOOVA2B67ix5JeMspRbJxs1FHkLfYNmfwVj1clp3axIS4jOq9eLqdRVRYJAz0dz4WeUlLy48hz_5jPdmL7h2xmANm3HGFsHPitlaXNjtcsDLrOxBvraxxxxxx",
  "accessExpire": 86400
}

For detailed API description, see: login api

Step 2: Create an Instance

Use the obtained token to create a new instance. The token should be passed as a cookie:

curl 'https://www.hpc-ai.com/api/instance/create' \
  -H 'content-type: application/json' \
  -b 'AccessToken=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsicGxhdGZvcm0uY29sb3NzYWxhaS5jb20iXSwiZXhwIjoxNzUxNTI5Njg2LCJncm91cCI6WyJhZG1pbiJdLCJpYXQiOjE3NTE0NDMyODYsImlzcyI6ImhwY2FpdGVjaC5jb20iLCJzdWIiOiIwOGY2ZjI2MS1hNzY2LTQ2M2UtOGJhNC04NWU2YWUzMmY0OTIifQ.pnTtcw2Spns2Xi_knR_LclTt4eJGUK-lDzIJxHEDi13p7gACVKpJz548QZGq891lg7jpiKpn4QJRgNYxrZQmSThmZVSbJnwmttz01ijy1cGKuq61UI3zaHLPIyVDhqVVjuch0KedFFC9ahr4jSPf6-7ibgaTN7ozHWsMkLKjDyDUPjYfAdfmIz2dtSxJ0WBC6-c4BkwcKOCjHj3eye9BI9c74JUOTVNinwIoKdOzdF5mqI83rVuVpS_7lSAfrsdscqFXRiGtHcHLrb9nLs2Jcv5IkIdnKo5zzRNdpKWYhQWPYKowSlSWDa5eZv-hw3EsyhiQAByZ5x6yYYn_R5Hxxxx' \
  --data-raw '{"name":"example-instance","imageId":"7a81788c-xxxx-xxxx-xxxx-2409e3c8150c","instanceTypeId":"c531be90-xxxx-xxxx-xxxx-59d3d911e29e","region":"fce31a0c-xxxx-xxxx-xxxx-41caa1bdd251","billing":{"chargeMode":"perHour","duration":1},"remoteStorages":[],"instanceConfiguration":{"enableCommonData":false,"enableDocker":false, "initScript": ""},"nodePorts":[]}'

Response:

{
  "instanceId": "notebook-78d36d6a-xxxx-xxxx-xxxx-eea5891c2019"
}

For detailed API description, see: launch instance api

Step 3: List All Instances

Retrieve a list of all your instances:

curl 'https://www.hpc-ai.com/api/instance/list' \
  -H 'content-type: application/json' \
  -b 'AccessToken=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsicGxhdGZvcm0uY29sb3NzYWxhaS5jb20iXSwiZXhwIjoxNzUxNjExOTE2LCJncm91cCI6WyJhZG1pbiJdLCJpYXQiOjE3NTE1MjU1MTYsImlzcyI6ImhwY2FpdGVjaC5jb20iLCJzdWIiOiIwOGY2ZjI2MS1hNzY2LTQ2M2UtOGJhNC04NWU2YWUzMmY0OTIifQ.hDEYrfq5zksB7ywx7scoNM-IJmyW88mYTtz435kamqoO8etsSPHy1yLe2L7WKAkUx_eJOISUauwTUX6Of8ys5gj8MP4BK6Ixh_saAWylRdF7IrFMDb16Yaxc2a91yAhK26IsiDCOoygSBYZ8tMHMUJkudkY2CqzSJvb3Z-kCqJfK8wlgY45Dgx6dTkVeYvA9bohnRQ6R4hI57HJo8fnav3VxkzEbYcs9UmLSNgfPYdC-mCURsSsPUaCTVEUxk9oJaHXmyH61uo7ZQKOHXNqsCHVgwFJPAm3YjPCx3n1jNYPGH-amnrLt0PQVpFa-PGWwjySrOVyjmjtlsxxxxxx' \
  --data-raw '{"pager":{"currentPage":1,"pageSize":20}}'

Response:

{
  "instances": [
    {
      "instanceMetadata": {
        "instanceAuth": {
          "ownerUserName": "08f6f261-xxxx-xxxx-xxxx-85e6ae32f492"
        },
        "instanceId": "notebook-5ac72ea0-xxxx-xxxx-xxxx-eea5891c2019",
        "instanceUsername": "username"
      },
      "instanceSpecInfo": {
        "name": "example-instance",
        "instanceBillingInfo": {
          "chargeMode": "perHour",
          "duration": 1,
          "price": 0.23999999463558197,
          "unit": "$",
          "type": "On-Demand"
        },
        "instanceTypeInfo": {
          "cpu": {
            "amount": 8,
            "type": "INTEL(R) XEON(R) PLATINUM 8558",
            "unit": ""
          },
          "memory": {
            "amount": 16,
            "type": "",
            "unit": "GB"
          },
          "gpu": {
            "amount": 0,
            "type": "",
            "unit": ""
          }
        },
        "regionInfo": {
          "domain": "asia-sg-1.hpc-ai.com",
          "location": "Asia,Singapore",
          "name": "asia-sg-1",
          "sshAddress": "122.xx.xx.202"
        }
      },
      "instanceRuntimeInfo": {
        "createAtUnixMs": 1751527726179,
        "status": "Running",
        "healthy": true,
        "subUrl": "/notebook/notebook-5ac72ea0-xxxx-xxxx-xxxx-eea5891c2019/notebook-5ac72ea0-xxxx-xxxx-xxxx-eea5891c2019-0"
      }
    }
  ],
  "pager": {
    "currentPage": 1,
    "pageSize": 20,
    "totalEntries": 92
  }
}

For detailed API description, see: list instances api

Access JupyterLab

After your instance is created and running, you can access JupyterLab through the following steps:

Check Instance Status: Monitor the instance status in instanceRuntimeInfo.status. When the status shows "Running", your instance is ready for use.
Construct JupyterLab URL: You can access JupyterLab by combining the domain from instanceSpecInfo.regionInfo.domain with the sub-URL from instanceRuntimeInfo.subUrl:
```
https://{instanceSpecInfo.regionInfo.domain}{instanceRuntimeInfo.subUrl}
```
For example, using the response data above:
```
https://asia-sg-1.hpc-ai.com/notebook/notebook-5ac72ea0-xxxx-xxxx-xxxx-eea5891c2019/notebook-5ac72ea0-xxxx-xxxx-xxxx-eea5891c2019-0
```
Access with Authentication: Make sure to include your access token as a cookie when accessing the JupyterLab URL. If you want to access JupyterLab on the website, you should login to hpc-ai.com first.

Use SSH

You can also access your instance via SSH using the following information:

Get SSH Info: The SSH info is available in the array instanceSpecInfo.nodePorts. This should contains a nodeport with port 22, which is the port for SSH. We define this info as sshinfo.
Connect via SSH: Use the SSH address and port to connect to your instance:
```
ssh -p {sshinfo.nodePort} username@{sshinfo.address}
```
For example, using the response data above:
```
ssh -p {sshinfo.nodePort} username@{sshinfo.address}
```

Note: You should configure your SSH public key in advance to ensure access to your instance via SSH.

Use Port Forwarding

If you have configured additional port forwards when launching an instance, they can be found in the array instanceSpecInfo.nodePorts. You can use these port forwards like SSH.

Example: If you have a web application running on port 8080 inside your instance, you can access it through the forwarded port using:

http://{sshinfo.address}:{forwarded_port}

Step 4: Stop an Instance

Stop a specific instance using its ID:

curl 'https://www.hpc-ai.com/api/instance/stop' \
  -H 'content-type: application/json' \
  -b 'AccessToken=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsicGxhdGZvcm0uY29sb3NzYWxhaS5jb20iXSwiZXhwIjoxNzUxNjExOTE2LCJncm91cCI6WyJhZG1pbiJdLCJpYXQiOjE3NTE1MjU1MTYsImlzcyI6ImhwY2FpdGVjaC5jb20iLCJzdWIiOiIwOGY2ZjI2MS1hNzY2LTQ2M2UtOGJhNC04NWU2YWUzMmY0OTIifQ.hDEYrfq5zksB7ywx7scoNM-IJmyW88mYTtz435kamqoO8etsSPHy1yLe2L7WKAkUx_eJOISUauwTUX6Of8ys5gj8MP4BK6Ixh_saAWylRdF7IrFMDb16Yaxc2a91yAhK26IsiDCOoygSBYZ8tMHMUJkudkY2CqzSJvb3Z-kCqJfK8wlgY45Dgx6dTkVeYvA9bohnRQ6R4hI57HJo8fnav3VxkzEbYcs9UmLSNgfPYdC-mCURsSsPUaCTVEUxk9oJaHXmyH61uo7ZQKOHXNqsCHVgwFJPAm3YjPCx3n1jNYPGH-amnrLt0PQVpFa-PGWwjySrOVyjmjtlsxxxxxx' \
  --data-raw '{"instanceId":"notebook-43f8fcd9-xxxx-xxxx-xxxx-96891d9dfb5e"}'

Response:

{
    "instanceId":"notebook-43f8fcd9-xxxx-xxxx-xxxx-96891d9dfb5e"
}

For detailed API description, see: stop instance api

Key Features​

Getting Started​

Available Endpoints​

Quickstart Example​

Step 1: Login to Get Access Token​

Step 2: Create an Instance​

Step 3: List All Instances​

Access JupyterLab​

Use SSH​

Use Port Forwarding​

Step 4: Stop an Instance​

Key Features

Getting Started

Available Endpoints

Quickstart Example

Step 1: Login to Get Access Token

Step 2: Create an Instance

Step 3: List All Instances

Access JupyterLab

Use SSH

Use Port Forwarding

Step 4: Stop an Instance