cloudscale.ch API Documentation

Overview

Introduction

The cloudscale.ch API is an HTTPS API following the REST principles. Resources (e.g. Servers or Floating IPs) are represented by unique URLs and can be created, listed, controlled and deleted by sending according HTTP requests to those URLs. Errors are returned as standard HTTP status codes.

In the following examples, we are going to use the command line tool curl, that is available for most UNIX and Linux operating systems as well as Microsoft Windows.

Authentication

Each request is authenticated by sending an API token in the request's header. API tokens can be generated and revoked in our Cloud Control Panel and must be kept secret!

An API token is a simple, long string of characters that identifies which user account and what permissions are granted to the requests. The token needs to be specified in the Authorization header of each request with a prefix word called Bearer. curl uses the -H option for this:

$ curl -H 'Authorization: Bearer HELPIMTRAPPEDINATOKENGENERATOR' ...

You can make your life easier by storing the header value in a shell variable. The examples on this page will use that variable instead so make sure to set it when trying the examples.

$ AUTH_HEADER='Authorization: Bearer HELPIMTRAPPEDINATOKENGENERATOR'
$ curl -H "$AUTH_HEADER" ...

When a token is generated, it can be granted either read-only or read-write access. Read-only access only allows you to use the GET method. This means that data can be read, but no changes or actions are possible. Read-write access allows the POST and DELETE methods to be used as well.

HTTP Requests

curl uses the -X option to specify the HTTP method. The default is GET:

$ curl -H "$AUTH_HEADER" -X POST

Three resource types are exported through the API: flavors, servers and images. All resource types follow the same scheme. To list all resources of the same type, send a GET request to the type's URL. For example:

$ curl -H "$AUTH_HEADER" -X GET https://api.cloudscale.ch/v1/flavors

This works with all resource types. Most operations apply to a single instance, for that reason each instance has its own URL:

$ curl -H "$AUTH_HEADER" -X GET https://api.cloudscale.ch/v1/servers/cfde831a-4e87-4a75-960f-89b0148aa2cc

This will return the same information as when listing all instances, but as a single object instead of a list. Operations generally follow the following conventions:

HTTP Response Codes

200 OK

This response status code is used for successful queries. The resulting data is returned in response's body. It happens e.g. when you receive a list of servers.

201 Created

For requests that create a new resources, this response status code signifies that the resource was created successfully. An example would be creating a server. A representation of the new resources is returned in the body of the response.

The URL used to access the new resource is contained in the Location header of the response.

204 No Content

For requests that initiate an action, this response status code signifies that the request was accepted and is already being operated on. An example would be restarting a server. The response has no body.

HTTP Error Codes

HTTP status codes starting at 400 and 500 are used to report errors. Such a response contains a human-readable description of the cause.

400 Bad Request

The request could no be processed because some of the data sent to the API was invalid. The body of the response will contain a description of the problem.

401 Unauthorized

The response status code is used when a request was not properly authorized with an API token. Either no token was specified in the Authorization header or the specified tokes does not exist or has been revoked. The body of the response will contain a description of the problem.

403 Forbidden

The request could not be processed because the necessary permissions were not granted. There are several different causes for this problem:

404 Not Found

This status code is returned when the requested resource type, instance or action could not be found. For example, accessing a server after it has been deleted produces this error.

405 Method Not Allowed

This status code is returned when the wrong HTTP method is used to perform an action or request data.

For example to request a list of flavors, only a GET request may be used. To reboot a server, only a POST request may be used. Any other method will lead to this error.

The exception to this is the HEAD method. This method can be used on all existing resource types, instance and action URLs and will, among other information, return a list of allowed methods in the Allow header.

Servers

Manage servers on the distributed compute platform. Servers can be created, listed, and deleted as well as renamed, scaled, started, stopped, and rebooted.

List Servers

GET /v1/servers

List all servers.

Name Type Description
href URL The URL of the resource.
uuid UUID The unique identifier of the server.
name string The display name of the server.
created_at ISO 8601 date and time The creation date and time of the resource.
status string The current status of the server. Can be "changing", "running" or "stopped".
flavor flavor object The flavor of the server.
image image object The image of the server.
volumes list of volume objects A list of volume objects describing the volumes that are attached to the server. The href and uuid of a volume object will be null until the volume has been allocated.
interfaces list of interface objects A list of interface objects describing the interfaces that are attached to the server, including assigned IP addresses.
ssh_fingerprints list of strings A list of SSH host key fingerprints. Will be null until the host keys could be retrieved from the server.
ssh_host_keys list of strings A list of SSH host keys. Will be null until the host keys could be retrieved from the server.
server_groups list of server group objects A list of server group objects describing the server groups that the server is part of. Currently, at most one group is returned.
anti_affinity_with list of server objects A list of server objects describing the servers that are part of the same anti-affinity group.
Deprecated use server_groups instead.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/servers

Response

HTTP/1.0 200 OK
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

[
  {
    "href": "https://api.cloudscale.ch/v1/servers/47cec963-fcd2-482f-bdb6-24461b2d47b1",
    "uuid": "47cec963-fcd2-482f-bdb6-24461b2d47b1",
    "name": "db-master",
    "created_at": "2019-05-27T16:45:32.241824Z",
    "status": "running",
    "flavor": {
      "slug": "flex-4",
      "name": "Flex-4",
      "vcpu_count": 2,
      "memory_gb": 4
    },
    "image": {
      "slug": "debian-9",
      "name": "Debian 9 (2018-02-02)",
      "operating_system": "Debian",
      "default_username": "debian"
    },
    "volumes": [
      {
        "href": "https://api.cloudscale.ch/v1/volumes/42424242-4242-4242-4242-424242424242",
        "uuid": "42424242-4242-4242-4242-424242424242",
        "name": "db-master-root",
        "size_gb": 50,
        "type": "ssd"
      }
    ],
    "interfaces": [
      {
        "type": "public",
        "addresses": [
          {
            "version": 4,
            "address": "185.98.122.176",
            "prefix_length": 24,
            "gateway": "185.98.122.1",
            "reverse_ptr": "185-98-122-176.cust.cloudscale.ch"
          },
          {
            "version": 6,
            "address": "2a06:c01:1:1902::7ab0:176",
            "prefix_length": 64,
            "gateway": "fe80::1",
            "reverse_ptr": "185-98-122-176.cust.cloudscale.ch"
          }
        ]
      }
    ],
    "ssh_fingerprints": [
      "ecdsa-sha2-nistp256 SHA256:xE11KE3xi8QVXk7bdmN/nWa7r0Iq2FnrqcYe/9wPzU8",
      "ecdsa-sha2-nistp256 f4:bc:da:49:50:9a:f2:f3:fe:f0:21:68:cc:41:f1:e6",
      "ssh-rsa SHA256:wFDYZXQkXmmFeAs/5vAF2iEodribKtNJF7INMqEi6UE",
      "ssh-rsa 8d:55:1d:67:2a:5b:84:71:b6:84:4f:13:e5:65:ea:de"
    ],
    "ssh_host_keys": [
      "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBFEepRNW5hDct4AdJ8oYsb4lNP5E9XY5fnz3ZvgNCEv7m48+bhUjJXUPuamWix3zigp2lgJHC6SChI/okJ41GUY=",
      "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDz2r+mG5MdYv1idI9xzlhYMap7Oa+Q5tccSvagkHzQQRUkaUD3rP4I3/nLqkMJxbeVXw+Mg2T6dO02HaNnq5fZsSXkB3lFcEgtPOaVhjQZkenhW3wFDqKW38t9/iYgzcslMBWe7OK7661al4cbAHuLKmmqAKX9G+HLMdQNsqeF/plKXHBcZzuYZ8wV/obWmton0zhbkzcdpo3egew61xWwe53YuQvJHttKFtNaiBl+2s5sE84how5HvItGf3exAHK3GFdsWTPBYensj4RoSfLW07RwEsmIxbuCFL2DkvCFFOOJYFuZkRMvJbf9DbETuXauKYadWZDM2oMSThqhpVqx"
    ],
    "server_groups": [],
    "anti_affinity_with": []
  }
]
 

