Cloud API v5.0 - Legacy: v4.0 v3.0 v2.0 v1.0


What's New?

The endpoint for consuming version 5 of the Cloud API is:


https://api.ionos.com/cloudapi/v5
    

Cloud API version 5 adds the following new features:

Managed Kubernetes

Simple and efficient container orchestration with Kubernetes is now available. Using the Cloud API v5 you can provision and deploy Kubernetes clusters quickly into any of our datacenters. Our new Managed Kubernetes provides high availability, portability and efficient use of resources.

A Kubernetes cluster needs a name in order to be created. The name of the cluster needs to be compliant with Docker naming schema as detailed in the documentation below.

Once a cluster is created successfully, you can add one or more node pools to it where one or more replica worker nodes are orchestrated. To create a node pool provide a name, a target data center, the number of worker nodes and the configuration of worker nodes.

For more details please see Kubernetes.

This feature is available starting with 18.07.2019.

Manage Backup Units

It is now possible to create and manage backup units using the Cloud API v5. A backup unit needs a name, a password and an email in order to be created. The name for the backup unit is appended to the contract number to form a login name, so it must be unique inside a particular contract. It is not currently possible to change the name once a backup unit has been created, but this feature may be available in the future. The password is used when registering a new backup agent with a backup unit. It cannot be retrieved from the Cloud API, but it can be changed. The email is used to handle service notifications for the backup unit. It can also be changed after backup unit creation.

It is also possible to request a URL with a JSON Web Token (JWT) appended that will sign you directly into the backup unit.

For more details please see Backup Units.

This feature is available NOW.

S3 Key Management

A number of S3 key management features have been added to the User Management section of the Cloud API. It is now possible to manage S3 keys and see a specific user's S3 ID.

It is also possible to retrieve a SSO URL to automatically log into the S3 interface.

This feature is available NOW.

Changes to User Management

It is now possible for a contract owner to manage their own account in via the Cloud API. Contract Owners and users that have been granted admin privileges can also manage other users details. An option has been added to activate and deactivate users. This may be preferable to deleting a user in some situations.

This feature is available NOW.

Changes to Group Management

Group management has been extended to include S3 and Backup related privileges.

This feature is available NOW.

Other API Updates

Viewing resource limits of contracts is no longer filtered. All user levels can now see all resource limits and the current utilization.

It is possible to update the Live Vertical Scaling (LVS) attributes on provisioned instances. However this requires a restart of the virtual server.

The allowReboot flag for servers has been removed. Instead of requiring that this be set before a change requiring a restart is implemented, the virtual server will simply be restarted.

It is now possible to update the name of an IP block.

Contract Numbers are not passed via the X-Contract-Number header instead of the old PB-Contract-Number

Additional information about where an IP address has been assigned is now available when querying an IP block.

The licenceType for a snapshot can be set when the snapshot is created, rather than requiring a separate update operation.

Some new metadata is available that will indicate the userId of the user that created and last modified a resource.

These features are available NOW.

Getting Started

How to Access the API

You can consume the REST-based Cloud API using the following URL:

URL Description
https://api.ionos.com/cloudapi/v5/ CloudAPI v5 Endpoint

Swagger UI

It is possible to retrieve the swagger file for the Cloud API v5 by visiting Cloud API v5 swagger.json.

Protocol Elements

Request Methods

HTTP Verb Description
GET Used for any read request on resources. GET requests would not contain a body. Requests are idempotent.
HEAD Similar to GET, but response contains HTTP headers only, omitting the body. Requests are idempotent.
POST Used to create new resources or relationships as well as performing RPC-like actions such as start server, create snapshot, etc. These requests are not idempotent.
DELETE Used to remove a resource. This verb is disallowed on collection resources. These requests are not idempotent.
PUT Use this verb to change properties of a resource with the ones provided in the request. These requests are not idempotent.
PATCH Used to partially update properties of a resource. These requests are not idempotent. PATCH requests use specific patch representations.

HTTP Status Codes

HTTP Status Description
200 OK Synchronous request was successful using GET. 200 will also be returned for successful synchronous POST requests that do not result in item creation.
202 Accepted Used for asynchronous requests using PUT, DELETE, POST and PATCH methods. The response will also include a Location header pointing to a resource. This can be used for polling.
304 Not Modified Response for GETs on resources that have not been changed. (based on ETag values).
400 Bad Request Response to malformed requests or general client errors.
401 Unauthorized Response to an unauthenticated connection. You will need to use your API username and password to be authenticated.
404 Not Found Resource does not exist.
405 Method Not Allowed Use for any POST, PUT, PATCH, or DELETE performed on read-only resources. This is also there response to PATCH requests on resources that do not support partial updates.
422 Validation errors.
403 Forbidden
415 The content-type is incorrect for the payload.
429 The number of requests exceeds the rate limit.

HTTP Headers

Request Headers

Header Description
Content-Type Describes the data format of the request body.
Accept Used for content type negotiation.
Authorization Authorization header. See method details for examples.
If-Unmodified-Since This can be used to reliably and deterministically reflect the client state to the server.
If-None-Match The request-counterpart for the ETag response header. Usually used with GET requests.
If-Match The request-counterpart for the ETag response header. Use with modification requests (PATCH, DELETE) for opportunistic locking.
X-HTTP-Method-Override Convenience header for clients with a limited choice of HTTP methods. The HTTP method specified in this header overwrites the HTTP method used to make the request. Example: A client library cannot make PATCH requests. Instead it sends a POST request and sets the X-HTTP-Method-Override header to PATCH.

Authorization

HTTP Basic authentication is used to authorize access to the API.

You will need to base64 encode the string containing your credentials. Separate your username and password with a colon, i.e., username:password.

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

If you are using curl to interact with the REST API, you can supply your credentials with the --user command-line parameter. It will perform the base64 encoding for you.

curl --user 'username@domain.tld:password'

There are numerous ways to generate the base64 encoded authorization string depending on the operating system and tools you have access too. On Mac OS X or Linux, you may be able to use the base64 utility to encode them:

echo -n 'username@domain.tld:password' | base64
dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

The -n is significant as it prevents the "newline" character from being encoded into the output string. We can verify the encoded string like this:

echo 'dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==' | base64 -d
username@domain.tld:password

When using base64 in Mac OS X, the decode option is -D instead of -d.

Other tools such as openssl, perl, php, python, or powershell are capable of encoding and decoding base64 strings.

If you are experiencing difficulty authenticating with the encoded credentials:

  • Properly escape special characters (including the @ in your username)
  • Make sure that the newlines are being handled properly.

Response Headers

Header Description
Content-Type Describes data format conveyed in the response body.
Last-modified Used with only GET requests. Returns the latest modification date of all resources displayed.
ETag The entity tag of a resource. Used to support caching and conditional updates.
Location Used together with 201 Created response code to point to the newly created item. For asynchronous requests, together with 202 Accepted response code, points to a resource which can be used for polling.
X-RateLimit-Burst Maximum number of concurrent API requests allowed.
X-RateLimit-Remaining Number of requests which can still be made without triggering a failure response. This number grows as time elapses, eg. if X-RateLimit-Limit=60 then X-RateLimit-Remaining will grow by 1 every second until it reaches the X-RateLimit-Burst.
X-RateLimit-Limit Average number of requests allowed per minute.

Data Representation

The API implements the standard application/json content type.

The Accept header can be omitted in a GET request; however, if it is present you must specify application/json.

For any request containing a body -- POST, PUT, PATCH -- the Content-Type header is required and should be set to application/json unless otherwise noted. There are a few Cloud API v5 calls that utilize x-www-form-urlencoded.


Request Depth

You can append the query parameter depth to GET requests. The default depth=0 generally returns an href that can be queried for additional details. When you increase depth to 1, you may get additional details about those resources. This can be useful in many cases as you can gather most of the relevant information with a single API call.

The supported depth range is [0-10] with 10 returning the most amount of information. You would simply append ?depth=[value] to the end of your GET request. For example GET https://api.ionos.com/cloudapi/v5/snapshots?depth=1.


Custom Response Filters

There are three response filters available to assist in parsing information retrieved via the Cloud API.

Query Parameter Example Description
filter.<property>=<value> filter.cpuFamily=intel Limits results to those containing a matching value for a specific property.
orderBy=<property> orderBy=cores Sorts the results alphanumerically in ascending order based on the specified property.
maxResults=<integer> maxResult=4 Limits the number of results returned.

These query parameters can be applied on any property or metatag returned in the response to a Cloud API GET request. This would include:

  • Data Centers
  • Servers
  • Images
  • Volumes
  • Snapshots
  • IP Blocks
  • LANs
  • NICs
  • Firewall Rules
  • Load Balancers
  • Requests
  • Users

Please refer to the "Request Parameters - Query" sections of relevant GET operations for examples of how to use custom filters.


Features:

  • The filters support sub-string matching and are case insensitive.
  • All three filters can be used in combination with one another and the depth query parameter described in the preceding section.

Restrictions:

  • It is currently not possible to toggle between "ascending" and "descending" order. Results are returned in ascending order.
  • It is currently not possible to apply operators other than "=" to the query parameter. (Such as ">" or "<")

Implicit Volume Creation

create-attach is a notation of convenience. Traditionally, you would need to create the storage volume prior to creating a new server. Using create-attach you can ensure that a storage volume is created and attached in the same request as create server. You would specify an inline definition of a new volume instead of providing a reference identifier to an existing volume. This is covered in the Servers section of this documentation.

The following stories are support using create-attach:

  • create-attach multiple volumes at the same time.
  • create-attach new volumes and attach existing volumes at the same time.

Creation, Modification, and Deletion Responses

POST, PUT and PATCH responses contain the updated version of a resource, including the generated ID for the newly created resources. The state of the object(s) are set to BUSY indicating that the object(s) cannot be updated or used.

DELETE responses return an empty body.

All responses include a Location header which points to a request object which can be used to poll the state of the request.

The response status code 202 Accepted is returned.


PATCH requests

PATCH is used to perform updates on resources. The implementation adheres to RFC 5789.

[...] the enclosed entity contains a set of instructions describing how a resource currently residing on the origin server should be modified to produce a new version.

PATCH requests are made using a Content-Type of application/json.


Entity Tags

GET responses will return an ETag header.

Usage Examples:

  • Caching - In a GET request using the If-None-Match header would return the resource representation only if the ETag has changed.
  • Conditional Requests - In PATCH, PUT and DELETE requests, using the entity tag as a value for If-Match header, the resource will be changed/deleted only if its ETag has not changed.

Error format

Error entities are returned for any operation that results in a status code of 4xx or 5xx.

An erroneous response is returned using the application/json media type.


Date Format

Timestamps adhere to ISO-8601 and are presented in UTC.

YYYY-MM-DDThh:mm:ssZ


Resource Types

Here is a list of resources along with their types.

Document

A Document resource represents a singular object. Examples would be: datacenter, server, region, NIC, etc. This resource can contain collections and controller resources. The URI uses the identifier of a resource (often UUID) to refer to it. The domain model does not contain any singleton resources, therefore all document resources are grouped in collections.

Example:

[base-url]/.../servers/[server-id]
[base-url]/locations/{regionId}/{locationId}

Collection

This type of resource represents an aggregation of document resources. The URI uses a plural noun to refer to a collection resource.

Example:

[base-url]/.../servers
[base-url]/locations

Controller

This type of resource is used for RPC-like calls. This approach is used whenever it is difficult to model a desired client interaction using HTTP method verbs performed on noun resources.

Example:

[base-url]/.../servers/[server-id]/start

Callback Resources for Asynchronous Calls

All CRUD requests (HTTP POST, DELETE and PATCH) performed on virtual data center resources are asynchronous. Each call to any of those methods creates a callback-resource, which allows polling for the operation status.

Each successful asynchronous operation call returns a response code 202 Accepted. The response header Location contains a URL to the "pollable" callback-resource.


Callback Resource

Callback resources are available under:

[base-url]/requests/[request-status-id]/status

This is a read-only resource; the resource only allows GET requests.


Polling

A client can poll for the operation status by making a GET request on the callback-resource returned in the Location header of a CRUD request.

When the underlying asynchronous operation is still running the response status code 202 Accepted is returned.

When the underlying asynchronous operation is successful the response status code will be a 200 OK.

The response body contains a list of reports for all modified resources. In the event of an error a standard error object is returned.

GET [base-url]/requests/[request-status-id]/status results in:

Status Body Description
202 Accepted Contains a ‘polling object’. Async operation is still running
200 OK updated object PATCH operation finished OK
201 Created newly created object POST operation finished OK
204 No Content DELETE operation finished OK
4xx Error Object Whenever an error occurs, the proper error code is returned.

The payload is a Request Status object.

Example:

{
    "metadata": {
        "id": "[request-status-id]",
        "type": "request-status",
        "href": "https://[base-url]/request/[request-status-id]/status",
        "requestStatus": "RUNNING"
    },
    "entities": {
        "targets": [
            {
                "target": {
                    "id": "[NEW-SERVER-ID]",
                    "type": "server",
                    "href": "[base-url]/datacenters/[UUID1]/servers/[NEW-SERVER-ID]"
                },
                "status": "RUNNING"
            },
            {
                "target": {
                    "id": "[NEW-NIC-ID]",
                    "type": "NEW-NIC-ID",
                    "href": "[base-url]/datacenters/[UUID1]/servers/[NEW-SERVER-ID]/nics/[NEW-NIC-ID]"
                },
                "status": "RUNNING"
            }
        ]
    }
}

The callback-resources are garbage-collected once the underlying asynchronous operation has finished, but no earlier than 24h afterwards.


API User Management

We support a user management feature which allows you to restrict access to resources in the DCD or API. These permissions are inherited into the Cloud API.

Previously, this was managed in the DCD, but enforced in the API. Cloud API v5 adds the ability to manage users, groups, and shared resources through the API as described in the "What's New" and "User Management" sections of this documentation.


Users & Groups

Administrators can add additional users or groups to their account. Permissions are managed at the group level.

The API adheres to all permissions applied through the DCD:

  • For read operations, resource lists are filtered according to configured visibility (groups membership), e.g. calling GET /datacenters returns all data centers the user is allowed to view.
  • Create requests from groups without the correct privileges causes a HTTP 403 (Forbidden) error.
  • Fetching a resource without the read permission causes a HTTP 403 (Forbidden) error.
  • Modifying a resource without the edit permission causes a HTTP 403 (Forbidden) error.
  • Referring to a restricted resource in an editable data center (e.g. mounting non-shared image, adding non-shared CRIP to a NIC) causes a HTTP 422 error. I

Groups

  • CRUD model for objects like data centers, snapshots, etc.
  • Add resources (snapshots, IP Blocks, etc.) to groups with read-write or read-only permissions.

API Rate Limits

The API request rate is limited. The response for each request advertises the current limits. (See X-RateLimit-XXX response headers.)


Multi-user

The limits apply to all calls made within a given contract. For contracts having multiple users, requests from all users share a common limit.


Separate Limits for Read and Write

There are independent limits for read (GET, HEAD) and write operations (POST, PUT, PATCH, DELETE)


Exceeding the Limit

When the request rate limit has been exceeded, the client receives HTTP code 429, and a JSON response indicating current limits.


HTTP Status Codes

HTTP Status Description
429 The number of requests exceeds the rate limit.

Response Headers

Response Header Description
X-RateLimit-Burst Maximum number of concurrent API requests allowed.
X-RateLimit-Remaining Number of requests which can still be made without triggering a failure response. This number grows as time elapses, eg. if X-RateLimit-Limit=60 then X-RateLimit-Remaining will grow by 1 every second until it reaches the X-RateLimit-Burst.
X-RateLimit-Limit Average number of requests allowed per minute.

Data Centers

Create a Data Center

Virtual Data Centers (VDCs) are the foundation of the IONOS platform. VDCs act as logical containers for all other objects you will be creating, e.g. servers. You can provision as many data centers as you want. Data centers have their own private network and are logically segmented from each other to create isolation.

Create a Basic Data Center

You can use this POST method to create a simple data center or to create a data center with multiple objects under it such as servers and storage volumes.

Request

To create a new VDC, send a POST request to https://api.ionos.com/cloudapi/v5/datacenters


Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Body

The format of the request body is as follows:

{
    "properties": {
      "name": "[data-center-name]",
      "description": "[data-center-description]",
      "location": "[data-center-location]"
    }
}

Request Parameters - Body

The following table describes the properties of the request body:

Name Required Type Default Description
name no string n/a An optional name for the VDC.
location yes string n/a The physical location where the VDC will be created. I.e. "{regionId}/{locationId}". See locations.
description no string n/a An optional description for the VDC, e.g., "Staging", "Production".

NOTE: The value for 'name' cannot contain the following characters: (@, /, , |, ‘’, ‘).

NOTE: You cannot change the location of a virtual data center once it has been provisioned.

See locations for locations currently supported


Curl Example

The following shows how to submit a POST \datacenters request using curl:

curl --include \
     --request POST \
     --user '[username@domain.tld:password]' \
     --header "Content-Type: application/json" \
     --data-binary '{
         "properties": {
             "name": "[data-center-name]",
             "description": "[data-center-description]",
             "location": "[data-center-location]"
         }
     }' \
https://api.ionos.com/cloudapi/v5/datacenters

Response Body

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.ionos.com/cloudapi/v5/requests/{dataCenterId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{dataCenterId}",
  "type" : "datacenter",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "createdByUserId" : "[userId]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "lastModifiedByUserId" : "[userId]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "[data-center-name]",
    "description" : "[data-center-description]",
    "location" : "[data-center-location]",
    "version" : null,
    "features" : [ ]
  }
}

Response Attributes

The following table describes the attributes found in the JSON response body:

Name Type Description
id string The resource's unique identifier (UUID) in the form 8-4-4-4-12.
type string The type of object that has been created.
href string URL to the object’s representation (absolute path).
metadata collection Metadata for the VDC.
properties collection Properties of the VDC.

The metadata collection contains the following attributes:

Name Type Description
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
createdDate string The date the resource was created.
createdBy string The user who created the resource.
createdByUserId string The userId who created the resource.
state string AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued; INACTIVE Resource has been de-provisioned.
etag string The ETag for the request.

The properties collection contains the following attributes:

Name Type Description
name string The name of the VDC.
description string The description of the VDC.
location string The location of the VDC. See locations.
version string The version of the VDC.
features string A list of available features in the VDC. ["SSD", "MULTIPLE_CPU", etc]

Create a Data Center with Multiple Resources

Request

To create a new VDC with additional resources, send a POST request to https://api.ionos.com/cloudapi/v5/datacenters

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".
Request Body

The format of the request body is as follows:


{
  "properties": {
    "name": "[data-center-name]",
    "description": "[data-center-description]",
    "location": "[data-center-location]"
  },
  "entities": {
    "items": [{
      "servers": [{
        "properties": {
          "name": "[server-name]",
          "ram": [server-memory-in-mb],
          "cores": [server-cores]
        },
        "nics": [{
          "properties": {
            "ip": "auto",
            "lan": [server-lan-id]
          },
          "firewallrules": [{
            "properties": {
              "protocol": "[firewall-rule-protocol]",
              "portRangeStart": "[firewall-rule-port-range-start]",
              "portRangeEnd": "[firewall-rule-port-range-end]"
            }
          }]
        }],
        "cdroms": [{
          "properties": {
            "image": {
              "id": "[image-iso-id]"
            }
          }
        }]
      }]
    }]
  }
}

Request Parameters - Body

The following table describes the properties of the request body:

Name Required Type Default Description
name no string n/a An optional name for the VDC.
location yes string n/a The physical location where the VDC will be created. See locations.
description no string n/a An optional description for the VDC, e.g., "Staging", "Production".

NOTE: The value for name cannot contain the following characters: (@, /, , |, ‘’, ‘).

NOTE: You cannot change the location of a VDC once it has been provisioned.

See locations for the locations currently supported

The following describes the entities that may be included in the request body:

Name Required Type Default Description
servers no collection n/a You can define multiple servers to be created when the VDC is provisioned. See create server for request parameter details.
volumes no collection n/a A collection that represents volumes you wish to create when the VDC is provisioned. See create storage volume for request parameter details.
loadbalancers no collection n/a A collection that represents the load balancers you wish to create when the VDC is provisioned.
lans no collection n/a A collection that represents the LANs you wish to create when the VDC is provisioned.

Curl Example

The following shows how to submit a POST \datacenters request using curl:

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '{
  "properties": {
    "name": "[data-center-name]",
    "description": "Example Data Center",
    "location": "{regionId}/{locationId}"
  },
  "entities": {
    "servers": {
      "items": [
        {
          "properties": {
            "name": "Server1",
            "ram": 1024,
            "cores": 1
          },
          "entities": {
            "nics": {
              "items": [
                {
                  "properties": {
                    "ips": [],
                    "lan": 1,
                    "dhcp": false
                  },
                  "entities": {
                    "firewallrules": {
                      "items": [
                        {
                          "properties": {
                            "protocol": "TCP",
                            "portRangeStart": "22",
                            "portRangeEnd": "22"
                          }
                        },
                        {
                          "properties": {
                            "protocol": "TCP",
                            "targetIp": "192.168.3.10"
                          }
                        }
                      ]
                    }
                  }
                }
              ]
            },
            "cdroms": {
              "items": [
                {
                  "id": "[cdrom-image-id]"
                }
              ]
            },
            "volumes": {
              "items": [
                {
                  "properties": {
                    "size": 15,
                    "bus": "VIRTIO",
                    "type": "HDD",
                    "licenceType": "LINUX"
                  }
                }
              ]
            }
          }
        }
      ]
    },
    "lans": {
      "items": [
        {
          "id": 2,
          "properties": {
            "public": false
          }
        }
      ]
    }
  }
}' \
https://api.ionos.com/cloudapi/v5/datacenters

Response Body

HTTP/1.1 100 Continue

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.ionos.com/cloudapi/v5/requests/{requestId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{dataCenterId}",
  "type" : "datacenter",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "createdByUserId" : "[userId]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "lastModifiedByUserId" : "[userId]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "[data-center-name]",
    "description" : "Example Description",
    "location" : "{regionId}/{locationId}",
    "version" : null,
    "features" : [ ]
  },
  "entities" : {
    "servers" : {
      "id" : "{serverId}/servers",
      "type" : "collection",
      "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers"
    },
    "lans" : {
      "id" : "{dataCenterId}/lans",
      "type" : "collection",
      "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans"
    }
  }
}

Response Attributes

The following table describes the attributes found in the response body:

Name Type Description
id string The resource's unique identifier.
type string The type of object that has been created.
href string URL to the object’s representation (absolute path).
metadata collection VDC metadata.
properties collection VDC properties.
entities collection VDC entities.

The metadata includes the following attributes:

Name Type Description
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
createdDate string The date the resource was created.
createdBy string The user who created the resource.
createdByUserId string The userId who created the resource.
state string AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued; INACTIVE Resource has been de-provisioned.
etag string The ETag for the request.

The properties include the following attributes:

Name Type Description
name string The name of the VDC.
description string The description of the VDC.
location string The location you provisioned the VDC. See locations.
version int32 The version of the VDC.
features collection A list of available features in the VDC. ["SSD", "MULTIPLE_CPU"]

The entities collection includes the following:

Name Type Description
servers collection Servers that are part of the VDC.
volumes collection Volumes that are part of the VDC.
loadbalancers collection Load balancers that are part of the VDC.
lans collection A collection that represents the LANs provisioned in the VDC.

Read a Data Center

You can retrieve details about a VDC by using its ID. This value can be found in the response body when a VDC is created or when you use GET to retrieve a list of provisioned VDCs.

Request

To retrieve a VDC, send a GET request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information beyond the default amount returned with a value of 0.

Curl Example

The following shows how to submit the GET request using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}

Response Body

HTTP/1.1 200 OK
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
X-RateLimit-Remaining: 299
X-RateLimit-Burst: 300
X-RateLimit-Limit: 600
ETag: [etag]
Content-Type: application/json
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{dataCenterId}",
  "type" : "datacenter",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "createdByUserId" : "[userId]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "lastModifiedByUserId" : "[userId]",
    "state" : "AVAILABLE"
  },
  "properties" : {
    "name" : "ExampleDataCenter",
    "description" : "Example Description",
    "location" : "{regionId}/{locationId}",
    "version" : 22,
    "features" : [ ]
  },
  "entities" : {
    "servers" : {
      "id" : "{dataCenterId}/servers",
      "type" : "collection",
      "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers"
    },
    "volumes" : {
      "id" : "{dataCenterId}/volumes",
      "type" : "collection",
      "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes"
    },
    "loadbalancers" : {
      "id" : "{dataCenterId}/loadbalancers",
      "type" : "collection",
      "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers"
    },
    "lans" : {
      "id" : "{dataCenterId}/lans",
      "type" : "collection",
      "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans"
    }
  }
}

Response Attributes

The following table describes the attributes found in the JSON response body:

Name Type Description
id string The resource's unique identifier.
type string The type of object that has been created.
href string URL to the object’s representation (absolute path).
metadata collection VDC metadata.
properties collection VDC properties.
entities collection VDC entities.

The metadata includes the following attributes:

Name Type Description
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
createdDate string The date the resource was created.
createdBy string The user who created the resource.
createdByUserId string The userId who created the resource.
state string AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued; INACTIVE Resource has been de-provisioned.
etag string The ETag for the request.

The properties include the following attributes:

Name Type Description
name string The name of the VDC.
description string The description of the VDC.
location string The location you provisioned the VDC. See locations.
version int32 The version of the VDC.
features collection A list of available features in the VDC. ["SSD", "MULTIPLE_CPU"]

The entities collection includes the following:

Name Type Description
servers collection Servers that are part of the VDC.
volumes collection Volumes that are part of the VDC.
loadbalancers collection Load balancers that are part of the VDC.
lans collection A collection that represents the LANs provisioned in the VDC.

If you used the query parameter depth and set a value of 1 or more, then additional information about each of the entities is returned.

List Data Centers

You can retrieve a complete list of Virtual Data Centers provisioned under your account.

Request

To list all data centers, send a GET request to https://api.ionos.com/cloudapi/v5/datacenters

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/datacenters?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/datacenters?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information beyond the default amount returned with a value of 0.

If you have a number of VDCs provisioned in different locations, perhaps you'd like to get a list of VDCs in a specific locations. This request would return VDCs whose location is as requested:

https://api.ionos.com/cloudapi/v5/datacenters/?depth=0&filter.location={locationId}

If you had a large number of VDCs provisioned in a specific location, but just wanted to get one of them, you could utilize "maxResults=1" to accomplish that:

https://api.ionos.com/cloudapi/v5/datacenters/?depth=0&filter.location=las&maxResults=1

Maybe you recall setting up a couple VDCs with "test" in the name and want to find those:

https://api.ionos.com/cloudapi/v5/datacenters/?depth=1&filter.name=test

As a final example, a filter on version could be used to get a list of VDCs in ascending order based on the number of resource changes that have been provisioned. The VDCs at the top of the list would have had the least number of resource changes made.

https://api.ionos.com/cloudapi/v5/datacenters/?depth=0&orderBy=version

Curl Example

The following shows how to submit the GET request using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
   https://api.ionos.com/cloudapi/v5/datacenters

Response Body

HTTP/1.1 200 OK
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
X-RateLimit-Remaining: 299
X-RateLimit-Burst: 300
X-RateLimit-Limit: 600
ETag: [ETag]
Content-Type: application/json
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "datacenters",
  "type" : "collection",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters",
  "items" : [ {
    "id" : "[first-data-center-id]",
    "type" : "datacenter",
    "href" : "https://api.ionos.com/cloudapi/v5/datacenters/[first-data-center-id]"
  }, {
    "id" : "[second-data-center-id]",
    "type" : "datacenter",
    "href" : "https://api.ionos.com/cloudapi/v5/datacenters/[second-data-center-id]"
  }, {
    "id" : "[third-data-center-id]",
    "type" : "datacenter",
    "href" : "https://api.ionos.com/cloudapi/v5/datacenters/[third-data-center-id]"
  }, {
    "id" : "[fourth-data-center-id]",
    "type" : "datacenter",
    "href" : "https://api.ionos.com/cloudapi/v5/datacenters/[fourth-data-center-id]"
  } ]
}

Response Attributes

The following table describes the attributes found in the JSON response body:

Name Type Description
id string "datacenters"
type string The type of object that has been created. "collection"
href string URL to the object’s representation (absolute path).
items collection A collection of VDCs.

For each of the items the following attributes are returned:

Name Type Description
id string The UUID of a VDC.
type string The type of object. "datacenter"
href string URL to the object’s representation (absolute path).

If you used the query parameter depth and set a value of 1 or more, then additional information about each of the items is returned.

Update a Data Center

The Cloud API implements both PUT and PATCH for making updates to an existing VDC. You could use an update request to rename the VDC or alter its description.

PATCH Update

Request

To partially update a data center you would send a PATCH request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Body

The format of the request body is as follows:

{
    "name": "[data-center-name]",
    "description": "[data-center-description]"
}

Request Parameters - Body

The following table describes the properties of the request body:

Name Required Type Default Description
name no string n/a A name for the VDC.
description no string n/a A description for the VDC, e.g., "Staging", "Production".

NOTE: The value for name cannot contain the following characters: (@, /, , |, ‘’, ‘).

NOTE: You cannot change the location of a VDC once it has been provisioned.

Curl Example

The following shows how to submit the PATCH request using curl:

curl --include \
     --request PATCH \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '{
         "name": "Example VDC Rename",
         "description": "Example VDC Description"
         }' \
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}

Response Body

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.ionos.com/cloudapi/v5/requests/{requestId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{dataCenterId}",
  "type" : "datacenter",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "createdByUserId" : "[userUUID]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "lastModifiedByUserId" : "[userUUID]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "Example DC Rename",
    "description" : "Example DC Description",
    "location" : "{regionId}/{locationId}",
    "version" : 22,
    "features" : [ ]
    "secAuthProtection" : null
  },
  "entities" : {
    "servers" : {
      "id" : "{dataCenterId}/servers",
      "type" : "collection",
      "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers"
    },
    "volumes" : {
      "id" : "{dataCenterId}/volumes",
      "type" : "collection",
      "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes"
    },
    "loadbalancers" : {
      "id" : "{dataCenterId}/loadbalancers",
      "type" : "collection",
      "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers"
    },
    "lans" : {
      "id" : "{dataCenterId}/lans",
      "type" : "collection",
      "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans"
    }
  }
}

Response Attributes

The following table describes the attributes found in the JSON response body:

