Skip to main content

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

Getting Started​

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

  1. Obtain your access token from the platform
  2. Review the available endpoints and their documentation
  3. 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:

Step 1: Login to Get Access Token​

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

curl 'https://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://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://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:

  1. Check Instance Status: Monitor the instance status in instanceRuntimeInfo.status. When the status shows "Running", your instance is ready for use.

  2. 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

  3. 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:

  1. 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.

  2. 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://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