Get a Server

GET /v1/servers/{uuid}

Get a server by its UUID.

Name Type Description
href URL The URL of the resource.
uuid UUID The unique identifier of the server.
name string The display name of the server.
created_at ISO 8601 date and time The creation date and time of the resource.
status string The current status of the server. Can be "changing", "running" or "stopped".
flavor flavor object The flavor of the server.
image image object The image of the server.
volumes list of volume objects A list of volume objects describing the volumes that are attached to the server. The href and uuid of a volume object will be null until the volume has been allocated.
interfaces list of interface objects A list of interface objects describing the interfaces that are attached to the server, including assigned IP addresses.
ssh_fingerprints list of strings A list of SSH host key fingerprints. Will be null until the host keys could be retrieved from the server.
ssh_host_keys list of strings A list of SSH host keys. Will be null until the host keys could be retrieved from the server.
server_groups list of server group objects A list of server group objects describing the server groups that the server is part of. Currently, at most one group is returned.
anti_affinity_with list of server objects A list of server objects describing the servers that are part of the same anti-affinity group.
Deprecated use server_groups instead.

Request

$ curl -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/servers/cfde831a-4e87-4a75-960f-89b0148aa2cc

Response

HTTP/1.0 200 OK
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

{
  "href": "https://api.cloudscale.ch/v1/servers/cfde831a-4e87-4a75-960f-89b0148aa2cc",
  "uuid": "cfde831a-4e87-4a75-960f-89b0148aa2cc",
  "name": "its-a-me-mario.cloudscale.ch",
  "created_at": "2019-05-27T16:45:32.241824Z",
  "status": "running",
  "flavor": {
    "slug": "flex-4",
    "name": "Flex-4",
    "vcpus": 2,
    "ram": 4096
  },
  "image": {
    "slug": "ubuntu-18.04",
    "name": "Ubuntu 18.04 LTS (2018-06-13)",
    "operating_system": "Ubuntu"
  },
  "volumes": [
    {
      "href": "https://api.cloudscale.ch/v1/volumes/42424242-4242-4242-4242-424242424242",
      "uuid": "42424242-4242-4242-4242-424242424242",
      "name": "its-a-me-mario.cloudscale.ch-root",
      "size_gb": 50,
      "type": "ssd"
    }
  ],
  "interfaces": [
    {
      "type": "public",
      "addresses": [
        {
          "version": 4,
          "address": "185.98.122.109",
          "prefix_length": "24",
          "gateway": "185.98.122.1"
        },
        {
          "version": 6,
          "address": "2a06:c01:1:1902::7a6d:109",
          "prefix_length": "64",
          "gateway": "fe80::1"
        }
      ]
    }
  ],
  "ssh_fingerprints": [
    "ecdsa-sha2-nistp256 SHA256:xE11KE3xi8QVXk7bdmN/nWa7r0Iq2FnrqcYe/9wPzU8",
    "ecdsa-sha2-nistp256 f4:bc:da:49:50:9a:f2:f3:fe:f0:21:68:cc:41:f1:e6",
    "ssh-rsa SHA256:wFDYZXQkXmmFeAs/5vAF2iEodribKtNJF7INMqEi6UE",
    "ssh-rsa 8d:55:1d:67:2a:5b:84:71:b6:84:4f:13:e5:65:ea:de"
  ],
  "ssh_host_keys": [
    "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBFEepRNW5hDct4AdJ8oYsb4lNP5E9XY5fnz3ZvgNCEv7m48+bhUjJXUPuamWix3zigp2lgJHC6SChI/okJ41GUY=",
    "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDz2r+mG5MdYv1idI9xzlhYMap7Oa+Q5tccSvagkHzQQRUkaUD3rP4I3/nLqkMJxbeVXw+Mg2T6dO02HaNnq5fZsSXkB3lFcEgtPOaVhjQZkenhW3wFDqKW38t9/iYgzcslMBWe7OK7661al4cbAHuLKmmqAKX9G+HLMdQNsqeF/plKXHBcZzuYZ8wV/obWmton0zhbkzcdpo3egew61xWwe53YuQvJHttKFtNaiBl+2s5sE84how5HvItGf3exAHK3GFdsWTPBYensj4RoSfLW07RwEsmIxbuCFL2DkvCFFOOJYFuZkRMvJbf9DbETuXauKYadWZDM2oMSThqhpVqx"
  ],
  "server_groups": [],
  "anti_affinity_with": []
}
 

Create a Server

POST /v1/servers

Create a server with the specified attributes.

The call completes immediately. Thereafter the compute, storage, and network resources will be allocated and the boot process is initiated.

Name Type Description
name string

The name of the new server. The name has to be a valid host name or a fully qualified domain name (FQDN).

In case of an FQDN, the reverse PTR for the public IP address(es) will be set accordingly.

