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:

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 Status Codes

HTTP Headers

Request Headers

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

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.

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:

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.

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

Response Headers

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:

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:

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:

The metadata collection contains the following attributes:

The properties collection contains the following attributes:

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:

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:

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:

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:

The metadata includes the following attributes:

The properties include the following attributes:

The entities collection includes the following:

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Query

The following optional query parameters may be included.

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:

The metadata includes the following attributes:

The properties include the following attributes:

The entities collection includes the following:

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:

Request Parameters - Query

The following optional query parameters may be included.

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:

For each of the items the following attributes are returned:

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

Request Parameters - Header

The following request headers are available:

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:

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:

The metadata includes the following attributes:

The properties include the following attributes:

The entities collection includes the following:

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

Request Parameters - Header

The following request headers are available:

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:

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:

The metadata includes the following attributes:

The properties include the following attributes:

The entities collection includes the following:

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

Request Parameters - Header

The following request headers are available:

Curl Example

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

curl --include \
     --request DELETE \
     --header "Content-Type: application/json"
     --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

Request Parameters - Header

The following request headers are available:

Request Parameters - Query

The following optional query parameters may be included.

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:

These properties are returned:

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:

Request Parameters - Query

The following optional query parameters may be included.

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:

Each of the returned items has these attributes:

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.

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Query

The following optional query parameters may be included.

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:

Each of the returned items has these attributes:

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.

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

Request Parameters - Header

The following request headers are available:

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

The following table outlines the availability zones currently supported:

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:

The metadata collection is described in this table:

The properties returned are:

The entities returned may include:

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Query

The following optional query parameters may be included.

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:

The metadata about the server includes:

The properties returned are:

The entities returned include:

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:

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Query

The following optional query parameters may be included.

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:

The items will have the following attributes.

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Body

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:

The metadata about the server includes:

The properties returned are:

The entities returned include:

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

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Query

The following optional query parameters may be included.

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Body

The following table describes the request body values:

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Query

The following optional query parameters may be included.

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Query

The following optional query parameters may be included.

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 \
     --header "Content-Type: application/json"
     --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

Request Parameters - Header

The following request headers are available:

Request Parameters - Body

The following table describes the request body values:

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Query

The following optional query parameters may be included.

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Header

The following request headers are available:

Curl Example

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

curl --include \
     --request POST \
     --header "Content-Type: application/json"
     --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

Request Parameters - Header

The following request headers are available:

Curl Example

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

curl --include \
     --request POST \
     --header "Content-Type: application/json"
     --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

Request Parameters - Header

The following request headers are available:

Curl Example

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

curl --include \
     --request POST \
     --header "Content-Type: application/json"
     --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

Request Parameters - Header

The following request headers are available:

Request Parameters - Query

The following optional query parameters may be included.

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:

The metadata returned includes the following attributes.

The properties returned include the following attributes:

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:

Request Parameters - Query

The following optional query parameters may be included.

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:

Each of the items returned has the following attributes.

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

Request Parameters - Header

The following request headers are available:

Request Body

{
    "description": "Updated Image Description"
}

Request Parameters - Body

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:

The metadata returned includes the following attributes.

The properties returned include the following attributes:

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

Request Parameters - Header

The following request headers are available:

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

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:

The metadata returned includes the following attributes.

The properties returned include the following attributes:

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

Request Parameters - Header

The following request headers are available:

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

When provisioning SSD volumes, you can select between two performance classes explicitly. If you provision a volume using the legacy type “SSD” only, you will get the “SSD Premium” performance tier that was also delivered before. Both SSD performance classes give 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. Multiple HDD and/or SSD volumes may be attached to a server.

To get the best performance from SSD volumes of both performance classes, 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 performance classes capabilities are

	SSD Premium Storage	SSD Standard Storage
READ	75 IOPS per GB	40 IOPS per GB
WRITE	50 IOPS per GB	30 IOPS per GB
Bandwidth	1 MB/s per GB	0.5 MB/s per GB

The performance of SSD Premium Storages scales up to a volume size of 600 GB which provides IOPS of 45.000 read and 30.000 write (full random at 4kb block size), along with bandwidth of 600MB/s (sequential at 1MB block size).

The performance of SSD Standard Storages scales up to a volume size of 600 GB which provides IOPS of 24.000 read and 18.000 write (full random at 4kb block size), along with bandwidth of 300MB/s (sequential at 1MB block size).

It is perfectly acceptable to create SSD volumes of both performance classes larger than 600 GB, however no additional performance gains are realized once you exceed 600 GB.

Request

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

Request Parameters - Path

Request Parameters - Header

The following request headers are available:

Request Parameters - Body

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

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:

The metadata returned for the volume:

The properties returned for the volume:

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Query

The following optional query parameters may be included.

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:

The metadata returned for each volume:

The properties returned for each volume:

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Query

The following optional query parameters may be included.

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:

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

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

The metadata returned for each volume:

The properties returned for each volume:

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

Request Parameters - Header

The following request headers are available:

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.

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:

The metadata returned for the volume:

The properties returned for the volume:

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

Request Parameters - Header

The following request headers are available:

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.

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:

The metadata returned for the volume:

The properties returned for the volume:

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Body

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:

The metadata returned for the snapshot:

The properties returned for the snapshot:

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Body

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/json"
     --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

Create Snapshot

Creation of snapshots is performed from the perspective of the storage volume. To create a volume snapshot send a POST request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes/{volumeId}/create-snapshot

Click here for a more detailed example.

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Query

The following optional query parameters may be included.

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

The metadata returned for the snapshot:

The properties returned for the snapshot:

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:

Request Parameters - Query

The following optional query parameters may be included.

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:

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

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

The metadata returned for the snapshot:

The properties returned for the snapshot:

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Body

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:

The metadata returned for the snapshot:

The properties returned for the snapshot:

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Body

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:

The metadata returned for the snapshot:

The properties returned for the snapshot:

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

Request Parameters - Header

The following request headers are available:

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:

Request Parameters - Body

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:

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

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

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Query

The following optional query parameters may be included.

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:

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

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

The ipConsumers collection contains the following information about each IP address that is part of the IP Block.

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Body

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:

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

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

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Header

The following request headers are available:

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:

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:

The metadata returned is outlined in this table:

The properties returned are summarized in this table:

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Query

The following optional query parameters may be included.

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:

The metadata returned for a LAN is shown in this table:

The properties returned for a LAN are outlined in this table:

The ipFailover collection contains two attributes:

The entities returned for a LAN are described in this table:

At the default depth=0, each entity in nics has the following attributes returned:

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Query

The following optional query parameters may be included.

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:

Each of the returned items has these attributes:

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

Request Parameters - Header

The following request headers are available:

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:

The ipFailover array consists of two attributes.

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:

The metadata returned is outlined in this table:

The properties returned are summarized in this table:

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

Request Parameters - Header

The following request headers are available:

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:

The ipFailover array consists of two attributes.

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

The metadata returned is outlined in this table:

The properties returned are summarized in this table:

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Header

The following request headers are available:

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

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:

The metadata about the NIC includes:

The properties returned are:

The entities returned include:

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Query

The following optional query parameters may be included.

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:

The metadata about the NIC includes:

The properties returned are:

The entities returned include:

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Query

The following optional query parameters may be included.

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:

The items will have the following attributes.

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

Request Parameters - Header

The following request headers are available:

Request Parameters

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:

The metadata about the NIC includes:

The properties returned are:

The entities returned include:

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Body

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:

The metadata about the NIC includes:

The properties returned are:

The entities returned include:

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Header

The following request headers are available:

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

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:

The metadata returned for each firewall rule:

The properties returned for the firewall rule:

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Query

The following optional query parameters may be included.

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:

The metadata returned for each firewall rule:

The properties returned for the firewall rule:

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Query

The following optional query parameters may be included.

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:

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

Request Parameters - Header

The following request headers are available:

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

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:

The metadata returned for each firewall rule:

The properties returned for the firewall rule:

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

Request Parameters - Header

The following request headers are available:

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

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:

The metadata returned for each volume:

The properties returned for the firewall rule:

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Header

The following request headers are available:

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

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:

The metadata returned for a load balancer is shown in this table:

The properties returned for a load balancer are outlined in this table:

The entities returned for a load balancer are described in this table:

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Query

The following optional query parameters may be included.

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

The metadata returned for a load balancer is shown in this table:

The properties returned for a load balancer are outlined in this table:

The entities returned for a load balancer are described in this table:

At the default depth=0, each entity in balancednics has the following attributes returned:

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Query

The following optional query parameters may be included.

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:

Each of the returned items has these attributes:

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Body

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:

The metadata returned for a load balancer is shown in this table:

The properties returned for a load balancer are outlined in this table:

The entities returned for a load balancer are described in this table:

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Body

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:

The metadata returned for a load balancer is shown in this table:

The properties returned for a load balancer are outlined in this table:

The entities returned for a load balancer are described in this table:

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Query

The following optional query parameters may be included.

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:

The items will have the following attributes.

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:

The properties returned are:

The entities returned include:

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Query

The following optional query parameters may be included.

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:

The metadata about the NIC includes:

The properties returned are:

The entities returned include:

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Body

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:

The metadata about the NIC includes:

The properties returned are:

The entities returned include:

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Query

The following optional query parameters may be included.

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:

The metadata returned will have the following attributes:

The requestStatus collection will contain:

The properties collection should contain:

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:

Request Parameters - Query

The following optional query parameters may be included.

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:

Each of the items returned will have the following attributes:

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Query

The following optional query parameters may be included.

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:

The metadata returned will have the following attributes:

The targets collection will contain:

Each target will contain:

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:

Request Parameters - Query

The following optional query parameters may be included.

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.

The following table describes the properties returned in the response.

The following table describes the resourceLimits returned as part of properties.

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:

Request Parameters - Body

The JSON encoded request body may contain the following information:

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

The metadata collection includes these attributes:

The properties collection includes these attributes:

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Query

The following optional query parameters may be included.

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

The metadata collection includes these attributes:

The properties collection includes these attributes:

The entities collection includes these attributes:

Each of the owns, groups, and s3Keys will include the following attributes.

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:

Request Parameters - Query

The following optional query parameters may be included.

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

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

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Body

The JSON encoded request body may contain the following information:

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

The metadata collection includes these attributes:

The properties collection includes these attributes:

The entities collection includes these attributes:

Each of the owns or groups will include the following attributes.

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

Request Parameters - Header

The following request headers are available:

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:

Request Parameters - Body

The JSON encoded request body may contain the following attributes:

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

The properties collection includes these attributes:

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

Request Parameters - Header

The following request headers are available:

Request Parameters - Query

The following optional query parameters may be included.

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

The properties collection includes these attributes:

The entities collection includes these attributes:

Each of the users or resources will include the following attributes.

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:

Request Parameters - Query

The following optional query parameters may be included.

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.

At the default depth value of 0, each of the items contains the following information:

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.

These are the properties that may be returned.