Skip to main content

API Documentation

Support
Updated

Introduction

Canopy Wave supports a set of REST API to enable servers to develop management clients or to integrate VMS functionality into users' own custom management infrastructure.

Obtaining an API Key

To manage Canopy Wave Cloud via the API, users must first register for an account at Canopy Wave (https://cloud.canopywave.io). After registering, follow these steps to generate an API key.

  1. In the left navigation bar, click on VM API Keys.

  2. Click on New API Key at the top right of the screen to create a new key.

  3. Copy the generated API key for future API calls.

Screenshot 2025-09-29 at 11.01.56 AM.png

Making an API Call

To make a request to the API, include an HTTP Bearer header with your API key:

Authorization: Bearer <YOUR-API-KEY>

A successful API call will return the following structure:

{
    "data": <PAYLOAD>
}

If the API call is invalid, an error status code and error message will be returned. For example,

401: Unauthorized

The error response will include an error message, formatted as follows:

{
    "error": <error message>
}

 

REST API Endpoints

1. List projects

GET https://cloud-api.canopywave.io/api/v1/projects

Response

Return the list of names of the projects you have permission to access. Many API calls will require project as a parameter. 

{
    "data": [
        "andrew.li@canopywave.com",
        "cynthia@canopywave.com",
        "Org1",
        "Org2"
    ]
}

 

2. List instances

GET https://cloud-api.canopywave.io/api/v1/instances

Query Parameter(s)

Required

  • project: Specifies the project.

Optional

  • region: Specifies the data center.

Example 

GET https://cloud-api.canopywave.io/api/v1/instances?project=cynthia@canopywave.com&dataCenter=KEF-2

Response

Return a list of instances in the specified region. If no region is specified, returns all instances across all regions.

{
    "data": [
        {
            "flavor": "2x H100 (80 GB SXM5)",
            "id": "9bc56d2b-411b-47c3-b93a-691c3931009c",
            "launchedAt": "2025-05-24T01:17:09.000000",
            "name": "cynthia-2",
            "paymentMode": null,
            "publicIp": null,
            "region": "KEF-2",
            "role": "worker",
            "status": "active"
        },
        {
            "flavor": "16 vCPU x86 Server",
            "id": "36346e91-90db-4c38-97cd-bf94e4a138ce",
            "launchedAt": "2025-05-24T00:45:10.000000",
            "name": "cynthia-test-snapshot",
            "paymentMode": null,
            "publicIp": null,
            "region": "KEF-2",
            "role": "worker",
            "status": "active"
        },
        {
            "flavor": "4x H100 (80 GB SXM5)",
            "id": "730dcf5a-bada-45f3-9a32-e8657cf7b200",
            "launchedAt": null,
            "name": "cynthia-4",
            "paymentMode": null,
            "publicIp": null,
            "region": "KEF-2",
            "role": "worker",
            "status": "error"
        }
    ]
}

 

3. List running instances

GET https://cloud-api.canopywave.io/api/v1/instances/running

Query Parameter(s)

Required

  • project: Specifies the project.

  • region: Specifies the data center.

Response

Return all active instances for the specified region

{
    "data": [
        {
            "flavor": "2x H100 (80 GB SXM5)",
            "id": "9bc56d2b-411b-47c3-b93a-691c3931009c",
            "launchedAt": "2025-05-24T01:17:09.000000",
            "name": "cynthia-2",
            "paymentMode": null,
            "publicIp": "213.181.122.171",
            "region": "KEF-2",
            "role": "worker",
            "status": "active"
        },
        {
            "flavor": "16 vCPU x86 Server",
            "id": "36346e91-90db-4c38-97cd-bf94e4a138ce",
            "launchedAt": "2025-05-24T00:45:10.000000",
            "name": "cynthia-test-snapshot",
            "paymentMode": null,
            "publicIp": null,
            "region": "KEF-2",
            "role": "worker",
            "status": "active"
        }
    ]
}

 

4. List details of specified instance

GET https://cloud-api.canopywave.io/api/v1/instances/<instance-id>

Query Parameter(s)

Required

  • region: Specifies the data center.

  • project: Specifies the project.

Response

Return the details of specified instance for the specified region.

{
    "data": {
        "OS-DCF:diskConfig": "MANUAL",
        "OS-EXT-AZ:availability_zone": "nova",
        "OS-EXT-SRV-ATTR:host": "h1-31-gpu",
        "OS-EXT-SRV-ATTR:hypervisor_hostname": "h1-31-gpu",
        "OS-EXT-SRV-ATTR:instance_name": "instance-00001bc9",
        "OS-EXT-STS:power_state": 1,
        "OS-EXT-STS:task_state": null,
        "OS-EXT-STS:vm_state": "active",
        "OS-SRV-USG:launched_at": "2025-05-24T01:17:09.000000",
        "OS-SRV-USG:terminated_at": null,
        "accessIPv4": "",
        "accessIPv6": "",
        "addresses": {
            "cynthia_canopywave_com-network": [
                {
                    "OS-EXT-IPS-MAC:mac_addr": "fa:16:3e:9d:aa:19",
                    "OS-EXT-IPS:type": "fixed",
                    "addr": "172.16.0.252",
                    "version": 4
                }
            ]
        },
        "config_drive": "",
        "created": "2025-05-24T01:15:50Z",
        "flavor": {
            "id": "7c7f97b0-b80f-44dc-859d-71e04834b1cc",
            "links": [
                {
                    "href": "http://213.181.122.220:8774/flavors/7c7f97b0-b80f-44dc-859d-71e04834b1cc",
                    "rel": "bookmark"
                }
            ]
        },
        "hostId": "421e003d15a3a862186597aae14c6e19d0ec66ffe8093222f71b59c5",
        "id": "9bc56d2b-411b-47c3-b93a-691c3931009c",
        "image": {
            "id": "66d16f9e-f984-4738-a170-97457ecfe4b6",
            "links": [
                {
                    "href": "http://213.181.122.220:8774/images/66d16f9e-f984-4738-a170-97457ecfe4b6",
                    "rel": "bookmark"
                }
            ]
        },
        "key_name": null,
        "links": [
            {
                "href": "http://213.181.122.220:8774/v2.1/servers/9bc56d2b-411b-47c3-b93a-691c3931009c",
                "rel": "self"
            },
            {
                "href": "http://213.181.122.220:8774/servers/9bc56d2b-411b-47c3-b93a-691c3931009c",
                "rel": "bookmark"
            }
        ],
        "metadata": {},
        "name": "cynthia-2",
        "os-extended-volumes:volumes_attached": [],
        "progress": 0,
        "security_groups": [
            {
                "name": "ssh"
            },
            {
                "name": "default"
            },
            {
                "name": "monitoring"
            }
        ],
        "status": "ACTIVE",
        "tenant_id": "a6a0dcd9c8764726b4ede6569fc26568",
        "updated": "2025-05-24T01:17:09Z",
        "user_id": "b7ef9befa66d456b866fa09603694b4a"
    }
}

 

5. List Images

GET https://cloud-api.canopywave.io/api/v1/images

Query Parameter(s)

Required

  • project: Specifies the project.

Response

Return all OS images that are available for the instance.

{
    "data": [
        "CPU-Ubuntu.22.04",
        "GPU-Ubuntu.24.04",
        "GPU-Ubuntu.22.04",
        "CPU-Ubuntu.24.04"
    ]
}

 

6. List instance Types

GET https://cloud-api.canopywave.io/api/v1/instance-types

Query Parameter(s)

Required

  • project: Specifies the project.

Response

Returns a list of instance types the specified project has access to.

{
    "data": [
        {
            "flavor": "H100-4",
            "images": [
                "GPU-Ubuntu.22.04",
                "GPU-Ubuntu.24.04"
            ],
            "name": "4x H100 (80 GB SXM5)",
            "price": 900,
            "priceHour": "$2.25 / gpu / hour",
            "specs": "80 cores, 800.0 GB RAM, 2 TB NVMe"
        },
        {
            "flavor": "H100-8",
            "images": [
                "GPU-Ubuntu.22.04",
                "GPU-Ubuntu.24.04"
            ],
            "name": "8x H100 (80 GB SXM5)",
            "price": 1800,
            "priceHour": "$2.25 / gpu / hour",
            "specs": "160 cores, 1536.0 GB RAM, 17 TB NVMe"
        },
        {
            "flavor": "m1.advanced",
            "images": [
                "CPU-Ubuntu.22.04",
                "CPU-Ubuntu.24.04"
            ],
            "name": "16 vCPU x86 Server",
            "price": 56,
            "priceHour": "$0.035 / cpu / hour",
            "specs": "16 cores, 32.0 GB RAM, 500 GB SSD"
        },
        {
            "flavor": "H200-8",
            "images": [
                "GPU-Ubuntu.22.04",
                "GPU-Ubuntu.24.04"
            ],
            "name": "8x H200 (80 GB SXM5)",
            "price": 1800,
            "priceHour": "$3.00 / gpu / hour",
            "specs": "160 cores, 1536.0 GB RAM, 17 TB NVMe"
        }
    ]
}

 

7. List Regions

https://cloud-api.canopywave.io/api/v1/regions

Query Parameter(s)

Required

  • project: Specifies the project.

Response

Returns all regions the specified project has access to.

{
    "data": [
        "KEF-1",
        "KEF-2"
    ]
}

 

8. Query Flavor Availability

GET https://cloud-api.canopywave.io/api/v1/flavor-availability

Query Parameter(s)

Required

  • project: Specifies the project.

  • flavor: Specifies the type of instance.

  • region: Specifies the data center.

Example:

GET https://cloud-api.canopywave.io/api/v1/flavor-availability?project=Canopy Wave&region=KEF-2&flavor=H100-8

Response

Return the number of available instances of the given flavor in the given data center. This number is limited by the number of available public IPs to ensure that every provisioned VM can be assigned a public IP address.

{
    "KEF-2_H100-8_available_vms": 10
}

 

 

 

9. Launch instance

POST https://cloud-api.canopywave.io/api/v1/instance-operations/launch

Request Body

Required

  • region: Specifies the data center.

  • project: Specifies the project.

  • name: A unique identifier for the instance.

  • flavor: Defines the type of instance.

  • image: The operating system to be used for the instance.

  • password: The password for default SSH login.

{
    "region": "your-region",
    "project": your-project",
    "name": "your-instance-name",
    "flavor": "your-selected-flavor",
    "image": "your-selected-image",
    "password": "your-password",
}

 

Optional

  • keypair: The key used for SSH access.

  • is_monitoring: Enables the monitoring page for the instance.

{
    "keypair": "your-key-name",
    "is_monitoring": true,
}

Response

Return the id of the newly-created instance.

{
    "data": {
        "id": "e0ad011b-c690-4ab6-adc1-35187efff1d5"
    }
}

Note: A 200 OK status code from this endpoint acknowledges that the VM instance has begun spawning. To reliably proceed to your next step, send a GET request to https://cloud-api.canopywave.io/api/v1/instances/<instance-id> and ensure that the status field is "ACTIVE".

 

10. Restart instance

POST https://cloud-api.canopywave.io/api/v1/instance-operations/restart

Request Body

Required

  • region: Specified data center.

  • project: Specifies the project.

  • id: The instance id.

{
    "region": "your-region",
    "project": "your-project",
    "id": "your-selected-instance-id",
}

Response

Return the id of the instance.

{
    "data": {
        "id": "e0ad011b-c690-4ab6-adc1-35187efff1d5"
    }
}

 

11. Terminate instance

POST https://cloud-api.canopywave.io/api/v1/instance-operations/terminate

Request Body

Required

  • region: Specifies data center.

  • project: Specifies the project.

  • id: The instance id.

{
    "region": "your-region",
    "project": "your-project",
    "id": "your-selected-instance-id",
}

Response

Return the id of the instance.

{
    "project": "cynthia@canopywave.com",
    "region": "KEF-2",
    "id": "0952989f-8ed0-4228-8526-efff1a6b02bb0b4"
}

 

12. List SSH keys

GET https://cloud-api.canopywave.io/api/v1/ssh-keys

Query Parameter(s)

  • region: Specific data center.

  • project: Specifies the project.

Response

Return a list of ssh-keys for the specified region.

{
    "data": [
        {
            "keypair": {
                "fingerprint": "bd:37:33:4d:8a:77:54:d3:f8:07:51:26:e2:9d:e7:db",
                "name": "cynthia-key-1",
                "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIMy/6SeyjtenrEyUDS4b7LBMCphEOPQu1tcnWGE7keZe andrew.li@canopywave.com"
            }
        },
        {
            "keypair": {
                "fingerprint": "20:65:c6:e6:06:fb:1e:50:e2:1b:10:c1:e0:36:08:3f",
                "name": "cynthia-key-test-generate-key-pair",
                "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCwo/sYPYxyE3fS2PqGq/pJAEfLuphL+u87Z5oDJJoBipNUiyLFWveX6yYCXTjiyfXu6J+VBzHhzx1lTFqqAQqsF1K/TD5/z6GBHnl0NsL4/FG0xmqYIzCGnGD3BN6NSlR4si1H7Jl0CZluXR2Oo37JHUA7V+wDjO1p8WVJVveiI1s20zsQPQOI4Zpc/1UOiS8NgK430k2Up9kqFxV5ory9bvz4QKN7LyabRAgTWtOsLIWD2hEpi6SZOf3MXiwL4c9KOWyheE5/y/38bcep000cTWjsx42v23B88BDuJzDTwPuZrLN7J2Ktk2V"
            }
        },
        {
            "keypair": {
                "fingerprint": "45:2e:fc:23:b2:11:9a:41:77:6f:3c:20:0d:d4:dc:0a",
                "name": "cynthia-key-2",
                "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCi716NkC1Ir9JbIYeBidS3ZvVNkArxUDybahX94weqlDGsxJFlz01bdO7HiA7I2QIocbUqD1I+LNEtMqFi63lr0GQAWhcwGL+/R2RpCNLj5y0VxMCIOYOmEh01qZ7zq2UJn9IvuvU5WD5cSSJrQnXLo1mdYM/eeNrr4NKOY+aoCdmI6gCO44wegG/f8nAMV+zyNw8i+duZXBsZMQTT29TgxcESGTYBY7TOc8WE/MlnbfNo9EHZ8ygYkDNQbfOE5ZcjqkXdHJqFJNyZfa1ko8RcIfltCNNprQLrrP4Qgaf1feaXnvaHUEHArE9"
            }
        }
    ]
}

 

13. Add SSH key

POST https://cloud-api.canopywave.io/api/v1/ssh-keys

Request Body

Required

  • region: Specifies the data center.

  • project: Specifies the project.

  • name: name of new key.

{
    "region": "your-region",
    "project": "your-project",
    "name": "your-ssh-key-name",
}

Optional

  • publicKey: If you want to import your key, enter your public key here.

{
    "publicKey": "ssh-rsa xxxxxxxxxxxxxxx",
}

Response

If no optional parameter is provided, return the public key and private key that the system generates.

{
    "data": {
        "privateKey": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAou9ejZAtSK/SWyGHgYnUt2b1TZAK8VA8m2oV/eMHqpQxrMSR\nZc9NW3Tux4gOyNkCKHG1Kg9SPizRLTKhYut5a9BkAFoXMBi/v0dkaQjS4+/Dm6P0LSY6UmUTsBw\nTML8wArAnk7upfvb6rKaGxlYBGwKu/yH45I+\/Xd\n-----END RSA PRIVATE KEY-----\n",
        "publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCi716NkC1Ir9JbIYeBidS3ZvVNkArxUDybahX94weqlDGsxJFlz01bdO7HiA7I2QIocbUqD1I+Y+aoCdmI6gCO44wegG/f8nAMV+zyNw8i+duZXBsZMQTT29TgxcESGTYBY7TOc8WE/MlnbfNo9EHZ8ygYkDNQbfOE5ZcjqkXdHJqFJNyZfa1ko8RcIfltCNNprQLrrP4Qgaf1feaXnvaHUEHArE9neDudxyyNtUjEi8038RVEOnWzvweP"
    }
}

If the optional parameter is provided, return the public key you imported.

 

14. Delete SSH key

DELETE https://cloud-api.canopywave.io/api/v1/ssh-keys/<key-name>

Query Parameter(s)

  • region: Specifies the data center.

  • project: Specifies the project.

Response

Return the id of the ssh key.

{
    "data": {
        "name": "ddrgdfg"
    }
}

 

15. List shared file systems

GET https://cloud-api.canopywave.io/api/v1/file-systems

Query Parameter(s)

Required

  • region: Specifies the data center.

  • project: Specifies the project.

Response

Return a list of ALL file systems for the specified region.

 

16. Create shared file system

POST https://cloud-api.canopywave.io/api/v1/file-systems

Request Body

Required

  • region: Specified data center.

  • project: Specifies the project.

  • name: Define for identification.

  • size: The size for file system in GB.

{
    "region": "your-region",
    "project": "your-project",
    "name": "your-share-fileSys-name",
    "size": "your-selected size"
}

Response

Return the id the file system.

 

17. Delete shared file system

DELETE https://cloud-api.canopywave.io/api/v1/file-systems/<id>

Query Parameter(s)

  • region: Specifies the data center.

  • project: Specifies the project.

Response

Return the ID of the file system.

 

18. List volumes

GET https://cloud-api.canopywave.io/api/v1/volumes

Query Parameter(s)

  • region: Specifies the data center.

  • project: Specifies the project.

Response

Return a list of ALL volumes for the specified region.

 

19. Create volume

POST https://cloud-api.canopywave.io/api/v1/volumes

Request Body

Required

  • region: Specifies the data center.

  • project: Specifies the project.

  • name: Define for identification.

  • type: The type of storage.

  • size: The size for the volume in GB.

{
    "region": "your-region",
    "project": "your-project",
    "name": "your-volume-name",
    "type": "hdd",
    "size": "your-selected size",
}

Response

Return the id the volume.

{
    "data": {
        "id": "c585949f-f88e-4515-b60e-6e6a6ff0da89"
    }
}

 

20. Delete volume

DELETE https://cloud-api.canopywave.io/api/v1/volumes/<volume-id>

Query Parameter(s)

Required

  • region: The available data center.

  • project: Specifies the project.

Response

Return the id of the volume.

{
    "data": {
        "id": "c585949f-f88e-4515-b60e-6e6a6ff0da89"
    }
}

 

21. List public IP addresses

GET https://cloud-api.canopywave.io/api/v1/ips

Query Parameter(s)

Required

  • region: The available data center.

  • project: Specifies the project.

Response

Return a list of of IP address objects

{
    "data": [
        {
            "id": "09e40279-e757-461f-a6e7-82829aba8536",
            "ip": "213.181.122.171",
            "server": "cynthia-2",
            "serverId": "15876dc7-17cf-4284-973e-324c3543751a",
            "status": "ACTIVE"
        },
        {
            "id": "5bb56a56-372f-41ff-b746-52460f03e99d",
            "ip": "213.181.122.206",
            "server": null,
            "serverId": null,
            "status": "DOWN"
        }
    ]
}

 

22. Allocate public IP address

POST https://cloud-api.canopywave.io/api/v1/ips

Request Body

Required

  • region: The available data center.

  • project: Specifies the project.

Response

Object containing id and ip of newly-allocated IP address

{
    "data": {
        "id": "d3889c71-72b0-43bd-8ab5-7c8091264cf9",
        "ip": "213.181.122.218"
    }
}

 

23. Associate public IP address to instance

POST https://cloud-api.canopywave.io/api/v1/ips/<ipId>/associate

Request Body

Required

  • region: The available data center.

  • project: Specifies the project.

  • instanceId: The ID of the instance to associate the IP with

Path Variable

Required

  • <ipId>: the id of ip you get in 21. GET https://cloud-api.canopywave.io/api/v1/ips

Response

Return the object containing IDs of the IP, port, and instance

{
    "data": {
        "instanceId": "9bc56d2b-411b-47c3-b93a-691c3931009c",
        "ipId": "09e40279-e757-461f-a6e7-82829aba8536",
        "portId": "e56bc512-14a0-4ecd-9480-ca83f8695c4c"
    }
}

 

24. Disassociate public IP address from instance

POST https://cloud-api.canopywave.io/api/v1/ips/<ipId>/disassociate

Request Body

Required

  • region: The available data center.

  • project: Specifies the project.

Response

Return Object containing ID of the IP

{
    "data": {
        "id": "09e40279-e757-461f-a6e7-82829aba8536"
    }
}

 

25. Release public IP address

DELETE https://cloud-api.canopywave.io/api/v1/ips/<id>

Query Parameter(s)

Required

  • region: The available data center.

  • project: Specifies the project.

Response

ID of the released address

{
    "data": {
        "id": "09e40279-e757-461f-a6e7-82829aba8536"
    }
}

 

 

Related articles

Comments

0 comments

Please sign in to leave a comment.