flavor flavor slug The slug of the flavor of the new server.
image image slug The slug of the image of the new server.
volume_size_gb integer The size of the root volume (in gigabytes) of the new server. Default is 10.
bulk_volume_size_gb integer The size of the bulk volume (in gigabytes) of the new server. Default is null in which case no bulk storage will be attached to the new server.
Deprecated use volumes instead.
volumes list of volume objects A list of volume objects specifying the volumes to be attached to the new server. A volume object has the attributes size_gb and type. Default is [].
ssh_keys list of strings A list of SSH public keys to be placed on the new server. Use the full content of your .pub file here.
password string The password of the default user of the new server. When omitted, no password will be set.
use_public_network boolean Attach a public network interface to the new server. Can be true (default) or false.
use_private_network boolean Attach a private network interface to the new server. Can be true or false (default).
use_ipv6 boolean Enable IPv6 on the public network interface of the new server. Can be true (default) or false.
server_groups list of UUIDs A list of UUIDs identifying the server groups to which the new server will be added.
anti_affinity_with UUID The UUID identifying another server to create an anti-affinity group with or add it to the same group as that server.
Deprecated use server_groups instead.
user_data string User data (cloud-config for cloud-init) to use for the new server. Needs to be valid YAML. A default configuration is used if this parameter is not specified. Use only if you are an advanced user with knowledge of cloud-config.

The returned object contains the following information:

Name Type Description
href URL The URL of the resource.
uuid UUID The unique identifier of the server.
name string The display name of the server.
created_at ISO 8601 date and time The creation date and time of the resource.
status string The current status of the server. Can be "changing", "running" or "stopped".
flavor flavor object The flavor of the server.
image image object The image of the server.
volumes list of volume objects A list of volume objects describing the volumes that are attached to the server. The href and uuid of a volume object will be null until the volume has been allocated.
interfaces list of interface objects A list of interface objects describing the interfaces that are attached to the server, including assigned IP addresses.
ssh_fingerprints list of strings A list of SSH host key fingerprints. Will be null until the host keys could be retrieved from the server.
ssh_host_keys list of strings A list of SSH host keys. Will be null until the host keys could be retrieved from the server.
server_groups list of server group objects A list of server group objects describing the server groups that the server is part of. Currently, at most one group is returned.
anti_affinity_with list of server objects A list of server objects describing the servers that are part of the same anti-affinity group.
Deprecated use server_groups instead.

Most Common Errors

  • You don't have enough credits. Please recharge your account.
  • The name of the server is not a valid host name or FQDN.
  • The image or flavor slug is not valid (please verify that the slug still exists).
  • The size of the root volume is not in the range of 10 GB to 2000 GB.
  • The size of an SSD volume is not a multiple of 1 GB or exceeds your current quota.
  • The size of a bulk volume is not a multiple of 100 GB or exceeds your current quota.
  • Your SSH public keys are invalid.
  • The provided password is less than 8 characters long and/or contains non-alphanumeric characters.

Request

$ # With the syntax @.ssh/id_rsa.pub, curl will read the SSH key from that file and upload it. You can specify -F ssh_keys="<..." multiple times to upload multiple keys.
$ curl -i -H "$AUTH_HEADER" -F name=db-master -F flavor=flex-4 -F image=debian-9 -F volume_size_gb=50 -F ssh_keys="<.ssh/id_rsa.pub" https://api.cloudscale.ch/v1/servers

Response

HTTP/1.0 201 Created
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
Location: https://api.cloudscale.ch/v1/servers/47cec963-fcd2-482f-bdb6-24461b2d47b1

{
  "href": "https://api.cloudscale.ch/v1/servers/47cec963-fcd2-482f-bdb6-24461b2d47b1",
  "uuid": "47cec963-fcd2-482f-bdb6-24461b2d47b1",
  "name": "db-master",
  "created_at": "2019-05-27T16:45:32.241824Z",
  "status": "changing",
  "flavor": {
    "slug": "flex-4",
    "name": "Flex-4",
    "vcpu_count": 2,
    "memory_gb": 4
  },
  "image": {
    "slug": "debian-9",
    "name": "Debian 9 (2018-02-02)",
    "operating_system": "Debian",
    "default_username": "debian"
  },
  "volumes": [
    {
      "href": null,
      "uuid": null,
      "name": "db-master-root",
      "size_gb": 50,
      "type": "ssd"
    }
  ],
  "interfaces": [
    {
      "type": "public",
      "addresses": [
        {
          "version": 4,
          "address": "185.98.122.176",
          "prefix_length": 24,
          "gateway": "185.98.122.1",
          "reverse_ptr": "185-98-122-176.cust.cloudscale.ch"
        },
        {
          "version": 6,
          "address": "2a06:c01:1:1902::7ab0:176",
          "prefix_length": 64,
          "gateway": "fe80::1",
          "reverse_ptr": "185-98-122-176.cust.cloudscale.ch"
        }
      ]
    }
  ],
  "ssh_fingerprints": null,
  "ssh_host_keys": null,
  "server_groups": [],
  "anti_affinity_with": []
}

Using Anti-Affinity

$ curl -i -H "$AUTH_HEADER" -F name=db-slave -F flavor=flex-4 -F image=debian-9 -F volume_size_gb=50 -F ssh_keys="<.ssh/id_rsa.pub" -F server_groups=4699d737-da8a-45a3-931e-c41602cc8431 https://api.cloudscale.ch/v1/servers
HTTP/1.0 201 Created
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json
Location: https://api.cloudscale.ch/v1/servers/4328e7a2-5d03-4b7a-8a5d-0b9d6c8abd45

{
  /* See first example of this section for the rest of the response. */
  "server_groups": [
    {
      "href": "https://api.cloudscale.ch/v1/server-groups/4699d737-da8a-45a3-931e-c41602cc8431",
      "uuid": "4699d737-da8a-45a3-931e-c41602cc8431",
      "name" "db-group"
    }
  ],
  "anti_affinity_with": [
    {
      "href": "https://api.cloudscale.ch/v1/servers/47cec963-fcd2-482f-bdb6-24461b2d47b1",
      "uuid": "47cec963-fcd2-482f-bdb6-24461b2d47b1",
      "name" "db-master"
    }
  ]
}

Using Additional Volumes

The use of lists in requests with Content-Type: multipart/form-data is not supported. Use Content-Type: application/json instead.

$ curl -i -H "$AUTH_HEADER" -H "Content-Type: application/json" \
  --data '{"name": "db-master", "flavor": "flex-4", "image": "debian-9", "volume_size_gb": 100, "volumes": [{"size_gb": 150, "type": "ssd"}, {"size_gb": 200, "type": "bulk"}], "ssh_keys": ["'"$(cat ~/.ssh/id_rsa.pub)"'"]}' https://api.cloudscale.ch/v1/servers
HTTP/1.0 201 Created
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json
Location: https://api.cloudscale.ch/v1/servers/7298adae-7856-492f-a2be-ee910ad48d97