Name Type Description
id string The resource's unique identifier.
type string The type of object that has been created.
href string URL to the object’s representation (absolute path).
metadata collection VDC metadata.
properties collection VDC properties.
entities collection VDC entities.

The metadata includes the following attributes:

Name Type Description
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
createdDate string The date the resource was created.
createdBy string The user who created the resource.
createdBy createdByUserId string The userId who created the resource.
state string AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued; INACTIVE Resource has been de-provisioned.
etag string The ETag for the request.

The properties include the following attributes:

Name Type Description
name string The name of the VDC.
description string The description of the VDC.
location string The location you provisioned the VDC. See locations.
version int32 The version of the VDC.
features collection A list of available features in the VDC. ["SSD", "MULTIPLE_CPU"]

The entities collection includes the following:

Name Type Description
servers collection Servers that are part of the VDC.
volumes collection Volumes that are part of the VDC.
loadbalancers collection Load balancers that are part of the VDC.
lans collection A collection that represents the LANs provisioned in the VDC.

PUT Update

Request

You may also update a VDC by sending a PUT request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}

Values you wish to update must be wrapped in {"properties":{}}.

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Body

The format of the request body is as follows:

{
    "properties": {
        "name": "Example VDC Rename 2",
        "description": "Example VDC Description 2"
    }
}

Request Parameters - Body

The following table describes the properties of the request body:

Name Required Type Default Description
name no string n/a A name for the VDC.
description no string n/a A description for the VDC, e.g., "Staging", "Production".

NOTE: The value for name cannot contain the following characters: (@, /, , |, ‘’, ‘).

NOTE: You cannot change the location of a VDC once it has been provisioned.

Curl Example

The following shows how to submit the PUT request using curl:

curl --include \
     --request PUT \
     --user 'username@domain.tld:password'
     --header "Content-Type: application/json" \
     --data-binary '{
        "properties": {
          "name": "Example VDC Rename 2",
          "description": "Example VDC Description 2"
        }
     }' \
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}

Response Body

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.ionos.com/cloudapi/v5/requests/{requestId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{dataCenterId}",
  "type" : "datacenter",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "createdByUserId" : "[userId]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "lastModifiedByUserId" : "[userId]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "Example VDC Rename 2",
    "description" : "Example VDC Description 2",
    "location" : "{regionId}/{locationId}",
    "version" : 24,
    "features" : [ ]
  },
  "entities" : {
    "servers" : {
      "id" : "{dataCenterId}/servers",
      "type" : "collection",
      "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers"
    },
    "volumes" : {
      "id" : "{dataCenterId}/volumes",
      "type" : "collection",
      "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes"
    },
    "loadbalancers" : {
      "id" : "{dataCenterId}/loadbalancers",
      "type" : "collection",
      "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers"
    },
    "lans" : {
      "id" : "{dataCenterId}/lans",
      "type" : "collection",
      "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans"
    }
  }
}

Response Attributes

The following table describes the attributes found in the JSON response body:

Name Type Description
id string The resource's unique identifier.
type string The type of object that has been created.
href string URL to the object’s representation (absolute path).
metadata collection VDC metadata.
properties collection VDC properties.
entities collection VDC entities.

The metadata includes the following attributes:

Name Type Description
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
createdDate string The date the resource was created.
createdBy string The user who created the resource.
createdByUserId string The userId who created the resource.
state string AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued; INACTIVE Resource has been de-provisioned.
etag string The ETag for the request.

The properties include the following attributes:

Name Type Description
name string The name of the VDC.
description string The description of the VDC.
location string The location you provisioned the VDC. See locations.
version int32 The version of the VDC.
features collection A list of available features in the VDC. ["SSD", "MULTIPLE_CPU"]

The entities collection includes the following:

Name Type Description
servers collection Servers that are part of the VDC.
volumes collection Volumes that are part of the VDC.
loadbalancers collection Load balancers that are part of the VDC.
lans collection A collection that represents the LANs provisioned in the VDC.

Delete a Data Center

This will remove all objects within the VDC and remove the VDC object itself. NOTE: This is a highly destructive operation which should be used with extreme caution!

Request

To remove a VDC you would send a DELETE request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Curl Example

The following shows how to submit the DELETE request using curl:

curl --include \
     --request DELETE \
     --user 'username@domain.tld:password' \
   https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: [date]
Location: https://api.ionos.com/cloudapi/v5/requests/{requestId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Length: 0
Strict-Transport-Security: max-age=15768000

There is no JSON response body returned with a successful DELETE request.

Checking the Status

Using the Location: HTTP header value returned above, we can check the status of our DELETE request by making a GET request. Using curl, it would look like this:

curl --include \
     --request GET \
     --user '[username@domain.tld:password]' \
     https://api.ionos.com/cloudapi/v5/requests/{requestId}/status
Status Response

Example output when checking the status of a DELETE request that has completed successfully:

HTTP/1.1 200 OK
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: [date]
X-RateLimit-Remaining: 299
X-RateLimit-Burst: 300
X-RateLimit-Limit: 600
ETag: [etag]
Content-Type: application/json
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{requestId}/status",
  "type" : "request-status",
  "href" : "https://api.ionos.com/cloudapi/v5/requests/{requestId}/status",
  "metadata" : {
     "status" : "DONE",
     "message" : "Request has been successfully executed",
     "etag" : "[etag]",
     "targets" : [ {
      "target" : {
        "id" : "{dataCenterId}",
        "type" : "datacenter",
        "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}"
      },
      "status" : "DONE"
    } ]
  }
}

Locations

These operations are related to the geographic regions and locations where you can provision cloud resources. A location is identified by a combination of a two character regionId, which represents a country, and a three character locationId, which represents a city.

Read Location

Retrieves all the details about a specific regional location.

Request

To retrieve details about a specific location in a specific region you would send a GET request to https://api.ionos.com/cloudapi/v5/locations/{regionId}/{locationId}

Request Parameters - Path

Parameter Required Type Default Description
{regionId} yes string n/a The two character region identifier.
{locationId} yes string n/a The three character region identifier.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/{regionId}/{locationId}?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/{regionId}/{locationId}?depth=1

Note: For this particular operation, increasing the value supplied to depth does NOT return any additional information beyond the default amount returned with a value of 0.

Curl Example

The following shows how to submit a GET /locations/{regionId}/{locationId} request for the {regionId}/{locationId} location using curl:

curl --include \
       --request GET
       --user 'username@domain.tld:password'
       https://api.ionos.com/cloudapi/v5/locations/{regionId}/{locationId}

The response will be similar to this:

{
    "id": "{regionId}/{locationId}",
    "type": "location",
    "href": "https://api.ionos.com/cloudapi/v5/locations/{regionId}/{locationId}",
    "properties": {
      "name": "{string}",
      "features": [
        "SSD",
        "MULTIPLE_CPU"
      ],
      "imageAliases": []
    }
  }

Response Payload

The following table describes the attributes included in the JSON response:

Name Type Description
id string The resource's unique identifier consisting of country/city.
type string The type of object.
href string URL to the object’s representation (absolute path).
properties collection Detailed properties for each available location.

These properties are returned:

Name Type Description
name string A descriptive name for the location.
features array A list of features available at the location.
imageAliases array A list of available image aliases at the location.

Image aliases

The list of available image aliases for the HDD public images at each location will generally have a format made up of the operation system name, a colon, and the operating system version. Some examples are: centos:7, fedora:23, and windows:2016. The current or latest available version of a HDD public image will generally be accessible as the operating system name, a colon, and the word "latest". Some examples are: centos:latest, fedora:latest, and windows:latest.

The list of available image aliases for the CDROM public images at each location will generally have a format made up of the operation system name, a colon, the operating system version, and _iso. Some examples are: ubuntu:16.04_iso, windows:2016_iso, and opensuse:13.2_iso.

There are also image aliases for CDROM public images that aren't necessarily an operating system. Some examples are clonezilla:latest_iso and gparted:latest_iso.

List Locations

All locations might not always be available. Retrieve a list of all available regional locations.

Request

To retrieve a list of all locations send a GET request to https://api.ionos.com/cloudapi/v5/locations

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/locations?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/locations?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information beyond the default amount returned with a value of 0.

To demonstrate the use of custom filters, perhaps you are looking for the location abbreviation for one of our locations. We can filter on the name like this:

https://api.ionos.com/cloudapi/v5/locations/?depth=0&filter.name={location}

and get back the one matching location:

{
      "id": "locations",
      "type": "collection",
      "href": "https://api.ionos.com/cloudapi/v5/locations",
      "items": [
          {
              "id": "{regionId}/{locationId}",
              "type": "location",
              "href": "https://api.ionos.com/cloudapi/v5/locations/{regionId}/{locationId}"
          }
      ]
  }

Curl Example

The following shows how to submit a GET /locations request using curl:

curl --include \
       --request GET \
       --user 'username@domain.tld:password' \
       https://api.ionos.com/cloudapi/v5/locations

An example response to a GET /locations request. (Headers first, then the JSON body):

HTTP/1.1 200 OK
  Date: [date]
  Server: ""
  Pragma: No-cache
  Cache-Control: no-cache
  Expires: [date]
  X-RateLimit-Remaining: 299
  X-RateLimit-Burst: 300
  X-RateLimit-Limit: 600
  ETag: [etag]
  Content-Type: application/json
  Vary: Accept-Encoding
  Strict-Transport-Security: max-age=15768000
  Transfer-Encoding: chunked

  {
    "id" : "locations",
    "type" : "collection",
    "href" : "https://api.ionos.com/cloudapi/v5/locations",
    "items" : [ {
      "id" : "{regionId}/{locationId}",
      "type" : "location",
      "href" : "https://api.ionos.com/cloudapi/v5/locations/{regionId}/{locationId}"
    } ]
  }

Including the optional ?depth=1 parameter will return additional properties for each location. The data returned for each available location will be similar to what you would see if you made a GET /location/{regionId}/{locationId}. Here is a partial response showing one location when additional depth is requested.

"items" : [ {
    "id" : "{regionId}/{locationId}",
    "type" : "location",
    "href" : "https://api.ionos.com/cloudapi/v5/locations/{regionId}/{locationId}",
    "properties" : {
      "name" : "{string}",
      "features" : [ ],
      "imageAliases": []
    }
  ]

Response Payload

The JSON response body will contain a collection of regional locations.

The following table describes the attributes found in the JSON response:

Name Type Description
id string The resource's unique identifier consisting of country/city.
type string The type of object. In this case location.
href string URL to the object’s representation (absolute path).
items collection A collection of available locations.

Each of the returned items has these attributes:

Name Type Description
id string The resource's unique identifier consisting of country/city.
type string The type of object. In this case location.
href string URL to the object’s representation (absolute path).
properties collection Detailed properties for each available location.

Note: The properties collection is NOT included in the response at the default depth=0.

These properties are returned for each of the items when the depth query parameter is greater than or equal to 1.

Name Type Description
name string A descriptive name for the location.
features array A list of features available at the location.
imageAliases array A list of available image aliases at the location.

Get Regional Locations

Retrieves the locations available in a specific region.

Request

To retrieve a list of available locations in a specific region you would send a GET request to https://api.ionos.com/cloudapi/v5/locations/{regionId}

Request Parameters - Path

Parameter Required Type Default Description
{regionId} yes string n/a The two character region (country) identifier. [de, us]

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/locations?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/locations?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information beyond the default amount returned with a value of 0.

Curl Example

The following shows how to submit a GET /locations/{regionId} for the de region using curl:

curl --include \
       --request GET
       --user 'username@domain.tld:password'
       https://api.ionos.com/cloudapi/v5/locations/de

The response will be similar to this:

{
    "id": "locations",
    "type": "collection",
    "href": "https://api.ionos.com/cloudapi/v5/locations",
    "items": [
      {
        "id" : "{regionId}/{locationId}",
        "type" : "location",
        "href" : "https://api.ionos.com/cloudapi/v5/locations/{regionId}/{locationId}"
      },
    ]
  }

If we pass the optional depth query parameter with a value of 1 and request the us region instead:

curl --include \
       --request GET
       --user 'username@domain.tld:password'
       https://api.ionos.com/cloudapi/v5/locations/us?depth=1

Now the response includes additional properties for each item:

{
    "id": "locations",
    "type": "collection",
    "href": "https://api.ionos.com/cloudapi/v5/locations",
    "items": [
      {
        "id": "{regionId}/{locationId}",
        "type": "location",
        "href": "https://api.ionos.com/cloudapi/v5/locations/{regionId}/{locationId}",
        "properties": {
          "name": "{string}",
          "features": [
            "SSD",
            "MULTIPLE_CPU"
          ],
          "imageAliases": []
        }
      },
      {
        "id": "{regionId}/{locationId}",
        "type": "location",
        "href": "https://api.ionos.com/cloudapi/v5/locations/{regionId}/{locationId}",
        "properties": {
          "name": "newark",
          "features": [
            "SSD",
            "MULTIPLE_CPU"
          ],
          "imageAliases": [
            "windows:2008",
            "windows:2012"
          ]
        }
      }
    ]
  }

Response Payload

The following table describes the attributes found in the JSON response:

Name Type Description
id string The resource's unique identifier consisting of country/city.
type string The type of object. In this case collection.
href string URL to the object’s representation (absolute path).
items collection A collection of available locations.

Each of the returned items has these attributes:

Name Type Description
id string The resource's unique identifier consisting of country/city.
type string The type of object.
href string URL to the object’s representation (absolute path).
properties collection Detailed properties for each available location.

Note: The properties collection is NOT included in the response at the default depth=0.

These properties are returned for each location when the depth query parameter is greater than or equal to 1.

Name Type Description
name string A descriptive name for the location.
features array A list of features available at the location.
imageAliases array A list of available image aliases at the location.

Servers

Create a Server

Creates a server within an existing VDC. You can configure additional properties such as specifying a boot volume and connecting the server to an existing LAN.

Request

To create a server send a POST request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a virtual data center.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Body

It is possible to create a very basic server by just specifying the desired number of CPU cores and the amount of memory ram. However, you can also create a server and have additional resources such as volumes and NICs created at the same time. You can also attach a CD-ROM during server creation.

The following request will create a server and implicitly create a storage volume. If you want to use a storage volume that already exists, you reference its id as the only parameter within the properties of the specific item in the volumes collection.

The format of the request body is as follows:


{
  "properties": {
    "name": "New Server01",
    "ram": 4096,
    "cores": 2,
    "cpuFamily": "INTEL_XEON",
    "availabilityZone": "AUTO"
  },
  "entities": {
    "volumes": {
      "items": [
        {
          "properties": {
            "type": "HDD",
            "size": 50,
            "name": "HDD Volume01",
            "image": "9389a417-2e28-11e7-9888-525400f64d8d",
            "imagePassword": "abc1230321CBA"
          }
        }
      ]
    }
  }
}

This is what the request body could like if you are creating a server with a pre-existing volume:

{
   "entities":{
      "volumes":{
         "items":[
            {
               "id":"[existing-storage-volume-id]"
            }
         ]
      }
   },
   "properties":{
      "cores": 2,
      "ram": 4096,
      "name": "Server02"
   }
}

Request Parameters - Body

Name Required Type Default Description
name no string n/a A name for the server.
cores yes int32 n/a The total number of cores for the server.
ram yes int32 n/a The amount of memory for the server in MB, e.g. 2048. Size must be specified in multiples of 256 MB with a minimum of 256 MB; however, if you set ramHotPlug to TRUE then you must use a minimum of 1024 MB.
availabilityZone no string AUTO The compute availability zone in which the server should exist. [ZONE_1, ZONE_2, AUTO]
cpuFamily no string AMD_OPTERON Sets the CPU type. "AMD_OPTERON", "INTEL_XEON", …. Defaults to "AMD_OPTERON".
bootVolume no string n/a Reference to a Volume used for booting. If not ‘null’ then bootCdrom has to be ‘null’.
bootCdrom no string n/a Reference to a CD-ROM used for booting. If not 'null' then bootVolume has to be 'null'.
volumes no collection n/a A collection of volume IDs that you want to connect to the server. If the volume does not exist it will be created implicitly.
nics no collection n/a A collection of NICs you wish to create at the time the server is provisioned.
cdroms no collection n/a A collection of CD-ROMs you want to connect to the server.

The following table outlines the availability zones currently supported:

Zone Value Comment
AUTO Automatically Selected Zone
ZONE_1 Fire Zone 1
ZONE_2 Fire Zone 2

Please Note: The availabilityZone setting for a server will be treated as AUTO for all servers that are booting from a volume with the licenceType set to WINDOWS2016. This is a temporary situation and only affects servers running the Microsoft Windows 2016 operating system. Servers that boot from volumes using a licenceType of WINDOWS, LINUX, or OTHER are not affected and will be provisioned in the availabilityZone (ZONE_1, ZONE_2, or AUTO) specified.

Curl Example

The following shows how to submit a POST request using curl:

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '{
         "properties": {
             "name": "Server001",
             "ram": 2048,
             "cores": 1,
             "availabilityZone": "ZONE_1",
             "cpuFamily": "INTEL_XEON"
         },
         "entities": {
             "volumes": {
                 "items": [ {
                    "properties": {
                      "size": 50,
                      "type": "HDD",
                      "name": "Server001_HDD",
                      "imageAlias": "ubuntu:latest",
                      "imagePassword": "abc1230321CBA"
                      "sshKeys": ["ssh-rsa AAAAB3NzaC1yc2EAA..."]
                    }
                 } ]
             },
             "nics": {
                 "items": [ {
                    "properties": {
                      "name": "NIC001",
                      "dhcp": true,
                      "lan": 1
                      }
                    } , {
                    "properties": {
                      "name": "NIC002",
                      "dhcp": true,
                      "lan": 2
                      }
                 } ]
             }
        }
        }' \
 https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers

Note: When creating a volume there are certain parameters that must be supplied. Please refer to the Create Volume section of this documentation for additional information.

Response Body

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.ionos.com/cloudapi/v5/requests/{requestId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{serverId}",
  "type" : "server",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[username]",
    "createdByUserId" : "[userId]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[username]",
    "lastModifiedByUserId" : "[userId]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "Server001",
    "cores" : 1,
    "ram" : 2048,
    "availabilityZone" : "ZONE_1",
    "vmState" : null,
    "bootCdrom" : null,
    "bootVolume" : null,
    "cpuFamily" : "INTEL_XEON"
  },
  "entities" : {
    "volumes" : {
      "id" : "{serverId}/volumes",
      "type" : "collection",
      "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/volumes"
    }
  }
}

The following table describes the attributes found in the response body:

Name Type Description
id string The server's unique identifier.
type string The type of object that has been created. "server"
href string A URL for the new server object.
metadata collection Metadata about the new server.
properties collection Properties of the new server. Some will not be populated until provisioning is completed.
entities collection Entities that are associated with the new server.

The metadata collection is described in this table:

Name Type Description
createdDate string The date the resource was created.
createdBy string The user who created the resource.
createdByUserId string The userId who created the resource.
etag string The ETag.
lastModifiedDate string The last time the resource was been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
state string AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued. INACTIVE The resource has been de-provisioned.

The properties returned are:

Name Type Description
name string The name of the server.
cores int32 The number of cores for the server.
ram int32 The amount of memory on the server in MB.
availabilityZone string The availability zone for the server. [ZONE_1, ZONE_2, AUTO]
vmState string The current state of the virtual machine. [NOSTATE, RUNNING, BLOCKED, PAUSED, SHUTDOWN, SHUTOFF, CRASHED]
bootCdrom string Reference to a CD-ROM used for booting.
bootVolume string Reference to a Volume used for booting.
cpuFamily string Type of CPU assigned.

The entities returned may include:

Name Type Description
cdroms collection A collection of CD-ROMs attached to the server.
volumes collection A collection of volumes attached to the server.
nics collection A collection of NICs attached to the server.

Retrieve a Server

Returns information about a server such as its configuration, provisioning status, etc.

Request

To retrieve a server, send a GET request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.
{serverId} yes string n/a The ID of a server.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information beyond the default amount returned with a value of 0.

Curl Example

The following shows how to submit the GET request using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}

Response Body

HTTP/1.1 200 OK
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: [date]
X-RateLimit-Remaining: 299
X-RateLimit-Burst: 300
X-RateLimit-Limit: 600
ETag: [etag]
Content-Type: application/json
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{serverId}",
  "type" : "server",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "createdByUserId" : "[userId]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "lastModifiedByUserId" : "[userId]",
    "state" : "AVAILABLE"
  },
  "properties" : {
    "name" : "Server001",
    "cores" : 1,
    "ram" : 512,
    "availabilityZone" : "ZONE_1",
    "vmState" : "RUNNING",
    "bootCdrom" : null,
    "bootVolume" : {
      "id" : "{volumeId}",
      "type" : "volume",
      "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes/{volumeId}"
    },
    "cpuFamily" : "AMD_OPTERON"
  },
  "entities" : {
    "cdroms" : {
      "id" : "{serverId}/cdroms",
      "type" : "collection",
      "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/cdroms"
    },
    "volumes" : {
      "id" : "{serverId}/volumes",
      "type" : "collection",
      "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/volumes"
    },
    "nics" : {
      "id" : "{serverId}/nics",
      "type" : "collection",
      "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics"
    }
  }
}

Response Attributes

The following table describes the attributes found in the response body:

Name Type Description
id string The server's unique identifier.
type string The type of object. "server"
href string An API URL to the server’s representation (absolute path).
metadata collection Server metadata.
properties collection Server properties.
entities collection Entities associated with the server.

The metadata about the server includes:

Name Type Description
createdDate string The date the resource was created.
createdBy string The user who created the resource.
createdByUserId string The userId who created the resource.
etag string The ETag.
lastModifiedDate string The last modified time for the resource.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
state string AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued. INACTIVE The resource has been de-provisioned.

The properties returned are:

Name Type Description
name string The name of the server.
cores int32 The number of cores for the server.
ram int32 The amount of memory on the server in MB.
availabilityZone string The availability zone for the server. [ZONE_1, ZONE_2, AUTO]
vmState string The current state of the virtual machine. [NOSTATE, RUNNING, BLOCKED, PAUSED, SHUTDOWN, SHUTOFF, CRASHED]
bootCdrom string Reference to a CD-ROM used for booting. If not 'null' then bootVolume has to be 'null'.
bootVolume string Reference to a volume used for booting. If not 'null' then bootCdrom has to be 'null'.
cpuFamily string Type of CPU assigned.

The entities returned include:

Name Type Description
cdroms collection A collection of CD-ROMs attached to the server.
volumes collection A collection of volumes attached to the server.
nics collection A collection of NICs attached to the server.

At the default depth=0, each of the entities will include an id, type, and href that can be used to get additional information about the specific resource.

If you chose to pass the depth query parameter with a value of 1 or greater, then additional information about each server entity will be returned.

Server States

The following table enumerates the possible server states returned as vmState:

State Description
NOSTATE The server has no state, e.g. provisioning is still in progress, server failed to boot once provisioned.
RUNNING The server is in a normal, running state.
BLOCKED The server is blocked from running.
PAUSED The server has been paused. While in paused state, the server will still consume allocated resources like memory but will not be eligible for scheduling.
SHUTDOWN The server is in the process of being shutdown correctly.
SHUTOFF The server is currently offline.
CRASHED The server is in a crashed, non-bootable state.

List Servers

You can retrieve a list of all servers within a VDC.

Request

To retrieve a list of servers, send a GET request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information beyond the default amount returned with a value of 0.

You can filter the result set using custom filters.

An example of using the custom filter to find all servers in a particular VDC that have 2 GB of RAM assigned:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers?filter.ram=2&depth=1

You can also filter on metadata such as lastModifiedBy:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers?filter.lastModifiedBy=joe&depth=1

Curl Example

The following shows how to submit the GET request using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
 https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers

Response

HTTP/1.1 200 OK
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: [date]
X-RateLimit-Remaining: 299
X-RateLimit-Burst: 300
X-RateLimit-Limit: 600
ETag: [etag]
Content-Type: application/json
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{dataCenterId}/servers",
  "type" : "collection",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers",
  "items" : [ {
    "id" : "{serverId}",
    "type" : "server",
    "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}"
  }, {
    "id" : "{serverId",
    "type" : "server",
    "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}"
  } ]
}

Response Attributes

The request will return a collection of servers.

The following table describes the attributes found in the response body:

Name Type Description
id string {dataCenterId}/servers
type string The type of object that has been created. "collection"
href string URL to the object’s representation (absolute path).
items collection A collection of servers that are provisioned in the VDC.

The items will have the following attributes.

Name Type Description
id string The server's unique identifier.
type string The type of object. "server"
href string An API URL to the server’s representation (absolute path).

If you chose to pass the depth query parameter with a value of 1 or greater, then additional information about each server item will be returned. See the next section for additional details.

Update a Server

The Cloud API implements both PUT and PATCH for updates.

PATCH

You may use PATCH to perform partial updates to the attributes of a server.

Request

To perform a partial update to the server's properties you would submit a PATCH request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.
{serverId} yes string n/a The ID of a server.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Body

Name Required Type Default Description
name no string n/a A name for the server.
cores no int32 n/a The total number of cores for the server.
ram no int32 n/a The amount of memory for the server in MB, e.g. 2048. Size must be specified in multiples of 256 MB with a minimum of 256 MB; however, if you set ramHotPlug to TRUE then you must use a minimum of 1024 MB.
availabilityZone no string AUTO The compute availability zone in which the server should exist. [ZONE_1, ZONE_2, AUTO]
cpuFamily no string AMD_OPTERON Sets the CPU type. For example "AMD_OPTERON", "INTEL_XEON", etc. Defaults to "AMD_OPTERON".
bootVolume no string n/a Reference to a Volume used for booting. If not ‘null’ then bootCdrom has to be ‘null’.
bootCdrom no string n/a Reference to a CD-ROM used for booting. If not 'null' then bootVolume has to be 'null'.

Please Note: The allowReboot parameter has been removed from Cloud API v5. Explicitely allowing a reboot is not nescessary anymore.

If you try to set allowReboot when using Cloud API v5 you should get an error message returned, something similar to:

{
    "httpStatus": 422,
    "messages": [
        {
            "errorCode": "122",
            "message": "[(root).properties.allowReboot] Failed to parse request body. Unrecognized field 'allowReboot'"
        }
    ]
}

Curl Example

The following shows how to submit a PATCH request to update the "name" of the server using curl:

curl --include \
     --request PATCH \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '{
         "name": "Server001A"
         }' \
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.ionos.com/cloudapi/v5/requests/{requestId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{serverId}",
  "type" : "server",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[username]",
    "createdByUserId" : "[usernameId]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[username]",
    "lastModifiedByUserId" : "[userId]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "Server001A",
    "cores" : 1,
    "ram" : 512,
    "availabilityZone" : "AUTO",
    "vmState" : "RUNNING",
    "bootCdrom" : null,
    "bootVolume" : {
      "id" : "{volumeId}",
      "type" : "volume",
      "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes/{volumeId}"
    },
    "cpuFamily" : "AMD_OPTERON"
  },
  "entities" : {
    "cdroms" : {
      "id" : "{serverId}/cdroms",
      "type" : "collection",
      "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/cdroms"
    },
    "volumes" : {
      "id" : "{serverId}/volumes",
      "type" : "collection",
      "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/volumes"
    },
    "nics" : {
      "id" : "367fffcd-965f-4aa5-a6c2-afbd81e407ba/nics",
      "type" : "collection",
      "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics"
    }
  }
}

Response Attributes

The following table describes the attributes found in the response body:

Name Type Description
id string The server's unique identifier.
type string The type of object. "server"
href string An API URL to the server’s representation (absolute path).
metadata collection Server metadata.
properties collection Server properties.
entities collection Entities associated with the server.

The metadata about the server includes:

Name Type Description
createdDate string The date the resource was created.
createdBy string The user who created the resource.
createdByUserId string The userId who created the resource.
etag string The ETag.
lastModifiedDate string The last modified time for the resource.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
state string AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued. INACTIVE The resource has been de-provisioned.

The properties returned are:

Name Type Description
name string The name of the server.
cores int32 The number of cores for the server.
ram int32 The amount of memory on the server in MB.
availabilityZone string The availability zone for the server. [ZONE_1, ZONE_2, AUTO]
vmState string The current state of the virtual machine. [NOSTATE, RUNNING, BLOCKED, PAUSED, SHUTDOWN, SHUTOFF, CRASHED]
bootCdrom string Reference to a CD-ROM used for booting. If not 'null' then bootVolume has to be 'null'.
bootVolume string Reference to a Volume used for booting. If not 'null' then bootCdrom has to be 'null'.
cpuFamily string Type of CPU assigned.

The entities returned include:

Name Type Description
cdroms collection A collection of CD-ROMs attached to the server.
volumes collection A collection of volumes attached to the server.
nics collection A collection of NICs attached to the server.

PUT

You may use PUT to perform an update of server properties.

Request

To perform an update of the server's properties you would send a PUT request to: https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}

Please refer to the PATCH section above for details on the valid Path and Header request parameters.

The JSON body of this PUT request should have individual properties wrapped in "{"properties":()}". Unlike the PATCH request above, this PUT request requires that you pass values for cores and ram, even if you don't intend to change them.

Request Parameters - Body

Name Required Type Default Description
name no string n/a A name for the server.
cores yes int32 n/a The total number of cores for the server.
ram yes int32 n/a The amount of memory for the server in MB, e.g. 2048. Size must be specified in multiples of 256 MB with a minimum of 256 MB; however, if you set ramHotPlug to TRUE then you must use a minimum of 1024 MB.
availabilityZone no string AUTO The compute availability zone in which the server should exist. [ZONE_1, ZONE_2, AUTO]
cpuFamily no string AMD_OPTERON Sets the CPU type. For example: "AMD_OPTERON", "INTEL_XEON", …. Defaults to "AMD_OPTERON".
bootVolume no string n/a Reference to a Volume used for booting. If not ‘null’ then bootCdrom has to be ‘null’.
bootCdrom no string n/a Reference to a CD-ROM used for booting. If not 'null' then bootVolume has to be 'null'.

Please Note: The allowReboot parameter has been removed from Cloud API v5 and is not nescessary anymore.

If you try to set allowReboot when using Cloud API v5 you should get an error message returned, something similar to:

{
    "httpStatus": 422,
    "messages": [
        {
            "errorCode": "122",
            "message": "[(root).properties.allowReboot] Failed to parse request body. Unrecognized field 'allowReboot'"
        }
    ]
}

Curl Example

The following shows how to submit the PUT request using curl:

curl --include \
     --request PUT \
     --user 'username@domain.tld:password'
     --header "Content-Type: application/json" \
     --data-binary '{
         "properties": {
             "name": "[server-name]",
             "cores": "[server-cores]",
             "ram": "[server-ram]",
             "availabilityZone": "[server-availability-zone]",
             "bootVolume": {
                 "id": "[server-storage-volume-id]"
                 },
             "bootCdrom": null,
             "cpuFamily": "AMD_OPTERON"
         }
     }' \
 https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}

Response Body

202 (Accepted)
Content-Type: application/json
Location: URL of a request resource which should be used for the operation's polling status
{
    "id": "server-d",
    "type": "server",
    "href": "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}",
    "metadata": {
        "lastModifiedDate": "last-modified-date",
        "lastModifiedBy": "last-modified-by-user",
        "createdDate": "created-by-date",
        "createdBy": "created-by-user",
        "state": "server-state",
        "etag": "etag"
    },
    "properties": {
        "name": "server-name",
        "cores": "server-cores",
        "ram": "server-ram",
        "availabilityZone": "server-availability-zone",
        "cpuFamily": "server-cpu",
        "bootVolume": {
            "id": "storage-id"
        },
        "bootCdrom": null
    },
    "entities": {
        "nics": [],
        "volumes": []
    }
}

Please refer to the PATCH section above for details on the contents of the response body.

Delete a Server

This will remove a server from a VDC. NOTE: This will not automatically remove the storage volume(s) attached to a server. A separate API call is required to perform that action.

Request

To remove a server, send a DELETE request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.
{serverId} yes string n/a The ID of a server.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Curl Example

The following shows how to submit the DELETE request using curl:

curl --include \
    --request DELETE \
     --user 'username@domain.tld:password' \
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.ionos.com/cloudapi/v5/requests/{requestId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Length: 0
Strict-Transport-Security: max-age=15768000

There is no JSON response body returned with a successful DELETE request.

List Attached Volumes

Retrieves a list of volumes attached to the server.

Request

To get a list of attached volumes using the default depth you would send a GET request to: https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/volumes

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.
{serverId} yes string n/a The ID of a server.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/volumes?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/volumes?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information beyond the default amount returned with a value of 0.

Curl Example

The following shows you how to submit the GET request using curl with the default depth of 0:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/volumes

The following shows you how to submit the GET request with an appended depth of 1:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/volumes?depth=1

Response

When using a depth of 0, the response will be similar to this:

HTTP/1.1 200 OK
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
X-RateLimit-Remaining: 299
X-RateLimit-Burst: 300
X-RateLimit-Limit: 600
ETag: [etag]
Content-Type: application/json
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{serverId}/volumes",
  "type" : "collection",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/volumes",
  "items" : [ {
    "id" : "{volumeId}",
    "type" : "volume",
    "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes/{volumeId}"
  } ]
}

When using a depth of 1, the response will be similar to this:

HTTP/1.1 200 OK
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
X-RateLimit-Remaining: 299
X-RateLimit-Burst: 300
X-RateLimit-Limit: 600
Content-Type: application/json
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{serverId}/volumes",
  "type" : "collection",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/volumes",
  "items" : [ {
    "id" : "{volumeId}",
    "type" : "volume",
    "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes/{volumeId}",
    "metadata" : {
      "createdDate" : "[date]",
      "createdBy" : "[user]",
      "createdByUserId" : "[userId]",
      "etag" : "[etag]",
      "lastModifiedDate" : "[date]",
      "lastModifiedBy" : "[user]",
      "lastModifiedByUserId" : "[userId]",
      "state" : "AVAILABLE"
    },
    "properties" : {
      "name" : "Server002_HDD",
      "type" : "HDD",
      "size" : 10,
      "image" : null,
      "imagePassword" : null,
      "bus" : "VIRTIO",
      "licenceType" : "LINUX",
      "cpuHotPlug" : false,
      "cpuHotUnplug" : false,
      "ramHotPlug" : false,
      "ramHotUnplug" : false,
      "nicHotPlug" : false,
      "nicHotUnplug" : false,
      "discVirtioHotPlug" : false,
      "discVirtioHotUnplug" : false,
      "discScsiHotPlug" : false,
      "discScsiHotUnplug" : false,
      "deviceNumber" : 1
    }
  } ]
}

Response Parameters

A collection of volumes is returned.

Please reference the Volumes section for attribute definitions.

Attach a Volume

This will attach a pre-existing storage volume to the server.

Request

To attach a storage volume to a server, send a POST request to: https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/volumes

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.
{serverId} yes string n/a The ID of a server.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Body

The following table describes the request body values:

Name Required Type Description
id yes string The unique ID of a storage volume to attach.

Curl Example

The following shows how to submit the POST request using curl:

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
     --data-binary '{
         "id": "{volumeId}"
         }' \
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/volumes

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.ionos.com/cloudapi/v5/requests/{requestId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{volumeId}",
  "type" : "volume",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes/{volumeId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "createdByUserId" : "[userId]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "lastModifiedByUserId" : "[userId]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "ExtraSpace",
    "type" : "HDD",
    "size" : 10,
    "image" : null,
    "imageAlias": null,
    "imagePassword" : null,
    "bus" : null,
    "licenceType" : "OTHER",
    "cpuHotPlug" : false,
    "cpuHotUnplug" : false,
    "ramHotPlug" : false,
    "ramHotUnplug" : false,
    "nicHotPlug" : false,
    "nicHotUnplug" : false,
    "discVirtioHotPlug" : false,
    "discVirtioHotUnplug" : false,
    "discScsiHotPlug" : false,
    "discScsiHotUnplug" : false,
    "deviceNumber" : null
  }
}

Response Attributes

Please see the Volumes section for attribute definitions.

Some values will not be populated until the provisioning request has completed and "state" changes from "BUSY" to "AVAILABLE".

Retrieve an Attached Volume

This will retrieve the properties of an attached volume.

Request

Send a GET request to: https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/volumes/{volumeId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.
{serverId} yes string n/a The ID of a server.
{volumeId} yes string n/a The ID of a volume.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/volumes/{volumeId}?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/volumes/{volumeId}?depth=1

Note: For this particular operation, increasing the value supplied to depth does NOT return any additional information beyond the default amount returned with a value of 0.

Curl Example

The following shows how to submit the GET request using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/volumes/{volumeId}

Response

HTTP/1.1 200 OK
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
X-RateLimit-Remaining: 299
X-RateLimit-Burst: 300
X-RateLimit-Limit: 600
ETag: [etag]
Content-Type: application/json
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{volumeId}",
  "type" : "volume",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes/{volumeId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "createdByUserId" : "[userId]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "lastModifiedByUserId" : "[userId]",
    "state" : "AVAILABLE"
  },
  "properties" : {
    "name" : "ExtraSpace",
    "type" : "HDD",
    "size" : 10,
    "image" : null,
    "imagePassword" : null,
    "bus" : "VIRTIO",
    "licenceType" : "OTHER",
    "cpuHotPlug" : false,
    "cpuHotUnplug" : false,
    "ramHotPlug" : false,
    "ramHotUnplug" : false,
    "nicHotPlug" : false,
    "nicHotUnplug" : false,
    "discVirtioHotPlug" : false,
    "discVirtioHotUnplug" : false,
    "discScsiHotPlug" : false,
    "discScsiHotUnplug" : false,
    "deviceNumber" : 2
  }
}

Response Parameters

Please see the Volumes section for attribute definitions.

Detach a Volume

This will detach the volume from the server. Depending on the volume HotUnplug settings, this may result in the server being rebooted.

This will NOT delete the volume from your virtual data center. You will need to make a separate request to delete a volume.

Request

Send a DELETE request to: https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/volumes/{volumeId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a virtual data center.
{serverId} yes string n/a The ID of a server.
{volumeId} yes string n/a The ID of a volume.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Curl Example

The following shows how to submit the DELETE request using curl:

curl --include \
     --request DELETE \
     --user 'username@domain.tld:password' \
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/volumes/{volumeId}

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.ionos.com/cloudapi/v5/requests/{requestId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Length: 0
Strict-Transport-Security: max-age=15768000

There is no JSON response body returned for a successful DELETE request.

List Attached CD-ROMs

You can retrieve a list of CD-ROMs attached to the server.

Request

To get a list of CD-ROMs attached to the server, send a GET request to: https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/cdroms

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a virtual data center.
{serverId} yes string n/a The ID of a server.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/cdroms?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/cdroms?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information beyond the default amount returned with a value of 0.

Curl Example

The following example shows how to retrieve the list using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/cdroms

Response

You should receive a response similar to this:

HTTP/1.1 200 OK
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
X-RateLimit-Remaining: 299
X-RateLimit-Burst: 300
X-RateLimit-Limit: 600
ETag: [etag]
Content-Type: application/json
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{serverId}/cdroms",
  "type" : "collection",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/cdroms",
  "items" : [ {
    "id" : "[image-id]",
    "type" : "image",
    "href" : "https://api.ionos.com/cloudapi/v5/images/{imageId}"
  } ]
}

The response will contain a collection of CD-ROMs.

Response Parameters

Please reference the CD-ROMs section for attribute definitions.

Attach a CD-ROM

You can attach a CD-ROM to an existing server.

Request

To attach a CD-ROM to a server, send a POST request to: https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/cdroms

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a virtual data center.
{serverId} yes string n/a The ID of a server.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Body

The following table describes the request body values:

Name Required Type Description
id yes string The ID of a CD-ROM (ISO) image to attach.

Curl Example

The following example shows how to attach a CD-ROM to the server:

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '{
         "id": "[cdromImageId]"
        }' \
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/cdroms

Response

You should receive a response similar to this:

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.ionos.com/cloudapi/v5/requests/{requestId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "[image-id]",
  "type" : "image",
  "href" : "https://api.ionos.com/cloudapi/v5/images/{imageId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "createdByUserId" : "[userId]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "lastModifiedByUserId" : "[userId]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "ubuntu-14.04.3-server-amd64.iso",
    "description" : "",
    "location" : "{regionId}/{locationId}",
    "size" : 0.57,
    "cpuHotPlug" : false,
    "cpuHotUnplug" : false,
    "ramHotPlug" : false,
    "ramHotUnplug" : false,
    "nicHotPlug" : false,
    "nicHotUnplug" : false,
    "discVirtioHotPlug" : false,
    "discVirtioHotUnplug" : false,
    "discScsiHotPlug" : false,
    "discScsiHotUnplug" : false,
    "licenceType" : "LINUX",
    "imageType" : "CDROM",
    "public" : false
  }
}

Response Parameters

Please reference the CD-ROMs section for attribute definitions.

Retrieve Attached CD-ROM

You can retrieve a specific CD-ROM attached to the server.

Request

To get details on a specific CD-ROM attached to a server, send a GET request to: https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/cdroms/[cdrom-id]

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.
{serverId} yes string n/a The ID of a server.
{cdromId} yes string n/a The ID of the attached CD-ROM.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/cdroms?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/cdroms?depth=1

Note: For this particular operation, increasing the value supplied to depth does NOT return any additional information beyond the default amount returned with a value of 0.

Curl Example

The following example shows you how to retrieve the CD-ROM details using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/cdroms/{cdromId}

Response

You should receive a response similar to this:

HTTP/1.1 200 OK
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
X-RateLimit-Remaining: 299
X-RateLimit-Burst: 300
X-RateLimit-Limit: 600
ETag: [etag]
Content-Type: application/json
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "[image-id]",
  "type" : "image",
  "href" : "https://api.ionos.com/cloudapi/v5/images/[image-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "System",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "System",
    "state" : "AVAILABLE"
  },
  "properties" : {
    "name" : "ubuntu-14.04.4-server-amd64.iso",
    "description" : null,
    "location" : "{regionId}/{locationId}",
    "size" : 0.57,
    "cpuHotPlug" : true,
    "cpuHotUnplug" : false,
    "ramHotPlug" : true,
    "ramHotUnplug" : false,
    "nicHotPlug" : true,
    "nicHotUnplug" : true,
    "discVirtioHotPlug" : true,
    "discVirtioHotUnplug" : true,
    "discScsiHotPlug" : false,
    "discScsiHotUnplug" : false,
    "licenceType" : "LINUX",
    "imageType" : "CDROM",
    "public" : true
  }
}

Response Parameters

Please reference the CD-ROMs and Images section for attribute definitions.

Detach a CD-ROM

This will detach a CD-ROM from the server.

Request

To detach a CDROM from a server, send a DELETE request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/cdroms/[cdrom-id]

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.
{serverId} yes string n/a The ID of a server.
{cdromId} yes string n/a The ID of the attached CD-ROM.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Curl Example

The following shows how to submit the DELETE request using curl:

curl --include \
     --request DELETE \
     --user 'username@domain.tld:password' \
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/cdroms/{cdromId}

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.ionos.com/cloudapi/v5/requests/{requestId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Length: 0
Strict-Transport-Security: max-age=15768000

There is no JSON response body returned with a successful DELETE request.

Reboot a Server

This will force a hard reboot of the server. Do not use this method if you want to gracefully reboot the machine. This is the equivalent of powering off the machine and turning it back on.

Request

To reboot a server, send a POST request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/reboot

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.
{serverId} yes string n/a The ID of a server.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Curl Example

The following shows you how to submit the POST request using curl:

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/reboot

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.ionos.com/cloudapi/v5/requests/{requestId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Length: 0
Strict-Transport-Security: max-age=15768000

Response Body

None

Start a Server

This will start a server. If the server's public IP was deallocated then a new IP will be assigned.

Request

To start a server, send a POST request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/start

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.
{serverId} yes string n/a The ID of a server.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Curl Example

The following shows how to submit the POST request using curl:

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
     https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/start

Response

HTTP/1.1 202 Accepted
Date: Thu, 10 Mar 2016 23:13:41 GMT
Server: ""
Location: https://api.ionos.com/cloudapi/v5/requests/{requestId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [ETag]
Content-Length: 0
Strict-Transport-Security: max-age=15768000

Response Body

None

Stop a Server

This will stop a server. The machine will be forcefully powered off, billing will cease, and the public IP, if one is allocated, will be deallocated.

Request

To stop a server you would send a POST request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/stop

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.
{serverId} yes string n/a The ID of a server.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Curl Example

The following shows how to submit the POST request using curl:

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/stop

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.ionos.com/cloudapi/v5/requests/{requestId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Length: 0
Strict-Transport-Security: max-age=15768000

Response Body

None

Images

Read Image

Retrieves the attributes of a specific image.

Request

To retrieve details on a single image send a GET request to https://api.ionos.com/cloudapi/v5/images/{imageId}

Request Parameters - Path

Parameter Required Type Default Description
{imageId} yes string n/a The ID of an image.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/images?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/images?depth=1

Note: For this particular operation, increasing the value supplied to depth does NOT return any additional information beyond the default amount returned with a value of 0.

Curl Example

The following shows how to submit the GET request using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
https://api.ionos.com/cloudapi/v5/images/{imageId}

Response

HTTP/1.1 200 OK
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
X-RateLimit-Remaining: 299
X-RateLimit-Burst: 300
X-RateLimit-Limit: 600
ETag: [date]
Content-Type: application/json
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "[image-id]",
  "type" : "image",
  "href" : "https://api.ionos.com/cloudapi/v5/images/{imageId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "System",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "System",
    "state" : "AVAILABLE"
  },
  "properties" : {
    "name" : "CentOS-6.7-x86_64-netinstall.iso",
    "description" : null,
    "location" : "{regionId}/{locationId}",
    "size" : 0.23,
    "cpuHotPlug" : true,
    "cpuHotUnplug" : false,
    "ramHotPlug" : true,
    "ramHotUnplug" : false,
    "nicHotPlug" : true,
    "nicHotUnplug" : true,
    "discVirtioHotPlug" : true,
    "discVirtioHotUnplug" : true,
    "discScsiHotPlug" : false,
    "discScsiHotUnplug" : false,
    "licenceType" : "LINUX",
    "imageType" : "CDROM",
    "public" : true
  }
}

Response Attributes

The following table describes the attributes found in the JSON response body:

Name Type Description
id string The resource's unique identifier.
type string The type of object that has been created.
href string URL to the object’s representation (absolute path).
metadata collection Image metadata.
properties collection Image properties.

The metadata returned includes the following attributes.

Name Type Description
createdDate string The date the resource was created.
createdBy string The user who created the resource.
createdByUserId string The userId who created the resource.
etag string The ETag for the resource.
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
state string Image state.

The properties returned include the following attributes:

Name Type Description
name string The name of the image.
description string The description of the image.
location string The image's location.
size string The size of the image in GB.
cpuHotPlug Boolean This volume is capable of CPU hot plug (no reboot required).
cpuHotUnplug Boolean This volume is capable of CPU hot unplug (no reboot required).
ramHotPlug Boolean This volume is capable of memory hot plug (no reboot required).
ramHotUnplug Boolean This volume is capable of memory hot unplug (no reboot required).
nicHotPlug Boolean This volume is capable of NIC hot plug (no reboot required).
nicHotUnplug Boolean This volume is capable of NIC hot unplug (no reboot required).
discVirtioHotPlug Boolean This volume is capable of VirtIO drive hot plug (no reboot required).
discVirtioHotUnplug Boolean This volume is capable of VirtIO drive hot unplug (no reboot required).
discScsiHotPlug Boolean This volume is capable of SCSI drive hot plug (no reboot required).
discScsiHotUnplug Boolean This volume is capable of SCSI drive hot unplug (no reboot required).
licenceType Boolean The image's licence type: LINUX, WINDOWS, WINDOWS2016, OTHER, or UNKNOWN.
imageType Boolean The type of image: HDD, CDROM (ISO).
public Boolean Indicates if the image is part of the public repository (true) or not (false).

List Images

Retrieve a list of images within the data center.

Request

To retrieve a list of images submit a GET request to https://api.ionos.com/cloudapi/v5/images

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/images?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/images?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information beyond the default amount returned with a value of 0.

This API call could be used to return a set of images matching some specific criteria. To demonstrate, we will use filter.<property>=<value> to look for "public" images in the selected location that, contain the string "cent" in the name, with an imageType of "HDD". We will use orderBy to sort the results based on the lastModifiedDate.

https://api.ionos.com/cloudapi/v5/images/?depth=1&filter.location={location}&filter.public=true&filter.imageType=hdd&filter.name=Cent&orderBy=lastModifiedDate

At the time of writing, this would return two results, one for CentOS 7 and one for CentOS 6.

{
"id": "images",
"type": "collection",
"href": "https://api.ionos.com/cloudapi/v5/images",
"items": [
    {
        "id": "79753350-a65e-11e7-90a7-525400f64d8d",
        "type": "image",
        "href": "https://api.ionos.com/cloudapi/v5/images/79753350-a65e-11e7-90a7-525400f64d8d",
        "metadata": {
            "createdDate": "2017-10-01T04:10:35Z",
            "createdBy": "System",
            "etag": "9559303a85b6df30a48cfc6b0a8db947",
            "lastModifiedDate": "2017-10-01T04:10:35Z",
            "lastModifiedBy": "System",
            "state": "AVAILABLE"
        },
        "properties": {
            "name": "CentOS-7-server-2017-10-01",
            "description": null,
            "location": "{regionId}/{locationId}",
            "size": 2,

            "imageType": "HDD",
            "imageAliases": [
                "centos:latest",
                "centos:7"
            ],
            "public": true
        }
    },
    {
        "id": "2b4bbb39-a75d-11e7-90a7-525400f64d8d",
        "type": "image",
        "href": "https://api.ionos.com/cloudapi/v5/images/2b4bbb39-a75d-11e7-90a7-525400f64d8d",
        "metadata": {
            "createdDate": "2017-10-02T10:33:45Z",
            "createdBy": "System",
            "etag": "ca605563b94d6c562ea38a610680cce8",
            "lastModifiedDate": "2017-10-02T10:33:45Z",
            "lastModifiedBy": "System",
            "state": "AVAILABLE"
        },
        "properties": {
            "name": "CentOS-6-server-2017-10-02",
            "description": null,
            "location": "{regionId}/{locationId}",
            "size": 2,

            "imageType": "HDD",
            "imageAliases": [
                "centos:6"
            ],
            "public": true
        }
    }
]
}

Curl Example

The following shows you how to submit the GET request via curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
https://api.ionos.com/cloudapi/v5/images

Response Body

HTTP/1.1 200 OK
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
X-RateLimit-Remaining: 299
X-RateLimit-Burst: 300
X-RateLimit-Limit: 600
ETag: [etag]
Content-Type: application/json
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "images",
  "type" : "collection",
  "href" : "https://api.ionos.com/cloudapi/v5/images",
  "items" : [ {
    "id" : "[image-id]",
    "type" : "image",
    "href" : "https://api.ionos.com/cloudapi/v5/images/[image-id]"
  }, {
    "id" : "[another-image-id]",
    "type" : "image",
    "href" : "https://api.ionos.com/cloudapi/v5/images/[another-image-id]"
  } ]
}

Response Attributes

The request will return a collection of images.

The following table describes the attributes found in the JSON response body:

Name Type Description
id string The resource's unique identifier.
type string The type of object that has been created.
href string URL to the object’s representation (absolute path).
items collection A collection of image IDs.

Each of the items returned has the following attributes.

Name Type Description
id string The resource's unique identifier.
type string The type of object that has been created.
href string URL to the object’s representation (absolute path).

If you pass the query parameter depth with a value greater than or equal to 1 then each of the items will include additional attributes. See the next section for details.

Update Image

The Cloud API implements both PUT and PATCH for updates.

PATCH

Use PATCH to perform updates to attributes of a private image.

Request

To perform an update to the private image's properties send a PATCH request to https://api.ionos.com/cloudapi/v5/images/{imageId}

Request Parameters - Path

Parameter Required Type Default Description
{imageId} yes string n/a The ID of a private image.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Body

{
    "description": "Updated Image Description"
}

Request Parameters - Body

Name Required Type Description
name no string The name of the image.
description no string The description of the image.
licenceType no string The image's licence type: LINUX, WINDOWS, WINDOWS2016, OTHER, or UNKNOWN.
cpuHotPlug no Boolean This volume is capable of CPU hot plug (no reboot required).
cpuHotUnplug no Boolean This volume is capable of CPU hot unplug (no reboot required).
ramHotPlug no Boolean This volume is capable of memory hot plug (no reboot required).
ramHotUnplug no Boolean This volume is capable of memory hot unplug (no reboot required).
nicHotPlug no Boolean This volume is capable of NIC hot plug (no reboot required).
nicHotUnplug no Boolean This volume is capable of NIC hot unplug (no reboot required).
discVirtioHotPlug no Boolean This volume is capable of VirtIO drive hot plug (no reboot required).
discVirtioHotUnplug no Boolean This volume is capable of VirtIO drive hot unplug (no reboot required).
discScsiHotPlug no Boolean This volume is capable of SCSI drive hot plug (no reboot required).
discScsiHotUnplug no Boolean This volume is capable of SCSI drive hot unplug (no reboot required).

Curl Example

The following shows you how to submit the PATCH request to replace the description of an image using curl:

curl --include \
     --request PATCH \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '{
            "description": "Updated Image Description"
        }' \
https://api.ionos.com/cloudapi/v5/images/{imageId}

Response Body

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.ionos.com/cloudapi/v5/requests/{requestId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{imageId}",
  "type" : "image",
  "href" : "https://api.ionos.com/cloudapi/v5/images/{imageId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "createdByUserId" : "[userId]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "lastModifiedByUserId" : "[userId]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "[name]",
    "description" : "Example Description",
    "location" : "[location]",
    "size" : 5,
    "cpuHotPlug" : false,
    "cpuHotUnplug" : false,
    "ramHotPlug" : false,
    "ramHotUnplug" : false,
    "nicHotPlug" : false,
    "nicHotUnplug" : false,
    "discVirtioHotPlug" : false,
    "discVirtioHotUnplug" : false,
    "discScsiHotPlug" : false,
    "discScsiHotUnplug" : false,
    "licenceType" : "LINUX",
    "imageType" : "HDD",
    "public" : false
  }
}

Response Attributes

The following table describes the attributes found in the JSON response body:

Name Type Description
id string The resource's unique identifier.
type string The type of object that has been created.
href string URL to the object’s representation (absolute path).
metadata collection Image metadata.
properties collection Image properties.

The metadata returned includes the following attributes.

Name Type Description
createdDate string The date the resource was created.
createdBy string The user who created the resource.
createdByUserId string The userId who created the resource.
etag string The ETag for the resource.
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
state string Image state.

The properties returned include the following attributes:

Name Type Description
name string The name of the image.
description string The description of the image.
location string The image's location.
size string The size of the image in GB.
cpuHotPlug Boolean This volume is capable of CPU hot plug (no reboot required).
cpuHotUnplug Boolean This volume is capable of CPU hot unplug (no reboot required).
ramHotPlug Boolean This volume is capable of memory hot plug (no reboot required).
ramHotUnplug Boolean This volume is capable of memory hot unplug (no reboot required).
nicHotPlug Boolean This volume is capable of NIC hot plug (no reboot required).
nicHotUnplug Boolean This volume is capable of NIC hot unplug (no reboot required).
discVirtioHotPlug Boolean This volume is capable of VirtIO drive hot plug (no reboot required).
discVirtioHotUnplug Boolean This volume is capable of VirtIO drive hot unplug (no reboot required).
discScsiHotPlug Boolean This volume is capable of SCSI drive hot plug (no reboot required).
discScsiHotUnplug Boolean This volume is capable of SCSI drive hot unplug (no reboot required).
licenceType Boolean The image's licence type: LINUX, WINDOWS, WINDOWS2016, OTHER, or UNKNOWN.
imageType Boolean The type of image: HDD, CDROM (ISO).
public Boolean Indicates if the image is part of the public repository (true) or not (false).

PUT

Use PUT to perform an update of the attributes of an image.

Request

To perform an update of the private image's properties send a PUT request to: https://api.ionos.com/cloudapi/v5/images/{imageId}

Request Parameters - Path

Parameter Required Type Default Description
{imageId} yes string n/a The ID of a private image.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Body

{
    "properties": {
        "name": "Updated Image Name",
        "description": "Updated Image Description",
        "licenceType": "OTHER",
        "cpuHotPlug": true,
        "cpuHotUnplug": true,
        "ramHotPlug": true,
        "ramHotUnplug": true,
        "nicHotPlug": true,
        "nicHotUnplug": true,
        "discVirtioHotPlug": true,
        "discVirtioHotUnplug": true,
        "discScsiHotPlug": true,
        "discScsiHotUnplug": true
    }
}

Request Parameters - Body

Name Required Type Description
name no string The name of the image.
description no string The description of the image.
licenceType yes string The image's licence type: LINUX, WINDOWS, WINDOWS2016, OTHER, or UNKNOWN.
cpuHotPlug no Boolean This volume is capable of CPU hot plug (no reboot required).
cpuHotUnplug no Boolean This volume is capable of CPU hot unplug (no reboot required).
ramHotPlug no Boolean This volume is capable of memory hot plug (no reboot required).
ramHotUnplug no Boolean This volume is capable of memory hot unplug (no reboot required).
nicHotPlug no Boolean This volume is capable of NIC hot plug (no reboot required).
nicHotUnplug no Boolean This volume is capable of NIC hot unplug (no reboot required).
discVirtioHotPlug no Boolean This volume is capable of VirtIO drive hot plug (no reboot required).
discVirtioHotUnplug no Boolean This volume is capable of VirtIO drive hot unplug (no reboot required).
discScsiHotPlug no Boolean This volume is capable of SCSI drive hot plug (no reboot required).
discScsiHotUnplug no Boolean This volume is capable of SCSI drive hot unplug (no reboot required).
Curl Example

The following shows how to submit a PUT request using curl:

curl --include \
     --request PUT \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '{
         "properties": {
             "name": "Updated Image Name",
             "description": "Updated Image Description",
             "licenceType": "OTHER",
             "cpuHotPlug": true,
             "cpuHotUnplug": true,
             "ramHotPlug": true,
             "ramHotUnplug": true,
             "nicHotPlug": true,
             "nicHotUnplug": true,
             "discVirtioHotPlug": true,
             "discVirtioHotUnplug": true,
             "discScsiHotPlug": true,
             "discScsiHotUnplug": true
         }' \
https://api.ionos.com/cloudapi/v5/images/{imageId}

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.ionos.com/cloudapi/v5/requests/{requestId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "[image-id]",
  "type" : "image",
  "href" : "https://api.ionos.com/cloudapi/v5/images/{imageId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "createdByUserId" : "[userId]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "lastModifiedByUserId" : "[userId]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "[name]",
    "description" : "Updated Example Description",
    "location" : "[location]",
    "size" : 5,
    "cpuHotPlug" : true,
    "cpuHotUnplug" : true,
    "ramHotPlug" : false,
    "ramHotUnplug" : false,
    "nicHotPlug" : false,
    "nicHotUnplug" : false,
    "discVirtioHotPlug" : false,
    "discVirtioHotUnplug" : false,
    "discScsiHotPlug" : false,
    "discScsiHotUnplug" : false,
    "licenceType" : "OTHER",
    "imageType" : "HDD",
    "public" : false
  }
}
Response Parameters

The following table describes the attributes found in the JSON response body:

Name Type Description
id string The resource's unique identifier.
type string The type of object that has been created.
href string URL to the object’s representation (absolute path).
metadata collection Image metadata.
properties collection Image properties.

The metadata returned includes the following attributes.

Name Type Description
createdDate string The date the resource was created.
createdBy string The user who created the resource.
createdByUserId string The userId who created the resource.
etag string The ETag for the resource.
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
state string Image state.

The properties returned include the following attributes:

Name Type Description
name string The name of the image.
description string The description of the image.
location string The image's location.
size string The size of the image in GB.
cpuHotPlug Boolean This volume is capable of CPU hot plug (no reboot required).
cpuHotUnplug Boolean This volume is capable of CPU hot unplug (no reboot required).
ramHotPlug Boolean This volume is capable of memory hot plug (no reboot required).
ramHotUnplug Boolean This volume is capable of memory hot unplug (no reboot required).
nicHotPlug Boolean This volume is capable of NIC hot plug (no reboot required).
nicHotUnplug Boolean This volume is capable of NIC hot unplug (no reboot required).
discVirtioHotPlug Boolean This volume is capable of VirtIO drive hot plug (no reboot required).
discVirtioHotUnplug Boolean This volume is capable of VirtIO drive hot unplug (no reboot required).
discScsiHotPlug Boolean This volume is capable of SCSI drive hot plug (no reboot required).
discScsiHotUnplug Boolean This volume is capable of SCSI drive hot unplug (no reboot required).
licenceType Boolean The image's licence type: LINUX, WINDOWS, WINDOWS2016, OTHER, or UNKNOWN.
imageType Boolean The type of image: HDD, CDROM (ISO).
public Boolean Indicates if the image is part of the public repository (true) or not (false).