{
  /* See first example of this section for the rest of the response. */
  "volumes": [
    {
      "href": null,
      "uuid": null,
      "name": "db-master-root",
      "size_gb": 100,
      "type": "ssd"
    },
    {
      "href": null,
      "uuid": null,
      "name": "db-master-ssd1",
      "size_gb": 150,
      "type": "ssd"
    },
    {
      "href": null,
      "uuid": null,
      "name": "db-master-bulk1",
      "size_gb": 200,
      "type": "bulk"
    }
  ]
}
 

Update a Server

PATCH /v1/servers/{uuid}

Update properties of a server.

Name Type Description
name string The new display name of the server.
flavor flavor slug The new slug of the flavor of the server. In order to change the flavor, the server must be in "stopped" state.

Important Note

Attributes can only be updated one at a time to avoid inconsistencies.

Request

$ curl -i -H "$AUTH_HEADER" -X PATCH -F flavor=flex-32 https://api.cloudscale.ch/v1/servers/4328e7a2-5d03-4b7a-8a5d-0b9d6c8abd45

Response

HTTP/1.0 204 No Content
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json
 

Delete a Server

DELETE /v1/servers/{uuid}

Delete a server along with its root volume.

Important Notes

  • The root volume of the server will be erased permanently.
  • Floating IPs will not be deleted.

Request

$ curl -i -H "$AUTH_HEADER" -X DELETE https://api.cloudscale.ch/v1/servers/4328e7a2-5d03-4b7a-8a5d-0b9d6c8abd45

Response

HTTP/1.0 204 No Content
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json
 

Reboot a Server

POST /v1/servers/{uuid}/reboot

Initiates a reboot of the server. Services will be shut down cleanly, if the server responds to ACPI events.

The status attribute of the server will transition through "changing" and return to "running" after the server has been rebooted.

Request

$ curl -i -H "$AUTH_HEADER" -X POST https://api.cloudscale.ch/v1/servers/47cec963-fcd2-482f-bdb6-24461b2d47b1/reboot

Response

HTTP/1.0 204 No Content
Allow: POST, OPTIONS
Content-Type: text/html; charset=utf-8
 

Start a Server

POST /v1/servers/{uuid}/start

Initiates the boot process of the server.

The status attribute of the server will change from "stopped" to "running" once the server has been powered on.

Request

$ curl -i -H "$AUTH_HEADER" -X POST https://api.cloudscale.ch/v1/servers/47cec963-fcd2-482f-bdb6-24461b2d47b1/start

Response

HTTP/1.0 204 No Content
Allow: POST, OPTIONS
Content-Type: text/html; charset=utf-8
 

Stop a Server

POST /v1/servers/{uuid}/stop

Initiates a shutdown of the server. Services will be shut down cleanly, if the server responds to ACPI events.

The status attribute of the server will change from "running" to "stopped" after the server has been powered off.

Request

$ curl -i -H "$AUTH_HEADER" -X POST https://api.cloudscale.ch/v1/servers/47cec963-fcd2-482f-bdb6-24461b2d47b1/stop

Response

HTTP/1.0 204 No Content
Allow: POST, OPTIONS
Content-Type: text/html; charset=utf-8
 

Server Groups

Manage server groups, which provide a mechanism to group servers according to a certain policy. Currently, the following types of server groups are supported:

  • "anti-affinity": Ensures that each server in the server group runs on a different physical host than the other servers.

List Server Groups

GET /v1/server-groups

List all server groups.

Name Type Description
href URL The URL of the resource.
uuid UUID The unique identifier of the server group.
name string The display name of the server group.
type string The type of the server group. Currently, the only supported type is "anti-affinity".
servers list of server objects A list of servers that are part of the server group.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/server-groups

Response

HTTP/1.0 200 OK
Content-Type: application/json
Allow: GET, POST, HEAD, OPTIONS

[
  {
    "href": "https://api.cloudscale.ch/v1/server-groups/e3b63018-fad6-45f2-9f57-3ea0da726d8c",
    "uuid": "e3b63018-fad6-45f2-9f57-3ea0da726d8c",
    "name": "load balancers",
    "type": "anti-affinity",
    "servers": [
      {
        "href": "https://api.cloudscale.ch/v1/servers/32d2f586-14ff-4da9-81df-134ca45d635f",
        "uuid": "32d2f586-14ff-4da9-81df-134ca45d635f",
        "name": "tesla"
      },
      {
        "href": "https://api.cloudscale.ch/v1/servers/375870c2-d4ee-49af-a048-efcf59ef14ef",
        "uuid": "375870c2-d4ee-49af-a048-efcf59ef14ef",
        "name": "edison"
      }
    ]
  }
]
 

Get a Server Group

GET /v1/server-groups/{uuid}

Get a server group by its UUID.

Name Type Description
href URL The URL of the resource.
uuid UUID The unique identifier of the server group.
name string The display name of the server group.
type string The type of the server group. Currently, the only supported type is "anti-affinity".
servers list of server objects A list of servers that are part of the server group.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/server-groups/e3b63018-fad6-45f2-9f57-3ea0da726d8c

Response

HTTP/1.0 200 OK
Content-Type: application/json
Allow: GET, PATCH, DELETE, HEAD, OPTIONS

{
  "href": "https://api.cloudscale.ch/v1/server-groups/e3b63018-fad6-45f2-9f57-3ea0da726d8c",
  "uuid": "e3b63018-fad6-45f2-9f57-3ea0da726d8c",
  "name": "load balancers",
  "type": "anti-affinity",
  "servers": [
    {
      "href": "https://api.cloudscale.ch/v1/servers/32d2f586-14ff-4da9-81df-134ca45d635f",
      "uuid": "32d2f586-14ff-4da9-81df-134ca45d635f",
      "name": "tesla"
    },
    {
      "href": "https://api.cloudscale.ch/v1/servers/375870c2-d4ee-49af-a048-efcf59ef14ef",
      "uuid": "375870c2-d4ee-49af-a048-efcf59ef14ef",
      "name": "edison"
    }
  ]
}
 

Create a Server Group

POST /v1/server-groups

Create a server group with the specified attributes.

Name Type Description
name string The display name of the new server group.
type string The type of the new server group. Currently, the only supported type is "anti-affinity".

The returned object contains the following information:

Name Type Description
href URL The URL of the resource.
uuid UUID The unique identifier of the server group.
name string The display name of the server group.
type string The type of the server group. Currently, the only supported type is "anti-affinity".
servers list of server objects A list of servers that are part of the server group.

Request

$ curl -i -H "$AUTH_HEADER" -F name='load balancers' -F type='anti-affinity' https://api.cloudscale.ch/v1/server-groups

Response

HTTP/1.0 201 Created
Content-Type: application/json
Location: https://api.cloudscale.ch/v1/server-groups/e3b63018-fad6-45f2-9f57-3ea0da726d8c
Allow: GET, POST, HEAD, OPTIONS

{
  "href": "https://api.cloudscale.ch/v1/server-groups/e3b63018-fad6-45f2-9f57-3ea0da726d8c",
  "uuid": "e3b63018-fad6-45f2-9f57-3ea0da726d8c",
  "name": "load balancers",
  "type": "anti-affinity",
  "servers": []
}
 

Update a Server Group

PATCH /v1/server-groups/{uuid}

Update the properties of a server group.

Name Type Description
name string The new display name of the server group.

Important Note

Attributes can only be updated one at a time to avoid inconsistencies.

Request

$ curl -i -H "$AUTH_HEADER" -X PATCH -F name='current' https://api.cloudscale.ch/v1/server-groups/e3b63018-fad6-45f2-9f57-3ea0da726d8c

Response

HTTP/1.0 204 No Content
Content-Type: application/json
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
 

Delete a Server Group

DELETE /v1/server-groups/{uuid}

Delete a server group.

Most Common Errors

  • There are still servers associated with the server group. Only empty server groups can be deleted.

Request

$ curl -i -H "$AUTH_HEADER" -X DELETE https://api.cloudscale.ch/v1/server-groups/e3b63018-fad6-45f2-9f57-3ea0da726d8c

Response

HTTP/1.0 204 No Content
Content-Type: application/json
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
 

Flavors

Flavors represent different combinations of vCPU count and amount of RAM that can be used when creating a new server. Flavors are identified by their slug, which has to be specified when creating a new or scaling an existing server.

We currently provide the following (publicly available) flavors:

Slug Description
flex-2 Flex-2 (1 vCPU, 2 GB RAM)
flex-4 Flex-4 (2 vCPUs, 4 GB RAM)
flex-8 Flex-8 (4 vCPUs, 8 GB RAM)
flex-16 Flex-16 (6 vCPUs, 16 GB RAM)
flex-32 Flex-32 (8 vCPUs, 32 GB RAM)
flex-48 Flex-48 (10 vCPUs, 48 GB RAM)
flex-64 Flex-64 (12 vCPUs, 64 GB RAM)
flex-96 Flex-96 (16 vCPUs, 96 GB RAM)

List Flavors

GET /v1/flavors

List all available flavors.

Name Type Description
slug string A unique string identifying the flavor within the API.
name string The human readable name of the flavor.
vcpu_count integer The number of vCPUs provided by the flavor.
memory_gb integer The amount of RAM (in gigabytes) provided by the flavor.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/flavors

Response

HTTP/1.0 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json

[
  {
    "slug": "flex-2",
    "name": "Flex-2",
    "vcpu_count": 1,
    "memory_gb": 2
  },
  {
    "slug": "flex-4",
    "name": "Flex-4",
    "vcpu_count": 2,
    "memory_gb": 4
  },
  {
    "slug": "flex-8",
    "name": "Flex-8",
    "vcpu_count": 4,
    "memory_gb": 8
  },
  /* ... */
  {
    "slug": "flex-96",
    "name": "Flex-96",
    "vcpu_count": 16,
    "memory_gb": 96
  }
]
 

Images

Images provide pre-installed operating systems and are used when creating new servers. Separate images are provided for different major versions of each available operating system.

Images are identified by their slug, which has to be specified when creating a new server. We regularly update images to provide minor release upgrades and to keep pre-installed packages at a recent version. If we do a minor release upgrade, the slug of an image will not change but you will automatically get the latest minor release when creating a new server.

We currently provide the following (publicly available) images:

Slug Description
arch-18.06 Arch 18.06
centos-7 CentOS 7
coreos-2079.3 CoreOS 2079.3.0 (stable)
coreos-2107.2 CoreOS 2107.2.0 (beta)
coreos-2135.0 CoreOS 2135.0.0 (alpha)
debian-9 Debian 9.8
fedora-27 Fedora 27
fedora-28 Fedora 28
gentoo-18.06 Gentoo 18.06
opnsense-19.1 OPNsense 19.1
pfsense-2.4.4 pfSense 2.4.4
ubuntu-16.04 Ubuntu 16.04 LTS
ubuntu-18.04 Ubuntu 18.04 LTS

List Images

GET /v1/images

List all images.

Name Type Description
slug string A unique string identifying the image within the API.
name string The human readable name of the image including its release version.
operating_system string The human readable name of the distribution without a release or version number.
default_username string The name of the user that has been set up during server creation and can be used when logging in for the first time.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/images

Response

HTTP/1.0 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json

[
  {
    "slug": "ubuntu-18.04",
    "name": "Ubuntu 18.04 LTS",
    "operating_system": "Ubuntu",
    "default_username": "ubuntu"
  },
  {
    "slug": "ubuntu-16.04",
    "name": "Ubuntu 16.04 LTS",
    "operating_system": "Ubuntu",
    "default_username": "ubuntu"
  },
  {
    "slug": "debian-9",
    "name": "Debian 9",
    "operating_system": "Debian",
    "default_username": "debian"
  },
  {
    "slug": "centos-7",
    "name": "CentOS 7",
    "operating_system": "CentOS",
    "default_username": "centos"
  }
  /* ... */
]
 

Volumes

Manage volumes on the distributed storage clusters. Volumes can be created, listed, and deleted as well as renamed, scaled, and attached to different servers.

Currently, the following volume types are supported:

  • "ssd" for maximum performance and minimal latency
  • "bulk" for your big chunks of data

List Volumes

GET /v1/volumes

List all volumes.

Name Type Description
href URL The URL of the resource.
created_at ISO 8601 date and time The creation date and time of the resource.
uuid UUID The unique identifier of the volume.
name string The display name of the volume.
size_gb integer The size of the volume in GB.
type string There are currently two options: "ssd" (default) and "bulk".
server_uuids list of UUIDs A list of server UUIDs that the volume is attached to. Currently, a volume can only be attached to a single server.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/volumes

Response

HTTP/1.0 200 OK
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

[
  {
    "href": "https://api.cloudscale.ch/v1/volumes/2db69ba3-1864-4608-853a-0771b6885a3a",
    "created_at": "2019-05-29T13:18:42.511407Z",
    "uuid": "2db69ba3-1864-4608-853a-0771b6885a3a",
    "name": "capitano-root",
    "size_gb": 150,
    "type": "ssd",
    "server_uuids": [
      "9e1f9a7f-e8d0-4086-ad7e-fea161d7c5f7"
    ]
  }
]
 

Get a Volume