Delete Image

Deletes the specified private image. This only applies to private images that you have uploaded.

Request

To delete an image send a DELETE request to https://api.ionos.com/cloudapi/v5/images/{imageId}

Request Parameters - Path

Parameter Required Type Default Description
{imageId} yes string n/a The ID of a private image.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Curl Example

The following shows you how to submit the request body via curl:

curl --include \
     --request DELETE \
     --user 'username@domain.tld:password' \
https://api.ionos.com/cloudapi/v5/images/{imageId}

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.ionos.com/cloudapi/v5/requests/{requestId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Length: 0
Strict-Transport-Security: max-age=15768000

There is no JSON response body returned for a successful DELETE request.

If you do not have permission to delete the image, you will get a response similar to this:

HTTP/1.1 403 Forbidden
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "httpStatus" : 403,
  "messages" : [ {
    "errorCode" : "313",
    "message" : "Access Denied as you don't have permission for this operation"
  } ]
}

Volumes

Create Volume

Creates a volume within the data center. This will NOT attach the volume to a server. Please see the Servers section for details on how to attach storage volumes.

Guidelines for SSD Volume Sizing

Provisioning volumes with the type set to "SSD" gives your server the capability to handle a significantly higher number of IOPS. (Input/output operations per second) The increased IOPS provided by SSD volumes can have a noticeable benefit on your servers overall performance. When provisioning SSD volumes there are few things to consider related to sizing the volume for optimal performance.

As with HDD volumes, you have the option to create a SSD volume as small as 1GB. The maximum volume size is determined by your contract limit. Typical limits are 2048 GB for HDD and 1024 GB for SSD volumes, but again, your volume size limit may be different. Multiple HDD and/or SSD volumes may be attached to a server.

To get the best performance from SSD volumes, it is recommended that you provision a SSD volume of at least 100 GB in size. As you increase SSD volume size above 100GB, your IOPS and available storage bandwidth will also increase. The optimal combination of IOPS and storage bandwidth capability on the IONOS platform is currently reached with a volume size of 300 GB. (IOPS of 15000 read and 9000 write, along with bandwidth of 300MB/s) It is perfectly acceptable to create SSD volumes larger than 300 GB, however no additional performance gains are realized once you exceed 300 GB.

Request

To create a volume send a POST request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of the virtual data center.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Body

Construct your JSON request body by specifying the attributes of the volume.

Name Required Type Default Description
name no string n/a The name of the volume.
size yes number n/a The size of the volume in GB.
bus no string VIRTIO The bus type of the volume ["VIRTIO" or "IDE"]
image yes string n/a The image or snapshot ID.
imageAlias yes string n/a An alias to a IONOS public image. Use instead of "image".
type yes string n/a The volume type. ["HDD" or "SSD"]
licenceType yes string n/a The licence type of the volume. Options: LINUX, WINDOWS, WINDOWS2016, UNKNOWN, OTHER
imagePassword yes string n/a A password is set on the image for the "root" or "Administrator" account. This field may only be set during volume creation. Only valid with supplied HDD (not ISO) images. The password must contain at least 8 and no more than 50 characters. Only these characters are allowed: [a-z][A-Z][0-9]
sshKeys yes Array[string] n/a One or more SSH keys to allow access to the volume via SSH. Only valid with supplied Linux HDD (not ISO) images.
availabilityZone no string AUTO The storage availability zone assigned to the volume. Valid values: AUTO, ZONE_1, ZONE_2, or ZONE_3. This only applies to HDD volumes. Leave blank or set to AUTO when provisioning SSD volumes.
cpuHotPlug no Boolean false This volume is capable of CPU hot plug (no reboot required)
ramHotPlug no Boolean false This volume is capable of memory hot plug (no reboot required)
nicHotPlug no Boolean false This volume is capable of NIC hot plug (no reboot required)
nicHotUnplug no Boolean false This volume is capable of NIC hot unplug (no reboot required)
discVirtioHotPlug no Boolean false This volume is capable of VirtIO drive hot plug (no reboot required)
discVirtioHotUnplug no Boolean false This volume is capable of VirtIO drive hot unplug (no reboot required)

Note: The "Required" column needs some additional explanation. You will need to provide a valid value for either the image, imageAlias, or the licenceType parameters. The licenceType is required, but if image or imageAlias is supplied, then licenceType is already set and cannot be changed. Similarly either the imagePassword or sshKeys attributes need to be defined when creating a volume that uses an image or imageAlias of an IONOS public HDD image. You may wish to set a valid value for imagePassword even when using sshKeys so that it is possible to authenticate with a password when using the remote console feature of the DCD. Alternatively, you can load your SSH Keys into the DCD. Because the allowed character values for imagePassword are limited, it would be a good idea to change to a more complex password after you initially access a server. This is especially applicable for servers that are connected to the public internet full-time.

Request Body Example

The format of the request body is as follows:

{
    "properties": {
        "size": volume-size-in-gb,
        "name": "volume-name",
        "image": "image-or-snapshot-id",
        "imageAlias": "image-alias"
        "imagePassword": "password for image",
        "sshKeys": ["ABC123..."]
        "bus": "volume-bus-type",
        "type": "type",
        "licenceType": "licenceType",
        "availabilityZone" : "AUTO or specific zone"
    }
}

Curl Example

The following shows how to submit a POST datacenters/{dataCenterId}/volumes request using curl:

curl --include \
    --request POST \
    --user 'username@domain.tld:password' \
    --header "Content-Type: application/json" \
    --data-binary '{
        "properties": {
        "size": [volume-size-in-gb],
        "name": "[volume-name]",
        "image": "[image-or-snapshot-id]",
        "imagePassword": "abc123321CBA",
        "bus": "VIRTIO",
        "type": "HDD",
        "licenceType": "OTHER",
        "availabilityZone": "ZONE_1"
        }
    }' \
    https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.ionos.com/cloudapi/v5/requests/{requestStatusId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "[volume-id]",
  "type" : "volume",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes/[volume-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "createdByUserId" : "[userId]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "lastModifiedByUserId" : "[userId]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "TestVolume01",
    "type" : "HDD",
    "size" : 5,
    "availabilityZone" : "ZONE_1",
    "image" : null,
    "imageAlias" : "null",
    "imagePassword" : null,
    "sshKeys" : null,
    "bus" : "VIRTIO",
    "licenceType" : "OTHER",
    "cpuHotPlug" : false,
    "cpuHotUnplug" : false,
    "ramHotPlug" : false,
    "ramHotUnplug" : false,
    "nicHotPlug" : false,
    "nicHotUnplug" : false,
    "discVirtioHotPlug" : false,
    "discVirtioHotUnplug" : false,
    "deviceNumber" : null
  }
}

Response Attributes

These attributes are found in the JSON response body:

Name Type Description
id string The resource's unique identifier.
type string The type of object that has been created. Should be "volume".
href string URL to the volume.
metadata collection Volume metadata.
properties collection Volume properties.

The metadata returned for the volume:

Name Type Description
createdDate string The date the volume was created.
createdBy string The user who created the volume.
createdByUserId string The userId who created the resource.
etag string The etag for the resource.
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
state string The Volume state. AVAILABLE, BUSY, INACTIVE

The properties returned for the volume:

Name Type Description
name string The name of the volume.
type string The volume type, [HDD or SSD].
size int32 The size of the volume in GB.
availabilityZone string The storage availability zone assigned to the volume. [AUTO, ZONE_1, ZONE_2, or ZONE_3]
image string The image or snapshot ID.
imageAlias string Always returns "null".
imagePassword string Always returns "null".
sshKeys string Always returns "null".
bus string The bus type: VIRTIO or IDE. Returns "null" if not connected to a server.
licenceType string Licence type. [WINDOWS, WINDOWS2016, LINUX, OTHER, UNKNOWN]
cpuHotPlug Boolean This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug Boolean This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug Boolean This volume is capable of memory hot plug (no reboot required)
ramHotUnplug Boolean This volume is capable of memory hot unplug (no reboot required)
nicHotPlug Boolean This volume is capable of NIC hot plug (no reboot required)
nicHotUnplug Boolean This volume is capable of NIC hot unplug (no reboot required)
discVirtioHotPlug Boolean This volume is capable of VirtIO drive hot plug (no reboot required)
discVirtioHotUnplug Boolean This volume is capable of VirtIO drive hot unplug (no reboot required)
deviceNumber int32 The LUN ID of the storage volume. Returns "null" for volumes not mounted/attached to a server.

Helpful errors are returned if the request contains invalid data:

{
  "httpStatus" : 422,
  "messages" : [ {
    "errorCode" : "100",
    "message" : "[(root).properties.imagePassword] Password syntax error Password invalid, valid characters are:a-zA-Z0-9. Length between 8 and 50."
  }, {
    "errorCode" : "100",
    "message" : "[(root).properties.licenceType] Attribute must not be set if 'image' is set"
  } ]
}

Read Volume

Retrieves the attributes of a given volume.

Request

To retrieve a single volume you would send a GET request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes/{volumeId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of the virtual data center.
{volumeId} yes string n/a The ID of the volume.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/?depth=1

Note: For this particular operation, increasing the value supplied to depth does NOT return any additional information beyond the default amount returned with a value of 0.

Curl Example

The following shows how to submit the GET /datacenters/{dataCenterId}/volumes/{volumeId} request using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes/{volumeId}

Response

HTTP/1.1 200 OK
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
X-RateLimit-Remaining: 299
X-RateLimit-Burst: 300
X-RateLimit-Limit: 600
ETag: [etag]
Content-Type: application/json
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "[volume-id]",
  "type" : "volume",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes/{volumeId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "createdByUserId" : "[userId]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "lastModifiedByUserId" : "[userId]",
    "state" : "AVAILABLE"
  },
  "properties" : {
    "name" : "[Volume Name]",
    "type" : "HDD",
    "size" : 5,
    "availabilityZone" : "AUTO",
    "image" : null,
    "imageAlias" : null,
    "imagePassword" : null,
    "sshKeys" : null,
    "bus" : "VIRTIO",
    "licenceType" : "LINUX",
    "cpuHotPlug" : false,
    "cpuHotUnplug" : false,
    "ramHotPlug" : false,
    "ramHotUnplug" : false,
    "nicHotPlug" : false,
    "nicHotUnplug" : false,
    "discVirtioHotPlug" : false,
    "discVirtioHotUnplug" : false,
    "deviceNumber" : 1
   }
}

Response Attributes

The request will return a collection of volumes.

If you used the optional depth parameter (?depth=1) to the end of the request you will receive more detailed output on each of the volumes. The output will be similar to what is returned when issuing a GET request for each specific volume.

These attributes are found in the JSON response body:

Name Type Description
id string The resource's unique identifier.
type string The type of object that has been created. Should be "volume".
href string URL to the volume.
metadata collection Volume metadata.
properties collection Volume properties.

The metadata returned for each volume:

Name Type Description
createdDate string The date the volume was created.
createdBy string The user who created the volume.
createdByUserId string The userId who created the resource.
etag string The etag for the resource.
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
state string The Volume state. AVAILABLE, BUSY, INACTIVE

The properties returned for each volume:

Name Type Description
name string The name of the volume.
type string The volume type, [HDD or SSD].
size int32 The size of the volume in GB.
availabilityZone string The storage availability zone assigned to the volume. [AUTO, ZONE_1, ZONE_2, or ZONE_3]
image string The image or snapshot ID.
imageAlias string Always returns "null".
imagePassword string Always returns "null".
sshKeys string Always returns "null".
bus string The bus type: VIRTIO or IDE. Returns "null" if not connected to a server.
licenceType string Licence type. ( WINDOWS, WINDOWS2016, LINUX, OTHER, UNKNOWN)
cpuHotPlug Boolean This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug Boolean This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug Boolean This volume is capable of memory hot plug (no reboot required)
ramHotUnplug Boolean This volume is capable of memory hot unplug (no reboot required)
nicHotPlug Boolean This volume is capable of NIC hot plug (no reboot required)
nicHotUnplug Boolean This volume is capable of NIC hot unplug (no reboot required)
discVirtioHotPlug Boolean This volume is capable of VirtIO drive hot plug (no reboot required)
discVirtioHotUnplug Boolean This volume is capable of VirtIO drive hot unplug (no reboot required)
deviceNumber int32 The LUN ID of the storage volume. Returns "null" for volumes not mounted/attached to a server.

List Volumes

Retrieve a list of volumes within a VDC. If you want to retrieve a list of volumes attached to a server please see the Servers section of this documentation for examples on how to do so.

Request

To retrieve a list of volumes send a GET request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of the virtual data center.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information beyond the default amount returned with a value of 0.

You can filter the result set using custom filters.

An example of using the custom filter to find all volumes in a particular virtual data center that have a licenceType of "OTHER" assigned:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes?filter.licenceType=other&depth=1

You can also filter on metadata such as createdBy. This example would return volumes that contain the string "joe" in createdBy:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes?filter.createdBy=joe&depth=1

Curl Example

The following shows how to submit a GET datacenters/{dataCenterId}/volumes request using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes

Response

HTTP/1.1 200 OK
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
X-RateLimit-Remaining: 299
X-RateLimit-Burst: 300
X-RateLimit-Limit: 600
ETag: [etag]
Content-Type: application/json
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{dataCenterId}/volumes",
  "type" : "collection",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes",
  "items" : [ {
    "id" : "{volumeId}",
    "type" : "volume",
    "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes/{volumeId}"
  }, {
    "id" : "{volumeId}",
    "type" : "volume",
    "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes/{volumeId}"
  } ]
}

Response Attributes

The request will return a collection of volumes.

If you used the optional depth parameter (?depth=1) to the end of the request you will receive more detailed output on each of the volumes. The output will be similar to what is returned when issuing a GET request for each specific volume.

These attributes are found in the JSON response body:

Name Type Description
id string The resource's unique identifier.
type string The type of object that has been created. Should be "collection".
href string URL to the volumes collection.
items collection A collection of volumes.

At the default depth=0 each of the items will have the following attributes:

Name Type Description
id string The resource's unique identifier.
type string The type of object that has been created. Should be "volume".
href string A URL to the specific volume.

Increasing to depth=1, additional information is returned for each volume in items as described in the next section.

Name Type Description
id string The resource's unique identifier.
type string The type of object that has been created. Should be "volume".
href string A URL to the specific volume.
metadata collection Volume metadata.
properties collection Volume properties.

The metadata returned for each volume:

Name Type Description
createdDate string The date the volume was created.
createdBy string The user who created the volume.
createdByUserId string The userId who created the resource.
etag string The etag for the resource.
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
state string The Volume state. AVAILABLE, BUSY, INACTIVE

The properties returned for each volume:

Name Type Description
name string The name of the volume.
type string The volume type, [HDD or SSD].
size int32 The size of the volume in GB.
availabilityZone string The storage availability zone assigned to the volume. [AUTO, ZONE_1, ZONE_2, or ZONE_3]
image string The image or snapshot ID.
imageAlias string Always returns "null".
imagePassword string Always returns "null".
sshKeys string Always returns "null".
bus string The bus type: VIRTIO or IDE. Returns "null" if not connected to a server.
licenceType string Licence type. [WINDOWS, WINDOWS2016, LINUX, OTHER, UNKNOWN]
cpuHotPlug Boolean This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug Boolean This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug Boolean This volume is capable of memory hot plug (no reboot required)
ramHotUnplug Boolean This volume is capable of memory hot unplug (no reboot required)
nicHotPlug Boolean This volume is capable of NIC hot plug (no reboot required)
nicHotUnplug Boolean This volume is capable of NIC hot unplug (no reboot required)
discVirtioHotPlug Boolean This volume is capable of VirtIO drive hot plug (no reboot required)
discVirtioHotUnplug Boolean This volume is capable of VirtIO drive hot unplug (no reboot required)
deviceNumber int32 The LUN ID of the storage volume. Returns "null" for volumes not mounted/attached to a server.

Update Volume

The IONOS API implements both PUT and PATCH for updates. You may choose one or the other.

You can update -- in full or partially -- various attributes on the volume using the above methods; however, some restrictions are in place:

You may increase the size of an existing storage volume. You cannot reduce the size of an existing storage volume. The volume size will be increased without reboot if the appropriate "hot plug" settings have been set to true. The additional capacity is not added to any partition therefore you will need to adjust the partition inside the operating system afterwards. Once you have increased the volume size you cannot decrease the volume size using the Cloud API. There are some tutorials available that describe a process for reducing volume size using Gparted.

Certain attributes can only be set when a volume is created and are considered immutable once the volume has been provisioned. Trying to alter these with either the PATCH or PUT methods will result in an error similar to this:

{
  "httpStatus" : 422,
  "messages" : [ {
    "errorCode" : "104",
    "message" : "[(root).properties.cpuHotUnplug] Attribute is read-only"
  }, {
    "errorCode" : "104",
    "message" : "[(root).properties.ramHotUnplug] Attribute is read-only"
  } ]
}

PATCH

Use PATCH to perform an update to the attributes of a volume.

Request

To perform an update to the volume's properties send a PATCH request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes/{volumeId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of the VDC.
{volumeId} yes string n/a The ID of a volume.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Body

Since we are modifying an existing volume, none of the request parameters are specifically required. However, many of the volume parameters are immutable or read-only once a volume is created and therefore cannot be changed with a PATCH request.

Header Required Type Description
name no string The name of the volume.
size no int32 The size of the volume in GB. Can only be increased, not decreased.
bus no string The bus type of the volume ["VIRTIO" or "IDE"].

Curl Example

The following shows how to submit a PATCH request to change the name and size of an existing volume using curl:

curl --include \
    --request PATCH \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '{
          "name": "TestVolumeRename",
          "size": 20,
          "bus": "VIRTIO"
          }' \
          https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes/{volumeId}

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.ionos.com/cloudapi/v5/requests/{requestStatusId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "[volume-id]",
  "type" : "volume",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes/{volumeId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "createdByUserId" : "[userId]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "lastModifiedByUserId" : "[userId]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "TestVolume01Rename",
    "type" : "HDD",
    "size" : 20,
    "availabilityZone" : "AUTO",
    "image" : null,
    "imageAlias" : null,
    "imagePassword" : null,
    "sshKeys" : null,
    "bus" : null,
    "licenceType" : "OTHER",
    "cpuHotPlug" : false,
    "cpuHotUnplug" : false,
    "ramHotPlug" : false,
    "ramHotUnplug" : false,
    "nicHotPlug" : false,
    "nicHotUnplug" : false,
    "discVirtioHotPlug" : false,
    "discVirtioHotUnplug" : false,
    "deviceNumber" : null
  }
}

Response Attributes

These attributes are found in the JSON response body:

Name Type Description
id string The resource's unique identifier.
type string The type of object that has been created. Should be "volume".
href string URL to the volume.
metadata collection Volume metadata.
properties collection Volume properties.

The metadata returned for the volume:

Name Type Description
createdDate string The date the volume was created.
createdBy string The user who created the volume.
createdByUserId string The userId who created the resource.
etag string The etag for the resource.
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
state string The Volume state. AVAILABLE, BUSY, INACTIVE

The properties returned for the volume:

Name Type Description
name string The name of the volume.
type string The volume type, [HDD or SSD].
size int32 The size of the volume in GB.
availabilityZone string The storage availability zone assigned to the volume. [AUTO, ZONE_1, ZONE_2, or ZONE_3]
image string The image or snapshot ID.
imageAlias string Always returns "null".
imagePassword string Always returns "null".
sshKeys string Always returns "null".
bus string The bus type: VIRTIO or IDE. Returns "null" if not connected to a server.
licenceType string Licence type. [WINDOWS, WINDOWS2016, LINUX, OTHER, UNKNOWN]
cpuHotPlug Boolean This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug Boolean This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug Boolean This volume is capable of memory hot plug (no reboot required)
ramHotUnplug Boolean This volume is capable of memory hot unplug (no reboot required)
nicHotPlug Boolean This volume is capable of NIC hot plug (no reboot required)
nicHotUnplug Boolean This volume is capable of NIC hot unplug (no reboot required)
discVirtioHotPlug Boolean This volume is capable of VirtIO drive hot plug (no reboot required)
discVirtioHotUnplug Boolean This volume is capable of VirtIO drive hot unplug (no reboot required)
deviceNumber int32 The LUN ID of the storage volume. Returns "null" for volumes not mounted/attached to a server.

PUT

Use PUT to perform an update of the attributes of a volume.

Request

To perform an update of the volume's properties send a PUT request to: https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes/{volumeId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of the virtual data center.
{volumeId} yes string n/a The ID of a volume.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Body

The majority of volume properties can only be set at volume creation and cannot be updated with a PUT request. Unlike the PATCH request described above, using PUT requires that you pass in a value for size even if it isn't being changed.

Header Required Type Description
name no string The name of the volume.
size yes int32 The size of the volume in GB. Can only be increased, not decreased.
bus no string The bus type of the volume ["VIRTIO" or "IDE"].

Attempting to change other parameters will result in a response similar to this:

{
  "httpStatus" : 422,
  "messages" : [ {
    "errorCode" : "102",
    "message" : "[(root).properties.availabilityZone] Attribute is immutable, therefore not allowed in update requests"
  }, {
    "errorCode" : "102",
    "message" : "[(root).properties.type] Attribute is immutable, therefore not allowed in update requests"
  }, {
    "errorCode" : "102",
    "message" : "[(root).properties.imagePassword] Attribute is immutable, therefore not allowed in update requests"
  }, {
    "errorCode" : "104",
    "message" : "[(root).properties.nicHotUnplug] Attribute is read-only"
  } ]
}

Curl Example

The following shows how to submit the PUT request using curl:

curl --include \
     --request PUT \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '{
         "properties": {
            "name": "TestVolume01Replaced",
            "size": 12,
            "bus": "VIRTIO"
         }
    }' \
     https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes/{volumeId}

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.ionos.com/cloudapi/v5/requests/{requestStatusId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "[volume-id]",
  "type" : "volume",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes/{volumeId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "createdByUserId" : "[userId]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "lastModifiedByUserId" : "[userId]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "TestVolume01Replaced",
    "type" : "HDD",
    "size" : 12,
    "availabilityZone" : "AUTO",
    "image" : null,
    "imageAlias" : null,
    "imagePassword" : null,
    "sshKeys" : null,
    "bus" : null,
    "licenceType" : "OTHER",
    "cpuHotPlug" : false,
    "cpuHotUnplug" : false,
    "ramHotPlug" : false,
    "ramHotUnplug" : false,
    "nicHotPlug" : false,
    "nicHotUnplug" : false,
    "discVirtioHotPlug" : false,
    "discVirtioHotUnplug" : false,
    "deviceNumber" : null
  }
}

Response Attributes

These attributes are found in the JSON response body:

Name Type Description
id string The resource's unique identifier.
type string The type of object that has been created. Should be "volume".
href string URL to the volume.
metadata collection Volume metadata.
properties collection Volume properties.

The metadata returned for the volume:

Name Type Description
createdDate string The date the volume was created.
createdBy string The user who created the volume.
createdByUserId string The userId who created the resource.
etag string The etag for the resource.
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
state string The Volume state. AVAILABLE, BUSY, INACTIVE

The properties returned for the volume:

Name Type Description
name string The name of the volume.
type string The volume type, [HDD or SSD].
size int32 The size of the volume in GB.
availabilityZone string The storage availability zone assigned to the volume. [AUTO, ZONE_1, ZONE_2, or ZONE_3]
image string The image or snapshot ID.
imageAlias string Always returns "null".
imagePassword string Always returns "null".
sshKeys string Always returns "null".
bus string The bus type: VIRTIO or IDE. Returns "null" if not connected to a server.
licenceType string Licence type. [WINDOWS, WINDOWS2016, LINUX, OTHER, UNKNOWN]
cpuHotPlug Boolean This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug Boolean This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug Boolean This volume is capable of memory hot plug (no reboot required)
ramHotUnplug Boolean This volume is capable of memory hot unplug (no reboot required)
nicHotPlug Boolean This volume is capable of NIC hot plug (no reboot required)
nicHotUnplug Boolean This volume is capable of NIC hot unplug (no reboot required)
discVirtioHotPlug Boolean This volume is capable of VirtIO drive hot plug (no reboot required)
discVirtioHotUnplug Boolean This volume is capable of VirtIO drive hot unplug (no reboot required)
deviceNumber int32 The LUN ID of the storage volume. Returns "null" for volumes not mounted/attached to a server.

Delete Volume

Deletes the specified volume. This will result in the volume being removed from your virtual data center. Please use this with caution!

Request

To delete a volume send a DELETE request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes/{volumeId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of the virtual data center.
{volumeId} yes string n/a The ID of a volume.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Curl Example

The following shows how to submit the DELETE datacenters/{dataCenterId}/volumes/{volumeId} request using curl:

curl --include \
    --request DELETE \
     --user 'username@domain.tld:password' \
     https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes/{volumeId}

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.ionos.com/cloudapi/v5/requests/{requestStatusId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Length: 0
Strict-Transport-Security: max-age=15768000

Response Body

There is no JSON response body returned with a successful DELETE call.

Create Volume Snapshot

Creates a snapshot of a volume within the virtual data center. You can use a snapshot to create a new storage volume or to restore a storage volume.

Request

To create a volume snapshot send a POST request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes/{volumeId}/create-snapshot

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of the VDC.
{volumeId} yes string n/a The ID of a volume.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Body

Name Required Type Description
name yes string The name of the snapshot.
description no string The description of the snapshot.
licenceType no string Set to one of the values: [WINDOWS, WINDOWS2016, LINUX, OTHER, UNKNOWN]

Note: You will need to URL encode the name and description values and pass that as data to the request.

Curl Example

The following shows how to submit the POST request using curl:

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "name=TestSnapshot01" \
'https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes/{volumeId}/create-snapshot'

NOTE: The --data-urlencode option may not be available depending on the version of curl being used.

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.ionos.com/cloudapi/v5/requests/{requestId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{snapshotId}",
  "type" : "snapshot",
  "href" : "https://api.ionos.com/cloudapi/v5/snapshots/{snapshotId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "createdByUserId" : "[userId]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "lastModifiedByUserId" : "[userId]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "TestSnapshot01",
    "description" : "Created from \"[volume-name]\" in Data Center \"[data-center-name]\"",
    "location" : "{regionId}/{locationId}",
    "size" : null,
    "cpuHotPlug" : false,
    "cpuHotUnplug" : false,
    "ramHotPlug" : false,
    "ramHotUnplug" : false,
    "nicHotPlug" : false,
    "nicHotUnplug" : false,
    "discVirtioHotPlug" : false,
    "discVirtioHotUnplug" : false,
    "licenceType" : null
  }
}

Note: The values for various properties returned when creating a snapshot are not fully populated until the snapshot creation has completed and the state changes from "BUSY" to "AVAILABLE".

Response Body

These attributes are found in the JSON response body:

Name Type Description
id string The resource's unique identifier.
type string The type of object that has been created. Should be "snapshot".
href string URL to the snapshot.
metadata collection Snapshot metadata.
properties collection Snapshot properties.

The metadata returned for the snapshot:

Name Type Description
createdDate string The date the snapshot was created.
createdBy string The user who created the snapshot.
createdByUserId string The userId who created the resource.
etag string The etag for the resource.
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
state string The snapshot state. [AVAILABLE, BUSY, INACTIVE]

The properties returned for the snapshot:

Name Type Description
name string The name of the snapshot.
description string A description of the snapshot.
location string The location where the snapshot is stored.
size int32 The size of the snapshot in GB.
cpuHotPlug Boolean This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug Boolean This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug Boolean This volume is capable of memory hot plug (no reboot required)
ramHotUnplug Boolean This volume is capable of memory hot unplug (no reboot required)
nicHotPlug Boolean This volume is capable of NIC hot plug (no reboot required)
nicHotUnplug Boolean This volume is capable of NIC hot unplug (no reboot required)
discVirtioHotPlug Boolean This volume is capable of VirtIO drive hot plug (no reboot required)
discVirtioHotUnplug Boolean This volume is capable of VirtIO drive hot unplug (no reboot required)
licenceType string Licence type. [WINDOWS, WINDOWS2016, LINUX, OTHER, UNKNOWN]

Restore Volume Snapshot

This will restore a snapshot onto a volume. A snapshot is created as just another image that can be used to create new volumes or to restore an existing volume.

Request

To restore a snapshot send a POST request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes/{volumeId}/restore-snapshot

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of the VDC.
{volumeId} yes string n/a The ID of a volume.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Body

Name Required Type Description
snapshotId yes string This is the ID of the snapshot.

You will need to URL encode the snapshotId value and pass that as data to the request.

Curl Example

The following shows how to submit the POST request using curl:

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "snapshotId={snapshotId}" \
    https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes/{volumeId}/restore-snapshot'

Response

For a successful /restore-snapshot operation, you will receive a HTTP "Status: 202 (Accepted)" and the regular HTTP headers. The significant header is Location which will contain a URL that can be polled to check the status of the request. For example, if the Location header contained the value https://api.ionos.com/cloudapi/v5/requests/d8b9c6e3-63c0-4b0c-a176-27d7da8cd371/status we can submit a GET request to that URL to get the status.

While the operation is in progress, querying for the request status will return something similar to:

{
    "id": "d8b9c6e3-63c0-4b0c-a176-27d7da8cd371/status",
    "type": "request-status",
    "href": "https://api.ionos.com/cloudapi/v5/requests/d8b9c6e3-63c0-4b0c-a176-27d7da8cd371/status",
    "metadata": {
        "status": "RUNNING",
        "message": "Request is running",
        "etag": "43491564ebcfd38568918efbd6e840fd",
        "targets": [
        {
            "target": {
                "id": "53d0ebc5-7abb-465d-a256-29d5c3c1d4c3",
                "type": "volume",
                "href": "TO_BE_INJECTED"
            },
            "status": "RUNNING"
            }
        ]
}
}

Once the snapshot has been restored to the volume, querying the request status will return something similar to:

{
    "id": "d8b9c6e3-63c0-4b0c-a176-27d7da8cd371/status",
    "type": "request-status",
    "href": "https://api.ionos.com/cloudapi/v5/requests/d8b9c6e3-63c0-4b0c-a176-27d7da8cd371/status",
    "metadata": {
        "status": "DONE",
        "message": "Request has been successfully executed",
        "etag": "2ba22e58ca17bb728d522bba36cf8350",
        "targets": [
        {
            "target": {
                "id": "53d0ebc5-7abb-465d-a256-29d5c3c1d4c3",
                "type": "volume",
                "href": "TO_BE_INJECTED"
                },
                "status": "DONE"
            }
            ]
        }
    }

Snapshots

Read Snapshot

Retrieves the attributes of a specific snapshot.

Request

To retrieve details about a specific snapshot, send a GET request to https://api.ionos.com/cloudapi/v5/snapshots/{snapshotId}

Request Parameters - Path

Parameter Required Type Default Description
{snapshotId} yes string n/a The ID of a snapshot.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/snapshots/{snapshotId}?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/snapshots/{snapshotId}?depth=1

Note: For this particular operation, increasing the value supplied to depth does NOT return any additional information beyond the default amount returned with a value of 0.

Curl Example

The following shows how to submit the GET snapshots/{snapshotId} request using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password" \
     https://api.ionos.com/cloudapi/v5/snapshots/{snapshotId}

Response

HTTP/1.1 200 OK
Date: Wed, 09 Mar 2016 23:55:54 GMT
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
X-RateLimit-Remaining: 299
X-RateLimit-Burst: 300
X-RateLimit-Limit: 600
ETag: 32ea16245baf03d348bab665391df579
Content-Type: application/json
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{snapshotId}",
  "type" : "snapshot",
  "href" : "https://api.ionos.com/cloudapi/v5/snapshots/{snapshotId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "createdByUserId" : "[userId]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "lastModifiedByUserId" : "[userId]",
    "state" : "AVAILABLE"
  },
  "properties" : {
    "name" : "TestSnapshot02",
    "description" : "Created from Volume in Data Center Name",
    "location" : "{regionId}/{locationId}",
    "size" : 5,
    "cpuHotPlug" : false,
    "cpuHotUnplug" : false,
    "ramHotPlug" : false,
    "ramHotUnplug" : false,
    "nicHotPlug" : false,
    "nicHotUnplug" : false,
    "discVirtioHotPlug" : false,
    "discVirtioHotUnplug" : false,
    "discScsiHotPlug" : false,
    "discScsiHotUnplug" : false,
    "licenceType" : "LINUX"
  }
}