GET /v1/volumes/{uuid}

Get a volume by its UUID.

Name Type Description
href URL The URL of the resource.
created_at ISO 8601 date and time The creation date and time of the resource.
uuid UUID The unique identifier of the volume.
name string The display name of the volume.
size_gb integer The size of the volume in GB.
type string There are currently two options: "ssd" (default) and "bulk".
server_uuids list of UUIDs A list of server UUIDs that the volume is attached to. Currently, a volume can only be attached to a single server.

Request

$ curl -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/volumes/2db69ba3-1864-4608-853a-0771b6885a3a

Response

HTTP/1.0 200 OK
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

{
  "href": "https://api.cloudscale.ch/v1/volumes/2db69ba3-1864-4608-853a-0771b6885a3a",
  "created_at": "2019-05-29T13:18:42.511407Z",
  "uuid": "2db69ba3-1864-4608-853a-0771b6885a3a",
  "name": "capitano-root",
  "size_gb": 150,
  "type": "ssd",
  "server_uuids": [
    "9e1f9a7f-e8d0-4086-ad7e-fea161d7c5f7"
  ]
}
 

Create a Volume

POST /v1/volumes

Create a volume with the specified attributes.

Name Type Description
name string The display name of the volume.
size_gb integer The size of the volume in GB.
type string There are currently two options: "ssd" (default) and "bulk".
server_uuids list of UUIDs A list of server UUIDs that the volume is attached to. Currently, a volume can only be attached to a single server.

The returned object contains the following information:

Name Type Description
href URL The URL of the resource.
created_at ISO 8601 date and time The creation date and time of the resource.
uuid UUID The unique identifier of the volume.
name string The display name of the volume.
size_gb integer The size of the volume in GB.
type string There are currently two options: "ssd" (default) and "bulk".
server_uuids list of UUIDs A list of server UUIDs that the volume is attached to. Currently, a volume can only be attached to a single server.

Most Common Errors

There are a variety of errors that can occur if you try to create a volume without the proper arguments. Those errors are mostly self-explanatory. However there are a few more common errors:

  • You do not have enough credits. Please add more funds to your account.
  • The size of an SSD volume is not a multiple of 1 GB or exceeds your current quota.
  • The size of a bulk volume is not a multiple of 100 GB or exceeds your current quota.

Request

$ curl -i -H "$AUTH_HEADER" -F size_gb=150 -F name=my-volume-name -F type=ssd -F server_uuids=9e1f9a7f-e8d0-4086-ad7e-fea161d7c5f7 https://api.cloudscale.ch/v1/volumes

Response

HTTP/1.0 201 Created
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
Location: https://api.cloudscale.ch/v1/volumes/2db69ba3-1864-4608-853a-0771b6885a3a

{
  "href": "https://api.cloudscale.ch/v1/volumes/2db69ba3-1864-4608-853a-0771b6885a3a",
  "created_at": "2019-05-29T13:18:42.511407Z",
  "uuid": "2db69ba3-1864-4608-853a-0771b6885a3a",
  "name": "my-volume-name",
  "size_gb": 150,
  "type": "ssd",
  "server_uuids": [
    "9e1f9a7f-e8d0-4086-ad7e-fea161d7c5f7"
  ]
}
 

Update a Volume

PATCH /v1/volumes/{uuid}

Update the properties of a volume.

Name Type Description
name string The display name of the volume.
size_gb integer The size of the volume in GB.
server_uuids list of UUIDs A list of server UUIDs that the volume is attached to. Currently, a volume can only be attached to a single server.

Important Note

Attributes can only be updated one at a time to avoid inconsistencies.

Request

$ curl -i -H "$AUTH_HEADER" -X PATCH -F size_gb=100 https://api.cloudscale.ch/v1/volumes/4328e7a2-5d03-4b7a-8a5d-0b9d6c8abd45

Response

HTTP/1.0 204 No Content
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

Detaching an Existing Volume

The use of lists in requests with Content-Type: multipart/form-data is not supported. Use Content-Type: application/json instead.

$ curl -i -H "$AUTH_HEADER" -H "Content-Type: application/json" -X PATCH  \
--data '{ "server_uuids": [] }' https://api.cloudscale.ch/v1/volumes/4328e7a2-5d03-4b7a-8a5d-0b9d6c8abd45
 

Delete a Volume

DELETE /v1/volumes/{uuid}

Delete a volume and permanently destroy all of its data.

Request

$ curl -i -H "$AUTH_HEADER" -X DELETE https://api.cloudscale.ch/v1/volumes/12345678-5d03-4b7a-8a5d-0b9d6c8abd45

Response

HTTP/1.0 204 No Content
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json
 

Floating IPs

Floating IPs are IP addresses or networks that can be moved between servers. Possible use cases include: High-availability, non-disruptive maintenance, multiple IPs per server, or re-using the same IP after replacing a server.

List Floating IPs

GET /v1/floating-ips

List all Floating IPs.

Name Type Description
href URL The URL of the resource.
created_at ISO 8601 date and time The creation date and time of the resource.
network string The Floating IP in CIDR notation.
ip_version integer The IP version of the Floating IP. Can be either 4 or 6.
server server object The destination server of the Floating IP.
next_hop string The destination IP address of the Floating IP.
reverse_ptr string The reverse pointer of the Floating IP.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/floating-ips

Response

HTTP/1.0 200 OK
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

[
  {
    "href": "https://api.cloudscale.ch/v1/floating-ips/192.0.2.123",
    "created_at": "2019-05-29T13:18:42.505197Z",
    "network": "192.0.2.123/32",
    "ip_version": 4,
    "next_hop": "198.51.100.1",
    "server": {
      "href": "https://api.cloudscale.ch/v1/servers/47cec963-fcd2-482f-bdb6-24461b2d47b1",
      "uuid": "47cec963-fcd2-482f-bdb6-24461b2d47b1",
      "name" "db-master"
    },
    "next_hop": "198.51.100.1",
    "reverse_ptr": "192.0.2.123.cust.cloudscale.ch"
  }
]
 

Get a Floating IP

GET /v1/floating-ips/{network_id}

Get a Floating IP by its network ID.

Name Type Description
href URL The URL of the resource.
created_at ISO 8601 date and time The creation date and time of the resource.
network string The Floating IP in CIDR notation.
ip_version integer The IP version of the Floating IP. Can be either 4 or 6.
server server object The destination server of the Floating IP.
next_hop string The destination IP address of the Floating IP.
reverse_ptr string The reverse pointer of the Floating IP.

Request

$ curl -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/floating-ips/192.0.2.123

Response

HTTP/1.0 200 OK
Allow: GET, POST, DELETE, HEAD, OPTIONS
Content-Type: application/json

{
  "href": "https://api.cloudscale.ch/v1/floating-ips/192.0.2.123",
  "created_at": "2019-05-29T13:18:42.505197Z",
  "network": "192.0.2.123/32",
  "ip_version": 4,
  "server": {
    "href": "https://api.cloudscale.ch/v1/servers/47cec963-fcd2-482f-bdb6-24461b2d47b1",
    "uuid": "47cec963-fcd2-482f-bdb6-24461b2d47b1",
    "name" "db-master"
  },
  "next_hop": "198.51.100.1",
  "reverse_ptr": "192.0.2.123.cust.cloudscale.ch"
}
 

Create a Floating IP

POST /v1/floating-ips

Create a Floating IP with the specified attributes.

Name Type Description
ip_version integer The IP version of the new Floating IP. Can be either 4 or 6.
server UUID The destination server of the new Floating IP.
prefix_length integer The prefix length of the new Floating IP. Default is 32 for IPv4 and 128 for IPv6. Additionally, the prefix length 56 is supported for IPv6 only.
reverse_ptr string The reverse pointer of the new Floating IP.

The returned object contains the following information:

Name Type Description
href URL The URL of the resource.
created_at ISO 8601 date and time The creation date and time of the resource.
network string The Floating IP in CIDR notation.
ip_version integer The IP version of the Floating IP. Can be either 4 or 6.
server server object The destination server of the Floating IP.
next_hop string The destination IP address of the Floating IP.
reverse_ptr string The reverse pointer of the Floating IP.

Request

$ curl -i -H "$AUTH_HEADER" -F ip_version=6 -F server=47cec963-fcd2-482f-bdb6-24461b2d47b1 https://api.cloudscale.ch/v1/floating-ips

Response

HTTP/1.0 201 Created
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
Location: https://api.cloudscale.ch/v1/floating-ips/2001:db8::cafe

{
  "href": "https://api.cloudscale.ch/v1/floating-ips/2001:db8::cafe",
  "created_at": "2019-05-29T13:18:42.505197Z",
  "network": "2001:db8::cafe/128",
  "ip_version": 6,
  "server": {
    "href": "https://api.cloudscale.ch/v1/servers/47cec963-fcd2-482f-bdb6-24461b2d47b1",
    "uuid": "47cec963-fcd2-482f-bdb6-24461b2d47b1",
    "name" "db-master"
  },
  "next_hop": "2001:db8:dead:beef::42",
  "reverse_ptr": "null"
}
 

Update a Floating IP

PATCH /v1/floating-ips/{network_id}

Update the properties of a Floating IP.

Name Type Description
server UUID The new destination server of the Floating IP.
reverse_ptr string The new reverse pointer of the Floating IP.

Important Note

Attributes can only be updated one at a time to avoid inconsistencies.

Request

$ curl -H "$AUTH_HEADER" -X PATCH -F server=47777777-fcd2-482f-bdb6-24461b2d47b1 https://api.cloudscale.ch/v1/floating-ips/192.0.2.123

Response

HTTP/1.0 204 No Content
Allow: GET, POST, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json
Location: https://api.cloudscale.ch/v1/floating-ips/192.0.2.123
 

Update a Floating IP

POST /v1/floating-ips/{network_id} Deprecated

Deprecated, might be removed in future API versions.

The POST method on this URL has been deprecated in favor of the PATCH method.

Update the properties of a Floating IP.

Name Type Description
server UUID The new destination server of the Floating IP.

Request

$ curl -H "$AUTH_HEADER" -F server=47777777-fcd2-482f-bdb6-24461b2d47b1 https://api.cloudscale.ch/v1/floating-ips/192.0.2.123

Response

HTTP/1.0 200 OK
Allow: GET, POST, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json
Location: https://api.cloudscale.ch/v1/floating-ips/192.0.2.123

{
  "href": "https://api.cloudscale.ch/v1/floating-ips/192.0.2.123",
  "created_at": "2019-05-29T13:18:42.505197Z",
  "network": "192.0.2.123/32",
  "ip_version": 4,
  "server": {
    "href": "https://api.cloudscale.ch/v1/servers/47777777-fcd2-482f-bdb6-24461b2d47b1",
    "uuid": "47cec963-fcd2-482f-bdb6-24461b2d47b1",
    "name" "db-master"
  },
  "next_hop": "198.51.100.1",
  "reverse_ptr": "192.0.2.123.cust.cloudscale.ch"
}
 

Delete a Floating IP

DELETE /v1/floating-ips/{network_id}

Delete a Floating IP.

Request

$ curl -i -H "$AUTH_HEADER" -X DELETE https://api.cloudscale.ch/v1/floating-ips/192.0.2.123

Response

HTTP/1.0 204 No Content
Allow: GET, POST, DELETE, HEAD, OPTIONS
Content-Type: application/json
 

Objects Users

Manage users of the S3-compatible object storage.

List Objects Users

GET /v1/objects-users

List all objects users.

Name Type Description
href URL The URL of the resource.
id string The unique identifier of the objects user.
display_name string The display name of the objects user.
keys list of key objects A list of key objects containing the access and secret key associated with the objects user. Currently, only one key object is returned.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/objects-users

Response

HTTP/1.0 200 OK
Content-Type: application/json
Allow: GET, POST, HEAD, OPTIONS

[
  {
    "href": "https://api.cloudscale.ch/v1/objects-users/6fe39134bf4178747eebc429f82cfafdd08891d4279d0d899bc4012db1db6a15",
    "id": "6fe39134bf4178747eebc429f82cfafdd08891d4279d0d899bc4012db1db6a15",
    "display_name": "alan",
    "keys": [
      {
        "access_key": "0ZTAIBKSGYBRHQ09G11W",
        "secret_key": "bn2ufcwbIa0ARLc5CLRSlVaCfFxPHOpHmjKiH34T"
      }
    ]
  },
]
 

Get an Objects User

GET /v1/objects-users/{user_id}

Get an objects user by its ID.

Name Type Description
href URL The URL of the resource.
id string The unique identifier of the objects user.
display_name string The display name of the objects user.
keys list of key objects A list of key objects containing the access and secret key associated with the objects user. Currently, only one key object is returned.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/objects-users/6fe39134bf4178747eebc429f82cfafdd08891d4279d0d899bc4012db1db6a15

Response

HTTP/1.0 200 OK
Content-Type: application/json
Allow: GET, PATCH, DELETE, HEAD, OPTIONS