Response Attributes

Name Type Description
id string The snapshot's unique identifier.
type string The type of object. In this case: "snapshot"
href string URL to the object’s representation (absolute path).
metadata collection Snapshot metadata.
properties collection Snapshot properties.

The metadata returned for the snapshot:

Name Type Description
createdDate string The date the snapshot was created.
createdBy string The user who created the snapshot.
createdByUserId string The userId who created the resource.
etag string The etag for the resource.
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
state string The snapshot state. [AVAILABLE, BUSY, INACTIVE]

The properties returned for the snapshot:

Name Type Description
name string The name of the snapshot.
description string A description of the snapshot.
location string The location where the snapshot is stored.
size int32 The size of the snapshot in GB.
cpuHotPlug Boolean This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug Boolean This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug Boolean This volume is capable of memory hot plug (no reboot required)
ramHotUnplug Boolean This volume is capable of memory hot unplug (no reboot required)
nicHotPlug Boolean This volume is capable of NIC hot plug (no reboot required)
nicHotUnplug Boolean This volume is capable of NIC hot unplug (no reboot required)
discVirtioHotPlug Boolean This volume is capable of VirtIO drive hot plug (no reboot required)
discVirtioHotUnplug Boolean This volume is capable of VirtIO drive hot unplug (no reboot required)
discScsiHotPlug Boolean This volume is capable of SCSI drive hot plug (no reboot required)
discScsiHotUnplug Boolean This volume is capable of SCSI drive hot unplug (no reboot required)
licenceType string Licence type. [WINDOWS, WINDOWS2016, LINUX, OTHER, UNKNOWN]

List Snapshots

Retrieve a list of snapshots.

Request

Retrieve a list of snapshots by submitting a GET request to https://api.ionos.com/cloudapi/v5/snapshots

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/snapshots?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/snapshots?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information beyond the default amount returned with a value of 0.

You can filter the result set using custom filters.

An example of using the custom filter to find all snapshots in a particular location:

https://api.ionos.com/cloudapi/v5/snapshots?filter.location=las

You can also filter on metadata such as createdBy. This example refines the filter above to limit results to snapshots created by a specific user and also adds the depth parameter so additional info about each matching snapshot is returned:

https://api.ionos.com/cloudapi/v5/snapshots?filter.location=las&filter.createdBy=joe&depth=1

Curl Example

The following shows how to submit the GET /snapshots request using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.ionos.com/cloudapi/v5/snapshots

Response

HTTP/1.1 200 OK
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
X-RateLimit-Remaining: 299
X-RateLimit-Burst: 300
X-RateLimit-Limit: 600
ETag: [etag]
Content-Type: application/json
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "snapshots",
  "type" : "collection",
  "href" : "https://api.ionos.com/cloudapi/v5/snapshots",
  "items" : [ {
    "id" : "{snapshotId}",
    "type" : "snapshot",
    "href" : "https://api.ionos.com/cloudapi/v5/snapshots/{snapshotId}"
  } ]
}

Response Attributes

The request will return a collection of snapshots.

The following table describes the attributes found in the response body:

Name Type Description
id string "snapshots"
type string The type of object. In this case: "collection"
href string URL to the object’s representation (absolute path).
items collection A collection of snapshots.

At the default depth=0 each of the items returned has the following attributes:

Name Type Description
id string The snapshot's unique identifier.
type string The type of object. In this case: "snapshot"
href string URL to the object’s representation (absolute path).

If the query parameter depth=1 is used, then each of the items returned has the following attributes:

Name Type Description
id string The snapshot's unique identifier.
type string The type of object. In this case: "snapshot"
href string URL to the object’s representation (absolute path).
metadata collection Snapshot metadata.
properties collection Snapshot properties.

The metadata returned for the snapshot:

Name Type Description
createdDate string The date the snapshot was created.
createdBy string The user who created the snapshot.
createdByUserId string The userId who created the resource.
etag string The etag for the resource.
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
state string The snapshot state. [AVAILABLE, BUSY, INACTIVE]

The properties returned for the snapshot:

Name Type Description
name string The name of the snapshot.
description string A description of the snapshot.
location string The location where the snapshot is stored.
size int32 The size of the snapshot in GB.
cpuHotPlug Boolean This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug Boolean This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug Boolean This volume is capable of memory hot plug (no reboot required)
ramHotUnplug Boolean This volume is capable of memory hot unplug (no reboot required)
nicHotPlug Boolean This volume is capable of NIC hot plug (no reboot required)
nicHotUnplug Boolean This volume is capable of NIC hot unplug (no reboot required)
discVirtioHotPlug Boolean This volume is capable of VirtIO drive hot plug (no reboot required)
discVirtioHotUnplug Boolean This volume is capable of VirtIO drive hot unplug (no reboot required)
discScsiHotPlug Boolean This volume is capable of SCSI drive hot plug (no reboot required)
discScsiHotUnplug Boolean This volume is capable of SCSI drive hot unplug (no reboot required)
licenceType string Licence type. [WINDOWS, WINDOWS2016, LINUX, OTHER, UNKNOWN]

Update Snapshot

The Cloud API implements both PUT and PATCH for updates. You may choose one or the other depending on your preferences.

You can update, in full or partially, various attributes on the snapshot using the above methods.

PATCH

Use PATCH to perform updates to the attributes of an snapshot.

Request

To perform an update to the snapshot's properties, submit a PATCH request to https://api.ionos.com/cloudapi/v5/snapshots/{snapshotId}

Request Parameters - Path

Parameter Required Type Default Description
{snapshotId} yes string n/a The ID of the snapshot.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Body

Name Required Type Description
name no string The name of the snapshot.
description no string The description of the snapshot.
cpuHotPlug no bool This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug no bool This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug no bool This volume is capable of memory hot plug (no reboot required)
ramHotUnplug no bool This volume is capable of memory hot unplug (no reboot required)
nicHotPlug no bool This volume is capable of NIC hot plug (no reboot required)
nicHotUnplug no bool This volume is capable of NIC hot unplug (no reboot required)
discVirtioHotPlug no bool This volume is capable of VirtIO drive hot plug (no reboot required)
discVirtioHotUnplug no bool This volume is capable of VirtIO drive hot unplug (no reboot required)
discScsiHotPlug no bool This volume is capable of SCSI drive hot plug (no reboot required)
discScsiHotUnplug no bool This volume is capable of SCSI drive hot unplug (no reboot required)
licenceType no string The snapshot's licence type: [LINUX, WINDOWS, WINDOWS2016, OTHER, UNKNOWN]

Curl Example

The following shows you how to submit the request body via curl:

curl --include \
    --request PATCH \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '{
        "name": "Test Snapshot Rename",
        "description": "Created from Something in Somewhere"
        }' \
     https://api.ionos.com/cloudapi/v5/snapshots/{snapshotId}

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.ionos.com/cloudapi/v5/requests/{requestStatusId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{snapshotId}",
  "type" : "snapshot",
  "href" : "https://api.ionos.com/cloudapi/v5/snapshots/{snapshotId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "createdByUserId" : "[userId]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "lastModifiedByUserId" : "[userId]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "Test Snapshot Rename",
    "description" : "Updated Description",
    "location" : "{regionId}/{locationId}",
    "size" : 5,
    "cpuHotPlug" : false,
    "cpuHotUnplug" : false,
    "ramHotPlug" : false,
    "ramHotUnplug" : false,
    "nicHotPlug" : false,
    "nicHotUnplug" : false,
    "discVirtioHotPlug" : false,
    "discVirtioHotUnplug" : false,
    "discScsiHotPlug" : false,
    "discScsiHotUnplug" : false,
    "licenceType" : "LINUX"
  }
}

Response Attributes

The JSON response body will contain the following attributes:

Name Type Description
id string The snapshot's unique identifier.
type string The type of object. In this case: "snapshot"
href string URL to the object’s representation (absolute path).
metadata collection Snapshot metadata.
properties collection Snapshot properties.

The metadata returned for the snapshot:

Name Type Description
createdDate string The date the snapshot was created.
createdBy string The user who created the snapshot.
createdByUserId string The userId who created the resource.
etag string The etag for the resource.
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
state string The snapshot state. [AVAILABLE, BUSY, INACTIVE]

The properties returned for the snapshot:

Name Type Description
name string The name of the snapshot.
description string A description of the snapshot.
location string The location where the snapshot is stored.
size int32 The size of the snapshot in GB.
cpuHotPlug Boolean This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug Boolean This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug Boolean This volume is capable of memory hot plug (no reboot required)
ramHotUnplug Boolean This volume is capable of memory hot unplug (no reboot required)
nicHotPlug Boolean This volume is capable of NIC hot plug (no reboot required)
nicHotUnplug Boolean This volume is capable of NIC hot unplug (no reboot required)
discVirtioHotPlug Boolean This volume is capable of VirtIO drive hot plug (no reboot required)
discVirtioHotUnplug Boolean This volume is capable of VirtIO drive hot unplug (no reboot required)
discScsiHotPlug Boolean This volume is capable of SCSI drive hot plug (no reboot required)
discScsiHotUnplug Boolean This volume is capable of SCSI drive hot unplug (no reboot required)
licenceType string Licence type. [WINDOWS, WINDOWS2016, LINUX, OTHER, UNKNOWN]

PUT

Use PUT to perform an update of the attributes of a snapshot.

Request

To perform an update of the snapshot's properties, send a PUT request to: https://api.ionos.com/cloudapi/v5/snapshots/{snapshotId}

Request Parameters - Path

Parameter Required Type Default Description
{snapshotId} yes string n/a The ID of the snapshot.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Body

Name Required Type Description
name no string The name of the snapshot.
description no string The description of the snapshot.
cpuHotPlug no bool This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug no bool This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug no bool This volume is capable of memory hot plug (no reboot required)
ramHotUnplug no bool This volume is capable of memory hot unplug (no reboot required)
nicHotPlug no bool This volume is capable of NIC hot plug (no reboot required)
nicHotUnplug no bool This volume is capable of NIC hot unplug (no reboot required)
discVirtioHotPlug no bool This volume is capable of VirtIO drive hot plug (no reboot required)
discVirtioHotUnplug no bool This volume is capable of VirtIO drive hot unplug (no reboot required)
discScsiHotPlug no bool This volume is capable of SCSI drive hot plug (no reboot required)
discScsiHotUnplug no bool This volume is capable of SCSI drive hot unplug (no reboot required)
licenceType no string The snapshot's licence type: [LINUX, WINDOWS, WINDOWS2016, OTHER, UNKNOWN]

Curl Example

The following shows how to submit the PUT request using curl:

curl --include \
     --request PUT \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '{
        "properties": {
           "name": "Snapshot New Name",
           "description" : "Updated Snapshot Description",
           "cpuHotPlug" : false,
           "cpuHotUnplug" : false,
           "ramHotPlug" : false,
           "ramHotUnplug" : false,
           "nicHotPlug" : false,
           "nicHotUnplug" : false,
           "discVirtioHotPlug" : false,
           "discVirtioHotUnplug" : false,
           "discScsiHotPlug" : true,
           "discScsiHotUnplug" : true,
           "licenceType" : "OTHER"
        }
}' \
https://api.ionos.com/cloudapi/v5/snapshots/{snapshotId}

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.ionos.com/cloudapi/v5/requests/{requestId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{snapshotId}",
  "type" : "snapshot",
  "href" : "https://api.ionos.com/cloudapi/v5/snapshots/{snapshotId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "createdByUserId" : "[userId]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "lastModifiedByUserId" : "[userId]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "Snapshot New Name",
    "description" : "Updated Snapshot Description",
    "location" : "{regionId}/{locationId}",
    "size" : 5,
    "cpuHotPlug" : false,
    "cpuHotUnplug" : false,
    "ramHotPlug" : false,
    "ramHotUnplug" : false,
    "nicHotPlug" : false,
    "nicHotUnplug" : false,
    "discVirtioHotPlug" : false,
    "discVirtioHotUnplug" : false,
    "discScsiHotPlug" : true,
    "discScsiHotUnplug" : true,
    "licenceType" : "OTHER"
  }
}

Response Attributes

The JSON response body will contain the following attributes:

Name Type Description
id string The snapshot's unique identifier.
type string The type of object. In this case: "snapshot"
href string URL to the object’s representation (absolute path).
metadata collection Snapshot metadata.
properties collection Snapshot properties.

The metadata returned for the snapshot:

Name Type Description
createdDate string The date the snapshot was created.
createdBy string The user who created the snapshot.
createdByUserId string The userId who created the resource.
etag string The etag for the resource.
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
state string The snapshot state. [AVAILABLE, BUSY, INACTIVE]

The properties returned for the snapshot:

Name Type Description
name string The name of the snapshot.
description string A description of the snapshot.
location string The location where the snapshot is stored.
size int32 The size of the snapshot in GB.
cpuHotPlug Boolean This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug Boolean This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug Boolean This volume is capable of memory hot plug (no reboot required)
ramHotUnplug Boolean This volume is capable of memory hot unplug (no reboot required)
nicHotPlug Boolean This volume is capable of NIC hot plug (no reboot required)
nicHotUnplug Boolean This volume is capable of NIC hot unplug (no reboot required)
discVirtioHotPlug Boolean This volume is capable of VirtIO drive hot plug (no reboot required)
discVirtioHotUnplug Boolean This volume is capable of VirtIO drive hot unplug (no reboot required)
discScsiHotPlug Boolean This volume is capable of SCSI drive hot plug (no reboot required)
discScsiHotUnplug Boolean This volume is capable of SCSI drive hot unplug (no reboot required)
licenceType string Licence type. [WINDOWS, WINDOWS2016, LINUX, OTHER, UNKNOWN]

Delete Snapshot

Deletes the specified snapshot.

Request

To delete a snapshot, send a DELETE request to https://api.ionos.com/cloudapi/v5/snapshots/{snapshotId}

Request Parameters - Path

Parameter Required Type Default Description
{snapshotId} yes string n/a The ID of a snapshot.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Curl Example

The following shows how to submit the DELETE /snapshots/{snapshotId} request using curl:

curl --include \
    --request DELETE \
     --user 'username@domain.tld:password' \
     https://api.ionos.com/cloudapi/v5/snapshots/{snapshotId}

Response

HTTP/1.1 202 Accepted
Date: Thu, 10 Mar 2016 00:55:23 GMT
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.ionos.com/cloudapi/v5/requests/{requestId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: 7df1074bd6f415369eb335bff3ad1781
Content-Length: 0
Strict-Transport-Security: max-age=15768000

There is no JSON body returned for a successful DELETE request.

IP Block

Create IP Block

Reserves an IP block at a specified location that can be used by resources within any VDCs provisioned in that same location. An IP block consists of one or more static IP addresses.

Request

To create an IP block, send a POST request to https://api.ionos.com/cloudapi/v5/ipblocks

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Body

Name Required Type Description
location yes string This must be one of the available locations. See locations.
size yes int32 The size of the IP Block you want to create.
name no string A descriptive name for the IP Block.

Curl Example

The following shows you how to submit the POST request body via curl:

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
     --header 'Content-Type: application/json' \
     --data-binary ' {
        "properties": {
            "location": "{regionId}/{locationId}",
            "size": 2,
            "name": "API Doc Test"
        }
    }' \
https://api.ionos.com/cloudapi/v5/ipblocks

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.ionos.com/cloudapi/v5/requests/{requestId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{ipBlockId}",
  "type" : "ipblock",
  "href" : "https://api.ionos.com/cloudapi/v5/ipblocks/{ipBlockId}",
  "metadata" : {
    "etag" : "{etag}",
    "createdDate" : "{date}",
    "createdBy" : "{username}",
    "createdByUserId" : "{userId}",
    "lastModifiedDate" : "{timestamp}",
    "lastModifiedBy" : "{username}",
    "lastModifiedByUserId" : "{userId}",
    "state" : "BUSY"
  },
  "properties" : {
    "ips" : [
        "1.2.3.4",
        "5.6.7.8"
    ],
    "location" : "{regionId}/{locationId}",
    "size" : 2,
    "name" : "API Doc Test",
    "ipConsumers": []
  }
}

Response Parameters

The following table describes the attributes found in the JSON response body:

Name Type Description
id string The unique identifier.
type string The type of object. In this case: "ipblock".
href string URL to the object’s representation (absolute path).
metadata collection Metadata for the IP Block.
properties collection Properties of the IP Block.

The metadata returned for an IP Block is shown in this table:

Name Type Description
etag string The ETag for the resource.
createdDate string The date the resource was created.
createdBy string The username of the user who created the resource.
createdByUserId string The userId who created the resource.
createdByUserId string The userId of the user who created the resource.
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The username of the user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
lastModifiedByUserId string The userId of the user who last modified the resource.
state string The IP Block state. It will return "BUSY" on create.

The properties returned for an IP Block are outlined in this table:

Name Type Description
ips collection The reserved IP addresses that make up the IP Block.
location string The location where the IP Block has been reserved.
size int32 The number of IP addresses that make up the IP Block.
name string A descriptive name for the IP Block.
ipConsumers collection This will be empty for a newly created IP Block.

Read IP Block

Retrieves the attributes of a specific IP Block.

Request

To retrieve a single IP Block you would send a GET request to https://api.ionos.com/cloudapi/v5/ipblocks/{ipBlockId}

Request Parameters - Path

Parameter Required Type Default Description
{ipBlockId} yes string n/a The ID of an IP block.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/ipblocks?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/ipblocks?depth=1

Note: For this particular operation, increasing the value supplied to depth does NOT return any additional information beyond the default amount returned with a value of 0.

Curl Example

The following shows you how to submit the request body via curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
https://api.ionos.com/cloudapi/v5/ipblocks/{ipBlockId}

Response

HTTP/1.1 200 OK
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
X-RateLimit-Remaining: 299
X-RateLimit-Burst: 300
X-RateLimit-Limit: 600
ETag: [etag]
Content-Type: application/json
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
    "id" : "{ipBlockId}",
    "type" : "ipblock",
    "href" : "https://api.ionos.com/cloudapi/v5/ipblocks/{ipBlockId}",
    "metadata" : {
        "etag" : "{etag}",
        "createdDate" : "{date}",
        "createdBy" : "{username}",
        "createdByUserId" : "{userId}",
        "lastModifiedDate" : "{timestamp}",
        "lastModifiedBy" : "{username}",
        "lastModifiedByUserId" : "{userId}",
        "state" : "AVAILABLE"
    },
    "properties" : {
        "ips" : [
            "1.2.3.4"
        ],
        "location" : "{regionId}/{locationId}",
        "size" : 1,
        "name" : "IP Block Example",
        "ipConsumers": [
            {
                "ip": "1.2.3.4",
                "mac": "00:01:02:04:05:06",
                "nicId": "57007fa6-3e18-4c9d-82ca-cbe517b61234",
                "serverId": "0f61d48d-8365-4622-8ea3-d5f023f51234",
                "serverName": "A Server",
                "datacenterId": "8fc590c3-4cfb-4702-8bd6-7290ad461234",
                "datacenterName": "A Datacenter"
            }
        ]
    }
}

Response Attributes

The following table describes the attributes found in the JSON response body:

Name Type Description
id string The unique identifier.
type string The type of object. In this case: "ipblock".
href string URL to the object’s representation (absolute path).
metadata collection Metadata for the IP Block.
properties collection Properties of the IP Block.

The metadata returned for an IP Block is shown in this table:

Name Type Description
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
createdDate string The date the resource was created.
createdBy string The user who created the resource.
createdByUserId string The userId who created the resource.
state string The IP Block state. [BUSY, AVAILABLE]
etag string The ETag for the resource.

The properties returned for an IP Block are outlined in this table:

Name Type Description
ips collection The reserved IP addresses that make up the IP Block.
location string The location where the IP Block has been reserved.
size int32 The number of IP addresses that make up the IP Block.
name string A descriptive name for the IP Block.
ipConsumers collection Information about where each IP address is being used.

The ipConsumers collection contains the following information about each IP address that is part of the IP Block.

Name Type Description
ip string The IP address.
mac string The MAC of the interface the IP is assigned too.
nicId string The ID of the NIC that the IP is assigned too.
serverId string The ID of the server that the IP is assigned too.
serverName string The name of the server that the IP is assigned too.
datacenterId string The ID of the data center that the IP is assigned too.
datacenterName string The name of the data center that the IP is assigned too.

Note: ipConsumers will remain empty for any IP addresses in an IP block that have not been assigned to a resource yet.

Update IP Block

Updates the properties of an existing IP block.

Request

To update an IP block, send either a PATCH or PUT request to https://api.ionos.com/cloudapi/v5/ipblocks/{ipBlockId}

Request Parameters - Path

Parameter Required Type Default Description
{ipBlockId} yes string n/a The ID of the IP Block you want to update.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Body

Name Required Type Description
name no string A descriptive name for the IP Block.

Please Note: Neither the location nor the size of an IP Block may be updated. The attributes are read-only once an IP Block is created.

Curl Example

The following shows you how to submit the PATCH request body via curl:

curl --include \
     --request PATCH \
     --user 'username@domain.tld:password' \
     --header 'Content-Type: application/json' \
     --data-binary '{
              "name": "Updated Name"
        }' \
'https://api.ionos.com/cloudapi/v5/ipblocks/{ipBlockId}'

A PUT request can be made in a similar manner, the difference being that the name/value pairs need to be passed inside the properties object. {"properties": {}}

curl --include \
 --request PUT \
 --user 'username@domain.tld:password' \
 --header 'Content-Type: application/json' \
 --data-binary '{ "properties": {
          "name": "Updated Name"
      }
    }' \
'https://api.ionos.com/cloudapi/v5/ipblocks/{ipBlockId}'

Response

The response will be similar regardless of your choice to use PATCH or PUT. The updated IP Block properties are returned.

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.ionos.com/cloudapi/v5/requests/{requestId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{ipBlockId}",
  "type" : "ipblock",
  "href" : "https://api.ionos.com/cloudapi/v5/ipblocks/{ipBlockId}",
  "metadata" : {
      "etag" : "{etag}",
      "createdDate" : "{date}",
      "createdBy" : "{username}",
      "createdByUserId" : "{userId}",
      "lastModifiedDate" : "{timestamp}",
      "lastModifiedBy" : "{username}",
      "lastModifiedByUserId" : "{userId}",
      "state" : "BUSY"
  },
  "properties" : {
    "ips" : [
        "1.2.3.4",
        "5.6.7.8"
    ],
    "location" : "{regionId}/{locationId}",
    "size" : 2,
    "name" : "Updated Name",
    "ipConsumers" : []
  }
}

Response Parameters

The following table describes the attributes found in the JSON response body:

Name Type Description
id string The unique identifier.
type string The type of object. In this case: "ipblock".
href string URL to the object’s representation (absolute path).
metadata collection Metadata for the IP Block.
properties collection Properties of the IP Block.

The metadata returned for an IP Block is shown in this table:

Name Type Description
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
createdDate string The date the resource was created.
createdBy string The user who created the resource.
createdByUserId string The userId who created the resource.
state string The IP Block state. [BUSY]
etag string The ETag for the resource.

The properties returned for an IP Block are outlined in this table:

Name Type Description
ips collection The reserved IP addresses that make up the IP Block.
location string The location where the IP Block has been reserved.
size int32 The number of IP addresses that make up the IP Block.
name string The updated name for the IP Block.
ipConsumers collection Information about resources the IP address is assigned too.

Delete IP Block

Deletes the specified IP Block.

Request

To delete an IP block you would send a DELETE request to https://api.ionos.com/cloudapi/v5/ipblocks/{ipBlockId}

Request Parameters - Path

Parameter Required Type Default Description
{ipBlockId} yes string n/a The ID of an IP block.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Curl Example

The following demonstrates how to submit the DELETE request using curl:

curl --include \
     --request DELETE \
     --user 'username@domain.tld:password' \
     https://api.ionos.com/cloudapi/v5/ipblocks/{ipBlockId}

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.ionos.com/cloudapi/v5/requests/{requestStatusId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Length: 0
Strict-Transport-Security: max-age=15768000

There is no JSON response body returned for a successful DELETE request.

LANs

Create LAN

Creates a new LAN within a VDC.

Please Note: IP Failover is configured after LAN creation using an update request. Please refer to the PUT/PATCH section below for additional details on this process.

Request

To create a LAN you would send a POST request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Body

The format of the JSON request body is as follows:

{
    "properties": {
        "name": "First LAN",
        "public": "true"
    }
}

Request Parameters - Body

These are the available properties that can be set:

Name Required Type Default
name no string n/a
public yes Boolean false

Curl Example

The following shows how to create a LAN using curl:

curl --include \
    --request POST \
    --user 'username@domain.tld:password \
    --header "Content-Type: application/json" \
    --data-binary '{
        "properties": {
            "name": "My New LAN",
            "public": "false"
        }
    }' \
    https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.ionos.com/cloudapi/v5/requests/{requesId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id": "5",
  "type": "lan",
  "href": "https://api.ionos.com/cloudapi/v5/datacenters/[data-center-id]/lans/5",
  "metadata": {
    "createdDate": "[date]",
    "createdBy": "[user]",
    "etag": "[etag]",
    "lastModifiedDate": "[date]",
    "lastModifiedBy": "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name": "[descriptive-name]",
    "ipFailover": null,
    "public": false
  }
}

Response Attributes

The following table describes the attributes found in the response body:

Name Type Description
id string The resource's unique identifier.
type string The type of object that has been created.
href string URL to the object’s representation (absolute path).
metadata collection Metadata related to the creation of the LAN.
properties collection Properties of the LAN.

The metadata returned is outlined in this table:

Name Type Description
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
createdDate string The date the resource was created.
createdBy string The user who created the resource.
createdByUserId string The userId who created the resource.
state string LAN state. [AVAILABLE, BUSY, INACTIVE]
etag string The ETag for the resource.

The properties returned are summarized in this table:

Name Type Description
name string The descriptive name assigned to the LAN object.
ipFailover array Should return "null" when creating a new LAN.
public Boolean Indicates if the LAN faces the public Internet (true) or not (false).

Read LAN

Retrieves the attributes of a given LAN.

Request

To retrieve details about a single LAN you would send a GET request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans/{lanId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.
{lanId} yes string n/a The ID of a LAN.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information beyond the default amount returned with a value of 0.

Curl Example

The following shows how to submit the GET /datacenters/{dataCenterId}/lans/{lanId} request using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans/{lanId}

Response

{
  "id" : "1",
  "type" : "lan",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans/1",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[username]",
    "createdByUserId" : "[userId]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[username]",
    "lastModifiedByUserId" : "[userId]",
    "state" : "AVAILABLE"
  },
  "properties" : {
    "name" : "[descriptive-LAN-name]",
    "ipFailover" : [],
    "public" : true
  },
  "entities" : {
    "nics" : {
      "id" : "1/nics",
      "type" : "collection",
      "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans/1/nics"
    }
  }
}

The following table describes the attributes found in the response body:

Name Type Description
id string The unique identifier.
type string The type of object that has been created.
href string URL to the object’s representation (absolute path).
metadata collection Various details about the LAN.
properties collection Properties of the LAN.
entities collection NICs that are part of the LAN.

The metadata returned for a LAN is shown in this table:

Name Type Description
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
createdDate string The date the resource was created.
createdBy string The user who created the resource.
createdByUserId string The userId who created the resource.
state string LAN state.
etag string The ETag for the resource.

The properties returned for a LAN are outlined in this table:

Name Type Description
name string A descriptive name for the LAN.
public Boolean Boolean indicating if the LAN faces the public Internet (true) or not (false).
ipFailover collection Attributes related to IP failover groups.

The ipFailover collection contains two attributes:

Name Type Description
ip string The reserved public IP address assigned to the IP failover group.
nicUuid string The UUID of the "master" NIC for the failover group.

The entities returned for a LAN are described in this table:

Name Type Description
nics collection A collection of NICs associated with the LAN.

At the default depth=0, each entity in nics has the following attributes returned:

Name Type Description
id string The NIC ID with "/nics" appended.
type string The type of object, in this case "collection".
href string A URL to access details about the NICs that are part of the LAN.

Increasing to depth=1 will return an additional items collection with each individual NIC that is part of nics listed.

Increasing to depth=2 will return even more details about each NIC that is part of nics. With depth=3 you'll get basic information about any firewall rules that are assigned to the NIC. At depth=4 you'll get detailed information about each firewall rule that is assigned to the NIC. Please take a look at the Network Interfaces section of this documentation for additional information.

List LANs

Retrieve a list of LANs provisioned in a specific VDC.

Request

To retrieve a list of LANs you would submit a GET request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information beyond the default amount returned with a value of 0.

You can filter the result set using custom filters.

An example of using the custom filter to find all LANs where public is "true":

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans?filter.public=true&depth=1

You can also filter on metadata such as lastModifiedDate. This example returns LANs that were modified in Dec 2017:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans?filter.lastModifiedDate=2017-12&depth=1

Curl Example

The following shows how to submit the GET /datacenters/{dataCenterId}/lans request via curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans

Response

Here is an example response for a virtual data center that has three LANs:

HTTP/1.1 200 OK
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
X-RateLimit-Remaining: 299
X-RateLimit-Burst: 300
X-RateLimit-Limit: 600
ETag: [etag]
Content-Type: application/json
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "[datacenterId]/lans",
  "type" : "collection",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/[datacenterId]/lans",
  "items" : [ {
    "id" : "3",
    "type" : "lan",
    "href" : "https://api.ionos.com/cloudapi/v5/datacenters/[datacenterId]/lans/3"
  }, {
    "id" : "1",
    "type" : "lan",
    "href" : "https://api.ionos.com/cloudapi/v5/datacenters/[datacenterId]/lans/1"
  }, {
    "id" : "2",
    "type" : "lan",
    "href" : "https://api.ionos.com/cloudapi/v5/datacenters/[datacenterId]/lans/2"
  } ]
}

Response Body

The response will contain a collection of LANs.

The following table describes the attributes found in the JSON response:

Name Type Description
id string The resource's unique identifier.
type string The type of object. In this case "collection".
href string URL to the object’s representation (absolute path).
items collection A collection of available LANs.

Each of the returned items has these attributes:

Name Type Description
id string The LAN's identifier, generally an integer value.
type string The type of object. In this case "lan".
href string URL to the object’s representation (absolute path).

If you append the ?depth=1 query parameter to the end of the request then more details are returned for each individual LAN that is part of items. The additional details include metadata, properties, and entities. This is similar to issuing a GET request to each LAN independently. Please see the next section for additional information.

Update LAN

The Cloud API implements both PUT and PATCH for updates. You may choose one or the other. The end of this section contains details about the steps needed to create an IP Failover group.

PATCH

Use PATCH to perform updates to the attributes of a LAN.

Request

To perform an update to the LAN's properties you would send a PATCH request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans/{lanId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a virtual data center.
{lanId} yes string n/a The ID of a LAN.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Body

The format of the JSON request body is as follows:

{
    "name": "First LAN",
    "ipFailover": [
      {
        "ip": "string",
        "nicUuid": "string"
      }
    ],
    "public": "true"
}

These are the available properties that can be set:

Name Required Type Default
name no string n/a
ipFailover no array n/a
public no Boolean false

The ipFailover array consists of two attributes.

Name Required Type Default
ip no string n/a
nicUuid no string n/a

Curl Example

The following shows you how to submit the PATCH /datacenters/{dataCenterId}/lans/{lanId} request using curl:

curl --include \
    --request PATCH \
    --user 'username@domain.tld:password' \
    --header "Content-Type: application/json" \
    --data-binary '{
        "name": "My Old LAN"
    }' \
    https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans/{lanId}

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.ionos.com/cloudapi/v5/requests/{requestStatusId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "3",
  "type" : "lan",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans/3",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "createdByUserId" : "[userId]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "lastModifiedByUserId" : "[userId]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "My Old LAN",
    "ipFailover" : [],
    "public" : false
  },
  "entities" : {
    "nics" : {
      "id" : "3/nics",
      "type" : "collection",
      "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans/3/nics"
    }
  }
}

Response Attributes

The JSON response is described in this table:

Name Type Description
id string The resource's unique identifier.
type string The type of object that has been created.
href string URL to the object’s representation (absolute path).
metadata collection Metadata related to the creation of the LAN.
properties collection Properties of the LAN.
entities collection NICs that are part of the LAN.

The metadata returned is outlined in this table:

Name Type Description
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
createdDate string The date the resource was created.
createdBy string The user who created the resource.
createdByUserId string The userId who created the resource.
state string LAN state. [AVAILABLE, BUSY, INACTIVE]
etag string The ETag for the resource.

The properties returned are summarized in this table:

Name Type Description
name string A descriptive name assigned to the LAN object.
ipFailover array Details about the IP failover group.
public Boolean Indicates if the LAN faces the public Internet (true) or not (false).

PUT

Use PUT to perform an update of the attributes of a LAN.

Request

To perform a full update of the LAN's properties send a PUT request to: https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans/{lanId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a virtual data center.
{lanId} yes string n/a The ID of a LAN.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Body

The format of the JSON request body is as follows:

{
    "properties": {
        "name": "1st LAN",
        "ipFailover": [
          {
            "ip": "",
            "nicUuid": ""
          }
        ],
        "public": true
    }
}

These are the available properties that can be set:

Name Required Type Default
name no string n/a
ipFailover no array n/a
public no Boolean false

The ipFailover array consists of two attributes.

Name Required Type Default
ip yes string n/a
nicUuid yes string n/a

Curl Example

The following shows how to submit the PUT /datacenters/{dataCenterId}/lans/{lanId} request body using curl:

curl --include \
     --request PUT \
     --user 'username@domain.tld@password' \
     --header "Content-Type: application/json" \
     --data-binary '{
        "properties": {
            "name" : "1st LAN",
            "ipFailover": [
              {
                "ip": "",
                "nicUuid": ""
              }
            ],
            "public": "false"
        }
       }' \
     https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans/{lanId}

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.ionos.com/cloudapi/v5/requests/{requestId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "4",
  "type" : "lan",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans/4",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "createdByUserId" : "[userId]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "lastModifiedByUserId" : "[userId]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "1st LAN",
    "ipFailover" : [],
    "public" : true
  },
  "entities" : {
    "nics" : {
      "id" : "4/nics",
      "type" : "collection",
      "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans/4/nics"
    }
  }
}

Response Attributes

Name Type Description
id string The resource's unique identifier.
type string The type of object that has been created.
href string URL to the object’s representation (absolute path).
metadata collection Metadata related to the creation of the LAN.
properties collection Properties of the LAN.
entities collection NICs that are part of the LAN.

The metadata returned is outlined in this table:

Name Type Description
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
createdDate string The date the resource was created.
createdBy string The user who created the resource.
createdByUserId string The userId who created the resource.
state string LAN state. [AVAILABLE, BUSY, INACTIVE]
etag string The ETag for the resource.

The properties returned are summarized in this table:

Name Type Description
name string A descriptive name assigned to the LAN object.
ipFailover array Details about the IP failover group.
public Boolean Indicates if the LAN faces the public Internet (true) or not (false).

Delete LAN

Deletes the specified LAN.

Request

To delete a LAN you would send a DELETE request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans/{lanId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.
{lanId} yes string n/a The ID of a LAN.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Curl Example

The following shows how to submit the DELETE /datacenters/{dataCenterId}/lans/{lanId} request using curl:

curl --include \
     --request DELETE \
     --user 'username@domain.tld:password'
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans/{lanId}

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.ionos.com/cloudapi/v5/requests/{requestStatusId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Length: 0
Strict-Transport-Security: max-age=15768000

There is no JSON response body returned for a successful DELETE request.

Setup IP Failover

Successfully setting up an IP Failover group requires three steps:

  • Add a reserved IP address to a NIC that will become the IP Failover master.
  • Use PATCH or PUT to enable ipFailover by providing the relevant ip and nicUuid values.
  • Add the same reserved IP address to any other NICs that are a member of the same LAN. Those NICs will become IP Failover members.

To demonstrate this, say we have two servers provisioned in the same VDC connected to the same LAN. Assuming that we have already reserved an IP Block with a single IP address of 157.97.105.85, our first step would be to assign that reserved IP address to the NIC that will be the IP Failover master.

If the NIC has an ID of: d825dd33-78b2-4251-8e0a-72d792bb6582

Then the PATCH request would be directed to:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{masterServerId}/nics/d825dd33-78b2-4251-8e0a-72d792bb6582

with a JSON body of:

{
    "name": "MasterNIC",
    "ips": ["157.97.105.85"],
    "dhcp": false,
    "lan": 5
}

Please Note: You will need to substitute in your own relevant values for the ips and lan.

Then we would issue a PATCH request to the LAN:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans/5

with a JSON body of:

{
    "name": "FailoverLAN",
    "ipFailover": [
        {
            "ip": "157.97.105.85",
            "nicUuid": "d825dd33-78b2-4251-8e0a-72d792bb6582"
        }
    ]
}

Next we issue a PATCH request to the NIC on the secondary server.

If the NIC has an ID of: 69ec958f-054a-4f13-8bce-54d11e4ef3a9

Then the PATCH request would be directed to:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{secondaryServerId}/nics/69ec958f-054a-4f13-8bce-54d11e4ef3a9

with a JSON body of:

{
    "name": "SecondaryNIC",
    "ips": ["157.97.105.85"],
    "dhcp": false,
    "lan": 5
}

To verify success, we can issue a GET request to the LAN, which should return something similar to this:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans/5

{
    "id": "5",
    "type": "lan",
    "href": "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans/5",
    "metadata": {
        "createdDate": "2018-07-17T01:09:20Z",
        "createdBy": "user@domain.tld",
        "etag": "889f966c22b37add1dae9cb9ac97cead",
        "lastModifiedDate": "2018-07-17T01:34:16Z",
        "lastModifiedBy": "user@domain.tld",
        "state": "AVAILABLE"
    },
    "properties": {
        "name": "FailoverLAN",
        "ipFailover": [
            {
                "ip": "157.97.105.85",
                "nicUuid": "d825dd33-78b2-4251-8e0a-72d792bb6582"
            }
        ],
        "public": true
    },
    "entities": {
        "nics": {
            "id": "5/nics",
            "type": "collection",
            "href": "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans/5/nics"
        }
    }
}

Sending a request for the nics will return the list of NICS that are part of the IP Failover group:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans/5/nics

{
    "id": "5/nics",
    "type": "collection",
    "href": "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans/5/nics",
    "items": [
        {
            "id": "69ec958f-054a-4f13-8bce-54d11e4ef3a9",
            "type": "nic",
            "href": "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{secondaryServerId}/nics/69ec958f-054a-4f13-8bce-54d11e4ef3a9"
        },
        {
            "id": "d825dd33-78b2-4251-8e0a-72d792bb6582",
            "type": "nic",
            "href": "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{masterServerId}/nics/d825dd33-78b2-4251-8e0a-72d792bb6582"
        }
    ]
}
  • We also have the option of using a ?depth=2 parameter on the request to the LAN to have it include the detailed info about the nics entity. This would save us one API call and provide access to the same information.

  • We could have used PUT requests instead of PATCH. We would just need to adjust the formatting of the JSON body so it uses {"properties": {}} to wrap the keys and values we are updating.

Network Interfaces

Create a NIC

Adds a NIC to the target server.

Request

To create a NIC, send a POST request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.
{serverId} yes string n/a The ID of a server.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Body

The format of the request body is as follows:

{
    "properties": {
        "name": "nic-name",
        "ips": nic-ip-collection,
        "dhcp": "nic-dhcp",
        "firewallActive": false,
        "lan": nic-lan
    },
    "entities": {
        "firewallrules": []
    }
}

Request Parameters - Body

Name Required Type Default Description
name no string n/a The name of the NIC.
ips no string collection n/a IPs assigned to the NIC. This can be a collection.
dhcp no Boolean true Set to false if you wish to disable DHCP on the NIC. Default: true
lan yes int n/a The LAN ID the NIC will sit on. If the LAN ID does not exist it will be created.
nat no Boolean n/a Indicates the private IP address has outbound access to the public internet.
firewallActive no Boolean n/a A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.
firewallrules no string collection n/a A list of firewall rules associated to the NIC represented as a collection.

Curl Example

The following shows how to submit the POST request using curl:

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '{
         "properties": {
         "name": "Internal NIC",
         "ips": ["10.2.2.3"],
         "dhcp": false,
         "lan": 2
     }
    }' \
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.ionos.com/cloudapi/v5/requests/{requestId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{nicId}",
  "type" : "nic",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "createdByUserId" : "[userId]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "lastModifiedByUserId" : "[userId]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "Internal NIC",
    "mac" : null,
    "ips" : [ "10.1.1.2" ],
    "dhcp" : false,
    "lan" : 2,
    "firewallActive" : null
  }
}

Response Attributes

The following table describes the attributes found in the JSON response body:

Name Type Description
id string The NIC's unique identifier.
type string The type of object. "nic"
href string An API URL to the NIC’s representation (absolute path).
metadata collection NIC metadata.
properties collection NIC properties.
entities collection Entities associated with the NIC. "firewallrules"

The metadata about the NIC includes:

Name Type Description
createdDate string The date the resource was created.
createdBy string The user who created the resource.
createdByUserId string The userId who created the resource.
etag string The ETag.
lastModifiedDate string The last modified time for the resource.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
state string AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued. INACTIVE The resource has been de-provisioned.

The properties returned are:

Name Type Description
name string The name of the NIC.
mac string The MAC address of the NIC.
ips collection IPs assigned to the NIC represented as a collection.
dhcp Boolean Boolean value that indicates if the NIC is using DHCP (true) or not (false).
lan int32 The LAN ID the NIC sits on.
nat Boolean Boolean value indicating if the private IP address has outbound access to the public internet enabled (true) or not (false).
firewallActive Boolean A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.

The entities returned include:

Name Type Description
firewallrules collection A collection of firewall rules associated with the NIC.

Read a NIC

Retrieves the attributes of a given NIC.

Request

To retrieve attributes of a specific NIC, send a GET request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.
{serverId} yes string n/a The ID of a server.
{nicId} yes string n/a The ID of a NIC.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information beyond the default amount returned with a value of 0.

Curl Example

The following shows how to submit the GET request using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}

Response

HTTP/1.1 200 OK
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
X-RateLimit-Remaining: 299
X-RateLimit-Burst: 300
X-RateLimit-Limit: 600
ETag: [etag]
Content-Type: application/json
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{nicId}",
  "type" : "nic",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "createdByUserId" : "[userId]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "lastModifiedByUserId" : "[userId]",
    "state" : "AVAILABLE"
  },
  "properties" : {
    "name" : null,
    "mac" : "02:00:22:11:bb:00",
    "ips" : [ "162.254.1.1" ],
    "dhcp" : true,
    "lan" : 1,
    "firewallActive" : false
  },
  "entities" : {
    "firewallrules" : {
      "id" : "{nicId}/firewallrules",
      "type" : "collection",
      "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules"
    }
  }
}

Response Attributes

The following table describes the attributes found in the JSON response body:

Name Type Description
id string The NIC's unique identifier.
type string The type of object. "nic"
href string An API URL to the NIC’s representation (absolute path).
metadata collection NIC metadata.
properties collection NIC properties.
entities collection Entities associated with the NIC. "firewallrules"

The metadata about the NIC includes:

Name Type Description
createdDate string The date the resource was created.
createdBy string The user who created the resource.
createdByUserId string The userId who created the resource.
etag string The ETag.
lastModifiedDate string The last modified time for the resource.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
state string AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued. INACTIVE The resource has been de-provisioned.

The properties returned are:

Name Type Description
name string The name of the NIC.
mac string The MAC address of the NIC.
ips collection IPs assigned to the NIC represented as a collection.
dhcp Boolean Boolean value that indicates if the NIC is using DHCP (true) or not (false).
lan int32 The LAN ID the NIC sits on.
nat Boolean Boolean value indicating if the private IP address has outbound access to the public internet enabled (true) or not (false).
firewallActive Boolean A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.

The entities returned include:

Name Type Description
firewallrules collection A collection of firewall rules associated with the NIC.

If you passed a depth query parameter with a value of 1 or greater, then additional information about each of the entities is returned.

List NICs

Retrieves a list of NICs.

Request

To retrieve a list of NICs, submit a GET request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.
{serverId} yes string n/a The ID of a server.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information beyond the default amount returned with a value of 0.

You can filter the result set using custom filters.

An example of using the custom filter to find all NICs where dhcp is "true":

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics?filter.dhcp=true&depth=1

You can also filter on metadata such as createdBy. This example limits the results to NICs created by a specific user and also adds the depth parameter so additional info about each matching NIC is returned:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics?filter.createdBy=joe&depth=1

Curl Example

The following shows how to submit the GET request using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics

Response

HTTP/1.1 200 OK
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
X-RateLimit-Remaining: 299
X-RateLimit-Burst: 300
X-RateLimit-Limit: 600
ETag: [etag]
Content-Type: application/json
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{serverId}/nics",
  "type" : "collection",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics",
  "items" : [ {
    "id" : "{nicId}",
    "type" : "nic",
    "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}"
  } ]
}

Response Attributes

The request will return a collection of NICs assigned to the server.

The following table describes the attributes found in the response body:

Name Type Description
id string {serverId}/nics
type string The type of object that has been created. "collection"
href string URL to the object’s representation (absolute path).
items collection A collection of NICs.

The items will have the following attributes.

Name Type Description
id string The NIC's unique identifier.
type string The type of object. "nic"
href string An API URL to the NIC’s representation (absolute path).

If you chose to pass the depth query parameter with a value of 1 or greater, then additional information about each NIC item will be returned. See the next section for additional details.

Update a NIC

The Cloud API implements both PUT and PATCH for updates. You may choose one or the other depending on your preference.

You can update -- in full or partially -- various attributes on the NIC using the above methods; however, some restrictions are in place:

The primary address of a NIC connected to a load balancer can only be changed by changing the IP of the load balancer. You can also add additional reserved, public IPs to the NIC.

The user can specify and assign private IPs manually. Valid IP addresses for private networks are 10.0.0.0/8, 172.16.0.0/12 or 192.168.0.0/16.

The value for firewallActive can be toggled between true and false to enable or disable the firewall. When the firewall is enabled, incoming traffic is filtered by all the firewall rules configured on the NIC. When the firewall is disabled, then all incoming traffic is routed directly to the NIC and any configured firewall rules are ignored.

PATCH

Use PATCH to perform updates to attributes of a NIC.

Request

To perform an update to the NIC's properties, send a PATCH request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.
{serverId} yes string n/a The ID of a server.
{nicId} yes string n/a The ID of a server.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters

Name Required Type Description
name no string The name of the NIC.
ips no string collection IPs assigned to the NIC represented as a collection.
dhcp no Boolean Boolean value that indicates if the NIC is using DHCP (true) or not (false).
lan no int The LAN ID the NIC sits on.
nat no Boolean Indicates if the private IP address should have outbound access to the public internet.
firewallActive no Boolean A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.

Curl Example

The following shows how to submit the PATCH request using curl:

curl --include \
     --request PATCH \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '    {
         "name": "Heartbeat NIC",
         "ips": ["10.1.1.3"]
       }
    }' \
     https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.ionos.com/cloudapi/v5/requests/{requestId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{nicId}",
  "type" : "nic",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "createdByUserId" : "[userId]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "lastModifiedByUserId" : "[userId]",
    "state" : "BUSY"
 },
 "properties" : {
    "name" : "Heartbeat NIC",
    "mac" : "02:01:f8:bb:66:00",
    "ips" : [ "10.1.1.3" ],
    "dhcp" : false,
    "lan" : 2,
    "firewallActive" : false
  },
  "entities" : {
     "firewallrules" : {
      "id" : "{nicId}/firewallrules",
      "type" : "collection",
      "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules"
    }
  }
}

Response Attributes

The following table describes the attributes found in the response body:

Name Type Description
id string The NIC's unique identifier.
type string The type of object. "nic"
href string An API URL to the NIC’s representation (absolute path).
metadata collection NIC metadata.
properties collection NIC properties.
entities collection Entities associated with the NIC. "firewallrules"

The metadata about the NIC includes:

Name Type Description
createdDate string The date the resource was created.
createdBy string The user who created the resource.
createdByUserId string The userId who created the resource.
etag string The ETag.
lastModifiedDate string The last modified time for the resource.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
state string AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued. INACTIVE The resource has been de-provisioned.

The properties returned are:

Name Type Description
name string The name of the NIC.
mac string The MAC address of the NIC.
ips collection IPs assigned to the NIC represented as a collection.
dhcp Boolean Boolean value that indicates if the NIC is using DHCP (true) or not (false).
lan int32 The LAN ID the NIC sits on.
nat Boolean Boolean value indicating if the private IP address has outbound access to the public internet enabled (true) or not (false).
firewallActive Boolean A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.

The entities returned include:

Name Type Description
firewallrules collection A collection of firewall rules associated with the NIC.

PUT

Use PUT to perform an update of the attributes of a NIC. Unlike using PATCH above, you must supply a value for lan even if it is not being changed.

Request

To perform an update of the NIC's properties, send a PUT request to: https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.
{serverId} yes string n/a The ID of a server.
{nicId} yes string n/a The ID of a server.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Body

Name Required Type Description
name no string The name of the NIC.
ips no string collection IPs assigned to the NIC represented as a collection.
dhcp no Boolean Boolean value that indicates if the NIC is using DHCP or not.
lan yes int32 The LAN ID the NIC sits on.
nat no Boolean Indicates if the private IP address has outbound access to the public internet.
firewallActive no Boolean A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.

Curl Example

The following shows how to submit the PUT request using curl:

curl --include \
     --request PUT \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '    {
         "properties": {
             "name": "Failover NIC",
             "ips": ["10.1.1.4"],
             "dhcp": false,
             "lan": 2
         }
         } ' \
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.ionos.com/cloudapi/v5/requests/{requestId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{nicId}",
  "type" : "nic",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "createdByUserId" : "[userId]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "lastModifiedByUserId" : "[userId]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "Failover NIC",
    "mac" : "02:01:f8:bb:66:00",
    "ips" : [ "10.1.1.4" ],
    "dhcp" : false,
    "lan" : 2,
    "firewallActive" : false
  },
  "entities" : {
     "firewallrules" : {
      "id" : "{nicId}/firewallrules",
      "type" : "collection",
      "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules"
    }
  }
}

Response Attributes

The following table describes the attributes found in the JSON response body:

Name Type Description
id string The NIC's unique identifier.
type string The type of object. "nic"
href string An API URL to the NIC’s representation (absolute path).
metadata collection NIC metadata.
properties collection NIC properties.
entities collection Entities associated with the NIC. "firewallrules"

The metadata about the NIC includes:

Name Type Description
createdDate string The date the resource was created.
createdBy string The user who created the resource.
createdByUserId string The userId who created the resource.
etag string The ETag.
lastModifiedDate string The last modified time for the resource.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
state string AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued. INACTIVE The resource has been de-provisioned.

The properties returned are:

Name Type Description
name string The name of the NIC.
mac string The MAC address of the NIC.
ips collection IPs assigned to the NIC represented as a collection.
dhcp Boolean Boolean value that indicates if the NIC is using DHCP (true) or not (false).
lan int32 The LAN ID the NIC sits on.
nat Boolean Boolean value indicating if the private IP address has outbound access to the public internet enabled (true) or not (false).
firewallActive Boolean A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.

The entities returned include:

Name Type Description
firewallrules collection A collection of firewall rules associated with the NIC.

Delete a NIC

Deletes the specified NIC.

Request

To delete a NIC, send a DELETE request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.
{serverId} yes string n/a The ID of a server.
{nicId} yes string n/a The ID of a NIC.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Curl Example

The following shows you how to submit the DELETE request using curl:

curl --include \
     --request DELETE \
     --user 'username@domain.tld:password' \
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.ionos.com/cloudapi/v5/requests/{requestId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Length: 0
Strict-Transport-Security: max-age=15768000

There is no JSON response body returned for a successful DELETE request.

Firewall Rules

Create Firewall Rule

This will add a new firewall rule to the specified NIC. All firewall rules must be associated with a NIC.

Request

To create a new firewall rule you would send a POST request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/[server-id}/nics/{nicId}/firewallrules

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of the VDC.
{serverId} yes string n/a The ID of a server.
{nicId} yes string n/a The ID of a NIC.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Body

The format of the request body is as follows:

{
    "properties": {
        "name": "my-firewall-rule-name",
        "protocol": "my-protocol",
        "sourceMac": "source-mac",
        "sourceIp": "source-ip",
        "targetIp": "target-ip",
        "portRangeStart": "port-range-start",
        "portRangeEnd": "port-range-end",
        "icmpType": "icmp-type",
        "icmpCode": "icmp-code"
    }
}

Request Parameters - Body

Name Required Type Description
name no string A name for the firewall rule.
protocol yes string The protocol for the rule: TCP, UDP, ICMP, ANY.
sourceMac no string Only traffic originating from the respective MAC address is allowed. Valid format: aa:bb:cc:dd:ee:ff. A null value allows all source MAC addresses.
sourceIp no string Only traffic originating from the respective IPv4 address is allowed. A null value allows all source IPs.
targetIp no string In case the target NIC has multiple IP addresses, only traffic directed to the respective IP address of the NIC is allowed. Value null allows all target IPs.
icmpCode no int32 Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value null allows all codes.
icmpType no int32 Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value null allows all types.
portRangeStart no int32 Defines the start range of the allowed port (from 1 to 65534) if protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports.
portRangeEnd no int32 Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports.

Curl Example

The following shows how to submit the POST request using curl:

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '    {
        "properties": {
            "name": "AllowHTTP",
            "protocol": "TCP",
            "portRangeStart": "80",
            "portRangeEnd": "80"
        }
    }' \
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.ionos.com/cloudapi/v5/requests/{requestStatusId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{firewallRuleId}",
  "type" : "firewall-rule",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "createdByUserId" : "[userId]",
},
  "properties" : {
    "name" : "AllowHTTP",
    "protocol" : "TCP",
    "sourceMac" : null,
    "sourceIp" : null,
    "targetIp" : null,
    "icmpCode" : null,
    "icmpType" : null,
    "portRangeStart" : 80,
    "portRangeEnd" : 80
  }
}

These attributes are found in the JSON response body:

Name Type Description
id string The resource's unique identifier.
type string The type of object that has been created. Should be "firewall-rule".
href string URL to the firewall rule.
metadata collection Firewall rule metadata.
properties collection Firewall rule properties.

The metadata returned for each firewall rule:

Name Type Description
createdDate string The date the firewall rule was created.
createdBy string The user who created the firewall rule.
createdByUserId string The userId who created the resource.
etag string The ETag for the resource.
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
state string The firewall rule state. AVAILABLE, BUSY, INACTIVE

The properties returned for the firewall rule:

Name Type Description
name string The name of the firewall rule.
protocol string The protocol for the rule: TCP, UDP, ICMP, ANY.
sourceMac string Only traffic originating from the respective MAC address is allowed. Valid format: aa:bb:cc:dd:ee:ff. Value "null" allows all source MAC address.
sourceIp string Only traffic originating from the respective IPv4 address is allowed. Value "null" allows all source IPs.
targetIp string In case the target NIC has multiple IP addresses, only traffic directed to the respective IP address of the NIC is allowed. Value "null" allows all target IPs.
icmpType int32 Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value "null" allows all types.
icmpCode int32 Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value "null" allows all codes.
portRangeStart int32 Defines the start range of the allowed port (from 1 to 65534) if protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports.
portRangeEnd int32 Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports.

Read Firewall Rule

Retrieves the attributes of a specific firewall rule.

Request

To retrieve a specific firewall rule send a GET request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of the VDC.
{serverId} yes string n/a The ID of a server.
{nicId} yes string n/a The ID of a NIC.
{firewallRuleId} yes string n/a The ID of a firewall rule.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}?depth=1

Note: For this particular operation, increasing the value supplied to depth does NOT return any additional information beyond the default amount returned with a value of 0.

Curl Example

The following shows how to submit the GET request using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}

Response

HTTP/1.1 200 OK
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
X-RateLimit-Remaining: 299
X-RateLimit-Burst: 300
X-RateLimit-Limit: 600
ETag: [etag]
Content-Type: application/json
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{firewallRuleId}",
  "type" : "firewall-rule",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "createdByUserId" : "[userId]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "lastModifiedByUserId" : "[userId]",
    "state" : "AVAILABLE"
  },
  "properties" : {
    "name" : "AllowSSH",
    "protocol" : "TCP",
    "sourceMac" : null,
    "sourceIp" : null,
    "targetIp" : null,
    "icmpCode" : null,
    "icmpType" : null,
    "portRangeStart" : 22,
    "portRangeEnd" : 22
  }
}

These attributes are found in the JSON response body:

Name Type Description
id string The resource's unique identifier.
type string The type of object that has been created. Should be "firewall-rule".
href string URL to the firewall rule.
metadata collection Firewall rule metadata.
properties collection Firewall rule properties.

The metadata returned for each firewall rule:

Name Type Description
createdDate string The date the firewall rule was created.
createdBy string The user who created the firewall rule.
createdByUserId string The userId who created the resource.
etag string The ETag for the resource.
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
state string The firewall rule state. AVAILABLE, BUSY, INACTIVE

The properties returned for the firewall rule:

Name Type Description
name string The name of the firewall rule.
protocol string The protocol for the rule: TCP, UDP, ICMP, ANY.
sourceMac string Only traffic originating from the respective MAC address is allowed. Valid format: aa:bb:cc:dd:ee:ff. Value "null" allows all source MAC address.
sourceIp string Only traffic originating from the respective IPv4 address is allowed. Value "null" allows all source IPs.
targetIp string In case the target NIC has multiple IP addresses, only traffic directed to the respective IP address of the NIC is allowed. Value "null" allows all target IPs.
icmpType int32 Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value "null" allows all types.
icmpCode int32 Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value "null" allows all codes.
portRangeStart int32 Defines the start range of the allowed port (from 1 to 65534) if protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports.
portRangeEnd int32 Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports.

List Firewall Rules

Retrieves a list of firewall rules associated with a particular NIC.

Request

To retrieve a list of firewall rules submit a GET request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules.

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of the VDC.
{serverId} yes string n/a The ID of a server.
{nicId} yes string n/a The ID of a NIC.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information beyond the default amount returned with a value of 0.

You can filter the result set using custom filters.

An example of using the custom filter to find all firewall rules where a particular sourceIp is specified:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules?filter.sourceIp=123.123.123.123