{
  "href": "https://api.cloudscale.ch/v1/objects-users/6fe39134bf4178747eebc429f82cfafdd08891d4279d0d899bc4012db1db6a15",
  "id": "6fe39134bf4178747eebc429f82cfafdd08891d4279d0d899bc4012db1db6a15",
  "display_name": "alan",
  "keys": [
    {
      "access_key": "0ZTAIBKSGYBRHQ09G11W",
      "secret_key": "bn2ufcwbIa0ARLc5CLRSlVaCfFxPHOpHmjKiH34T"
    }
  ]
}
 

Create an Objects User

POST /v1/objects-users

Create an objects user with the specified attributes.

Name Type Description
display_name string The display name of the new objects user.

The returned object contains the following information:

Name Type Description
href URL The URL of the resource.
id string The unique identifier of the objects user.
display_name string The display name of the objects user.
keys list of key objects A list of key objects containing the access and secret key associated with the objects user. Currently, only one key object is returned.

Request

$ curl -i -H "$AUTH_HEADER" -F display_name=alan https://api.cloudscale.ch/v1/objects-users

Response

HTTP/1.0 201 Created
Content-Type: application/json
Location: https://api.cloudscale.ch/v1/objects-users/6fe39134bf4178747eebc429f82cfafdd08891d4279d0d899bc4012db1db6a15
Allow: GET, POST, HEAD, OPTIONS

{
  "href": "https://api.cloudscale.ch/v1/objects-users/6fe39134bf4178747eebc429f82cfafdd08891d4279d0d899bc4012db1db6a15",
  "id": "6fe39134bf4178747eebc429f82cfafdd08891d4279d0d899bc4012db1db6a15",
  "display_name": "alan",
  "keys": [
    {
      "access_key": "0ZTAIBKSGYBRHQ09G11W",
      "secret_key": "bn2ufcwbIa0ARLc5CLRSlVaCfFxPHOpHmjKiH34T"
    }
  ]
}
 

Update an Objects User

PATCH /v1/objects-users/{user_id}

Update the properties of an objects user.

Name Type Description
display_name string The new display name of the objects user.

Important Note

Attributes can only be updated one at a time to avoid inconsistencies.

Request

$ curl -i -H "$AUTH_HEADER" -X PATCH -F display_name=turing https://api.cloudscale.ch/v1/objects-users/6fe39134bf4178747eebc429f82cfafdd08891d4279d0d899bc4012db1db6a15

Response

HTTP/1.0 204 No Content
Content-Type: application/json
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
 

Delete an Objects User

DELETE /v1/objects-users/{user_id}

Delete an objects user.

Most Common Errors

  • There are still buckets associated with the objects user. Only objects users without buckets can be deleted.

Request

$ curl -i -H "$AUTH_HEADER" -X DELETE https://api.cloudscale.ch/v1/objects-users/6fe39134bf4178747eebc429f82cfafdd08891d4279d0d899bc4012db1db6a15

Response

HTTP/1.0 204 No Content
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json
 

Metrics

The metrics end-point can be used to collect usage information on cloud resources. We currently provide metrics for the following resource types:

resource_type Description
buckets Metrics for buckets on our S3-compatible object storage.

Get Metrics

GET /v1/metrics/{resource_type}?{query_string}

Beta, interface is subject to change.

We reserve the right to introduce breaking changes until this banner is removed.

Get the metrics for subjects of resource_type (see all available types here). Use the query_string to define the metrics time range and filter the subjects included. The parameters that be can used in the query_string are detailed in the table below.

When forming complex expressions using multiple parameters, the following rules apply:

  • First, parameters of the same type are combined using OR operators.
  • Then, parameters of different types are combined using AND operators.

resource_type Query Parameter Name Type Allowed Mutliplicities Description
all start ISO 8601 date 1 Start of the metrics time range. 00:00:00 local time in Europe/Zurich time zone on the date specified will be used.
all end ISO 8601 date 1 End of the metrics time range. 24:00:00 local time in Europe/Zurich time zone on the date specified (i.e. including that day) will be used.
buckets bucket_name string 0...* Filter subjects by bucket name. Can be repeated in order to search for multiple buckets.
buckets objects_user_id string 0...* Filter subjects by the bucket owner's unique identifier. Can be repeated in order to search for multiple bucket owners.

The returned object contains the following information:

Name Type Description
start ISO 8601 date and time Start of the metrics time range.
end ISO 8601 date and time End of the metrics time range.
data list of data objects A list of data objects, one for each subject of the given resource_type matching your query. Each data object has a subject and a time_series attribute. See below for details.

The returned subject objects uniquely identify the metrics subject. The attributes of the subject objects depend on the resource_type:

resource_type Name Type Description
buckets name string The name of the bucket.
buckets objects_user_id string The unique identifier of the objects user owning the bucket.

The returned time_series are lists of objects describing the intervals in your metrics range. Currently, there is always a single interval equal to the metrics time range returned. The interval object has the start, end and usage attributes. The attributes of the usage objects depend on the resource_type:

resource_type Name Type Description
buckets requests integer The number of requests made in the interval.
buckets object_count integer The average object count in the interval. For time ranges in the future, including the remaining hours of the current day, the object count is assumed to be zero when calculating the average.
buckets storage_bytes integer The average amount of data stored in the interval. For time ranges in the future, including the remaining hours of the current day, the amount of data stored is assumed to be zero when calculating the average.
buckets received_bytes integer The total amount of data received in the interval.
buckets sent_bytes integer The total amount of data sent in the interval.

Request

$ curl -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/metrics/buckets?start=2019-03-19&end=2019-03-20

Response

HTTP/1.0 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json

{
  "start": "2019-03-18T23:00:00Z",
  "end": "2019-03-19T23:00:00Z",
  "data": [
    {
      "subject": {
        "name": "Carmichael",
        "objects_user_id": "2b44ef90ff15f010dc013f8d32612e07d7734e5f5581d0c94be56780b0dcd58a"
      },
      "time_series": [
        {
          "start": "2019-03-18T23:00:00Z",
          "end": "2019-03-19T23:00:00Z",
          "usage": {
            "requests": 561,
            "object_count": 1105,
            "storage_bytes": 1729,
            "received_bytes": 2465,
            "sent_bytes": 2821
          }
        }
      ]
    },
    {
      "subject": {
        "name": "StellaOctangula",
        "objects_user_id": "2b44ef90ff15f010dc013f8d32612e07d7734e5f5581d0c94be56780b0dcd58a"
      },
      "time_series": [
        {
          "start": "2019-03-18T23:00:00Z",
          "end": "2019-03-19T23:00:00Z",
          "usage": {
            "requests": 1,
            "object_count": 14,
            "storage_bytes": 51,
            "received_bytes": 124,
            "sent_bytes": 426
          }
        }
      ]
    }
  ]
}