You can also filter on metadata such as createdBy. This example limits the results to firewall rules created by a specific user and also adds the depth parameter so additional info about each matching firewall rule is returned:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules?filter.createdBy=joe&depth=1

Curl Example

The following shows you how to submit the GET using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules

Response

HTTP/1.1 200 OK
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
X-RateLimit-Remaining: 299
X-RateLimit-Burst: 300
X-RateLimit-Limit: 600
ETag: [etag]
Content-Type: application/json
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{nicId}/firewallrules",
  "type" : "collection",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules",
  "items" : [ {
    "id" : "{firewallRuleId}",
    "type" : "firewall-rule",
    "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}"
  }, {
    "id" : "[another-firewall-rule-id]",
    "type" : "firewall-rule",
    "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/[another-firewall-rule-id]"
  } ]
}

Response Parameters

The request will return a collection of firewall rules assigned to the NIC.

The following table describes the attributes found in the response body:

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).

Update Firewall Rule

The Cloud API implements both PUT and PATCH for updates.

PATCH

Use PATCH to perform updates to the attributes of a firewall rule.

Request

To perform an update to the firewall rule properties send a PATCH request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of the virtual data center.
{serverId} yes string n/a The ID of a server.
{nicId} yes string n/a The ID of a NIC.
{firewallRuleId} yes string n/a The ID of a firewall rule.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Body

The format of the request body is as follows:

{
    "properties": {
        "name": "my-firewall-rule-name",
        "protocol": "my-protocol",
        "sourceMac": "source-mac",
        "sourceIp": "source-ip",
        "targetIp": "target-ip",
        "portRangeStart": "port-range-start",
        "portRangeEnd": "port-range-end",
        "icmpType": "icmp-type",
        "icmpCode": "icmp-code"
    }
}

Request Parameters - Body

Name Required Type Description
name no string A name for the firewall rule.
protocol -- string You cannot update the protocol of an existing firewall rule. If you need to change this, then delete and create a new firewall rule to replace the existing one.
sourceMac no string Only traffic originating from the respective MAC address is allowed. Valid format: aa:bb:cc:dd:ee:ff. A null value allows all source MAC addresses.
sourceIp no string Only traffic originating from the respective IPv4 address is allowed. A null value allows all source IPs.
targetIp no string In case the target NIC has multiple IP addresses, only traffic directed to the respective IP address of the NIC is allowed. Value null allows all target IPs.
icmpCode no int32 Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value null allows all codes.
icmpType no int32 Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value null allows all types.
portRangeStart no int32 Defines the start range of the allowed port (from 1 to 65534) if protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports.
portRangeEnd no int32 Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports.
Curl Example

The following shows you how to submit the PATCH request using curl:

curl --include \
     --request PATCH \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '{
        "sourceMac": "01:98:22:22:44:22",
        "targetIp": "123.100.101.102"
    }' \
'https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}'

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.ionos.com/cloudapi/v5/requests/{requestStatusId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{firewallRuleId}",
  "type" : "firewall-rule",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "createdByUserId" : "[userId]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "lastModifiedByUserId" : "[userId]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "AllowSSH",
    "protocol" : "TCP",
    "sourceMac" : "01:98:22:22:44:22",
    "sourceIp" : null,
    "targetIp" : "123.100.101.102",
    "icmpCode" : null,
    "icmpType" : null,
    "portRangeStart" : 22,
    "portRangeEnd" : 22
  }
}

These attributes are found in the JSON response body:

Name Type Description
id string The resource's unique identifier.
type string The type of object that has been created. Should be "firewall-rule".
href string URL to the firewall rule.
metadata collection Firewall rule metadata.
properties collection Firewall rule properties.

The metadata returned for each firewall rule:

Name Type Description
createdDate string The date the firewall rule was created.
createdBy string The user who created the firewall rule.
createdByUserId string The userId who created the resource.
etag string The ETag for the resource.
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
state string The firewall rule state. AVAILABLE, BUSY, INACTIVE

The properties returned for the firewall rule:

Name Type Description
name string The name of the firewall rule.
protocol string The protocol for the rule: TCP, UDP, ICMP, ANY.
sourceMac string Only traffic originating from the respective MAC address is allowed. Valid format: aa:bb:cc:dd:ee:ff. Value "null" allows all source MAC address.
sourceIp string Only traffic originating from the respective IPv4 address is allowed. Value "null" allows all source IPs.
targetIp string In case the target NIC has multiple IP addresses, only traffic directed to the respective IP address of the NIC is allowed. Value "null" allows all target IPs.
icmpType int32 Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value "null" allows all types.
icmpCode int32 Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value "null" allows all codes.
portRangeStart int32 Defines the start range of the allowed port (from 1 to 65534) if protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports.
portRangeEnd int32 Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports.

PUT

Use PUT to perform an update to the attributes of a firewall rule.

Request

To perform an update of the firewall rule's properties send a PUT request to: https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of the virtual data center.
{serverId} yes string n/a The ID of a server.
{nicId} yes string n/a The ID of a NIC.
{firewallRuleId} yes string n/a The ID of a firewall rule.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Body

The format of the request body is as follows:

{
    "properties": {
        "name": "my-firewall-rule-name",
        "protocol": "my-protocol",
        "sourceMac": "source-mac",
        "sourceIp": "source-ip",
        "targetIp": "target-ip",
        "portRangeStart": "port-range-start",
        "portRangeEnd": "port-range-end",
        "icmpType": "icmp-type",
        "icmpCode": "icmp-code"
    }
}

Request Parameters - Body

Name Required Type Description
name no string A name for the firewall rule.
protocol -- string You cannot update the protocol of an existing firewall rule. If you need to change this, then delete and create a new firewall rule to replace the existing one.
sourceMac no string Only traffic originating from the respective MAC address is allowed. Valid format: aa:bb:cc:dd:ee:ff. A null value allows all source MAC addresses.
sourceIp no string Only traffic originating from the respective IPv4 address is allowed. A null value allows all source IPs.
targetIp no string In case the target NIC has multiple IP addresses, only traffic directed to the respective IP address of the NIC is allowed. Value null allows all target IPs.
icmpCode no int32 Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value null allows all codes.
icmpType no int32 Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value null allows all types.
portRangeStart no int32 Defines the start range of the allowed port (from 1 to 65534) if protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports.
portRangeEnd no int32 Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports.
Curl Example

The following shows you how to submit the PUT request using curl:

curl --include \
     --request PUT \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '    {
        "properties": {
            "name": "SSH Port Plus One",
            "sourceMac": "01:23:45:67:89:00",
            "sourceIp": "1.2.3.4",
            "targetIp": "5.6.7.8",
            "portRangeStart": 22,
            "portRangeEnd": 23,
            "icmpType": null,
            "icmpCode": null
        }
    }' \
'https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}'

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.ionos.com/cloudapi/v5/requests/{requestStatusId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{firewallRuleId}",
  "type" : "firewall-rule",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "createdByUserId" : "[userId]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "lastModifiedByUserId" : "[userId]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "SSH Port Plus One",
    "protocol" : "TCP",
    "sourceMac" : "01:23:45:67:89:00",
    "sourceIp" : "1.2.3.4",
    "targetIp" : "5.6.7.8",
    "icmpCode" : null,
    "icmpType" : null,
    "portRangeStart" : 22,
    "portRangeEnd" : 23
  }
}

These attributes are found in the JSON response body:

Name Type Description
id string The resource's unique identifier.
type string The type of object that has been created. Should be "firewall-rule".
href string URL to the firewall rule.
metadata collection Firewall rule metadata.
properties collection Firewall rule properties.

The metadata returned for each volume:

Name Type Description
createdDate string The date the firewall rule was created.
createdBy string The user who created the firewall rule.
createdByUserId string The userId who created the resource.
etag string The ETag for the resource.
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
state string The firewall rule state. AVAILABLE, BUSY, INACTIVE

The properties returned for the firewall rule:

Name Type Description
name string The name of the firewall rule.
protocol string The protocol for the rule: TCP, UDP, ICMP, ANY.
sourceMac string Only traffic originating from the respective MAC address is allowed. Valid format: aa:bb:cc:dd:ee:ff. Value "null" allows all source MAC address.
sourceIp string Only traffic originating from the respective IPv4 address is allowed. Value "null" allows all source IPs.
targetIp string In case the target NIC has multiple IP addresses, only traffic directed to the respective IP address of the NIC is allowed. Value "null" allows all target IPs.
icmpType int32 Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value "null" allows all types.
icmpCode int32 Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value "null" allows all codes.
portRangeStart int32 Defines the start range of the allowed port (from 1 to 65534) if protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports.
portRangeEnd int32 Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports.

Delete Firewall Rule

Removes the specific firewall rule.

Request

To delete a firewall rule send a DELETE request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of the VDC.
{serverId} yes string n/a The ID of a server.
{nicId} yes string n/a The ID of a NIC.
{firewallRuleId} yes string n/a The ID of a firewall rule.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Curl Example

The following shows how to submit the DELETE request using curl:

curl --include \
     --request DELETE \
     --user 'username@domain.tld:password' \
     https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.ionos.com/cloudapi/v5/requests/{requestStatusId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Length: 0
Strict-Transport-Security: max-age=15768000

There is no JSON response body returned for a successful DELETE request.

Load Balancers

Create Load Balancer

Creates a load balancer within the VDC. Load balancers can be used for public or private IP traffic.

Request

To create a load balancer send a POST request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Body

The format of the request body is as follows:

{
    "properties": {
        "name": "load-balancer-name",
        "ip": "load-balancer-ip",
        "dhcp": true
    },
      "entities": {
          "balancednics": []
    }
}

Request Parameters - Body

Name Required Type Description
name yes string The name of the load balancer.
ip no string IPv4 address of the load balancer. All attached NICs will inherit this IP.
dhcp no Boolean Indicates if the load balancer will reserve an IP using DHCP.
balancednics no string collection List of NICs taking part in load-balancing. All balanced NICs inherit the IP of the load balancer.

Curl Example

The following shows how to submit the POST request using curl:

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '    {
        "properties": {
            "name": "[load-balancer-name]",
            "dhcp": false
    }' \
     https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.ionos.com/cloudapi/v5/requests/{requestStatusId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{loadBalancerId}",
  "type" : "loadbalancer",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "createdByUserId" : "[userId]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "lastModifiedByUserId" : "[userId]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "ExampleLoadBalancer01",
    "ip" : null,
    "dhcp" : false
  }
}

Response Attributes

The following table describes the attributes found in the JSON response body:

Name Type Description
id string The unique identifier.
type string The type of object that has been created.
href string URL to the object’s representation (absolute path).
metadata collection Various details about the load balancer.
properties collection Properties of the load balancer.
entities collection NICs that are part of the load balancer.

The metadata returned for a load balancer is shown in this table:

Name Type Description
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
createdDate string The date the resource was created.
createdBy string The user who created the resource.
createdByUserId string The userId who created the resource.
state string The load balancer state.
etag string The ETag for the resource.

The properties returned for a load balancer are outlined in this table:

Name Type Description
name string A descriptive name for the load balancer.
ip string The IP address assigned to the load balancer.
dhcp Boolean Indicates if the load balancer is using DHCP to have an IP address assigned.

The entities returned for a load balancer are described in this table:

Name Type Description
balancednics collection A collection of NICs associated with the load balancer.

Read Load Balancer

Retrieves the attributes of a given load balancer.

Request

To retrieve details about a specific load balancer send a GET request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.
{loadBalancerId} yes string n/a The ID of a load balancer.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information beyond the default amount returned with a value of 0.

Curl Example

The following shows how to submit the GET request using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}

Response

HTTP/1.1 200 OK
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
X-RateLimit-Remaining: 299
X-RateLimit-Burst: 300
X-RateLimit-Limit: 600
ETag: [etag]
Content-Type: application/json
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{loadBalancerId}",
  "type" : "loadbalancer",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "createdByUserId" : "[userId]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "lastModifiedByUserId" : "[userId]",
    "state" : "INACTIVE"
  },
  "properties" : {
    "name" : "ExampleLoadBalancer01",
    "ip" : null,
    "dhcp" : false
  },
  "entities" : {
    "balancednics" : {
      "id" : "{loadBalancerId}/balancednics",
      "type" : "collection",
      "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}/balancednics"
    }
  }
}

Response Attributes

Name Type Description
id string The unique identifier.
type string The type of object that has been created.
href string URL to the object’s representation (absolute path).
metadata collection Various details about the LAN.
properties collection Properties of the LAN.
entities collection NICs that are part of the LAN.

The metadata returned for a load balancer is shown in this table:

Name Type Description
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
createdDate string The date the resource was created.
createdBy string The user who created the resource.
createdByUserId string The userId who created the resource.
state string The load balancer state.
etag string The ETag for the resource.

The properties returned for a load balancer are outlined in this table:

Name Type Description
name string A descriptive name for the load balancer.
ip string The IP address assigned to the load balancer.
dhcp Boolean Indicates if the load balancer is using DHCP to have an IP address assigned.

The entities returned for a load balancer are described in this table:

Name Type Description
balancednics collection A collection of NICs associated with the LAN.

At the default depth=0, each entity in balancednics has the following attributes returned:

Name Type Description
id string The NIC ID with "/nics" appended.
type string The type of object, in this case "collection".
href string A URL to access details about the NICs that are part of the LAN.

Increasing to depth=1 will return an additional items collection with each individual NIC that is part of balancednics listed.

Increasing to depth=2 will return even more details about each NIC that is part of nics. With depth=3 you'll get basic information about any firewall rules that are assigned to the NIC. At depth=4 you'll get detailed information about each firewall rule that is assigned to the NIC. Please take a look at the Network Interfaces section of this documentation for additional information.

List Load Balancers

Retrieve a list of load balancers within the virtual data center.

Request

To retrieve a list of load balancers, submit a GET request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information beyond the default amount returned with a value of 0.

You can filter the result set using custom filters.

An example of using the custom filter to find all load balancers where dhcp is "true":

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers?filter.dhcp=true&depth=1

You can also filter on metadata such as createdBy. This example limits the results to load balancers created by a specific user:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers?filter.createdBy=joe&depth=1

Curl Example

The following shows how to submit the GET request using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers

Response

HTTP/1.1 200 OK
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
X-RateLimit-Remaining: 299
X-RateLimit-Burst: 300
X-RateLimit-Limit: 600
ETag: [etag]
Content-Type: application/json
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{dataCenterId}/loadbalancers",
  "type" : "collection",
  "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers",
  "items" : [ {
    "id" : "{loadBalancerId}",
    "type" : "loadbalancer",
    "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}"
  } ]
}

Response Attributes

The request will return a collection of load balancers.

The following table describes the attributes found in the JSON response:

Name Type Description
id string The resource's unique identifier.
type string The type of object. In this case "collection".
href string URL to the object’s representation (absolute path).
items collection A collection of available load balancers.

Each of the returned items has these attributes:

Name Type Description
id string The load balancer's ID.
type string The type of object. In this case "loadbalancer".
href string URL to the object’s representation (absolute path).

If you append the ?depth=1 query parameter to the end of the request then more details are returned for each individual load balancer that is part of items. The additional details include metadata, properties, and entities. This is similar to issuing a GET request to each load balancer independently. Please see the next section for additional information.

Update Load Balancer

The Cloud API implements both PUT and PATCH for updates.

You can update -- in full or partially -- various attributes on the load balancer using the above methods.

PATCH

Use PATCH to perform an update to the attributes of a load balancer.

Request

To perform an update to the load balancer's properties you would send a PATCH request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.
{loadBalancerId} yes string n/a The ID of a load balancer.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Body

Name Required Type Description
name no string The name of the load balancer.
ip no string The IP of the load balancer.
dhcp no Boolean Indicates if the load balancer will reserve an IP using DHCP.

Curl Example

The following shows how to submit the PATCH request using curl:

curl --include \
     --request PATCH \
     --header "Content-Type: application/json" \
     --data-binary '{
         "ip": "[ip]"
        }' \
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}

Response Body

Status: 202 (Accepted)
Headers: [
    "Date: [date]",
    "Content-Type: application/json",
    "Location: URL of a request resource which should be used for the operation's polling status",
    "Connection: keep-alive",
    "Content-Length: 426"
    ]
    ResponseBody: {
      "id": "loadbalancer-id",
      "type": "loadbalancer",
      "href": "[base-url]/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}",
      "metadata": {
          "lastModifiedDate": "last-modified-date",
          "lastModifiedBy": "last-modified-by-user",
          "createdDate": "created-date",
          "createdBy": "created-by-user",
          "state": "load-balancer-state",
          "etag": "etag"
          },
      "properties": {
          "name": "loadbalancer-name",
          "ip": "loadbalancer-ip",
          "dhcp": "loadbalancer-dhcp"
          },
      "entities": {
          "balancednics": []
      }
  }

The following table describes the attributes found in the JSON response body:

Name Type Description
id string The unique identifier.
type string The type of object that has been created.
href string URL to the object’s representation (absolute path).
metadata collection Various details about the load balancer.
properties collection Properties of the load balancer.
entities collection NICs that are part of the load balancer.

The metadata returned for a load balancer is shown in this table:

Name Type Description
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
createdDate string The date the resource was created.
createdBy string The user who created the resource.
createdByUserId string The userId who created the resource.
state string The load balancer state.
etag string The ETag for the resource.

The properties returned for a load balancer are outlined in this table:

Name Type Description
name string A descriptive name for the load balancer.
ip string The IP address assigned to the load balancer.
dhcp Boolean Indicates if the load balancer is using DHCP to have an IP address assigned.

The entities returned for a load balancer are described in this table:

Name Type Description
balancednics collection A collection of NICs associated with the load balancer.

PUT

Use PUT to perform an update of the attributes of a load balancer.

Request

To perform an update of the load balancer's properties send a PUT request to: https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.
{loadBalancerId} yes string n/a The ID of a load balancer.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Body

Name Required Type Description
name no string The name of the load balancer.
ip no string The IP of the load balancer.
dhcp no Boolean Indicates if the load balancer will reserve an IP using DHCP.

Curl Example

The following shows how to submit the PUT request using curl:

curl --include \
     --request PUT \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '{
         "properties": {
             "name": "[load-balancer-name]",
             "ip": "[load-balancer-ip]",
             "dhcp": [load-balancer-dhcp]
         }
     }    ' \
 https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/[loadbalancer_id]

Response

Status: 202 (Accepted)
Headers: [
    "Date: [date]",
    "Content-Type: application/json",
    "Location: URL of a request resource which should be used for the operation's polling status",
    "Connection: keep-alive",
    "Content-Length: 426"
    ]
ResponseBody: {
      "id": "loadbalancer-id",
      "type": "loadbalancer",
      "href": "[base-url]/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}",
      "metadata": {
          "lastModifiedDate": "last-modified-date",
          "lastModifiedBy": "last-modified-by-user",
          "createdDate": "created-date",
          "createdBy": "created-by-user",
          "state": "loadbalancer-state",
          "etag": "etag"
          },
      "properties": {
          "name": "loadbalancer-name",
          "ip": "loadbalancer-ip",
          "dhcp": "loadbalancer-dhcp"
          },
      "entities": {
          "balancednics": []
        }
    }

Response Attributes

The following table describes the attributes found in the JSON response body:

Name Type Description
id string The unique identifier.
type string The type of object that has been created.
href string URL to the object’s representation (absolute path).
metadata collection Various details about the LAN.
properties collection Properties of the LAN.
entities collection NICs that are part of the LAN.

The metadata returned for a load balancer is shown in this table:

Name Type Description
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
createdDate string The date the resource was created.
createdBy string The user who created the resource.
createdByUserId string The userId who created the resource.
state string The load balancer state.
etag string The ETag for the resource.

The properties returned for a load balancer are outlined in this table:

Name Type Description
name string A descriptive name for the load balancer.
ip string The IP address assigned to the load balancer.
dhcp Boolean Indicates if the load balancer is using DHCP to have an IP address assigned.

The entities returned for a load balancer are described in this table:

Name Type Description
balancednics collection A collection of NICs associated with the load balancer.

Delete Load Balancer

Deletes the specified load balancer.

Request

To delete a load balancer send a DELETE request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.
{loadBalancerId} yes string n/a The ID of a load balancer.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Curl Example

The following shows how to submit the DELETE request using curl:

curl --include \
     --request DELETE \
     --user 'username@domain.tld:password' \
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}

Response

Status: 202 (Accepted)
Headers: [
    "Location: URL of a request resource which should be used for the operation's polling status",
    "Date: [date]",
    "Content-Length: 0",
    "Connection: keep-alive"
    ]
ResponseBody: ""

There is no JSON response body returned with a successful DELETE request.

List Load Balanced NICs

This will retrieve a list of NICs associated with the load balancer.

Request

To retrieve a list of load balanced NICs submit a GET request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}/balancednics

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.
{loadBalancerId} yes string n/a The ID of a load balancer.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}/balancednics?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}/balancednics?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information beyond the default amount returned with a value of 0.

Curl Example

The following shows how to submit the GET request using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}/balancednics

Response

{
    "id": "{loadBalancerId}/balancednics",
    "type": "collection",
    "href": "[base-url]/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}/balancednics",
    "items": [
    {
        "id": "[nic-id]",
        "type": "nic",
        "href": "/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}",
        "metadata": {
            "lastModifiedDate": "last-modified-date",
            "lastModifiedBy": "last-modified-by",
            "createdDate": "created-date",
            "createdBy": "created-by",
            "state": "state",
            "etag": "etag"
            },
        "properties": {
            "name": "my-nic-name",
            "mac": "nic-mac",
            "nic-ip"
            ],
            "dhcp": "true",
            "lan": lan-id,
            "firewallActive": is-firewall-active
            },
        "entities": {
            "firewallrules": {
                "id": "{nic_id}/firewallrules",
                "type": "collection",
                "href": "/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules"
            }
      }
  }
  ]

}

Response Attributes

The request will return a collection of load balanced NICs.

The following table describes the attributes found in the response body:

Name Type Description
id string {serverId}/nics
type string The type of object that has been created. "collection"
href string URL to the object’s representation (absolute path).
items collection A collection of NICs.

The items will have the following attributes.

Name Type Description
id string The NIC's unique identifier.
type string The type of object. "nic"
href string An API URL to the NIC’s representation (absolute path).

If you appended ?depth=1 to the request to have more details returned, you will also get metadata, properties, and entities returned for each NIC in items.

The metadata about the NIC includes:

Name Type Description
createdDate string The date the resource was created.
createdBy string The user who created the resource.
createdByUserId string The userId who created the resource.
etag string The ETag.
lastModifiedDate string The last modified time for the resource.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
state string AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued. INACTIVE The resource has been de-provisioned.

The properties returned are:

Name Type Description
name string The name of the NIC.
mac string The MAC address of the NIC.
ips collection IPs assigned to the NIC represented as a collection.
dhcp Boolean Boolean value that indicates if the NIC is using DHCP (true) or not (false).
lan int32 The LAN ID the NIC sits on.
nat Boolean Boolean value indicating if the private IP address has outbound access to the public internet enabled (true) or not (false).
firewallActive Boolean A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.

The entities returned include:

Name Type Description
firewallrules collection A collection of firewall rules associated with the NIC.

Get Load Balanced NIC

Retrieves the attributes of a given load balanced NIC.

Request

To retrieve a single load balanced NIC you would send a GET request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}/balancednics/{nicId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.
{loadBalancerId} yes string n/a The ID of a load balancer.
{nicId} yes string n/a The ID of a NIC.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}/balancednics/{nicId}?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}/balancednics/{nicId}?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information beyond the default amount returned with a value of 0.

Curl Example

The following shows you how to submit the GET request using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
https://api.ionos.com/cloudapi/v5/datacenters/data-center-id]/loadbalancers/{loadBalancerId}/balancednics/{nicId}

Response

{
    "id": "[nic-id]",
    "type": "nic",
    "href": "/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}",
    "metadata": {
        "lastModifiedDate": "last-modified-date",
        "lastModifiedBy": "last-modified-by-user",
        "createdDate": "created-date",
        "createdBy": "created-by-user",
        "state": "nic-state",
        "etag": "etag"
    },
    "properties": {
        "name": "nic-name",
        "mac": "nic-mac",
        "ips": nic-ip-collection,
        "dhcp": "nic-dhcp-bool",
        "lan": nic-lan,
        "firewallActive": firewall-active-status
    },
    "entities": {
        "firewallrules": []
    }
}

Response Attributes

The following table describes the attributes found in the JSON response body:

Name Type Description
id string The NIC's unique identifier.
type string The type of object. "nic"
href string An API URL to the NIC’s representation (absolute path).
metadata collection NIC metadata.
properties collection NIC properties.
entities collection NIC entities. "firewallrules"

The metadata about the NIC includes:

Name Type Description
createdDate string The date the resource was created.
createdBy string The user who created the resource.
createdByUserId string The userId who created the resource.
etag string The ETag.
lastModifiedDate string The last modified time for the resource.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
state string AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued. INACTIVE The resource has been de-provisioned.

The properties returned are:

Name Type Description
name string The name of the NIC.
mac string The MAC address of the NIC.
ips collection IPs assigned to the NIC represented as a collection.
dhcp Boolean Boolean value that indicates if the NIC is using DHCP (true) or not (false).
lan int32 The LAN ID the NIC sits on.
nat Boolean Boolean value indicating if the private IP address has outbound access to the public internet enabled (true) or not (false).
firewallActive Boolean A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.

The entities returned include:

Name Type Description
firewallrules collection A collection of firewall rules associated with the NIC.

If you appended ?depth=1 to the request to retrieve more details, you will get additional information about the firewallrules.

Associate NIC to Load Balancer

This will associate a NIC to a Load Balancer, enabling the NIC to participate in load-balancing.

Request

To associate a NIC with a load balancer you would send a POST request to `https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}/balancednics``

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.
{loadBalancerId} yes string n/a The ID of a load balancer.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Body

Name Required Type Description
id yes string The UUID of the NIC.

The format of the request body is as follows:

{
    id": "{nicId}"
}

Curl Example

The following shows how to submit the POST request using curl:

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary "{
        \"id\": \"[nic-id]\"
        }" \
'https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}/balancednics'

Response

{
    "id": "[nic-id]",
    "type": "nic",
    "href": "/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}",
    "metadata": {
        "lastModifiedDate": "last-modified-date",
        "lastModifiedBy": "last-modified-by-user",
        "createdDate": "created-date",
        "createdBy": "created-by-user",
        "state": "nic-state",
        "etag": "etag"
    },
    "properties": {
        "name": "nic-name",
        "mac": "nic-mac",
        "ips": [nic-ip-collection],
        "dhcp": "nic-dhcp-bool",
        "lan": nic-lan,
        "firewallActive": true
    },
    "entities": {
        "firewallrules": []
    }
}

Response Attributes

The following table describes the attributes found in the response body:

Name Type Description
id string The NIC's unique identifier.
type string The type of object. "nic"
href string An API URL to the NIC’s representation (absolute path).
metadata collection NIC metadata.
properties collection NIC properties.
entities collection NIC entities. "firewallrules"

The metadata about the NIC includes:

Name Type Description
createdDate string The date the resource was created.
createdBy string The user who created the resource.
createdByUserId string The userId who created the resource.
etag string The ETag.
lastModifiedDate string The last modified time for the resource.
lastModifiedBy string The user who last modified the resource.
lastModifiedByUserId string The userId who last modified the resource.
state string AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued. INACTIVE The resource has been de-provisioned.

The properties returned are:

Name Type Description
name string The name of the NIC.
mac string The MAC address of the NIC.
ips collection IPs assigned to the NIC represented as a collection.
dhcp Boolean Boolean value that indicates if the NIC is using DHCP (true) or not (false).
lan int32 The LAN ID the NIC sits on.
nat Boolean Boolean value indicating if the private IP address has outbound access to the public internet enabled (true) or not (false).
firewallActive Boolean A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.

The entities returned include:

Name Type Description
firewallrules collection A collection of firewall rules associated with the NIC.

Remove a NIC Association

Removes the association of a NIC with a load balancer.

Request

To remove a NIC association send a DELETE request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId]/balancednics/{nicId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a VDC.
{loadBalancerId} yes string n/a The ID of a load balancer.
{nicId} yes string n/a The ID of a NIC.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Curl Example

The following shows you how to submit the DELETE request using curl:

curl --include \
     --request DELETE \
     --user 'username@domain.tld:password' \
     https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}/balancednics/{nicId}

Response

Status: 202 (Accepted)

There is no JSON response body returned with a successful DELETE request.

Requests

Read Request

Retrieves the attributes of a specific request based on the supplied request id.

Request

To retrieve details on a specific request you would send a GET request to https://api.ionos.com/cloudapi/v5/requests/{requestId}

Request Parameters - Path

Parameter Required Type Default Description
{requestId} yes string n/a The ID of a request.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/requests/{requestId}?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/requests/{requestId}?depth=1

Note: For this particular operation, increasing the value supplied to depth does NOT return any additional information beyond the default amount returned with a value of 0.

Curl Example

The following shows how to submit the GET request using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
https://api.ionos.com/cloudapi/v5/requests/{requestId}

Response

HTTP/1.1 200 OK
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: [date]
X-RateLimit-Remaining: 299
X-RateLimit-Burst: 300
X-RateLimit-Limit: 600
ETag: [etag]
Content-Type: application/json
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{requestId}",
  "type" : "request",
  "href" : "https://api.ionos.com/cloudapi/v5/requests/{requestId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "createdByUserId" : "[userId]",
    "etag" : "[etag]",
    "requestStatus" : {
      "id" : "[reuest-id]/status",
      "type" : "request-status",
      "href" : "https://api.ionos.com/cloudapi/v5/requests/{requestId}/status"
    }
},

The contents of "properties" returned will vary considerably depending on what the original request was. This is an example of what would be returned for a POST request:

  "properties" : {
    "method" : "POST",
    "headers" : {
      "content-type" : "application/json",
      "connection" : "Keep-Alive",
      "host" : "api.ionos.com",
      "x-forwarded-for" : "[ip-address]",
      "content-length" : "81",
      "x-forwarded-host" : "api.ionos.com",
      "user-agent" : "Go 1.1 package http",
      "accept-encoding" : "gzip",
      "x-forwarded-server" : "my.profitbricks.com"
    },
    "body" : "{\"properties\":{\"name\":\"test\",\"description\":\"description\",\"location\":\"{regionId}/{locationId}\"}}",
    "url" : "https://api.ionos.com/cloudapi/v5/datacenters"
  }
}

Response Body

The following table describes the attributes found in the JSON response body:

Name Type Description
id string The ID of the specific request.
type string The type of object, which should be "request" here.
href string URL to the object’s representation (absolute path).
metadata collection A collection of metadata about the request.
properties collection A collection of properties related to the request.

The metadata returned will have the following attributes:

Name Type Description
createdDate string The date the request was created.
createdBy string The username that created the request.
createdByUserId string The userId who created the resource.
etag string The etag.
requestStatus collection Information on the request-status.

The requestStatus collection will contain:

Name Type Description
id string The ID of the specific "request" with "/status" appended.
type string The type of object, which should be "request-status" here.
href string URL to the object’s representation (absolute path). Can be used to retrieve the status of the request.

The properties collection should contain:

Name Type Description
method string The request method. [GET, POST, PATCH, PUT, DELETE]
headers collection The HTTP headers that were submitted with the request.
body string The body that was submitted with the request. Usually JSON, but some API requests are URL encoded.
url string The URL used to make the request.

The headers and body returned in properties will differ considerably depending on the original request.

Once you have determined the type of request based on the returned properties, you can refer to the appropriate section of the Cloud API documentation for details.

List Requests

This operation allows you to retrieve a list of requests. Cloud API calls generate a request which is assigned an id. This "request id" can be used to get information about the request and its current status. The "list request" operation described here will return an array of request items. Each returned request item will have an id that can be used to get additional information as described in the Get Request and Get Request Status sections.

Request

To retrieve a list of requests you would send a GET request to https://api.ionos.com/cloudapi/v5/requests

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.
filter.status string A string (case sensitive) value to fetch all the request based on a particular status value. Valid value is one of the value from QUEUED, RUNNING, DONE or FAILED.
filter.createdAfter string The date time string value is used to filter all the requests after a particular created date/time. Valid format are yyyy-MM-dd or yyyy-MM-dd HH:mm:ss.
filter.createdBefore string The date time string value is used to filter all the requests before a particular created date/time. Valid format are yyyy-MM-dd or yyyy-MM-dd HH::mm:ss.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/requests?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/requests?depth=1

Note: For this particular operation, increasing the value supplied to depth does NOT return any additional information beyond the default amount returned with a value of 0.

You can filter the result set using custom filters.

An example of using the custom filter to find all requests where method is "PUT":

https://api.ionos.com/cloudapi/v5/requests?filter.method=put&depth=1

You can also filter on metadata such as createdDate. This example would find all requests where the method is "DELETE" and createdDate contains "2017-08":

https://api.ionos.com/cloudapi/v5/requests?filter.method=delete&filter.createdDate=2017-08&depth=1

Curl Example

The following shows you how to submit a GET request for /requests via curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.ionos.com/cloudapi/v5/requests

Response

HTTP/1.1 200 OK
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: [date]
X-RateLimit-Remaining: 299
X-RateLimit-Burst: 300
X-RateLimit-Limit: 600
ETag: [etag]
Content-Type: application/json
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "requests",
  "type" : "collection",
  "href" : "https://api.ionos.com/cloudapi/v5/requests",
  "items" : [ {
    "id" : "{requestId}",
    "type" : "request",
    "href" : "https://api.ionos.com/cloudapi/v5/requests/{requestId}"
  } ]
}

Response Body

The request will return a collection of requests.

The following table describes the attributes found in the JSON response body:

Name Type Description
id string "requests"
type string The type of object, which should be "collection" here.
href string URL to the object’s representation (absolute path).
items collection A collection of individual "request" items.

Each of the items returned will have the following attributes:

Name Type Description
id string The request's ID.
type string The type of object, which should be "request" here.
href string URL to the object’s representation (absolute path).

Read Request Status

Retrieves the status of a specific request based on the supplied request id.

Request

To retrieve the status of a specific request send a GET request to https://api.ionos.com/cloudapi/v5/requests/{requestId}/status

Request Parameters - Path

Parameter Required Type Default Description
{requestId} yes string n/a The ID of a request.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/requests/{requestId}/status?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/requests/{requestId}/status?depth=1

Note: For this particular operation, increasing the value supplied to depth does NOT return any additional information beyond the default amount returned with a value of 0.

Curl Example

The following shows you how to submit the request body via curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
https://api.ionos.com/cloudapi/v5/requests/{requestId}/status

Response

The following is an example status request response when the specific request has completed:

HTTP/1.1 200 OK
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: [date]
X-RateLimit-Remaining: 299
X-RateLimit-Burst: 300
X-RateLimit-Limit: 600
Content-Type: application/json
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{requestId}/status",
  "type" : "request-status",
  "href" : "https://api.ionos.com/cloudapi/v5/requests/{requestId}/status",
  "metadata" : {
    "status" : "DONE",
    "message" : "Request has been successfully executed",
    "etag" : "[etag]",
    "targets" : [ {
      "target" : {
        "id" : "[datacenter-id]",
        "type" : "datacenter",
        "href" : "https://api.ionos.com/cloudapi/v5/datacenters/{datacenterId}"
      },
      "status" : "DONE"
    } ]
  }
}

Response Attributes

The following table describes the attributes found in the JSON response body:

Name Type Description
id string The ID of the specific request with "/status" appended.
type string The type of object, which should be "request-status" here.
href string URL to the object’s representation (absolute path).
metadata collection A collection of metadata about the request's status.

The metadata returned will have the following attributes:

Name Type Description
status string The overall status of the request. [QUEUED, RUNNING, DONE, or FAILED]
message string The username that created the request.
etag string The etag.
targets collection An array of "sub-requests" related to the request. For example, a create server request could involve multiple requests for creating the server, a volume, and a NIC. These sub-requests and their status will be returned in this section of the response.

The targets collection will contain:

Name Type Description
target array Information about a specific "sub-request" related to the request.
status string The status of the request for this specific target. [QUEUED, RUNNING, DONE, or FAILED]

Each target will contain:

Name Type Description
id string The ID of the object or resource involved in the operation.
type string The type of object.
href string URL to the object’s representation (absolute path). Not always available, so it can be a string such as "TO_BE_INJECTED"

Contract Resources

Checking the amount of available resources under a contract can help you to avoid provisioning errors resulting from the attempt to provision more resources than are available.

List Contract Resources

Returns information about the resource limits for a particular contract and the current resource usage.

Request

Submit a GET request to https://api.ionos.com/cloudapi/v5/contracts

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/contracts?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/contracts?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information beyond the default amount returned with a value of 0.

Curl Example

The following shows how to submit the GET /contracts request using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
 https://api.ionos.com/cloudapi/v5/contracts

Response

In previous versions of the Cloud API, the amount of data included in the response payload would vary slightly depending on the credentials supplied when making the request. Now all users can view the resource and usage details for a contract.

{
  "type": "contract",
  "properties": {
    "contractNumber": 12345678,
    "owner": "test@domain.com",
    "status": "BILLABLE",
    "regDomain": "mydomain.com",
    "resourceLimits": {
      "coresPerServer": 20,
      "coresPerContract": 30,
      "coresProvisioned": 0,
      "ramPerServer": 204800,
      "ramPerContract": 3072000,
      "ramProvisioned": 0,
      "hddLimitPerVolume": 2048000,
      "hddLimitPerContract": 3072000,
      "hddVolumeProvisioned": 0,
      "ssdLimitPerVolume": 2048000,
      "ssdLimitPerContract": 3072000,
      "ssdVolumeProvisioned": 0,
      "reservableIps": 3,
      "reservedIpsOnContract": 0,
      "reservedIpsInUse": 0
      "k8sClusterLimitTotal": 0
      "k8sClustersProvisioned": 0
    }
  }
}

The following table describes each of the response attributes.

Name Type Description
type string The type of response, in this case it will be contract
properties collection A collection of properties for each item.

The following table describes the properties returned in the response.

Name Type Description
contractNumber int64 The contract number that the returned information is from.
owner string The username of the "Contract Owner".
status string The status of the contract. [ BILLABLE...]
regDomain string Registration domain of the contract
resourceLimits collection An object containing the contract's resource limits.

The following table describes the resourceLimits returned as part of properties.

Name Type Example Description
coresPerContract int32 20 Maximum number of CPU cores per contract.
coresPerServer int32 4 Maximum number of CPU cores per server.
coresProvisioned int32 4 The total number of CPU cores that have been provisioned.
hddLimitPerContract int64 3072000 The maximum amount of hard disk space (in MB) that may be provisioned under this contract.
hddLimitPerVolume int64 2048000 The maximum size (in MB) of an individual hard disk volume.
hddVolumeProvisioned int64 1024000 The amount of hard disk space (in MB) that is currently provisioned.
ramPerContract int32 3072000 The maximum amount of RAM (in MB) that may be provisioned under this contract.
ramPerServer int32 204800 The maximum amount of RAM (in MB) that may be provisioned for a particular server under this contract.
ramProvisioned int32 102400 The amount of RAM (in MB) that has been provisioned under this contract.
reservableIps int32 128 The maximum number of static public IP addresses that may be reserved by this customer across all contracts.
reservedIpsInUse int32 6 The number of static public IP addresses that have been reserved.
reservedIpsOnContract int32 32 The maximum number of static public IP addresses that can be reserved under this contract.
ssdLimitPerContract int64 2048000 The maximum amount of solid state disk space (in MB) that may be provisioned under this contract.
ssdLimitPerVolume int64 1024000 The maximum size (in MB) of an individual solid state disk volume.
ssdVolumeProvisioned int64 512000 The amount of solid state disk space (in MB) that is currently provisioned.
k8sClusterLimitTotal int32 5 The maximum limit of Kubernetes cluster that can be created under this contract.
k8sClustersProvisioned int32 3 The amount of Kubernetes clusters that is currently provisioned.

User Management

These operations are designed to allow you to orchestrate users and resources via the Cloud API. Previously this functionality required use of the DCD (Data Center Designer) web application.

Create a User

Creates a new user under a particular contract.

Request

Submit a POST request to https://api.ionos.com/cloudapi/v5/um/users

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Body

The JSON encoded request body may contain the following information:

Name Required Type Default Description
firstname yes string n/a A name for the user.
lastname yes string n/a A name for the user.
email yes string n/a An e-mail address for the user.
password yes string n/a A password for the user.
administrator no Boolean false Assigns the user have administrative rights.
forceSecAuth no Boolean false Indicates if secure (two-factor) authentication should be forced for the user.

Please Note: The password set here cannot be updated through the API currently. It is recommended that a new user log into the DCD and change their password.

Curl Example

The following shows how to submit the POST request using curl:

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '{
         "properties": {
             "firstname": "New",
             "lastname": "User",
             "email": "username@domain.tld",
             "password": "abc123-321CBA",
             "administrator": true,
             "forceSecAuth": false
         }
     }' \
https://api.ionos.com/cloudapi/v5/um/users

Response Body

{
  "id": "e1daff99-0f2c-4970-8643-XXXXXXXXXXXX",
  "type": "user",
  "href": "https://api.ionos.com/cloudapi/v5/um/users/e1daff99-0f2c-4970-8643-XXXXXXXXXXXX",
  "metadata": {
    "etag": "37a6259cc0c1dae299a7866489dff0bd",
    "creationDate": "2017-05-22T08:15:55Z",
    "lastLogin": null
  },
  "properties": {
    "firstname": "New",
    "lastname": "Admin",
    "email": "new_admin@domain.tld",
    "administrator": true,
    "forceSecAuth": false,
    "secAuthActive": false
  }
}

Response Attributes

Name Type Description
id string The user's identifier.
type string The type of response, in this case it will be user.
href string A URI for accessing the user object.
metadata collection A collection containing metadata for the user.
properties collection A collection containing the user's properties.

The metadata collection includes these attributes:

Name Type Description
etag string ETag for the user.
creationDate string A time and date stamp indicating when the user was created.
lastLogin string A time and date stamp indicating when the user last logged in. Should be "null" for a new user.

The properties collection includes these attributes:

Name Type Description
firstname string The first name of the user.
lastname string The last name of the user.
email string The e-mail address of the user.
administrator Boolean Indicates if the user has administrative rights.
forceSecAuth Boolean Indicates if secure (two-factor) authentication was enabled for the user.
secAuthActive Boolean Indicates if secure (two-factor) authentication is enabled for the user.

Retrieve a User

Retrieve details about a specific user including what groups and resources the user is associated with.

Request

Submit a GET request to https://api.ionos.com/cloudapi/v5/um/users/{userId}

Request Parameters - Path

Parameter Required Type Default Description
{userId} yes string n/a The ID of the specific user to retrieve information about.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/um/users/{userId}?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/um/users/{userId}?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information beyond the default amount returned with a value of 0.

Curl Example

The following shows how to submit the GET request using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
 https://api.ionos.com/cloudapi/v5/um/users/15f67991-0f51-4efc-a8ad-XXXXXXXXXXXX

Response Body

{
  "id": "e1daff99-0f2c-4970-8643-XXXXXXXXXXXX",
  "type": "user",
  "href": "https://api.ionos.com/cloudapi/v5/um/users/e1daff99-0f2c-4970-8643-XXXXXXXXXXXX",
  "metadata": {
    "etag": "37a6259cc0c1dae299a7866489dff0bd",
    "creationDate": "2017-05-22T08:15:55Z",
    "lastLogin": null
  },
  "properties": {
    "firstname": "New",
    "lastname": "Admin",
    "email": "new_admin@domain.tld",
    "administrator": true,
    "forceSecAuth": false,
    "secAuthActive": false,
    "active": true,
    "s3CanonicalUserId": "{S3UserId}"
  },
  "entities": {
    "owns": {
        "id": "e1daff99-0f2c-4970-8643-XXXXXXXXXXXX/owns",
        "type": "collection",
        "href": "https://api.ionos.com/cloudapi/v5/um/users/e1daff99-0f2c-4970-8643-XXXXXXXXXXXX/owns"
    },
    "groups": {
        "id": "e1daff99-0f2c-4970-8643-XXXXXXXXXXXX/groups",
        "type": "collection",
        "href": "https://api.ionos.com/cloudapi/v5/um/users/e1daff99-0f2c-4970-8643-XXXXXXXXXXXX/groups"
    },
    "s3Keys": {
        "id": "e1daff99-0f2c-4970-8643-XXXXXXXXXXXX/s3keys",
        "type": "collection",
        "href": "https://api.ionos.com/cloudapi/v5/um/users/e1daff99-0f2c-4970-8643-XXXXXXXXXXXX/s3keys"
    }
  }
}

Response Attributes

Name Type Description
id string The user's identifier.
type string The type of response, in this case it will be user.
href string A URI for accessing the user object.
metadata collection A collection containing metadata for the user.
properties collection A collection containing the user's properties.
entities collection A collection containing resources the user owns, and groups the user is a member of.

The metadata collection includes these attributes:

Name Type Description
etag string ETag for the user.
creationDate string A time and date stamp indicating when the user was created.
lastLogin string A time and date stamp indicating when the user last logged in.

The properties collection includes these attributes:

Name Type Description
firstname string The first name of the user.
lastname string The last name of the user.
email string The e-mail address of the user.
administrator Boolean Indicates if the user has administrative rights.
forceSecAuth Boolean Indicates if secure (two-factor) authentication was enabled for the user.
secAuthActive Boolean Indicates if secure (two-factor) authentication is enabled for the user.
active Boolean Indicates if the user is active (true) or disabled (false).
s3CanonicalUserId string The user's S3 ID.

The entities collection includes these attributes:

Name Type Description
owns collection A collection of resources that this user owns.
groups collection A collection of groups that this user is a member of.
s3Keys collection A collection of s3Keys associated with the user.

Each of the owns, groups, and s3Keys will include the following attributes.

Name Type Description
id string The group's identifier with /users or /resources appended.
type string The type of response, in this case it will be "collection".
href string A URL for directly accessing the object.

At depth=1 each of the entities will also include an items collection with details about the particular resource that the user owns, the groups that the user is a member of, and the s3Keys associated with the user.

If you are only interested in seeing details about owns, groups, or s3Keys, you can append the entity name to your get request and the API will return details about the specified entity.

For example:

For owns, submit a GET request to https://api.ionos.com/cloudapi/v5/um/users/{userId}/owns

For groups, submit a GET request to https://api.ionos.com/cloudapi/v5/um/users/{userId}/groups

For s3keys, submit a GET request to https://api.ionos.com/cloudapi/v5/um/users/{userId}/s3keys

As with other GET requests, you can utilize the depth=X parameter to control the amount of detail returned.

List Users

Retrieve a list of all the users that have been created under a contract.

Request

Submit a GET request to https://api.ionos.com/cloudapi/v5/um/users

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/um/users?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/um/users?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information beyond the default amount returned with a value of 0.

You can filter the result set using custom filters.

An example of using the custom filter to find all users where firstname contains "joe":

https://api.ionos.com/cloudapi/v5/requests?filter.firstname=joe&depth=1

or where administrator is "true":

https://api.ionos.com/cloudapi/v5/um/users?depth=1&filter.administrator=true

You can also filter on metadata such as lastLogin. This example would find all users where the lastLogin is "2017-11":

https://api.ionos.com/cloudapi/v5/um/users?depth=1&filter.lastLogin=2017-11

Curl Example

The following shows how to submit the GET request using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
 https://api.ionos.com/cloudapi/v5/um/users

Response Body

{
  "id": "users",
  "type": "collection",
  "href": "https://api.ionos.com/cloudapi/v5/users",
  "items": [
    {
      "id": "e1daff99-0f2c-4970-8643-0ec34433b05f",
      "type": "user",
      "href": "https://api.ionos.com/cloudapi/v5/um/users/e1daff99-0f2c-4970-8643-XXXXXXXXXXXX"
    }
  ]
}

Response Attributes

Name Type Description
id string "users"
type string The type of response, in this case is collection.
href string A URI for accessing the object. "baseurl/users"
items collection A collection containing the users that are members of the group.

At the default depth=0 each of the items has the following attributes:

Name Type Description
id string The user's identifier.
type string The type of response, in this case it is user.
href string A URI for accessing the user object. "baseurl/um/users/{userId}"

At depth=1 each of the items will include the metadata, properties, and entities collections. Details on the contents of those collections can be found in the Retrieve a User section below.

Update a User

Update details about a specific user including their privileges.

Submit a PUT request to https://api.ionos.com/cloudapi/v5/um/users/{userId}

Request Parameters - Path

Parameter Required Type Default Description
{userId} yes string n/a The ID of the specific user to update.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Body

The JSON encoded request body may contain the following information:

Name Required Type Default Description
firstname yes string n/a A name for the user.
lastname yes string n/a A name for the user.
email yes string n/a An e-mail address for the user.
administrator no Boolean false Enables administrative rights for the user.
forceSecAuth no Boolean false Indicates if secure authentication should be forced for the user.

Note: The password attribute is immutable. It is not allowed in update requests. It is recommended that a new user log into the DCD and change their password.

Note: The attributes marked Required in the table need to be passed in, even if they are not being changed.

Curl Example

The following shows how to submit the PUT request using curl:

curl --include \
     --request PUT \
     --user 'username@domain.tld:password' \
     --data-binary '{
         "properties": {
             "firstname": "Changed",
             "lastname": "Person",
             "email": "changedusername@domain.tld",
             "administrator": false,
             "forceSecAuth": false
         }
     }' \
https://api.ionos.com/cloudapi/v5/um/users/{userId}

Response Body

{
  "id": "e1daff99-0f2c-4970-8643-XXXXXXXXXXXX",
  "type": "user",
  "href": "https://api.ionos.com/cloudapi/v5/um/users/e1daff99-0f2c-4970-8643-XXXXXXXXXXXX",
  "metadata": {
    "etag": "37a6259cc0c1dae299a7866489dff0bd",
    "creationDate": "2017-05-22T08:15:55Z",
    "lastLogin": null
  },
  "properties": {
    "firstname": "New",
    "lastname": "Administrator",
    "email": "new_admin@domain.tld",
    "administrator": true,
    "forceSecAuth": false,
    "secAuthActive": false
  },
  "entities": {
    "owns": {
      "id": "e1daff99-0f2c-4970-8643-XXXXXXXXXXXX/owns",
      "type": "collection",
      "href": "https://api.ionos.com/cloudapi/v5/um/users/e1daff99-0f2c-4970-8643-XXXXXXXXXXXX/owns"
    },
    "groups": {
      "id": "e1daff99-0f2c-4970-8643-XXXXXXXXXXXX/groups",
      "type": "collection",
      "href": "https://api.ionos.com/cloudapi/v5/um/users/e1daff99-0f2c-4970-8643-XXXXXXXXXXXX/groups"
    }
  }
}

Response Attributes

Name Type Description
id string The user's identifier.
type string The type of response, in this case it will be "user".
href string A URI for accessing the user object.
metadata collection A collection containing metadata for the user.
properties collection A collection containing the user's properties.
entities collection A collection containing resources the user owns, and groups the user is a member of.

The metadata collection includes these attributes:

Name Type Description
etag string ETag for the user.
creationDate string A time and date stamp indicating when the user was created.
lastLogin string A time and date stamp indicating when the user last logged in.

The properties collection includes these attributes:

Name Type Description
firstname string The first name of the user.
lastname string The last name of the user.
email string The e-mail address of the user.
administrator Boolean Indicates if the user has administrative rights.
forceSecAuth Boolean Indicates if secure (two-factor) authentication was enabled for the user.
secAuthActive Boolean Indicates if secure (two-factor) authentication is enabled for the user.

The entities collection includes these attributes:

Name Type Description
owns collection A collection of resources that this user owns.
groups collection A collection of groups that this user is a member of.

Each of the owns or groups will include the following attributes.

Name Type Description
id string The group's identifier with /users or /resources appended.
type string The type of response, in this case it will be "collection".
href string A URL for directly accessing the object.

Delete a User

Blacklists the user, disabling them. The user is not completely purged, therefore if you anticipate needing to create a user with the same name in the future, we suggest renaming the user before you delete it.

Submit a DELETE request to https://api.ionos.com/cloudapi/v5/um/users/{userId}

Request Parameters - Path

Parameter Required Type Default Description
{userId} yes string n/a The ID of the specific user to delete.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Curl Example

The following shows how to submit the DELETE request using curl:

curl --include \
     --request DELETE \
     --user 'username@domain.tld:password' \
https://api.ionos.com/cloudapi/v5/um/users/{userId}

Response

202 - "successful operation" is returned.

Create a Group

Use this operation to create a new group and set group privileges.

Request

Submit a POST request to https://api.ionos.com/cloudapi/v5/um/groups

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Body

The JSON encoded request body may contain the following attributes:

Name Required Type Default Description
name yes string n/a A name for the group.
createDataCenter no Boolean false The group will be allowed to create virtual data centers.
createSnapshot no Boolean false The group will be allowed to create snapshots.
reserveIp no Boolean false The group will be allowed to reserve IP addresses.
accessActivityLog no Boolean false The group will be allowed to access the activity log.
s3Privilege no Boolean false The group will be allowed to manage S3.
createBackupUnit no Boolean false The group will be able to manage backup units.

Curl Example

The following shows how to submit a POST request to /um/groups using curl:

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '{
         "properties": {
             "name": "Super Admins",
             "createDataCenter": true,
             "createSnapshot": true,
             "reserveIp": true,
             "accessActivityLog": true,
             "s3Privilege": true,
             "createBackupUnit": true
         }
    }' \
https://api.ionos.com/cloudapi/v5/um/groups

Response Body

{
  "id": "20a8e4c1-03d4-48e2-8334-XXXXXXXXXXXX",
  "type": "group",
  "href": "https://api.ionos.com/cloudapi/v5/um/groups/20a8e4c1-03d4-48e2-8334-XXXXXXXXXXXX",
  "properties": {
    "name": "Super Admins",
    "createDataCenter": true,
    "createSnapshot": true,
    "reserveIp": true,
    "accessActivityLog": true,
    "s3Privilege": true,
    "createBackupUnit": true
  }
}

Response Attributes

Name Type Description
id string The new group's identifier.
type string The type of response, in this case it will be "group".
href string A URI for accessing the object.
properties collection A collection containing the group's properties.
entities collection A collection containing users and resources associated with the group.

The properties collection includes these attributes:

Name Type Description
name string A name that was given to the group.
createDataCenter Boolean The group has permission to create virtual data centers.
createSnapshot Boolean The group has permission to create snapshots.
reserveIp Boolean The group has permission to reserve IP addresses.
accessActivityLog Boolean The group has permission to access the activity log.
s3Privilege Boolean The group can interact with S3.
createBackupUnit Boolean The group can create backup units.

Retrieve a Group

Retrieves detailed information about a specific group.

Request

Submit a GET request to https://api.ionos.com/cloudapi/v5/um/groups/{groupId}

Request Parameters - Path

Parameter Required Type Default Description
{groupId} yes string n/a The ID of the specific group to retrieve.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5/um/groups/{groupId}?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5/um/groups/{groupId}?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information beyond the default amount returned with a value of 0.

Curl Example

The following shows how to submit the GET /um/groups/{groupId} request using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
https://api.ionos.com/cloudapi/v5/um/groups/20a8e4c1-03d4-48e2-8334-XXXXXXXXXXXX

Response Body

{
  "id": "20a8e4c1-03d4-48e2-8334-XXXXXXXXXXXX",
  "type": "group",
  "href": "https://api.ionos.com/cloudapi/v5/um/groups/20a8e4c1-03d4-48e2-8334-XXXXXXXXXXXX",
  "properties": {
    "name": "Super Admins",
    "createDataCenter": true,
    "createSnapshot": true,
    "reserveIp": true,
    "accessActivityLog": true,
    "s3Privilege": false,
    "createBackupUnit": false
  },
  "entities": {
    "users": {
      "id": "20a8e4c1-03d4-48e2-8334-XXXXXXXXXXXX/users",
      "type": "collection",
      "href": "https://api.ionos.com/cloudapi/v5/um/groups/20a8e4c1-03d4-48e2-8334-XXXXXXXXXXXX/users"
    },
    "resources": {
      "id": "20a8e4c1-03d4-48e2-8334-XXXXXXXXXXXX/resources",
      "type": "collection",
      "href": "https://api.ionos.com/cloudapi/v5/um/groups/20a8e4c1-03d4-48e2-8334-XXXXXXXXXXXX/resources"
    }
  }
}

The JSON response will contain the group properties and entities associated with the group.

Response Attributes

Name Type Description
id string The group's identifier.
type string The type of response, in this case it will be "group".
href string A URI for accessing the object.
properties collection A collection containing the group's properties.
entities collection A collection containing users and resources associated with the group.

The properties collection includes these attributes:

Name Type Description
name string A name that was given to the group.
createDataCenter Boolean The group has permission to create virtual data centers.
createSnapshot Boolean The group has permission to create snapshots.
reserveIp Boolean The group has permission to reserve IP addresses.
accessActivityLog Boolean The group has permission to access the activity log.
s3Privilege Boolean The group can interact with S3.
createBackupUnit Boolean The group can create backup units.

The entities collection includes these attributes:

Name Type Description
users collection A collection of users that belong to this group.
resources collection A collection of resources that are assigned to this group.

Each of the users or resources will include the following attributes.

Name Type Description
id string The group's identifier with /users or /resources appended.
type string The type of response, in this case it will be "collection".
href string A URL for directly accessing the object.

At depth=1 additional information is returned in an items collection for each of the users or resources.

At depth=2 or greater, then additional metadata, properties, and entities are returned for each of the items.

List Groups

This retrieves a full list of all groups.

Request

Submit a GET request to https://api.ionos.com/cloudapi/v5/um/groups

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
X-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty Boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.ionos.com/cloudapi/v5//um/groups?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.ionos.com/cloudapi/v5//um/groups?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information beyond the default amount returned with a value of 0.

Curl Example

The following shows how to submit the GET /um/groups request using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
 https://api.ionos.com/cloudapi/v5/um/groups/

Response Body

{
    "id": "groups",
    "type": "collection",
    "href": "https://api.ionos.com/cloudapi/v5/um/groups",
    "items": [
    {
        "id": "7fcc6d14-2d81-4bfe-a6dc-XXXXXXXXXXXX",
        "type": "group",
        "href": "https://api.ionos.com/cloudapi/v5/um/groups/7fcc6d14-2d81-4bfe-a6dc-XXXXXXXXXXXX"
    },
    {
        "id": "e1cb1f6d-eea1-409e-b2c0-XXXXXXXXXXXX",
        "type": "group",
        "href": "https://api.ionos.com/cloudapi/v5/um/groups/e1cb1f6d-eea1-409e-b2c0-XXXXXXXXXXXX"
    },
    {
        "id": "ad1aff06-513d-480f-ad27-XXXXXXXXXXXX",
        "type": "group",
        "href": "https://api.ionos.com/cloudapi/v5/um/groups/ad1aff06-513d-480f-ad27-XXXXXXXXXXXX"
    },
    {
        "id": "ed6ec36d-e35b-402a-9ed7-XXXXXXXXXXXX",
        "type": "group",
        "href": "https://api.ionos.com/cloudapi/v5/um/groups/ed6ec36d-e35b-402a-9ed7-XXXXXXXXXXXX"
    },
    {
        "id": "9e2cbcb6-7fca-4a3f-892c-XXXXXXXXXXXX",
        "type": "group",
        "href": "https://api.ionos.com/cloudapi/v5/um/groups/9e2cbcb6-7fca-4a3f-892c-XXXXXXXXXXXX"
    }
    ]
}

Response Attributes

The response will contain metadata, group properties, and group entities as described below.

Name Type Description
id string "groups"
type string The type of response, in this case it will be "collection".
href string A URI for accessing the object. "um/groups"
items collection A collection of groups.

At the default depth value of 0, each of the items contains the following information:

Name Type Description
id string The group's identifier.
type string The type of response, in this case it will be "group".
href string A URI for accessing the group.

If a depth value of 1 is passed in as a query parameter, then the response will include details about each item as outlined in these tables.

Name Type Description
id string The group's identifier.
type string The type of response, in this case it will be "group".
href string A URI for accessing the group.
properties collection A list of group properties.
entities collection A collection of entities (users and resources) that are part of the group.

These are the properties that may be returned.

Name Type Description
name string A name that was given to the group.
createDataCenter Boolean The group has permission to create virtual data centers.
createSnapshot Boolean The group has permission to create snapshots.
reserveIp Boolean The group has permission to reserve IP addresses.
accessActivityLog Boolean The group has permission to access the activity log.
s3Privilege Boolean The group can interact with S3.
createBackupUnit Boolean The group can create backup units.

These are the entities that may be returned.

Name Type Description