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:
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.
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.
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.
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.
Group management has been extended to include S3 and Backup related privileges.
This feature is available NOW.
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.
You can consume the REST-based Cloud API using the following URL:
URL | Description |
---|---|
https://api.ionos.com/cloudapi/v5/ | CloudAPI v5 Endpoint |
It is possible to retrieve the swagger file for the Cloud API v5 by visiting Cloud API v5 swagger.json.
HTTP Verb | Description |
---|---|
GET | Used for any read request on resources. GET requests would not contain a body. Requests are idempotent. |
HEAD | Similar to GET, but response contains HTTP headers only, omitting the body. Requests are idempotent. |
POST | Used to create new resources or relationships as well as performing RPC-like actions such as start server, create snapshot, etc. These requests are not idempotent. |
DELETE | Used to remove a resource. This verb is disallowed on collection resources. These requests are not idempotent. |
PUT | Use this verb to change properties of a resource with the ones provided in the request. These requests are not idempotent. |
PATCH | Used to partially update properties of a resource. These requests are not idempotent. PATCH requests use specific patch representations. |
HTTP Status | Description |
---|---|
200 OK | Synchronous request was successful using GET. 200 will also be returned for successful synchronous POST requests that do not result in item creation. |
202 Accepted | Used for asynchronous requests using PUT, DELETE, POST and PATCH methods. The response will also include a Location header pointing to a resource. This can be used for polling. |
304 Not Modified | Response for GETs on resources that have not been changed. (based on ETag values). |
400 Bad Request | Response to malformed requests or general client errors. |
401 Unauthorized | Response to an unauthenticated connection. You will need to use your API username and password to be authenticated. |
404 Not Found | Resource does not exist. |
405 Method Not Allowed | Use for any POST, PUT, PATCH, or DELETE performed on read-only resources. This is also there response to PATCH requests on resources that do not support partial updates. |
422 | Validation errors. |
403 | Forbidden |
415 | The content-type is incorrect for the payload. |
429 | The number of requests exceeds the rate limit. |
Header | Description |
---|---|
Content-Type | Describes the data format of the request body. |
Accept | Used for content type negotiation. |
Authorization | Authorization header. See method details for examples. |
If-Unmodified-Since | This can be used to reliably and deterministically reflect the client state to the server. |
If-None-Match | The request-counterpart for the ETag response header. Usually used with GET requests. |
If-Match | The request-counterpart for the ETag response header. Use with modification requests (PATCH, DELETE) for opportunistic locking. |
X-HTTP-Method-Override | Convenience header for clients with a limited choice of HTTP methods. The HTTP method specified in this header overwrites the HTTP method used to make the request. Example: A client library cannot make PATCH requests. Instead it sends a POST request and sets the X-HTTP-Method-Override header to PATCH. |
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:
@
in your username)Header | Description |
---|---|
Content-Type | Describes data format conveyed in the response body. |
Last-modified | Used with only GET requests. Returns the latest modification date of all resources displayed. |
ETag | The entity tag of a resource. Used to support caching and conditional updates. |
Location | Used together with 201 Created response code to point to the newly created item. For asynchronous requests, together with 202 Accepted response code, points to a resource which can be used for polling. |
X-RateLimit-Burst | Maximum number of concurrent API requests allowed. |
X-RateLimit-Remaining | Number of requests which can still be made without triggering a failure response.
This
number grows as time elapses, eg. if X-RateLimit-Limit=60 then
X-RateLimit-Remaining will grow by 1 every second until it reaches the
X-RateLimit-Burst . |
X-RateLimit-Limit | Average number of requests allowed per minute. |
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
.
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
.
There are three response filters available to assist in parsing information retrieved via the Cloud API.
Query Parameter | Example | Description |
---|---|---|
filter.<property>=<value> | filter.cpuFamily=intel | Limits results to those containing a matching value for a specific property. |
orderBy=<property> | orderBy=cores | Sorts the results alphanumerically in ascending order based on the specified property. |
maxResults=<integer> | maxResult=4 | Limits the number of results returned. |
These query parameters can be applied on any property or metatag returned in the response to a Cloud API GET request. This would include:
Please refer to the "Request Parameters - Query" sections of relevant GET operations for examples of how to use custom filters.
depth
query parameter
described in the preceding section.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:
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 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.
GET responses will return an ETag header.
Usage Examples:
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.
Timestamps adhere to ISO-8601 and are presented in UTC.
YYYY-MM-DDThh:mm:ssZ
Here is a list of resources along with their types.
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}
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
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
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 resources are available under:
[base-url]/requests/[request-status-id]/status
This is a read-only resource; the resource only allows GET requests.
A client can poll for the operation status by making a GET request on the callback-resource returned in the Location header of a CRUD request.
When the underlying asynchronous operation is still running the response status code 202 Accepted is returned.
When the underlying asynchronous operation is successful the response status code will be a 200 OK.
The response body contains a list of reports for all modified resources. In the event of an error a standard error object is returned.
GET [base-url]/requests/[request-status-id]/status results in:
Status | Body | Description |
---|---|---|
202 Accepted | Contains a ‘polling object’. | Async operation is still running |
200 OK | updated object | PATCH operation finished OK |
201 Created | newly created object | POST operation finished OK |
204 No Content |
|
DELETE operation finished OK |
4xx | Error Object | Whenever an error occurs, the proper error code is returned. |
The payload is a Request Status object.
Example:
{
"metadata": {
"id": "[request-status-id]",
"type": "request-status",
"href": "https://[base-url]/request/[request-status-id]/status",
"requestStatus": "RUNNING"
},
"entities": {
"targets": [
{
"target": {
"id": "[NEW-SERVER-ID]",
"type": "server",
"href": "[base-url]/datacenters/[UUID1]/servers/[NEW-SERVER-ID]"
},
"status": "RUNNING"
},
{
"target": {
"id": "[NEW-NIC-ID]",
"type": "NEW-NIC-ID",
"href": "[base-url]/datacenters/[UUID1]/servers/[NEW-SERVER-ID]/nics/[NEW-NIC-ID]"
},
"status": "RUNNING"
}
]
}
}
The callback-resources are garbage-collected once the underlying asynchronous operation has finished, but no earlier than 24h afterwards.
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.
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:
The API request rate is limited. The response for each request advertises the current limits. (See X-RateLimit-XXX response headers.)
The limits apply to all calls made within a given contract. For contracts having multiple users, requests from all users share a common limit.
There are independent limits for read (GET, HEAD) and write operations (POST, PUT, PATCH, DELETE)
When the request rate limit has been exceeded, the client receives HTTP code 429, and a JSON response indicating current limits.
HTTP Status | Description |
---|---|
429 | The number of requests exceeds the rate limit. |
Response Header | Description |
---|---|
X-RateLimit-Burst | Maximum number of concurrent API requests allowed. |
X-RateLimit-Remaining | Number of requests which can still be made without triggering a failure response.
This
number grows as time elapses, eg. if X-RateLimit-Limit=60 then
X-RateLimit-Remaining will grow by 1 every second until it reaches the
X-RateLimit-Burst . |
X-RateLimit-Limit | Average number of requests allowed per minute. |
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.
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.
To create a new VDC, send a POST request to https://api.ionos.com/cloudapi/v5/datacenters
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The format of the request body is as follows:
{
"properties": {
"name": "[data-center-name]",
"description": "[data-center-description]",
"location": "[data-center-location]"
}
}
The following table describes the properties of the request body:
Name | Required | Type | Default | Description |
---|---|---|---|---|
name | no | string | n/a | An optional name for the VDC. |
location | yes | string | n/a | The physical location where the VDC will be created. I.e. "{regionId}/{locationId}". See locations. |
description | no | string | n/a | An optional description for the VDC, e.g., "Staging", "Production". |
NOTE: The value for 'name' cannot contain the following characters: (@, /, , |, ‘’, ‘).
NOTE: You cannot change the location of a virtual data center once it has been provisioned.
See locations for locations currently supported
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
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" : [ ]
}
}
The following table describes the attributes found in the JSON response body:
Name | Type | Description |
---|---|---|
id | string | The resource's unique identifier (UUID) in the form 8-4-4-4-12. |
type | string | The type of object that has been created. |
href | string | URL to the object’s representation (absolute path). |
metadata | collection | Metadata for the VDC. |
properties | collection | Properties of the VDC. |
The metadata collection contains the following attributes:
Name | Type | Description |
---|---|---|
lastModifiedDate | string | The last time the resource has been modified. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
createdDate | string | The date the resource was created. |
createdBy | string | The user who created the resource. |
createdByUserId | string | The userId who created the resource. |
state | string | AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued; INACTIVE Resource has been de-provisioned. |
etag | string | The ETag for the request. |
The properties collection contains the following attributes:
Name | Type | Description |
---|---|---|
name | string | The name of the VDC. |
description | string | The description of the VDC. |
location | string | The location of the VDC. See locations. |
version | string | The version of the VDC. |
features | string | A list of available features in the VDC. ["SSD", "MULTIPLE_CPU", etc] |
To create a new VDC with additional resources, send a POST request to
https://api.ionos.com/cloudapi/v5/datacenters
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
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]"
}
}
}]
}]
}]
}
}
The following table describes the properties of the request body:
Name | Required | Type | Default | Description |
---|---|---|---|---|
name | no | string | n/a | An optional name for the VDC. |
location | yes | string | n/a | The physical location where the VDC will be created. See locations. |
description | no | string | n/a | An optional description for the VDC, e.g., "Staging", "Production". |
NOTE: The value for name cannot contain the following characters: (@, /, , |, ‘’, ‘).
NOTE: You cannot change the location of a VDC once it has been provisioned.
See locations for the locations currently supported
The following describes the entities that may be included in the request body:
Name | Required | Type | Default | Description |
---|---|---|---|---|
servers | no | collection | n/a | You can define multiple servers to be created when the VDC is provisioned. See create server for request parameter details. |
volumes | no | collection | n/a | A collection that represents volumes you wish to create when the VDC is provisioned. See create storage volume for request parameter details. |
loadbalancers | no | collection | n/a | A collection that represents the load balancers you wish to create when the VDC is provisioned. |
lans | no | collection | n/a | A collection that represents the LANs you wish to create when the VDC is provisioned. |
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
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"
}
}
}
The following table describes the attributes found in the response body:
Name | Type | Description |
---|---|---|
id | string | The resource's unique identifier. |
type | string | The type of object that has been created. |
href | string | URL to the object’s representation (absolute path). |
metadata | collection | VDC metadata. |
properties | collection | VDC properties. |
entities | collection | VDC entities. |
The metadata includes the following attributes:
Name | Type | Description |
---|---|---|
lastModifiedDate | string | The last time the resource has been modified. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
createdDate | string | The date the resource was created. |
createdBy | string | The user who created the resource. |
createdByUserId | string | The userId who created the resource. |
state | string | AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued; INACTIVE Resource has been de-provisioned. |
etag | string | The ETag for the request. |
The properties include the following attributes:
Name | Type | Description |
---|---|---|
name | string | The name of the VDC. |
description | string | The description of the VDC. |
location | string | The location you provisioned the VDC. See locations. |
version | int32 | The version of the VDC. |
features | collection | A list of available features in the VDC. ["SSD", "MULTIPLE_CPU"] |
The entities collection includes the following:
Name | Type | Description |
---|---|---|
servers | collection | Servers that are part of the VDC. |
volumes | collection | Volumes that are part of the VDC. |
loadbalancers | collection | Load balancers that are part of the VDC. |
lans | collection | A collection that represents the LANs provisioned in the VDC. |
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.
To retrieve a VDC, send a GET request to https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}?depth=1
Note: For this particular operation, increasing the value supplied to depth
will return additional information beyond the default amount returned with a value of 0.
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}
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"
}
}
}
The following table describes the attributes found in the JSON response body:
Name | Type | Description |
---|---|---|
id | string | The resource's unique identifier. |
type | string | The type of object that has been created. |
href | string | URL to the object’s representation (absolute path). |
metadata | collection | VDC metadata. |
properties | collection | VDC properties. |
entities | collection | VDC entities. |
The metadata includes the following attributes:
Name | Type | Description |
---|---|---|
lastModifiedDate | string | The last time the resource has been modified. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
createdDate | string | The date the resource was created. |
createdBy | string | The user who created the resource. |
createdByUserId | string | The userId who created the resource. |
state | string | AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued; INACTIVE Resource has been de-provisioned. |
etag | string | The ETag for the request. |
The properties include the following attributes:
Name | Type | Description |
---|---|---|
name | string | The name of the VDC. |
description | string | The description of the VDC. |
location | string | The location you provisioned the VDC. See locations. |
version | int32 | The version of the VDC. |
features | collection | A list of available features in the VDC. ["SSD", "MULTIPLE_CPU"] |
The entities collection includes the following:
Name | Type | Description |
---|---|---|
servers | collection | Servers that are part of the VDC. |
volumes | collection | Volumes that are part of the VDC. |
loadbalancers | collection | Load balancers that are part of the VDC. |
lans | collection | A collection that represents the LANs provisioned in the VDC. |
If you used the query parameter depth
and set a value of 1
or more, then additional
information about each of the entities is returned.
You can retrieve a complete list of Virtual Data Centers provisioned under your account.
To list all data centers, send a GET request to https://api.ionos.com/cloudapi/v5/datacenters
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/datacenters?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/datacenters?depth=1
Note: For this particular operation, increasing the value supplied to depth
will return additional information beyond the default amount returned with a value of 0.
If you have a number of VDCs provisioned in different locations, perhaps you'd like to get a list of VDCs in a specific locations. This request would return VDCs whose location is as requested:
https://api.ionos.com/cloudapi/v5/datacenters/?depth=0&filter.location={locationId}
If you had a large number of VDCs provisioned in a specific location, but just wanted to get one of them, you could utilize "maxResults=1" to accomplish that:
https://api.ionos.com/cloudapi/v5/datacenters/?depth=0&filter.location=las&maxResults=1
Maybe you recall setting up a couple VDCs with "test" in the name and want to find those:
https://api.ionos.com/cloudapi/v5/datacenters/?depth=1&filter.name=test
As a final example, a filter on version could be used to get a list of VDCs in ascending order based on the number of resource changes that have been provisioned. The VDCs at the top of the list would have had the least number of resource changes made.
https://api.ionos.com/cloudapi/v5/datacenters/?depth=0&orderBy=version
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
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]"
} ]
}
The following table describes the attributes found in the JSON response body:
Name | Type | Description |
---|---|---|
id | string | "datacenters" |
type | string | The type of object that has been created. "collection" |
href | string | URL to the object’s representation (absolute path). |
items | collection | A collection of VDCs. |
For each of the items the following attributes are returned:
Name | Type | Description |
---|---|---|
id | string | The UUID of a VDC. |
type | string | The type of object. "datacenter" |
href | string | URL to the object’s representation (absolute path). |
If you used the query parameter depth
and set a value of 1
or more, then additional
information about each of the items is returned.
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.
To partially update a data center you would send a PATCH request to
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The format of the request body is as follows:
{
"name": "[data-center-name]",
"description": "[data-center-description]"
}
The following table describes the properties of the request body:
Name | Required | Type | Default | Description |
---|---|---|---|---|
name | no | string | n/a | A name for the VDC. |
description | no | string | n/a | A description for the VDC, e.g., "Staging", "Production". |
NOTE: The value for name cannot contain the following characters: (@, /, , |, ‘’, ‘).
NOTE: You cannot change the location of a VDC once it has been provisioned.
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}
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"
}
}
}
The following table describes the attributes found in the JSON response body:
Name | Type | Description |
---|---|---|
id | string | The resource's unique identifier. |
type | string | The type of object that has been created. |
href | string | URL to the object’s representation (absolute path). |
metadata | collection | VDC metadata. |
properties | collection | VDC properties. |
entities | collection | VDC entities. |
The metadata includes the following attributes:
Name | Type | Description | |
---|---|---|---|
lastModifiedDate | string | The last time the resource has been modified. | |
lastModifiedBy | string | The user who last modified the resource. | |
lastModifiedByUserId | string | The userId who last modified the resource. | |
createdDate | string | The date the resource was created. | |
createdBy | string | The user who created the resource. | |
createdBy | createdByUserId | string | The userId who created the resource. |
state | string | AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued; INACTIVE Resource has been de-provisioned. | |
etag | string | The ETag for the request. |
The properties include the following attributes:
Name | Type | Description |
---|---|---|
name | string | The name of the VDC. |
description | string | The description of the VDC. |
location | string | The location you provisioned the VDC. See locations. |
version | int32 | The version of the VDC. |
features | collection | A list of available features in the VDC. ["SSD", "MULTIPLE_CPU"] |
The entities collection includes the following:
Name | Type | Description |
---|---|---|
servers | collection | Servers that are part of the VDC. |
volumes | collection | Volumes that are part of the VDC. |
loadbalancers | collection | Load balancers that are part of the VDC. |
lans | collection | A collection that represents the LANs provisioned in the VDC. |
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":{}}
.
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The format of the request body is as follows:
{
"properties": {
"name": "Example VDC Rename 2",
"description": "Example VDC Description 2"
}
}
The following table describes the properties of the request body:
Name | Required | Type | Default | Description |
---|---|---|---|---|
name | no | string | n/a | A name for the VDC. |
description | no | string | n/a | A description for the VDC, e.g., "Staging", "Production". |
NOTE: The value for name cannot contain the following characters: (@, /, , |, ‘’, ‘).
NOTE: You cannot change the location of a VDC once it has been provisioned.
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}
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"
}
}
}
The following table describes the attributes found in the JSON response body:
Name | Type | Description |
---|---|---|
id | string | The resource's unique identifier. |
type | string | The type of object that has been created. |
href | string | URL to the object’s representation (absolute path). |
metadata | collection | VDC metadata. |
properties | collection | VDC properties. |
entities | collection | VDC entities. |
The metadata includes the following attributes:
Name | Type | Description |
---|---|---|
lastModifiedDate | string | The last time the resource has been modified. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
createdDate | string | The date the resource was created. |
createdBy | string | The user who created the resource. |
createdByUserId | string | The userId who created the resource. |
state | string | AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued; INACTIVE Resource has been de-provisioned. |
etag | string | The ETag for the request. |
The properties include the following attributes:
Name | Type | Description |
---|---|---|
name | string | The name of the VDC. |
description | string | The description of the VDC. |
location | string | The location you provisioned the VDC. See locations. |
version | int32 | The version of the VDC. |
features | collection | A list of available features in the VDC. ["SSD", "MULTIPLE_CPU"] |
The entities collection includes the following:
Name | Type | Description |
---|---|---|
servers | collection | Servers that are part of the VDC. |
volumes | collection | Volumes that are part of the VDC. |
loadbalancers | collection | Load balancers that are part of the VDC. |
lans | collection | A collection that represents the LANs provisioned in the VDC. |
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!
To remove a VDC you would send a DELETE request to
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
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}
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.
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
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"
} ]
}
}
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.
Retrieves all the details about a specific regional location.
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}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{regionId} | yes | string | n/a | The two character region identifier. |
{locationId} | yes | string | n/a | The three character region identifier. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/{regionId}/{locationId}?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/{regionId}/{locationId}?depth=1
Note: For this particular operation, increasing the value supplied to depth
does
NOT return any additional information beyond the default amount returned with a value of
0.
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": []
}
}
The following table describes the attributes included in the JSON response:
Name | Type | Description |
---|---|---|
id | string | The resource's unique identifier consisting of country/city. |
type | string | The type of object. |
href | string | URL to the object’s representation (absolute path). |
properties | collection | Detailed properties for each available location. |
These properties are returned:
Name | Type | Description |
---|---|---|
name | string | A descriptive name for the location. |
features | array | A list of features available at the location. |
imageAliases | array | A list of available image aliases at the location. |
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
.
All locations might not always be available. Retrieve a list of all available regional locations.
To retrieve a list of all locations send a GET request to https://api.ionos.com/cloudapi/v5/locations
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/locations?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/locations?depth=1
Note: For this particular operation, increasing the value supplied to depth
will return additional information beyond the default amount returned with a value of 0.
To demonstrate the use of custom filters, perhaps you are looking for the location abbreviation for one of our locations. We can filter on the name like this:
https://api.ionos.com/cloudapi/v5/locations/?depth=0&filter.name={location}
and get back the one matching location:
{
"id": "locations",
"type": "collection",
"href": "https://api.ionos.com/cloudapi/v5/locations",
"items": [
{
"id": "{regionId}/{locationId}",
"type": "location",
"href": "https://api.ionos.com/cloudapi/v5/locations/{regionId}/{locationId}"
}
]
}
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": []
}
]
The JSON response body will contain a collection of regional locations.
The following table describes the attributes found in the JSON response:
Name | Type | Description |
---|---|---|
id | string | The resource's unique identifier consisting of country/city. |
type | string | The type of object. In this case location . |
href | string | URL to the object’s representation (absolute path). |
items | collection | A collection of available locations. |
Each of the returned items has these attributes:
Name | Type | Description |
---|---|---|
id | string | The resource's unique identifier consisting of country/city. |
type | string | The type of object. In this case location . |
href | string | URL to the object’s representation (absolute path). |
properties | collection | Detailed properties for each available location. |
Note: The properties collection is NOT included in the response at the
default depth=0
.
These properties are returned for each of the items when the depth
query parameter is
greater than or equal to 1.
Name | Type | Description |
---|---|---|
name | string | A descriptive name for the location. |
features | array | A list of features available at the location. |
imageAliases | array | A list of available image aliases at the location. |
Retrieves the locations available in a specific region.
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}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{regionId} | yes | string | n/a | The two character region (country) identifier. [de, us] |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/locations?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/locations?depth=1
Note: For this particular operation, increasing the value supplied to depth
will return additional information beyond the default amount returned with a value of 0.
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"
]
}
}
]
}
The following table describes the attributes found in the JSON response:
Name | Type | Description |
---|---|---|
id | string | The resource's unique identifier consisting of country/city. |
type | string | The type of object. In this case collection . |
href | string | URL to the object’s representation (absolute path). |
items | collection | A collection of available locations. |
Each of the returned items has these attributes:
Name | Type | Description |
---|---|---|
id | string | The resource's unique identifier consisting of country/city. |
type | string | The type of object. |
href | string | URL to the object’s representation (absolute path). |
properties | collection | Detailed properties for each available location. |
Note: The properties collection is NOT included in the response at the
default depth=0
.
These properties are returned for each location when the depth
query parameter is
greater than or equal to 1.
Name | Type | Description |
---|---|---|
name | string | A descriptive name for the location. |
features | array | A list of features available at the location. |
imageAliases | array | A list of available image aliases at the location. |
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.
To create a server send a POST request to
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a virtual data center. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
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"
}
}
Name | Required | Type | Default | Description |
---|---|---|---|---|
name | no | string | n/a | A name for the server. |
cores | yes | int32 | n/a | The total number of cores for the server. |
ram | yes | int32 | n/a | The amount of memory for the server in MB, e.g. 2048. Size must be specified in multiples of
256 MB with a minimum of 256 MB; however, if you set ramHotPlug to TRUE then you must use a
minimum of 1024 MB. |
availabilityZone | no | string | AUTO | The compute availability zone in which the server should exist. [ZONE_1, ZONE_2, AUTO] |
cpuFamily | no | string | AMD_OPTERON | Sets the CPU type. "AMD_OPTERON", "INTEL_XEON", …. Defaults to "AMD_OPTERON". |
bootVolume | no | string | n/a | Reference to a Volume used for booting. If not ‘null’ then bootCdrom has to be ‘null’. |
bootCdrom | no | string | n/a | Reference to a CD-ROM used for booting. If not 'null' then bootVolume has to be 'null'. |
volumes | no | collection | n/a | A collection of volume IDs that you want to connect to the server. If the volume does not exist it will be created implicitly. |
nics | no | collection | n/a | A collection of NICs you wish to create at the time the server is provisioned. |
cdroms | no | collection | n/a | A collection of CD-ROMs you want to connect to the server. |
The following table outlines the availability zones currently supported:
Zone Value | Comment |
---|---|
AUTO | Automatically Selected Zone |
ZONE_1 | Fire Zone 1 |
ZONE_2 | Fire Zone 2 |
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.
HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.ionos.com/cloudapi/v5/requests/{requestId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked
{
"id" : "{serverId}",
"type" : "server",
"href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}",
"metadata" : {
"createdDate" : "[date]",
"createdBy" : "[username]",
"createdByUserId" : "[userId]",
"etag" : "[etag]",
"lastModifiedDate" : "[date]",
"lastModifiedBy" : "[username]",
"lastModifiedByUserId" : "[userId]",
"state" : "BUSY"
},
"properties" : {
"name" : "Server001",
"cores" : 1,
"ram" : 2048,
"availabilityZone" : "ZONE_1",
"vmState" : null,
"bootCdrom" : null,
"bootVolume" : null,
"cpuFamily" : "INTEL_XEON"
},
"entities" : {
"volumes" : {
"id" : "{serverId}/volumes",
"type" : "collection",
"href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/volumes"
}
}
}
The following table describes the attributes found in the response body:
Name | Type | Description |
---|---|---|
id | string | The server's unique identifier. |
type | string | The type of object that has been created. "server" |
href | string | A URL for the new server object. |
metadata | collection | Metadata about the new server. |
properties | collection | Properties of the new server. Some will not be populated until provisioning is completed. |
entities | collection | Entities that are associated with the new server. |
The metadata collection is described in this table:
Name | Type | Description |
---|---|---|
createdDate | string | The date the resource was created. |
createdBy | string | The user who created the resource. |
createdByUserId | string | The userId who created the resource. |
etag | string | The ETag. |
lastModifiedDate | string | The last time the resource was been modified. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
state | string | AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued. INACTIVE The resource has been de-provisioned. |
The properties returned are:
Name | Type | Description |
---|---|---|
name | string | The name of the server. |
cores | int32 | The number of cores for the server. |
ram | int32 | The amount of memory on the server in MB. |
availabilityZone | string | The availability zone for the server. [ZONE_1, ZONE_2, AUTO] |
vmState | string | The current state of the virtual machine. [NOSTATE, RUNNING, BLOCKED, PAUSED, SHUTDOWN, SHUTOFF, CRASHED] |
bootCdrom | string | Reference to a CD-ROM used for booting. |
bootVolume | string | Reference to a Volume used for booting. |
cpuFamily | string | Type of CPU assigned. |
The entities returned may include:
Name | Type | Description |
---|---|---|
cdroms | collection | A collection of CD-ROMs attached to the server. |
volumes | collection | A collection of volumes attached to the server. |
nics | collection | A collection of NICs attached to the server. |
Returns information about a server such as its configuration, provisioning status, etc.
To retrieve a server, send a GET request to
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
{serverId} | yes | string | n/a | The ID of a server. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}?depth=1
Note: For this particular operation, increasing the value supplied to depth
will return additional information beyond the default amount returned with a value of 0.
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}
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"
}
}
}
The following table describes the attributes found in the response body:
Name | Type | Description |
---|---|---|
id | string | The server's unique identifier. |
type | string | The type of object. "server" |
href | string | An API URL to the server’s representation (absolute path). |
metadata | collection | Server metadata. |
properties | collection | Server properties. |
entities | collection | Entities associated with the server. |
The metadata about the server includes:
Name | Type | Description |
---|---|---|
createdDate | string | The date the resource was created. |
createdBy | string | The user who created the resource. |
createdByUserId | string | The userId who created the resource. |
etag | string | The ETag. |
lastModifiedDate | string | The last modified time for the resource. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
state | string | AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued. INACTIVE The resource has been de-provisioned. |
The properties returned are:
Name | Type | Description |
---|---|---|
name | string | The name of the server. |
cores | int32 | The number of cores for the server. |
ram | int32 | The amount of memory on the server in MB. |
availabilityZone | string | The availability zone for the server. [ZONE_1, ZONE_2, AUTO] |
vmState | string | The current state of the virtual machine. [NOSTATE, RUNNING, BLOCKED, PAUSED, SHUTDOWN, SHUTOFF, CRASHED] |
bootCdrom | string | Reference to a CD-ROM used for booting. If not 'null' then bootVolume has to be 'null'. |
bootVolume | string | Reference to a volume used for booting. If not 'null' then bootCdrom has to be 'null'. |
cpuFamily | string | Type of CPU assigned. |
The entities returned include:
Name | Type | Description |
---|---|---|
cdroms | collection | A collection of CD-ROMs attached to the server. |
volumes | collection | A collection of volumes attached to the server. |
nics | collection | A collection of NICs attached to the server. |
At the default depth=0
, each of the entities will include an id, type, and
href that can be used to get additional information about the specific resource.
If you chose to pass the depth
query parameter with a value of 1
or greater, then
additional information about each server entity will be returned.
The following table enumerates the possible server states returned as vmState
:
State | Description |
---|---|
NOSTATE | The server has no state, e.g. provisioning is still in progress, server failed to boot once provisioned. |
RUNNING | The server is in a normal, running state. |
BLOCKED | The server is blocked from running. |
PAUSED | The server has been paused. While in paused state, the server will still consume allocated resources like memory but will not be eligible for scheduling. |
SHUTDOWN | The server is in the process of being shutdown correctly. |
SHUTOFF | The server is currently offline. |
CRASHED | The server is in a crashed, non-bootable state. |
You can retrieve a list of all servers within a VDC.
To retrieve a list of servers, send a GET request to
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers?depth=1
Note: For this particular operation, increasing the value supplied to depth
will return additional information beyond the default amount returned with a value of 0.
You can filter the result set using custom filters.
An example of using the custom filter to find all servers in a particular VDC that have 2 GB of RAM assigned:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers?filter.ram=2&depth=1
You can also filter on metadata such as lastModifiedBy:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers?filter.lastModifiedBy=joe&depth=1
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
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}"
} ]
}
The request will return a collection of servers.
The following table describes the attributes found in the response body:
Name | Type | Description |
---|---|---|
id | string | {dataCenterId}/servers |
type | string | The type of object that has been created. "collection" |
href | string | URL to the object’s representation (absolute path). |
items | collection | A collection of servers that are provisioned in the VDC. |
The items will have the following attributes.
Name | Type | Description |
---|---|---|
id | string | The server's unique identifier. |
type | string | The type of object. "server" |
href | string | An API URL to the server’s representation (absolute path). |
If you chose to pass the depth
query parameter with a value of 1
or greater, then
additional information about each server item will be returned. See the next section for additional details.
The Cloud API implements both PUT and PATCH for updates.
You may use PATCH to perform partial updates to the attributes of a server.
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}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
{serverId} | yes | string | n/a | The ID of a server. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
Name | Required | Type | Default | Description |
---|---|---|---|---|
name | no | string | n/a | A name for the server. |
cores | no | int32 | n/a | The total number of cores for the server. |
ram | no | int32 | n/a | The amount of memory for the server in MB, e.g. 2048. Size must be specified in multiples of
256 MB with a minimum of 256 MB; however, if you set ramHotPlug to TRUE then you must use a
minimum of 1024 MB. |
availabilityZone | no | string | AUTO | The compute availability zone in which the server should exist. [ZONE_1, ZONE_2, AUTO] |
cpuFamily | no | string | AMD_OPTERON | Sets the CPU type. For example "AMD_OPTERON", "INTEL_XEON", etc. Defaults to "AMD_OPTERON". |
bootVolume | no | string | n/a | Reference to a Volume used for booting. If not ‘null’ then bootCdrom has to be ‘null’. |
bootCdrom | no | string | n/a | Reference to a CD-ROM used for booting. If not 'null' then bootVolume has to be 'null'. |
Please Note: The allowReboot
parameter has been removed from Cloud API v5. Explicitely
allowing a reboot is not nescessary anymore.
If you try to set allowReboot
when using Cloud API v5 you should get an error message returned,
something similar to:
{
"httpStatus": 422,
"messages": [
{
"errorCode": "122",
"message": "[(root).properties.allowReboot] Failed to parse request body. Unrecognized field 'allowReboot'"
}
]
}
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}
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"
}
}
}
The following table describes the attributes found in the response body:
Name | Type | Description |
---|---|---|
id | string | The server's unique identifier. |
type | string | The type of object. "server" |
href | string | An API URL to the server’s representation (absolute path). |
metadata | collection | Server metadata. |
properties | collection | Server properties. |
entities | collection | Entities associated with the server. |
The metadata about the server includes:
Name | Type | Description |
---|---|---|
createdDate | string | The date the resource was created. |
createdBy | string | The user who created the resource. |
createdByUserId | string | The userId who created the resource. |
etag | string | The ETag. |
lastModifiedDate | string | The last modified time for the resource. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
state | string | AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued. INACTIVE The resource has been de-provisioned. |
The properties returned are:
Name | Type | Description |
---|---|---|
name | string | The name of the server. |
cores | int32 | The number of cores for the server. |
ram | int32 | The amount of memory on the server in MB. |
availabilityZone | string | The availability zone for the server. [ZONE_1, ZONE_2, AUTO] |
vmState | string | The current state of the virtual machine. [NOSTATE, RUNNING, BLOCKED, PAUSED, SHUTDOWN, SHUTOFF, CRASHED] |
bootCdrom | string | Reference to a CD-ROM used for booting. If not 'null' then bootVolume has to be 'null'. |
bootVolume | string | Reference to a Volume used for booting. If not 'null' then bootCdrom has to be 'null'. |
cpuFamily | string | Type of CPU assigned. |
The entities returned include:
Name | Type | Description |
---|---|---|
cdroms | collection | A collection of CD-ROMs attached to the server. |
volumes | collection | A collection of volumes attached to the server. |
nics | collection | A collection of NICs attached to the server. |
You may use PUT to perform an update of server properties.
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.
Name | Required | Type | Default | Description |
---|---|---|---|---|
name | no | string | n/a | A name for the server. |
cores | yes | int32 | n/a | The total number of cores for the server. |
ram | yes | int32 | n/a | The amount of memory for the server in MB, e.g. 2048. Size must be specified in multiples of
256 MB with a minimum of 256 MB; however, if you set ramHotPlug to TRUE then you must use a
minimum of 1024 MB. |
availabilityZone | no | string | AUTO | The compute availability zone in which the server should exist. [ZONE_1, ZONE_2, AUTO] |
cpuFamily | no | string | AMD_OPTERON | Sets the CPU type. For example: "AMD_OPTERON", "INTEL_XEON", …. Defaults to "AMD_OPTERON". |
bootVolume | no | string | n/a | Reference to a Volume used for booting. If not ‘null’ then bootCdrom has to be ‘null’. |
bootCdrom | no | string | n/a | Reference to a CD-ROM used for booting. If not 'null' then bootVolume has to be 'null'. |
Please Note: The allowReboot
parameter has been removed from Cloud API v5 and is not
nescessary anymore.
If you try to set allowReboot
when using Cloud API v5 you should get an error message returned,
something similar to:
{
"httpStatus": 422,
"messages": [
{
"errorCode": "122",
"message": "[(root).properties.allowReboot] Failed to parse request body. Unrecognized field 'allowReboot'"
}
]
}
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}
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.
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.
To remove a server, send a DELETE request to
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
{serverId} | yes | string | n/a | The ID of a server. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
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}
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.
Retrieves a list of volumes attached to the server.
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
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
{serverId} | yes | string | n/a | The ID of a server. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/volumes?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/volumes?depth=1
Note: For this particular operation, increasing the value supplied to depth
will return additional information beyond the default amount returned with a value of 0.
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
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
}
} ]
}
A collection of volumes is returned.
Please reference the Volumes section for attribute definitions.
This will attach a pre-existing storage volume to the server.
To attach a storage volume to a server, send a POST request to:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/volumes
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
{serverId} | yes | string | n/a | The ID of a server. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following table describes the request body values:
Name | Required | Type | Description |
---|---|---|---|
id | yes | string | The unique ID of a storage volume to attach. |
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
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
}
}
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".
This will retrieve the properties of an attached volume.
Send a GET request to:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/volumes/{volumeId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
{serverId} | yes | string | n/a | The ID of a server. |
{volumeId} | yes | string | n/a | The ID of a volume. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/volumes/{volumeId}?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/volumes/{volumeId}?depth=1
Note: For this particular operation, increasing the value supplied to depth
does
NOT return any additional information beyond the default amount returned with a value of
0.
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}
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
}
}
Please see the Volumes section for attribute definitions.
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.
Send a DELETE request to:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/volumes/{volumeId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a virtual data center. |
{serverId} | yes | string | n/a | The ID of a server. |
{volumeId} | yes | string | n/a | The ID of a volume. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
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}
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.
You can retrieve a list of CD-ROMs attached to the server.
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
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a virtual data center. |
{serverId} | yes | string | n/a | The ID of a server. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/cdroms?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/cdroms?depth=1
Note: For this particular operation, increasing the value supplied to depth
will return additional information beyond the default amount returned with a value of 0.
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
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.
Please reference the CD-ROMs section for attribute definitions.
You can attach a CD-ROM to an existing server.
To attach a CD-ROM to a server, send a POST request to:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/cdroms
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a virtual data center. |
{serverId} | yes | string | n/a | The ID of a server. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following table describes the request body values:
Name | Required | Type | Description |
---|---|---|---|
id | yes | string | The ID of a CD-ROM (ISO) image to attach. |
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
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
}
}
Please reference the CD-ROMs section for attribute definitions.
You can retrieve a specific CD-ROM attached to the server.
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]
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
{serverId} | yes | string | n/a | The ID of a server. |
{cdromId} | yes | string | n/a | The ID of the attached CD-ROM. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/cdroms?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/cdroms?depth=1
Note: For this particular operation, increasing the value supplied to depth
does
NOT return any additional information beyond the default amount returned with a value of
0.
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}
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
}
}
Please reference the CD-ROMs and Images section for attribute definitions.
This will detach a CD-ROM from the server.
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]
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
{serverId} | yes | string | n/a | The ID of a server. |
{cdromId} | yes | string | n/a | The ID of the attached CD-ROM. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
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}
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.
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.
To reboot a server, send a POST request to
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/reboot
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
{serverId} | yes | string | n/a | The ID of a server. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
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
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
None
This will start a server. If the server's public IP was deallocated then a new IP will be assigned.
To start a server, send a POST request to
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/start
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
{serverId} | yes | string | n/a | The ID of a server. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
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
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
None
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.
To stop a server you would send a POST request to
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/stop
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
{serverId} | yes | string | n/a | The ID of a server. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
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
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
None
Retrieves the attributes of a specific image.
To retrieve details on a single image send a GET request to
https://api.ionos.com/cloudapi/v5/images/{imageId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{imageId} | yes | string | n/a | The ID of an image. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/images?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/images?depth=1
Note: For this particular operation, increasing the value supplied to depth
does
NOT return any additional information beyond the default amount returned with a value of
0.
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}
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
}
}
The following table describes the attributes found in the JSON response body:
Name | Type | Description |
---|---|---|
id | string | The resource's unique identifier. |
type | string | The type of object that has been created. |
href | string | URL to the object’s representation (absolute path). |
metadata | collection | Image metadata. |
properties | collection | Image properties. |
The metadata returned includes the following attributes.
Name | Type | Description |
---|---|---|
createdDate | string | The date the resource was created. |
createdBy | string | The user who created the resource. |
createdByUserId | string | The userId who created the resource. |
etag | string | The ETag for the resource. |
lastModifiedDate | string | The last time the resource has been modified. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
state | string | Image state. |
The properties returned include the following attributes:
Name | Type | Description |
---|---|---|
name | string | The name of the image. |
description | string | The description of the image. |
location | string | The image's location. |
size | string | The size of the image in GB. |
cpuHotPlug | Boolean | This volume is capable of CPU hot plug (no reboot required). |
cpuHotUnplug | Boolean | This volume is capable of CPU hot unplug (no reboot required). |
ramHotPlug | Boolean | This volume is capable of memory hot plug (no reboot required). |
ramHotUnplug | Boolean | This volume is capable of memory hot unplug (no reboot required). |
nicHotPlug | Boolean | This volume is capable of NIC hot plug (no reboot required). |
nicHotUnplug | Boolean | This volume is capable of NIC hot unplug (no reboot required). |
discVirtioHotPlug | Boolean | This volume is capable of VirtIO drive hot plug (no reboot required). |
discVirtioHotUnplug | Boolean | This volume is capable of VirtIO drive hot unplug (no reboot required). |
discScsiHotPlug | Boolean | This volume is capable of SCSI drive hot plug (no reboot required). |
discScsiHotUnplug | Boolean | This volume is capable of SCSI drive hot unplug (no reboot required). |
licenceType | Boolean | The image's licence type: LINUX, WINDOWS, WINDOWS2016, OTHER, or UNKNOWN. |
imageType | Boolean | The type of image: HDD, CDROM (ISO). |
public | Boolean | Indicates if the image is part of the public repository (true) or not (false). |
Retrieve a list of images within the data center.
To retrieve a list of images submit a GET request to https://api.ionos.com/cloudapi/v5/images
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/images?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/images?depth=1
Note: For this particular operation, increasing the value supplied to depth
will return additional information beyond the default amount returned with a value of 0.
This API call could be used to return a set of images matching some specific criteria. To demonstrate, we will use
filter.<property>=<value>
to look for "public" images in the
selected location that, contain the string "cent" in the name, with an
imageType of "HDD". We will use orderBy
to sort the results based on the
lastModifiedDate
.
https://api.ionos.com/cloudapi/v5/images/?depth=1&filter.location={location}&filter.public=true&filter.imageType=hdd&filter.name=Cent&orderBy=lastModifiedDate
At the time of writing, this would return two results, one for CentOS 7 and one for CentOS 6.
{
"id": "images",
"type": "collection",
"href": "https://api.ionos.com/cloudapi/v5/images",
"items": [
{
"id": "79753350-a65e-11e7-90a7-525400f64d8d",
"type": "image",
"href": "https://api.ionos.com/cloudapi/v5/images/79753350-a65e-11e7-90a7-525400f64d8d",
"metadata": {
"createdDate": "2017-10-01T04:10:35Z",
"createdBy": "System",
"etag": "9559303a85b6df30a48cfc6b0a8db947",
"lastModifiedDate": "2017-10-01T04:10:35Z",
"lastModifiedBy": "System",
"state": "AVAILABLE"
},
"properties": {
"name": "CentOS-7-server-2017-10-01",
"description": null,
"location": "{regionId}/{locationId}",
"size": 2,
"imageType": "HDD",
"imageAliases": [
"centos:latest",
"centos:7"
],
"public": true
}
},
{
"id": "2b4bbb39-a75d-11e7-90a7-525400f64d8d",
"type": "image",
"href": "https://api.ionos.com/cloudapi/v5/images/2b4bbb39-a75d-11e7-90a7-525400f64d8d",
"metadata": {
"createdDate": "2017-10-02T10:33:45Z",
"createdBy": "System",
"etag": "ca605563b94d6c562ea38a610680cce8",
"lastModifiedDate": "2017-10-02T10:33:45Z",
"lastModifiedBy": "System",
"state": "AVAILABLE"
},
"properties": {
"name": "CentOS-6-server-2017-10-02",
"description": null,
"location": "{regionId}/{locationId}",
"size": 2,
"imageType": "HDD",
"imageAliases": [
"centos:6"
],
"public": true
}
}
]
}
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
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]"
} ]
}
The request will return a collection of images.
The following table describes the attributes found in the JSON response body:
Name | Type | Description |
---|---|---|
id | string | The resource's unique identifier. |
type | string | The type of object that has been created. |
href | string | URL to the object’s representation (absolute path). |
items | collection | A collection of image IDs. |
Each of the items returned has the following attributes.
Name | Type | Description |
---|---|---|
id | string | The resource's unique identifier. |
type | string | The type of object that has been created. |
href | string | URL to the object’s representation (absolute path). |
If you pass the query parameter depth
with a value greater than or equal to 1
then each of
the items will include additional attributes. See the next section for details.
The Cloud API implements both PUT and PATCH for updates.
Use PATCH to perform updates to attributes of a private image.
To perform an update to the private image's properties send a PATCH request to
https://api.ionos.com/cloudapi/v5/images/{imageId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{imageId} | yes | string | n/a | The ID of a private image. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
{
"description": "Updated Image Description"
}
Name | Required | Type | Description |
---|---|---|---|
name | no | string | The name of the image. |
description | no | string | The description of the image. |
licenceType | no | string | The image's licence type: LINUX, WINDOWS, WINDOWS2016, OTHER, or UNKNOWN. |
cpuHotPlug | no | Boolean | This volume is capable of CPU hot plug (no reboot required). |
cpuHotUnplug | no | Boolean | This volume is capable of CPU hot unplug (no reboot required). |
ramHotPlug | no | Boolean | This volume is capable of memory hot plug (no reboot required). |
ramHotUnplug | no | Boolean | This volume is capable of memory hot unplug (no reboot required). |
nicHotPlug | no | Boolean | This volume is capable of NIC hot plug (no reboot required). |
nicHotUnplug | no | Boolean | This volume is capable of NIC hot unplug (no reboot required). |
discVirtioHotPlug | no | Boolean | This volume is capable of VirtIO drive hot plug (no reboot required). |
discVirtioHotUnplug | no | Boolean | This volume is capable of VirtIO drive hot unplug (no reboot required). |
discScsiHotPlug | no | Boolean | This volume is capable of SCSI drive hot plug (no reboot required). |
discScsiHotUnplug | no | Boolean | This volume is capable of SCSI drive hot unplug (no reboot required). |
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}
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
}
}
The following table describes the attributes found in the JSON response body:
Name | Type | Description |
---|---|---|
id | string | The resource's unique identifier. |
type | string | The type of object that has been created. |
href | string | URL to the object’s representation (absolute path). |
metadata | collection | Image metadata. |
properties | collection | Image properties. |
The metadata returned includes the following attributes.
Name | Type | Description |
---|---|---|
createdDate | string | The date the resource was created. |
createdBy | string | The user who created the resource. |
createdByUserId | string | The userId who created the resource. |
etag | string | The ETag for the resource. |
lastModifiedDate | string | The last time the resource has been modified. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
state | string | Image state. |
The properties returned include the following attributes:
Name | Type | Description |
---|---|---|
name | string | The name of the image. |
description | string | The description of the image. |
location | string | The image's location. |
size | string | The size of the image in GB. |
cpuHotPlug | Boolean | This volume is capable of CPU hot plug (no reboot required). |
cpuHotUnplug | Boolean | This volume is capable of CPU hot unplug (no reboot required). |
ramHotPlug | Boolean | This volume is capable of memory hot plug (no reboot required). |
ramHotUnplug | Boolean | This volume is capable of memory hot unplug (no reboot required). |
nicHotPlug | Boolean | This volume is capable of NIC hot plug (no reboot required). |
nicHotUnplug | Boolean | This volume is capable of NIC hot unplug (no reboot required). |
discVirtioHotPlug | Boolean | This volume is capable of VirtIO drive hot plug (no reboot required). |
discVirtioHotUnplug | Boolean | This volume is capable of VirtIO drive hot unplug (no reboot required). |
discScsiHotPlug | Boolean | This volume is capable of SCSI drive hot plug (no reboot required). |
discScsiHotUnplug | Boolean | This volume is capable of SCSI drive hot unplug (no reboot required). |
licenceType | Boolean | The image's licence type: LINUX, WINDOWS, WINDOWS2016, OTHER, or UNKNOWN. |
imageType | Boolean | The type of image: HDD, CDROM (ISO). |
public | Boolean | Indicates if the image is part of the public repository (true) or not (false). |
Use PUT to perform an update of the attributes of an image.
To perform an update of the private image's properties send a PUT request to:
https://api.ionos.com/cloudapi/v5/images/{imageId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{imageId} | yes | string | n/a | The ID of a private image. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
{
"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
}
}
Name | Required | Type | Description |
---|---|---|---|
name | no | string | The name of the image. |
description | no | string | The description of the image. |
licenceType | yes | string | The image's licence type: LINUX, WINDOWS, WINDOWS2016, OTHER, or UNKNOWN. |
cpuHotPlug | no | Boolean | This volume is capable of CPU hot plug (no reboot required). |
cpuHotUnplug | no | Boolean | This volume is capable of CPU hot unplug (no reboot required). |
ramHotPlug | no | Boolean | This volume is capable of memory hot plug (no reboot required). |
ramHotUnplug | no | Boolean | This volume is capable of memory hot unplug (no reboot required). |
nicHotPlug | no | Boolean | This volume is capable of NIC hot plug (no reboot required). |
nicHotUnplug | no | Boolean | This volume is capable of NIC hot unplug (no reboot required). |
discVirtioHotPlug | no | Boolean | This volume is capable of VirtIO drive hot plug (no reboot required). |
discVirtioHotUnplug | no | Boolean | This volume is capable of VirtIO drive hot unplug (no reboot required). |
discScsiHotPlug | no | Boolean | This volume is capable of SCSI drive hot plug (no reboot required). |
discScsiHotUnplug | no | Boolean | This volume is capable of SCSI drive hot unplug (no reboot required). |
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}
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
}
}
The following table describes the attributes found in the JSON response body:
Name | Type | Description |
---|---|---|
id | string | The resource's unique identifier. |
type | string | The type of object that has been created. |
href | string | URL to the object’s representation (absolute path). |
metadata | collection | Image metadata. |
properties | collection | Image properties. |
The metadata returned includes the following attributes.
Name | Type | Description |
---|---|---|
createdDate | string | The date the resource was created. |
createdBy | string | The user who created the resource. |
createdByUserId | string | The userId who created the resource. |
etag | string | The ETag for the resource. |
lastModifiedDate | string | The last time the resource has been modified. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
state | string | Image state. |
The properties returned include the following attributes:
Name | Type | Description |
---|---|---|
name | string | The name of the image. |
description | string | The description of the image. |
location | string | The image's location. |
size | string | The size of the image in GB. |
cpuHotPlug | Boolean | This volume is capable of CPU hot plug (no reboot required). |
cpuHotUnplug | Boolean | This volume is capable of CPU hot unplug (no reboot required). |
ramHotPlug | Boolean | This volume is capable of memory hot plug (no reboot required). |
ramHotUnplug | Boolean | This volume is capable of memory hot unplug (no reboot required). |
nicHotPlug | Boolean | This volume is capable of NIC hot plug (no reboot required). |
nicHotUnplug | Boolean | This volume is capable of NIC hot unplug (no reboot required). |
discVirtioHotPlug | Boolean | This volume is capable of VirtIO drive hot plug (no reboot required). |
discVirtioHotUnplug | Boolean | This volume is capable of VirtIO drive hot unplug (no reboot required). |
discScsiHotPlug | Boolean | This volume is capable of SCSI drive hot plug (no reboot required). |
discScsiHotUnplug | Boolean | This volume is capable of SCSI drive hot unplug (no reboot required). |
licenceType | Boolean | The image's licence type: LINUX, WINDOWS, WINDOWS2016, OTHER, or UNKNOWN. |
imageType | Boolean | The type of image: HDD, CDROM (ISO). |
public | Boolean | Indicates if the image is part of the public repository (true) or not (false). |
Deletes the specified private image. This only applies to private images that you have uploaded.
To delete an image send a DELETE request to https://api.ionos.com/cloudapi/v5/images/{imageId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{imageId} | yes | string | n/a | The ID of a private image. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
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}
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"
} ]
}
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.
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.
To create a volume send a POST request to
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of the virtual data center. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
Construct your JSON request body by specifying the attributes of the volume.
Name | Required | Type | Default | Description |
---|---|---|---|---|
name | no | string | n/a | The name of the volume. |
size | yes | number | n/a | The size of the volume in GB. |
bus | no | string | VIRTIO | The bus type of the volume ["VIRTIO" or "IDE"] |
image | yes | string | n/a | The image or snapshot ID. |
imageAlias | yes | string | n/a | An alias to a IONOS public image. Use instead of "image". |
type | yes | string | n/a | The volume type. ["HDD", "SSD", "SSD Standard" or "SSD Premium"] |
licenceType | yes | string | n/a | The licence type of the volume. Options: LINUX, WINDOWS, WINDOWS2016, UNKNOWN, OTHER |
imagePassword | yes | string | n/a | A password is set on the image for the "root" or "Administrator" account. This field may only be set during volume creation. Only valid with supplied HDD (not ISO) images. The password must contain at least 8 and no more than 50 characters. Only these characters are allowed: [a-z][A-Z][0-9] |
sshKeys | yes | Array[string] | n/a | One or more SSH keys to allow access to the volume via SSH. Only valid with supplied Linux HDD (not ISO) images. |
availabilityZone | no | string | AUTO | The storage availability zone assigned to the volume. Valid values: AUTO, ZONE_1, ZONE_2, or ZONE_3. This only applies to HDD volumes. Leave blank or set to AUTO when provisioning SSD volumes. |
cpuHotPlug | no | Boolean | false | This volume is capable of CPU hot plug (no reboot required) |
ramHotPlug | no | Boolean | false | This volume is capable of memory hot plug (no reboot required) |
nicHotPlug | no | Boolean | false | This volume is capable of NIC hot plug (no reboot required) |
nicHotUnplug | no | Boolean | false | This volume is capable of NIC hot unplug (no reboot required) |
discVirtioHotPlug | no | Boolean | false | This volume is capable of VirtIO drive hot plug (no reboot required) |
discVirtioHotUnplug | no | Boolean | false | This volume is capable of VirtIO drive hot unplug (no reboot required) |
Note: The "Required" column needs some additional explanation. You will need to provide a
valid value for either the image
, imageAlias
, or the licenceType
parameters.
The licenceType
is required, but if image
or imageAlias
is supplied, then
licenceType
is already set and cannot be changed. Similarly either the imagePassword
or
sshKeys
attributes need to be defined when creating a volume that uses an image
or
imageAlias
of an IONOS public HDD image. You may wish to set a valid value for
imagePassword
even when using sshKeys
so that it is possible to authenticate with a
password
when using the remote console feature of the DCD. Alternatively, you can load your SSH Keys into the DCD. Because
the
allowed character values for imagePassword
are limited, it would be a good idea to change to a more
complex password after you initially access a server. This is especially applicable for servers that are connected
to
the public internet full-time.
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"
}
}
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
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
}
}
These attributes are found in the JSON response body:
Name | Type | Description |
---|---|---|
id | string | The resource's unique identifier. |
type | string | The type of object that has been created. Should be "volume". |
href | string | URL to the volume. |
metadata | collection | Volume metadata. |
properties | collection | Volume properties. |
The metadata returned for the volume:
Name | Type | Description |
---|---|---|
createdDate | string | The date the volume was created. |
createdBy | string | The user who created the volume. |
createdByUserId | string | The userId who created the resource. |
etag | string | The etag for the resource. |
lastModifiedDate | string | The last time the resource has been modified. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
state | string | The Volume state. AVAILABLE, BUSY, INACTIVE |
The properties returned for the volume:
Name | Type | Description |
---|---|---|
name | string | The name of the volume. |
type | string | The volume type, [HDD, SSD, SSD Standard or SSD Premium]. |
size | int32 | The size of the volume in GB. |
availabilityZone | string | The storage availability zone assigned to the volume. [AUTO, ZONE_1, ZONE_2, or ZONE_3] |
image | string | The image or snapshot ID. |
imageAlias | string | Always returns "null". |
imagePassword | string | Always returns "null". |
sshKeys | string | Always returns "null". |
bus | string | The bus type: VIRTIO or IDE. Returns "null" if not connected to a server. |
licenceType | string | Licence type. [WINDOWS, WINDOWS2016, LINUX, OTHER, UNKNOWN] |
cpuHotPlug | Boolean | This volume is capable of CPU hot plug (no reboot required) |
cpuHotUnplug | Boolean | This volume is capable of CPU hot unplug (no reboot required) |
ramHotPlug | Boolean | This volume is capable of memory hot plug (no reboot required) |
ramHotUnplug | Boolean | This volume is capable of memory hot unplug (no reboot required) |
nicHotPlug | Boolean | This volume is capable of NIC hot plug (no reboot required) |
nicHotUnplug | Boolean | This volume is capable of NIC hot unplug (no reboot required) |
discVirtioHotPlug | Boolean | This volume is capable of VirtIO drive hot plug (no reboot required) |
discVirtioHotUnplug | Boolean | This volume is capable of VirtIO drive hot unplug (no reboot required) |
deviceNumber | int32 | The LUN ID of the storage volume. Returns "null" for volumes not mounted/attached to a server. |
Helpful errors are returned if the request contains invalid data:
{
"httpStatus" : 422,
"messages" : [ {
"errorCode" : "100",
"message" : "[(root).properties.imagePassword] Password syntax error Password invalid, valid characters are:a-zA-Z0-9. Length between 8 and 50."
}, {
"errorCode" : "100",
"message" : "[(root).properties.licenceType] Attribute must not be set if 'image' is set"
} ]
}
Retrieves the attributes of a given volume.
To retrieve a single volume you would send a GET request to
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes/{volumeId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of the virtual data center. |
{volumeId} | yes | string | n/a | The ID of the volume. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/?depth=1
Note: For this particular operation, increasing the value supplied to depth
does
NOT return any additional information beyond the default amount returned with a value of
0.
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}
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
}
}
The request will return a collection of volumes.
If you used the optional depth parameter (?depth=1) to the end of the request you will receive more detailed output on each of the volumes. The output will be similar to what is returned when issuing a GET request for each specific volume.
These attributes are found in the JSON response body:
Name | Type | Description |
---|---|---|
id | string | The resource's unique identifier. |
type | string | The type of object that has been created. Should be "volume". |
href | string | URL to the volume. |
metadata | collection | Volume metadata. |
properties | collection | Volume properties. |
The metadata returned for each volume:
Name | Type | Description |
---|---|---|
createdDate | string | The date the volume was created. |
createdBy | string | The user who created the volume. |
createdByUserId | string | The userId who created the resource. |
etag | string | The etag for the resource. |
lastModifiedDate | string | The last time the resource has been modified. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
state | string | The Volume state. AVAILABLE, BUSY, INACTIVE |
The properties returned for each volume:
Name | Type | Description |
---|---|---|
name | string | The name of the volume. |
type | string | The volume type, [HDD, SSD, SSD Standard or SSD Premium]. |
size | int32 | The size of the volume in GB. |
availabilityZone | string | The storage availability zone assigned to the volume. [AUTO, ZONE_1, ZONE_2, or ZONE_3] |
image | string | The image or snapshot ID. |
imageAlias | string | Always returns "null". |
imagePassword | string | Always returns "null". |
sshKeys | string | Always returns "null". |
bus | string | The bus type: VIRTIO or IDE. Returns "null" if not connected to a server. |
licenceType | string | Licence type. ( WINDOWS, WINDOWS2016, LINUX, OTHER, UNKNOWN) |
cpuHotPlug | Boolean | This volume is capable of CPU hot plug (no reboot required) |
cpuHotUnplug | Boolean | This volume is capable of CPU hot unplug (no reboot required) |
ramHotPlug | Boolean | This volume is capable of memory hot plug (no reboot required) |
ramHotUnplug | Boolean | This volume is capable of memory hot unplug (no reboot required) |
nicHotPlug | Boolean | This volume is capable of NIC hot plug (no reboot required) |
nicHotUnplug | Boolean | This volume is capable of NIC hot unplug (no reboot required) |
discVirtioHotPlug | Boolean | This volume is capable of VirtIO drive hot plug (no reboot required) |
discVirtioHotUnplug | Boolean | This volume is capable of VirtIO drive hot unplug (no reboot required) |
deviceNumber | int32 | The LUN ID of the storage volume. Returns "null" for volumes not mounted/attached to a server. |
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.
To retrieve a list of volumes send a GET request to
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of the virtual data center. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes?depth=1
Note: For this particular operation, increasing the value supplied to depth
will return additional information beyond the default amount returned with a value of 0.
You can filter the result set using custom filters.
An example of using the custom filter to find all volumes in a particular virtual data center that have a licenceType of "OTHER" assigned:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes?filter.licenceType=other&depth=1
You can also filter on metadata such as createdBy. This example would return volumes that contain the string "joe" in createdBy:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes?filter.createdBy=joe&depth=1
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
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}"
} ]
}
The request will return a collection of volumes.
If you used the optional depth parameter (?depth=1) to the end of the request you will receive more detailed output on each of the volumes. The output will be similar to what is returned when issuing a GET request for each specific volume.
These attributes are found in the JSON response body:
Name | Type | Description |
---|---|---|
id | string | The resource's unique identifier. |
type | string | The type of object that has been created. Should be "collection". |
href | string | URL to the volumes collection. |
items | collection | A collection of volumes. |
At the default depth=0
each of the items will have the following attributes:
Name | Type | Description |
---|---|---|
id | string | The resource's unique identifier. |
type | string | The type of object that has been created. Should be "volume". |
href | string | A URL to the specific volume. |
Increasing to depth=1
, additional information is returned for each volume in items as described
in the next section.
Name | Type | Description |
---|---|---|
id | string | The resource's unique identifier. |
type | string | The type of object that has been created. Should be "volume". |
href | string | A URL to the specific volume. |
metadata | collection | Volume metadata. |
properties | collection | Volume properties. |
The metadata returned for each volume:
Name | Type | Description |
---|---|---|
createdDate | string | The date the volume was created. |
createdBy | string | The user who created the volume. |
createdByUserId | string | The userId who created the resource. |
etag | string | The etag for the resource. |
lastModifiedDate | string | The last time the resource has been modified. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
state | string | The Volume state. AVAILABLE, BUSY, INACTIVE |
The properties returned for each volume:
Name | Type | Description |
---|---|---|
name | string | The name of the volume. |
type | string | The volume type, [HDD, SSD, SSD Standard or SSD Premium]. |
size | int32 | The size of the volume in GB. |
availabilityZone | string | The storage availability zone assigned to the volume. [AUTO, ZONE_1, ZONE_2, or ZONE_3] |
image | string | The image or snapshot ID. |
imageAlias | string | Always returns "null". |
imagePassword | string | Always returns "null". |
sshKeys | string | Always returns "null". |
bus | string | The bus type: VIRTIO or IDE. Returns "null" if not connected to a server. |
licenceType | string | Licence type. [WINDOWS, WINDOWS2016, LINUX, OTHER, UNKNOWN] |
cpuHotPlug | Boolean | This volume is capable of CPU hot plug (no reboot required) |
cpuHotUnplug | Boolean | This volume is capable of CPU hot unplug (no reboot required) |
ramHotPlug | Boolean | This volume is capable of memory hot plug (no reboot required) |
ramHotUnplug | Boolean | This volume is capable of memory hot unplug (no reboot required) |
nicHotPlug | Boolean | This volume is capable of NIC hot plug (no reboot required) |
nicHotUnplug | Boolean | This volume is capable of NIC hot unplug (no reboot required) |
discVirtioHotPlug | Boolean | This volume is capable of VirtIO drive hot plug (no reboot required) |
discVirtioHotUnplug | Boolean | This volume is capable of VirtIO drive hot unplug (no reboot required) |
deviceNumber | int32 | The LUN ID of the storage volume. Returns "null" for volumes not mounted/attached to a server. |
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"
} ]
}
Use PATCH to perform an update to the attributes of a volume.
To perform an update to the volume's properties send a PATCH request to
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes/{volumeId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of the VDC. |
{volumeId} | yes | string | n/a | The ID of a volume. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
Since we are modifying an existing volume, none of the request parameters are specifically required. However, many of the volume parameters are immutable or read-only once a volume is created and therefore cannot be changed with a PATCH request.
Header | Required | Type | Description |
---|---|---|---|
name | no | string | The name of the volume. |
size | no | int32 | The size of the volume in GB. Can only be increased, not decreased. |
bus | no | string | The bus type of the volume ["VIRTIO" or "IDE"]. |
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}
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
}
}
These attributes are found in the JSON response body:
Name | Type | Description |
---|---|---|
id | string | The resource's unique identifier. |
type | string | The type of object that has been created. Should be "volume". |
href | string | URL to the volume. |
metadata | collection | Volume metadata. |
properties | collection | Volume properties. |
The metadata returned for the volume:
Name | Type | Description |
---|---|---|
createdDate | string | The date the volume was created. |
createdBy | string | The user who created the volume. |
createdByUserId | string | The userId who created the resource. |
etag | string | The etag for the resource. |
lastModifiedDate | string | The last time the resource has been modified. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
state | string | The Volume state. AVAILABLE, BUSY, INACTIVE |
The properties returned for the volume:
Name | Type | Description |
---|---|---|
name | string | The name of the volume. |
type | string | The volume type, [HDD, SSD, SSD Standard or SSD Premium]. |
size | int32 | The size of the volume in GB. |
availabilityZone | string | The storage availability zone assigned to the volume. [AUTO, ZONE_1, ZONE_2, or ZONE_3] |
image | string | The image or snapshot ID. |
imageAlias | string | Always returns "null". |
imagePassword | string | Always returns "null". |
sshKeys | string | Always returns "null". |
bus | string | The bus type: VIRTIO or IDE. Returns "null" if not connected to a server. |
licenceType | string | Licence type. [WINDOWS, WINDOWS2016, LINUX, OTHER, UNKNOWN] |
cpuHotPlug | Boolean | This volume is capable of CPU hot plug (no reboot required) |
cpuHotUnplug | Boolean | This volume is capable of CPU hot unplug (no reboot required) |
ramHotPlug | Boolean | This volume is capable of memory hot plug (no reboot required) |
ramHotUnplug | Boolean | This volume is capable of memory hot unplug (no reboot required) |
nicHotPlug | Boolean | This volume is capable of NIC hot plug (no reboot required) |
nicHotUnplug | Boolean | This volume is capable of NIC hot unplug (no reboot required) |
discVirtioHotPlug | Boolean | This volume is capable of VirtIO drive hot plug (no reboot required) |
discVirtioHotUnplug | Boolean | This volume is capable of VirtIO drive hot unplug (no reboot required) |
deviceNumber | int32 | The LUN ID of the storage volume. Returns "null" for volumes not mounted/attached to a server. |
Use PUT to perform an update of the attributes of a volume.
To perform an update of the volume's properties send a PUT request to:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes/{volumeId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of the virtual data center. |
{volumeId} | yes | string | n/a | The ID of a volume. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The majority of volume properties can only be set at volume creation and cannot be updated with a PUT request. Unlike the PATCH request described above, using PUT requires that you pass in a value for size even if it isn't being changed.
Header | Required | Type | Description |
---|---|---|---|
name | no | string | The name of the volume. |
size | yes | int32 | The size of the volume in GB. Can only be increased, not decreased. |
bus | no | string | The bus type of the volume ["VIRTIO" or "IDE"]. |
Attempting to change other parameters will result in a response similar to this:
{
"httpStatus" : 422,
"messages" : [ {
"errorCode" : "102",
"message" : "[(root).properties.availabilityZone] Attribute is immutable, therefore not allowed in update requests"
}, {
"errorCode" : "102",
"message" : "[(root).properties.type] Attribute is immutable, therefore not allowed in update requests"
}, {
"errorCode" : "102",
"message" : "[(root).properties.imagePassword] Attribute is immutable, therefore not allowed in update requests"
}, {
"errorCode" : "104",
"message" : "[(root).properties.nicHotUnplug] Attribute is read-only"
} ]
}
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}
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
}
}
These attributes are found in the JSON response body:
Name | Type | Description |
---|---|---|
id | string | The resource's unique identifier. |
type | string | The type of object that has been created. Should be "volume". |
href | string | URL to the volume. |
metadata | collection | Volume metadata. |
properties | collection | Volume properties. |
The metadata returned for the volume:
Name | Type | Description |
---|---|---|
createdDate | string | The date the volume was created. |
createdBy | string | The user who created the volume. |
createdByUserId | string | The userId who created the resource. |
etag | string | The etag for the resource. |
lastModifiedDate | string | The last time the resource has been modified. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
state | string | The Volume state. AVAILABLE, BUSY, INACTIVE |
The properties returned for the volume:
Name | Type | Description |
---|---|---|
name | string | The name of the volume. |
type | string | The volume type, [HDD, SSD, SSD Standard or SSD Premium]. |
size | int32 | The size of the volume in GB. |
availabilityZone | string | The storage availability zone assigned to the volume. [AUTO, ZONE_1, ZONE_2, or ZONE_3] |
image | string | The image or snapshot ID. |
imageAlias | string | Always returns "null". |
imagePassword | string | Always returns "null". |
sshKeys | string | Always returns "null". |
bus | string | The bus type: VIRTIO or IDE. Returns "null" if not connected to a server. |
licenceType | string | Licence type. [WINDOWS, WINDOWS2016, LINUX, OTHER, UNKNOWN] |
cpuHotPlug | Boolean | This volume is capable of CPU hot plug (no reboot required) |
cpuHotUnplug | Boolean | This volume is capable of CPU hot unplug (no reboot required) |
ramHotPlug | Boolean | This volume is capable of memory hot plug (no reboot required) |
ramHotUnplug | Boolean | This volume is capable of memory hot unplug (no reboot required) |
nicHotPlug | Boolean | This volume is capable of NIC hot plug (no reboot required) |
nicHotUnplug | Boolean | This volume is capable of NIC hot unplug (no reboot required) |
discVirtioHotPlug | Boolean | This volume is capable of VirtIO drive hot plug (no reboot required) |
discVirtioHotUnplug | Boolean | This volume is capable of VirtIO drive hot unplug (no reboot required) |
deviceNumber | int32 | The LUN ID of the storage volume. Returns "null" for volumes not mounted/attached to a server. |
Deletes the specified volume. This will result in the volume being removed from your virtual data center. Please use this with caution!
To delete a volume send a DELETE request to
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes/{volumeId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of the virtual data center. |
{volumeId} | yes | string | n/a | The ID of a volume. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
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}
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 with a successful DELETE call.
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.
To create a volume snapshot send a POST request to
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes/{volumeId}/create-snapshot
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of the VDC. |
{volumeId} | yes | string | n/a | The ID of a volume. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
Name | Required | Type | Description |
---|---|---|---|
name | yes | string | The name of the snapshot. |
description | no | string | The description of the snapshot. |
licenceType | no | string | Set to one of the values: [WINDOWS, WINDOWS2016, LINUX, OTHER, UNKNOWN] |
Note: You will need to URL encode the name and description values and pass that as data to the request.
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.
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".
These attributes are found in the JSON response body:
Name | Type | Description |
---|---|---|
id | string | The resource's unique identifier. |
type | string | The type of object that has been created. Should be "snapshot". |
href | string | URL to the snapshot. |
metadata | collection | Snapshot metadata. |
properties | collection | Snapshot properties. |
The metadata returned for the snapshot:
Name | Type | Description |
---|---|---|
createdDate | string | The date the snapshot was created. |
createdBy | string | The user who created the snapshot. |
createdByUserId | string | The userId who created the resource. |
etag | string | The etag for the resource. |
lastModifiedDate | string | The last time the resource has been modified. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
state | string | The snapshot state. [AVAILABLE, BUSY, INACTIVE] |
The properties returned for the snapshot:
Name | Type | Description |
---|---|---|
name | string | The name of the snapshot. |
description | string | A description of the snapshot. |
location | string | The location where the snapshot is stored. |
size | int32 | The size of the snapshot in GB. |
cpuHotPlug | Boolean | This volume is capable of CPU hot plug (no reboot required) |
cpuHotUnplug | Boolean | This volume is capable of CPU hot unplug (no reboot required) |
ramHotPlug | Boolean | This volume is capable of memory hot plug (no reboot required) |
ramHotUnplug | Boolean | This volume is capable of memory hot unplug (no reboot required) |
nicHotPlug | Boolean | This volume is capable of NIC hot plug (no reboot required) |
nicHotUnplug | Boolean | This volume is capable of NIC hot unplug (no reboot required) |
discVirtioHotPlug | Boolean | This volume is capable of VirtIO drive hot plug (no reboot required) |
discVirtioHotUnplug | Boolean | This volume is capable of VirtIO drive hot unplug (no reboot required) |
licenceType | string | Licence type. [WINDOWS, WINDOWS2016, LINUX, OTHER, UNKNOWN] |
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.
To restore a snapshot send a POST request to
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/volumes/{volumeId}/restore-snapshot
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of the VDC. |
{volumeId} | yes | string | n/a | The ID of a volume. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
Name | Required | Type | Description |
---|---|---|---|
snapshotId | yes | string | This is the ID of the snapshot. |
You will need to URL encode the snapshotId value and pass that as data to the request.
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'
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"
}
]
}
}
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
Retrieves the attributes of a specific snapshot.
To retrieve details about a specific snapshot, send a GET request to
https://api.ionos.com/cloudapi/v5/snapshots/{snapshotId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{snapshotId} | yes | string | n/a | The ID of a snapshot. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/snapshots/{snapshotId}?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/snapshots/{snapshotId}?depth=1
Note: For this particular operation, increasing the value supplied to depth
does
NOT return any additional information beyond the default amount returned with a value of
0.
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}
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"
}
}
Name | Type | Description |
---|---|---|
id | string | The snapshot's unique identifier. |
type | string | The type of object. In this case: "snapshot" |
href | string | URL to the object’s representation (absolute path). |
metadata | collection | Snapshot metadata. |
properties | collection | Snapshot properties. |
The metadata returned for the snapshot:
Name | Type | Description |
---|---|---|
createdDate | string | The date the snapshot was created. |
createdBy | string | The user who created the snapshot. |
createdByUserId | string | The userId who created the resource. |
etag | string | The etag for the resource. |
lastModifiedDate | string | The last time the resource has been modified. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
state | string | The snapshot state. [AVAILABLE, BUSY, INACTIVE] |
The properties returned for the snapshot:
Name | Type | Description |
---|---|---|
name | string | The name of the snapshot. |
description | string | A description of the snapshot. |
location | string | The location where the snapshot is stored. |
size | int32 | The size of the snapshot in GB. |
cpuHotPlug | Boolean | This volume is capable of CPU hot plug (no reboot required) |
cpuHotUnplug | Boolean | This volume is capable of CPU hot unplug (no reboot required) |
ramHotPlug | Boolean | This volume is capable of memory hot plug (no reboot required) |
ramHotUnplug | Boolean | This volume is capable of memory hot unplug (no reboot required) |
nicHotPlug | Boolean | This volume is capable of NIC hot plug (no reboot required) |
nicHotUnplug | Boolean | This volume is capable of NIC hot unplug (no reboot required) |
discVirtioHotPlug | Boolean | This volume is capable of VirtIO drive hot plug (no reboot required) |
discVirtioHotUnplug | Boolean | This volume is capable of VirtIO drive hot unplug (no reboot required) |
discScsiHotPlug | Boolean | This volume is capable of SCSI drive hot plug (no reboot required) |
discScsiHotUnplug | Boolean | This volume is capable of SCSI drive hot unplug (no reboot required) |
licenceType | string | Licence type. [WINDOWS, WINDOWS2016, LINUX, OTHER, UNKNOWN] |
Retrieve a list of snapshots.
Retrieve a list of snapshots by submitting a GET request to https://api.ionos.com/cloudapi/v5/snapshots
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/snapshots?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/snapshots?depth=1
Note: For this particular operation, increasing the value supplied to depth
will return additional information beyond the default amount returned with a value of 0.
You can filter the result set using custom filters.
An example of using the custom filter to find all snapshots in a particular location:
https://api.ionos.com/cloudapi/v5/snapshots?filter.location=las
You can also filter on metadata such as createdBy. This example refines the filter above to limit results to snapshots created by a specific user and also adds the depth parameter so additional info about each matching snapshot is returned:
https://api.ionos.com/cloudapi/v5/snapshots?filter.location=las&filter.createdBy=joe&depth=1
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
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}"
} ]
}
The request will return a collection of snapshots.
The following table describes the attributes found in the response body:
Name | Type | Description |
---|---|---|
id | string | "snapshots" |
type | string | The type of object. In this case: "collection" |
href | string | URL to the object’s representation (absolute path). |
items | collection | A collection of snapshots. |
At the default depth=0
each of the items returned has the following attributes:
Name | Type | Description |
---|---|---|
id | string | The snapshot's unique identifier. |
type | string | The type of object. In this case: "snapshot" |
href | string | URL to the object’s representation (absolute path). |
If the query parameter depth=1
is used, then each of the items returned has the following
attributes:
Name | Type | Description |
---|---|---|
id | string | The snapshot's unique identifier. |
type | string | The type of object. In this case: "snapshot" |
href | string | URL to the object’s representation (absolute path). |
metadata | collection | Snapshot metadata. |
properties | collection | Snapshot properties. |
The metadata returned for the snapshot:
Name | Type | Description |
---|---|---|
createdDate | string | The date the snapshot was created. |
createdBy | string | The user who created the snapshot. |
createdByUserId | string | The userId who created the resource. |
etag | string | The etag for the resource. |
lastModifiedDate | string | The last time the resource has been modified. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
state | string | The snapshot state. [AVAILABLE, BUSY, INACTIVE] |
The properties returned for the snapshot:
Name | Type | Description |
---|---|---|
name | string | The name of the snapshot. |
description | string | A description of the snapshot. |
location | string | The location where the snapshot is stored. |
size | int32 | The size of the snapshot in GB. |
cpuHotPlug | Boolean | This volume is capable of CPU hot plug (no reboot required) |
cpuHotUnplug | Boolean | This volume is capable of CPU hot unplug (no reboot required) |
ramHotPlug | Boolean | This volume is capable of memory hot plug (no reboot required) |
ramHotUnplug | Boolean | This volume is capable of memory hot unplug (no reboot required) |
nicHotPlug | Boolean | This volume is capable of NIC hot plug (no reboot required) |
nicHotUnplug | Boolean | This volume is capable of NIC hot unplug (no reboot required) |
discVirtioHotPlug | Boolean | This volume is capable of VirtIO drive hot plug (no reboot required) |
discVirtioHotUnplug | Boolean | This volume is capable of VirtIO drive hot unplug (no reboot required) |
discScsiHotPlug | Boolean | This volume is capable of SCSI drive hot plug (no reboot required) |
discScsiHotUnplug | Boolean | This volume is capable of SCSI drive hot unplug (no reboot required) |
licenceType | string | Licence type. [WINDOWS, WINDOWS2016, LINUX, OTHER, UNKNOWN] |
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.
Use PATCH to perform updates to the attributes of an snapshot.
To perform an update to the snapshot's properties, submit a PATCH request to
https://api.ionos.com/cloudapi/v5/snapshots/{snapshotId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{snapshotId} | yes | string | n/a | The ID of the snapshot. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
Name | Required | Type | Description |
---|---|---|---|
name | no | string | The name of the snapshot. |
description | no | string | The description of the snapshot. |
cpuHotPlug | no | bool | This volume is capable of CPU hot plug (no reboot required) |
cpuHotUnplug | no | bool | This volume is capable of CPU hot unplug (no reboot required) |
ramHotPlug | no | bool | This volume is capable of memory hot plug (no reboot required) |
ramHotUnplug | no | bool | This volume is capable of memory hot unplug (no reboot required) |
nicHotPlug | no | bool | This volume is capable of NIC hot plug (no reboot required) |
nicHotUnplug | no | bool | This volume is capable of NIC hot unplug (no reboot required) |
discVirtioHotPlug | no | bool | This volume is capable of VirtIO drive hot plug (no reboot required) |
discVirtioHotUnplug | no | bool | This volume is capable of VirtIO drive hot unplug (no reboot required) |
discScsiHotPlug | no | bool | This volume is capable of SCSI drive hot plug (no reboot required) |
discScsiHotUnplug | no | bool | This volume is capable of SCSI drive hot unplug (no reboot required) |
licenceType | no | string | The snapshot's licence type: [LINUX, WINDOWS, WINDOWS2016, OTHER, UNKNOWN] |
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}
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"
}
}
The JSON response body will contain the following attributes:
Name | Type | Description |
---|---|---|
id | string | The snapshot's unique identifier. |
type | string | The type of object. In this case: "snapshot" |
href | string | URL to the object’s representation (absolute path). |
metadata | collection | Snapshot metadata. |
properties | collection | Snapshot properties. |
The metadata returned for the snapshot:
Name | Type | Description |
---|---|---|
createdDate | string | The date the snapshot was created. |
createdBy | string | The user who created the snapshot. |
createdByUserId | string | The userId who created the resource. |
etag | string | The etag for the resource. |
lastModifiedDate | string | The last time the resource has been modified. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
state | string | The snapshot state. [AVAILABLE, BUSY, INACTIVE] |
The properties returned for the snapshot:
Name | Type | Description |
---|---|---|
name | string | The name of the snapshot. |
description | string | A description of the snapshot. |
location | string | The location where the snapshot is stored. |
size | int32 | The size of the snapshot in GB. |
cpuHotPlug | Boolean | This volume is capable of CPU hot plug (no reboot required) |
cpuHotUnplug | Boolean | This volume is capable of CPU hot unplug (no reboot required) |
ramHotPlug | Boolean | This volume is capable of memory hot plug (no reboot required) |
ramHotUnplug | Boolean | This volume is capable of memory hot unplug (no reboot required) |
nicHotPlug | Boolean | This volume is capable of NIC hot plug (no reboot required) |
nicHotUnplug | Boolean | This volume is capable of NIC hot unplug (no reboot required) |
discVirtioHotPlug | Boolean | This volume is capable of VirtIO drive hot plug (no reboot required) |
discVirtioHotUnplug | Boolean | This volume is capable of VirtIO drive hot unplug (no reboot required) |
discScsiHotPlug | Boolean | This volume is capable of SCSI drive hot plug (no reboot required) |
discScsiHotUnplug | Boolean | This volume is capable of SCSI drive hot unplug (no reboot required) |
licenceType | string | Licence type. [WINDOWS, WINDOWS2016, LINUX, OTHER, UNKNOWN] |
Use PUT to perform an update of the attributes of a snapshot.
To perform an update of the snapshot's properties, send a PUT request to:
https://api.ionos.com/cloudapi/v5/snapshots/{snapshotId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{snapshotId} | yes | string | n/a | The ID of the snapshot. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
Name | Required | Type | Description |
---|---|---|---|
name | no | string | The name of the snapshot. |
description | no | string | The description of the snapshot. |
cpuHotPlug | no | bool | This volume is capable of CPU hot plug (no reboot required) |
cpuHotUnplug | no | bool | This volume is capable of CPU hot unplug (no reboot required) |
ramHotPlug | no | bool | This volume is capable of memory hot plug (no reboot required) |
ramHotUnplug | no | bool | This volume is capable of memory hot unplug (no reboot required) |
nicHotPlug | no | bool | This volume is capable of NIC hot plug (no reboot required) |
nicHotUnplug | no | bool | This volume is capable of NIC hot unplug (no reboot required) |
discVirtioHotPlug | no | bool | This volume is capable of VirtIO drive hot plug (no reboot required) |
discVirtioHotUnplug | no | bool | This volume is capable of VirtIO drive hot unplug (no reboot required) |
discScsiHotPlug | no | bool | This volume is capable of SCSI drive hot plug (no reboot required) |
discScsiHotUnplug | no | bool | This volume is capable of SCSI drive hot unplug (no reboot required) |
licenceType | no | string | The snapshot's licence type: [LINUX, WINDOWS, WINDOWS2016, OTHER, UNKNOWN] |
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}
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"
}
}
The JSON response body will contain the following attributes:
Name | Type | Description |
---|---|---|
id | string | The snapshot's unique identifier. |
type | string | The type of object. In this case: "snapshot" |
href | string | URL to the object’s representation (absolute path). |
metadata | collection | Snapshot metadata. |
properties | collection | Snapshot properties. |
The metadata returned for the snapshot:
Name | Type | Description |
---|---|---|
createdDate | string | The date the snapshot was created. |
createdBy | string | The user who created the snapshot. |
createdByUserId | string | The userId who created the resource. |
etag | string | The etag for the resource. |
lastModifiedDate | string | The last time the resource has been modified. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
state | string | The snapshot state. [AVAILABLE, BUSY, INACTIVE] |
The properties returned for the snapshot:
Name | Type | Description |
---|---|---|
name | string | The name of the snapshot. |
description | string | A description of the snapshot. |
location | string | The location where the snapshot is stored. |
size | int32 | The size of the snapshot in GB. |
cpuHotPlug | Boolean | This volume is capable of CPU hot plug (no reboot required) |
cpuHotUnplug | Boolean | This volume is capable of CPU hot unplug (no reboot required) |
ramHotPlug | Boolean | This volume is capable of memory hot plug (no reboot required) |
ramHotUnplug | Boolean | This volume is capable of memory hot unplug (no reboot required) |
nicHotPlug | Boolean | This volume is capable of NIC hot plug (no reboot required) |
nicHotUnplug | Boolean | This volume is capable of NIC hot unplug (no reboot required) |
discVirtioHotPlug | Boolean | This volume is capable of VirtIO drive hot plug (no reboot required) |
discVirtioHotUnplug | Boolean | This volume is capable of VirtIO drive hot unplug (no reboot required) |
discScsiHotPlug | Boolean | This volume is capable of SCSI drive hot plug (no reboot required) |
discScsiHotUnplug | Boolean | This volume is capable of SCSI drive hot unplug (no reboot required) |
licenceType | string | Licence type. [WINDOWS, WINDOWS2016, LINUX, OTHER, UNKNOWN] |
Deletes the specified snapshot.
To delete a snapshot, send a DELETE request to https://api.ionos.com/cloudapi/v5/snapshots/{snapshotId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{snapshotId} | yes | string | n/a | The ID of a snapshot. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
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}
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.
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.
To create an IP block, send a POST request to https://api.ionos.com/cloudapi/v5/ipblocks
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
Name | Required | Type | Description |
---|---|---|---|
location | yes | string | This must be one of the available locations. See locations. |
size | yes | int32 | The size of the IP Block you want to create. |
name | no | string | A descriptive name for the IP Block. |
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
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": []
}
}
The following table describes the attributes found in the JSON response body:
Name | Type | Description |
---|---|---|
id | string | The unique identifier. |
type | string | The type of object. In this case: "ipblock". |
href | string | URL to the object’s representation (absolute path). |
metadata | collection | Metadata for the IP Block. |
properties | collection | Properties of the IP Block. |
The metadata returned for an IP Block is shown in this table:
Name | Type | Description |
---|---|---|
etag | string | The ETag for the resource. |
createdDate | string | The date the resource was created. |
createdBy | string | The username of the user who created the resource. |
createdByUserId | string | The userId who created the resource. |
createdByUserId | string | The userId of the user who created the resource. |
lastModifiedDate | string | The last time the resource has been modified. |
lastModifiedBy | string | The username of the user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
lastModifiedByUserId | string | The userId of the user who last modified the resource. |
state | string | The IP Block state. It will return "BUSY" on create. |
The properties returned for an IP Block are outlined in this table:
Name | Type | Description |
---|---|---|
ips | collection | The reserved IP addresses that make up the IP Block. |
location | string | The location where the IP Block has been reserved. |
size | int32 | The number of IP addresses that make up the IP Block. |
name | string | A descriptive name for the IP Block. |
ipConsumers | collection | This will be empty for a newly created IP Block. |
Retrieves the attributes of a specific IP Block.
To retrieve a single IP Block you would send a GET request to
https://api.ionos.com/cloudapi/v5/ipblocks/{ipBlockId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{ipBlockId} | yes | string | n/a | The ID of an IP block. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/ipblocks?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/ipblocks?depth=1
Note: For this particular operation, increasing the value supplied to depth
does
NOT return any additional information beyond the default amount returned with a value of
0.
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}
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"
}
]
}
}
The following table describes the attributes found in the JSON response body:
Name | Type | Description |
---|---|---|
id | string | The unique identifier. |
type | string | The type of object. In this case: "ipblock". |
href | string | URL to the object’s representation (absolute path). |
metadata | collection | Metadata for the IP Block. |
properties | collection | Properties of the IP Block. |
The metadata returned for an IP Block is shown in this table:
Name | Type | Description |
---|---|---|
lastModifiedDate | string | The last time the resource has been modified. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
createdDate | string | The date the resource was created. |
createdBy | string | The user who created the resource. |
createdByUserId | string | The userId who created the resource. |
state | string | The IP Block state. [BUSY, AVAILABLE] |
etag | string | The ETag for the resource. |
The properties returned for an IP Block are outlined in this table:
Name | Type | Description |
---|---|---|
ips | collection | The reserved IP addresses that make up the IP Block. |
location | string | The location where the IP Block has been reserved. |
size | int32 | The number of IP addresses that make up the IP Block. |
name | string | A descriptive name for the IP Block. |
ipConsumers | collection | Information about where each IP address is being used. |
The ipConsumers collection contains the following information about each IP address that is part of the IP Block.
Name | Type | Description |
---|---|---|
ip | string | The IP address. |
mac | string | The MAC of the interface the IP is assigned too. |
nicId | string | The ID of the NIC that the IP is assigned too. |
serverId | string | The ID of the server that the IP is assigned too. |
serverName | string | The name of the server that the IP is assigned too. |
datacenterId | string | The ID of the data center that the IP is assigned too. |
datacenterName | string | The name of the data center that the IP is assigned too. |
Note: ipConsumers will remain empty for any IP addresses in an IP block that have not been assigned to a resource yet.
Updates the properties of an existing IP block.
To update an IP block, send either a PATCH or PUT request to
https://api.ionos.com/cloudapi/v5/ipblocks/{ipBlockId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{ipBlockId} | yes | string | n/a | The ID of the IP Block you want to update. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
Name | Required | Type | Description |
---|---|---|---|
name | no | string | A descriptive name for the IP Block. |
Please Note: Neither the location nor the size of an IP Block may be updated. The attributes are read-only once an IP Block is created.
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}'
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" : []
}
}
The following table describes the attributes found in the JSON response body:
Name | Type | Description |
---|---|---|
id | string | The unique identifier. |
type | string | The type of object. In this case: "ipblock". |
href | string | URL to the object’s representation (absolute path). |
metadata | collection | Metadata for the IP Block. |
properties | collection | Properties of the IP Block. |
The metadata returned for an IP Block is shown in this table:
Name | Type | Description |
---|---|---|
lastModifiedDate | string | The last time the resource has been modified. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
createdDate | string | The date the resource was created. |
createdBy | string | The user who created the resource. |
createdByUserId | string | The userId who created the resource. |
state | string | The IP Block state. [BUSY] |
etag | string | The ETag for the resource. |
The properties returned for an IP Block are outlined in this table:
Name | Type | Description |
---|---|---|
ips | collection | The reserved IP addresses that make up the IP Block. |
location | string | The location where the IP Block has been reserved. |
size | int32 | The number of IP addresses that make up the IP Block. |
name | string | The updated name for the IP Block. |
ipConsumers | collection | Information about resources the IP address is assigned too. |
Deletes the specified IP Block.
To delete an IP block you would send a DELETE request to
https://api.ionos.com/cloudapi/v5/ipblocks/{ipBlockId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{ipBlockId} | yes | string | n/a | The ID of an IP block. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
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}
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.
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.
To create a LAN you would send a POST request to
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The format of the JSON request body is as follows:
{
"properties": {
"name": "First LAN",
"public": "true"
}
}
These are the available properties that can be set:
Name | Required | Type | Default |
---|---|---|---|
name | no | string | n/a |
public | yes | Boolean | false |
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
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
}
}
The following table describes the attributes found in the response body:
Name | Type | Description |
---|---|---|
id | string | The resource's unique identifier. |
type | string | The type of object that has been created. |
href | string | URL to the object’s representation (absolute path). |
metadata | collection | Metadata related to the creation of the LAN. |
properties | collection | Properties of the LAN. |
The metadata returned is outlined in this table:
Name | Type | Description |
---|---|---|
lastModifiedDate | string | The last time the resource has been modified. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
createdDate | string | The date the resource was created. |
createdBy | string | The user who created the resource. |
createdByUserId | string | The userId who created the resource. |
state | string | LAN state. [AVAILABLE, BUSY, INACTIVE] |
etag | string | The ETag for the resource. |
The properties returned are summarized in this table:
Name | Type | Description |
---|---|---|
name | string | The descriptive name assigned to the LAN object. |
ipFailover | array | Should return "null" when creating a new LAN. |
public | Boolean | Indicates if the LAN faces the public Internet (true) or not (false). |
Retrieves the attributes of a given LAN.
To retrieve details about a single LAN you would send a GET request to
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans/{lanId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
{lanId} | yes | string | n/a | The ID of a LAN. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans?depth=1
Note: For this particular operation, increasing the value supplied to depth
will return additional information beyond the default amount returned with a value of 0.
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}
{
"id" : "1",
"type" : "lan",
"href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans/1",
"metadata" : {
"createdDate" : "[date]",
"createdBy" : "[username]",
"createdByUserId" : "[userId]",
"etag" : "[etag]",
"lastModifiedDate" : "[date]",
"lastModifiedBy" : "[username]",
"lastModifiedByUserId" : "[userId]",
"state" : "AVAILABLE"
},
"properties" : {
"name" : "[descriptive-LAN-name]",
"ipFailover" : [],
"public" : true
},
"entities" : {
"nics" : {
"id" : "1/nics",
"type" : "collection",
"href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans/1/nics"
}
}
}
The following table describes the attributes found in the response body:
Name | Type | Description |
---|---|---|
id | string | The unique identifier. |
type | string | The type of object that has been created. |
href | string | URL to the object’s representation (absolute path). |
metadata | collection | Various details about the LAN. |
properties | collection | Properties of the LAN. |
entities | collection | NICs that are part of the LAN. |
The metadata returned for a LAN is shown in this table:
Name | Type | Description |
---|---|---|
lastModifiedDate | string | The last time the resource has been modified. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
createdDate | string | The date the resource was created. |
createdBy | string | The user who created the resource. |
createdByUserId | string | The userId who created the resource. |
state | string | LAN state. |
etag | string | The ETag for the resource. |
The properties returned for a LAN are outlined in this table:
Name | Type | Description |
---|---|---|
name | string | A descriptive name for the LAN. |
public | Boolean | Boolean indicating if the LAN faces the public Internet (true) or not (false). |
ipFailover | collection | Attributes related to IP failover groups. |
The ipFailover collection contains two attributes:
Name | Type | Description |
---|---|---|
ip | string | The reserved public IP address assigned to the IP failover group. |
nicUuid | string | The UUID of the "master" NIC for the failover group. |
The entities returned for a LAN are described in this table:
Name | Type | Description |
---|---|---|
nics | collection | A collection of NICs associated with the LAN. |
At the default depth=0
, each entity in nics has the following attributes returned:
Name | Type | Description |
---|---|---|
id | string | The NIC ID with "/nics" appended. |
type | string | The type of object, in this case "collection". |
href | string | A URL to access details about the NICs that are part of the LAN. |
Increasing to depth=1
will return an additional items collection with each individual NIC that
is part of nics listed.
Increasing to depth=2
will return even more details about each NIC that is part of nics. With
depth=3
you'll get basic information about any firewall rules that are assigned to the NIC. At
depth=4
you'll get detailed information about each firewall rule that is assigned to the NIC. Please take
a look at the Network Interfaces section of this documentation for additional
information.
Retrieve a list of LANs provisioned in a specific VDC.
To retrieve a list of LANs you would submit a GET request to
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans?depth=1
Note: For this particular operation, increasing the value supplied to depth
will return additional information beyond the default amount returned with a value of 0.
You can filter the result set using custom filters.
An example of using the custom filter to find all LANs where public is "true":
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans?filter.public=true&depth=1
You can also filter on metadata such as lastModifiedDate. This example returns LANs that were modified in Dec 2017:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans?filter.lastModifiedDate=2017-12&depth=1
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
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"
} ]
}
The response will contain a collection of LANs.
The following table describes the attributes found in the JSON response:
Name | Type | Description |
---|---|---|
id | string | The resource's unique identifier. |
type | string | The type of object. In this case "collection". |
href | string | URL to the object’s representation (absolute path). |
items | collection | A collection of available LANs. |
Each of the returned items has these attributes:
Name | Type | Description |
---|---|---|
id | string | The LAN's identifier, generally an integer value. |
type | string | The type of object. In this case "lan". |
href | string | URL to the object’s representation (absolute path). |
If you append the ?depth=1
query parameter to the end of the request then more details are returned for
each individual LAN that is part of items. The additional details include metadata, properties, and entities.
This is similar to issuing a GET request to each LAN independently. Please see the next section for additional
information.
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.
Use PATCH to perform updates to the attributes of a LAN.
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}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a virtual data center. |
{lanId} | yes | string | n/a | The ID of a LAN. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The format of the JSON request body is as follows:
{
"name": "First LAN",
"ipFailover": [
{
"ip": "string",
"nicUuid": "string"
}
],
"public": "true"
}
These are the available properties that can be set:
Name | Required | Type | Default |
---|---|---|---|
name | no | string | n/a |
ipFailover | no | array | n/a |
public | no | Boolean | false |
The ipFailover array consists of two attributes.
Name | Required | Type | Default |
---|---|---|---|
ip | no | string | n/a |
nicUuid | no | string | n/a |
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}
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"
}
}
}
The JSON response is described in this table:
Name | Type | Description |
---|---|---|
id | string | The resource's unique identifier. |
type | string | The type of object that has been created. |
href | string | URL to the object’s representation (absolute path). |
metadata | collection | Metadata related to the creation of the LAN. |
properties | collection | Properties of the LAN. |
entities | collection | NICs that are part of the LAN. |
The metadata returned is outlined in this table:
Name | Type | Description |
---|---|---|
lastModifiedDate | string | The last time the resource has been modified. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
createdDate | string | The date the resource was created. |
createdBy | string | The user who created the resource. |
createdByUserId | string | The userId who created the resource. |
state | string | LAN state. [AVAILABLE, BUSY, INACTIVE] |
etag | string | The ETag for the resource. |
The properties returned are summarized in this table:
Name | Type | Description |
---|---|---|
name | string | A descriptive name assigned to the LAN object. |
ipFailover | array | Details about the IP failover group. |
public | Boolean | Indicates if the LAN faces the public Internet (true) or not (false). |
Use PUT to perform an update of the attributes of a LAN.
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}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a virtual data center. |
{lanId} | yes | string | n/a | The ID of a LAN. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The format of the JSON request body is as follows:
{
"properties": {
"name": "1st LAN",
"ipFailover": [
{
"ip": "",
"nicUuid": ""
}
],
"public": true
}
}
These are the available properties that can be set:
Name | Required | Type | Default |
---|---|---|---|
name | no | string | n/a |
ipFailover | no | array | n/a |
public | no | Boolean | false |
The ipFailover array consists of two attributes.
Name | Required | Type | Default |
---|---|---|---|
ip | yes | string | n/a |
nicUuid | yes | string | n/a |
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}
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"
}
}
}
Name | Type | Description |
---|---|---|
id | string | The resource's unique identifier. |
type | string | The type of object that has been created. |
href | string | URL to the object’s representation (absolute path). |
metadata | collection | Metadata related to the creation of the LAN. |
properties | collection | Properties of the LAN. |
entities | collection | NICs that are part of the LAN. |
The metadata returned is outlined in this table:
Name | Type | Description |
---|---|---|
lastModifiedDate | string | The last time the resource has been modified. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
createdDate | string | The date the resource was created. |
createdBy | string | The user who created the resource. |
createdByUserId | string | The userId who created the resource. |
state | string | LAN state. [AVAILABLE, BUSY, INACTIVE] |
etag | string | The ETag for the resource. |
The properties returned are summarized in this table:
Name | Type | Description |
---|---|---|
name | string | A descriptive name assigned to the LAN object. |
ipFailover | array | Details about the IP failover group. |
public | Boolean | Indicates if the LAN faces the public Internet (true) or not (false). |
Deletes the specified LAN.
To delete a LAN you would send a DELETE request to
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/lans/{lanId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
{lanId} | yes | string | n/a | The ID of a LAN. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
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}
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.
Successfully setting up an IP Failover group requires three steps:
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.
Adds a NIC to the target server.
To create a NIC, send a POST request to
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
{serverId} | yes | string | n/a | The ID of a server. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
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": []
}
}
Name | Required | Type | Default | Description |
---|---|---|---|---|
name | no | string | n/a | The name of the NIC. |
ips | no | string collection | n/a | IPs assigned to the NIC. This can be a collection. |
dhcp | no | Boolean | true | Set to false if you wish to disable DHCP on the NIC. Default: true |
lan | yes | int | n/a | The LAN ID the NIC will sit on. If the LAN ID does not exist it will be created. |
firewallActive | no | Boolean | n/a | A true value indicates the firewall is enabled. A false value indicates the firewall is disabled. |
firewallrules | no | string collection | n/a | A list of firewall rules associated to the NIC represented as a collection. |
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
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
}
}
The following table describes the attributes found in the JSON response body:
Name | Type | Description |
---|---|---|
id | string | The NIC's unique identifier. |
type | string | The type of object. "nic" |
href | string | An API URL to the NIC’s representation (absolute path). |
metadata | collection | NIC metadata. |
properties | collection | NIC properties. |
entities | collection | Entities associated with the NIC. "firewallrules" |
The metadata about the NIC includes:
Name | Type | Description |
---|---|---|
createdDate | string | The date the resource was created. |
createdBy | string | The user who created the resource. |
createdByUserId | string | The userId who created the resource. |
etag | string | The ETag. |
lastModifiedDate | string | The last modified time for the resource. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
state | string | AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued. INACTIVE The resource has been de-provisioned. |
The properties returned are:
Name | Type | Description |
---|---|---|
name | string | The name of the NIC. |
mac | string | The MAC address of the NIC. |
ips | collection | IPs assigned to the NIC represented as a collection. |
dhcp | Boolean | Boolean value that indicates if the NIC is using DHCP (true) or not (false). |
lan | int32 | The LAN ID the NIC sits on. |
firewallActive | Boolean | A true value indicates the firewall is enabled. A false value indicates the firewall is disabled. |
The entities returned include:
Name | Type | Description |
---|---|---|
firewallrules | collection | A collection of firewall rules associated with the NIC. |
Retrieves the attributes of a given NIC.
To retrieve attributes of a specific NIC, send a GET request to
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
{serverId} | yes | string | n/a | The ID of a server. |
{nicId} | yes | string | n/a | The ID of a NIC. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}?depth=1
Note: For this particular operation, increasing the value supplied to depth
will return additional information beyond the default amount returned with a value of 0.
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}
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"
}
}
}
The following table describes the attributes found in the JSON response body:
Name | Type | Description |
---|---|---|
id | string | The NIC's unique identifier. |
type | string | The type of object. "nic" |
href | string | An API URL to the NIC’s representation (absolute path). |
metadata | collection | NIC metadata. |
properties | collection | NIC properties. |
entities | collection | Entities associated with the NIC. "firewallrules" |
The metadata about the NIC includes:
Name | Type | Description |
---|---|---|
createdDate | string | The date the resource was created. |
createdBy | string | The user who created the resource. |
createdByUserId | string | The userId who created the resource. |
etag | string | The ETag. |
lastModifiedDate | string | The last modified time for the resource. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
state | string | AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued. INACTIVE The resource has been de-provisioned. |
The properties returned are:
Name | Type | Description |
---|---|---|
name | string | The name of the NIC. |
mac | string | The MAC address of the NIC. |
ips | collection | IPs assigned to the NIC represented as a collection. |
dhcp | Boolean | Boolean value that indicates if the NIC is using DHCP (true) or not (false). |
lan | int32 | The LAN ID the NIC sits on. |
firewallActive | Boolean | A true value indicates the firewall is enabled. A false value indicates the firewall is disabled. |
The entities returned include:
Name | Type | Description |
---|---|---|
firewallrules | collection | A collection of firewall rules associated with the NIC. |
If you passed a depth
query parameter with a value of 1
or greater, then additional
information about each of the entities is returned.
Retrieves a list of NICs.
To retrieve a list of NICs, submit a GET request to
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
{serverId} | yes | string | n/a | The ID of a server. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics?depth=1
Note: For this particular operation, increasing the value supplied to depth
will return additional information beyond the default amount returned with a value of 0.
You can filter the result set using custom filters.
An example of using the custom filter to find all NICs where dhcp is "true":
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics?filter.dhcp=true&depth=1
You can also filter on metadata such as createdBy. This example limits the results to NICs created by a specific user and also adds the depth parameter so additional info about each matching NIC is returned:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics?filter.createdBy=joe&depth=1
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
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}"
} ]
}
The request will return a collection of NICs assigned to the server.
The following table describes the attributes found in the response body:
Name | Type | Description |
---|---|---|
id | string | {serverId}/nics |
type | string | The type of object that has been created. "collection" |
href | string | URL to the object’s representation (absolute path). |
items | collection | A collection of NICs. |
The items will have the following attributes.
Name | Type | Description |
---|---|---|
id | string | The NIC's unique identifier. |
type | string | The type of object. "nic" |
href | string | An API URL to the NIC’s representation (absolute path). |
If you chose to pass the depth
query parameter with a value of 1
or greater, then
additional information about each NIC item will be returned. See the next section for additional details.
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.
Use PATCH to perform updates to attributes of a NIC.
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}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
{serverId} | yes | string | n/a | The ID of a server. |
{nicId} | yes | string | n/a | The ID of a server. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
Name | Required | Type | Description |
---|---|---|---|
name | no | string | The name of the NIC. |
ips | no | string collection | IPs assigned to the NIC represented as a collection. |
dhcp | no | Boolean | Boolean value that indicates if the NIC is using DHCP (true) or not (false). |
lan | no | int | The LAN ID the NIC sits on. |
firewallActive | no | Boolean | A true value indicates the firewall is enabled. A false value indicates the firewall is disabled. |
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}
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"
}
}
}
The following table describes the attributes found in the response body:
Name | Type | Description |
---|---|---|
id | string | The NIC's unique identifier. |
type | string | The type of object. "nic" |
href | string | An API URL to the NIC’s representation (absolute path). |
metadata | collection | NIC metadata. |
properties | collection | NIC properties. |
entities | collection | Entities associated with the NIC. "firewallrules" |
The metadata about the NIC includes:
Name | Type | Description |
---|---|---|
createdDate | string | The date the resource was created. |
createdBy | string | The user who created the resource. |
createdByUserId | string | The userId who created the resource. |
etag | string | The ETag. |
lastModifiedDate | string | The last modified time for the resource. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
state | string | AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued. INACTIVE The resource has been de-provisioned. |
The properties returned are:
Name | Type | Description |
---|---|---|
name | string | The name of the NIC. |
mac | string | The MAC address of the NIC. |
ips | collection | IPs assigned to the NIC represented as a collection. |
dhcp | Boolean | Boolean value that indicates if the NIC is using DHCP (true) or not (false). |
lan | int32 | The LAN ID the NIC sits on. |
firewallActive | Boolean | A true value indicates the firewall is enabled. A false value indicates the firewall is disabled. |
The entities returned include:
Name | Type | Description |
---|---|---|
firewallrules | collection | A collection of firewall rules associated with the NIC. |
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.
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}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
{serverId} | yes | string | n/a | The ID of a server. |
{nicId} | yes | string | n/a | The ID of a server. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
Name | Required | Type | Description |
---|---|---|---|
name | no | string | The name of the NIC. |
ips | no | string collection | IPs assigned to the NIC represented as a collection. |
dhcp | no | Boolean | Boolean value that indicates if the NIC is using DHCP or not. |
lan | yes | int32 | The LAN ID the NIC sits on. |
firewallActive | no | Boolean | A true value indicates the firewall is enabled. A false value indicates the firewall is disabled. |
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}
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"
}
}
}
The following table describes the attributes found in the JSON response body:
Name | Type | Description |
---|---|---|
id | string | The NIC's unique identifier. |
type | string | The type of object. "nic" |
href | string | An API URL to the NIC’s representation (absolute path). |
metadata | collection | NIC metadata. |
properties | collection | NIC properties. |
entities | collection | Entities associated with the NIC. "firewallrules" |
The metadata about the NIC includes:
Name | Type | Description |
---|---|---|
createdDate | string | The date the resource was created. |
createdBy | string | The user who created the resource. |
createdByUserId | string | The userId who created the resource. |
etag | string | The ETag. |
lastModifiedDate | string | The last modified time for the resource. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
state | string | AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued. INACTIVE The resource has been de-provisioned. |
The properties returned are:
Name | Type | Description |
---|---|---|
name | string | The name of the NIC. |
mac | string | The MAC address of the NIC. |
ips | collection | IPs assigned to the NIC represented as a collection. |
dhcp | Boolean | Boolean value that indicates if the NIC is using DHCP (true) or not (false). |
lan | int32 | The LAN ID the NIC sits on. |
firewallActive | Boolean | A true value indicates the firewall is enabled. A false value indicates the firewall is disabled. |
The entities returned include:
Name | Type | Description |
---|---|---|
firewallrules | collection | A collection of firewall rules associated with the NIC. |
Deletes the specified NIC.
To delete a NIC, send a DELETE request to
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
{serverId} | yes | string | n/a | The ID of a server. |
{nicId} | yes | string | n/a | The ID of a NIC. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
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}
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.
This will add a new firewall rule to the specified NIC. All firewall rules must be associated with a NIC.
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
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of the VDC. |
{serverId} | yes | string | n/a | The ID of a server. |
{nicId} | yes | string | n/a | The ID of a NIC. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
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"
}
}
Name | Required | Type | Description |
---|---|---|---|
name | no | string | A name for the firewall rule. |
protocol | yes | string | The protocol for the rule: TCP, UDP, ICMP, ANY. |
sourceMac | no | string | Only traffic originating from the respective MAC address is allowed. Valid format: aa:bb:cc:dd:ee:ff. A null value allows all source MAC addresses. |
sourceIp | no | string | Only traffic originating from the respective IPv4 address is allowed. A null value allows all source IPs. |
targetIp | no | string | In case the target NIC has multiple IP addresses, only traffic directed to the respective IP address of the NIC is allowed. Value null allows all target IPs. |
icmpCode | no | int32 | Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value null allows all codes. |
icmpType | no | int32 | Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value null allows all types. |
portRangeStart | no | int32 | Defines the start range of the allowed port (from 1 to 65534) if protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports. |
portRangeEnd | no | int32 | Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports. |
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
HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.ionos.com/cloudapi/v5/requests/{requestStatusId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked
{
"id" : "{firewallRuleId}",
"type" : "firewall-rule",
"href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}",
"metadata" : {
"createdDate" : "[date]",
"createdBy" : "[user]",
"createdByUserId" : "[userId]",
},
"properties" : {
"name" : "AllowHTTP",
"protocol" : "TCP",
"sourceMac" : null,
"sourceIp" : null,
"targetIp" : null,
"icmpCode" : null,
"icmpType" : null,
"portRangeStart" : 80,
"portRangeEnd" : 80
}
}
These attributes are found in the JSON response body:
Name | Type | Description |
---|---|---|
id | string | The resource's unique identifier. |
type | string | The type of object that has been created. Should be "firewall-rule". |
href | string | URL to the firewall rule. |
metadata | collection | Firewall rule metadata. |
properties | collection | Firewall rule properties. |
The metadata returned for each firewall rule:
Name | Type | Description |
---|---|---|
createdDate | string | The date the firewall rule was created. |
createdBy | string | The user who created the firewall rule. |
createdByUserId | string | The userId who created the resource. |
etag | string | The ETag for the resource. |
lastModifiedDate | string | The last time the resource has been modified. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
state | string | The firewall rule state. AVAILABLE, BUSY, INACTIVE |
The properties returned for the firewall rule:
Name | Type | Description |
---|---|---|
name | string | The name of the firewall rule. |
protocol | string | The protocol for the rule: TCP, UDP, ICMP, ANY. |
sourceMac | string | Only traffic originating from the respective MAC address is allowed. Valid format: aa:bb:cc:dd:ee:ff. Value "null" allows all source MAC address. |
sourceIp | string | Only traffic originating from the respective IPv4 address is allowed. Value "null" allows all source IPs. |
targetIp | string | In case the target NIC has multiple IP addresses, only traffic directed to the respective IP address of the NIC is allowed. Value "null" allows all target IPs. |
icmpType | int32 | Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value "null" allows all types. |
icmpCode | int32 | Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value "null" allows all codes. |
portRangeStart | int32 | Defines the start range of the allowed port (from 1 to 65534) if protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports. |
portRangeEnd | int32 | Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports. |
Retrieves the attributes of a specific firewall rule.
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}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of the VDC. |
{serverId} | yes | string | n/a | The ID of a server. |
{nicId} | yes | string | n/a | The ID of a NIC. |
{firewallRuleId} | yes | string | n/a | The ID of a firewall rule. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}?depth=1
Note: For this particular operation, increasing the value supplied to depth
does
NOT return any additional information beyond the default amount returned with a value of
0.
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}
HTTP/1.1 200 OK
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
X-RateLimit-Remaining: 299
X-RateLimit-Burst: 300
X-RateLimit-Limit: 600
ETag: [etag]
Content-Type: application/json
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked
{
"id" : "{firewallRuleId}",
"type" : "firewall-rule",
"href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}",
"metadata" : {
"createdDate" : "[date]",
"createdBy" : "[user]",
"createdByUserId" : "[userId]",
"etag" : "[etag]",
"lastModifiedDate" : "[date]",
"lastModifiedBy" : "[user]",
"lastModifiedByUserId" : "[userId]",
"state" : "AVAILABLE"
},
"properties" : {
"name" : "AllowSSH",
"protocol" : "TCP",
"sourceMac" : null,
"sourceIp" : null,
"targetIp" : null,
"icmpCode" : null,
"icmpType" : null,
"portRangeStart" : 22,
"portRangeEnd" : 22
}
}
These attributes are found in the JSON response body:
Name | Type | Description |
---|---|---|
id | string | The resource's unique identifier. |
type | string | The type of object that has been created. Should be "firewall-rule". |
href | string | URL to the firewall rule. |
metadata | collection | Firewall rule metadata. |
properties | collection | Firewall rule properties. |
The metadata returned for each firewall rule:
Name | Type | Description |
---|---|---|
createdDate | string | The date the firewall rule was created. |
createdBy | string | The user who created the firewall rule. |
createdByUserId | string | The userId who created the resource. |
etag | string | The ETag for the resource. |
lastModifiedDate | string | The last time the resource has been modified. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
state | string | The firewall rule state. AVAILABLE, BUSY, INACTIVE |
The properties returned for the firewall rule:
Name | Type | Description |
---|---|---|
name | string | The name of the firewall rule. |
protocol | string | The protocol for the rule: TCP, UDP, ICMP, ANY. |
sourceMac | string | Only traffic originating from the respective MAC address is allowed. Valid format: aa:bb:cc:dd:ee:ff. Value "null" allows all source MAC address. |
sourceIp | string | Only traffic originating from the respective IPv4 address is allowed. Value "null" allows all source IPs. |
targetIp | string | In case the target NIC has multiple IP addresses, only traffic directed to the respective IP address of the NIC is allowed. Value "null" allows all target IPs. |
icmpType | int32 | Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value "null" allows all types. |
icmpCode | int32 | Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value "null" allows all codes. |
portRangeStart | int32 | Defines the start range of the allowed port (from 1 to 65534) if protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports. |
portRangeEnd | int32 | Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports. |
Retrieves a list of firewall rules associated with a particular NIC.
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
.
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of the VDC. |
{serverId} | yes | string | n/a | The ID of a server. |
{nicId} | yes | string | n/a | The ID of a NIC. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules?depth=1
Note: For this particular operation, increasing the value supplied to depth
will return additional information beyond the default amount returned with a value of 0.
You can filter the result set using custom filters.
An example of using the custom filter to find all firewall rules where a particular sourceIp is specified:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules?filter.sourceIp=123.123.123.123
You can also filter on metadata such as createdBy. This example limits the results to firewall rules created by a specific user and also adds the depth parameter so additional info about each matching firewall rule is returned:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules?filter.createdBy=joe&depth=1
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
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]"
} ]
}
The request will return a collection of firewall rules assigned to the NIC.
The following table describes the attributes found in the response body:
Name | Description |
---|---|
id | The resource's unique identifier. |
type | The type of object that has been created. |
href | URL to the object’s representation (absolute path). |
The Cloud API implements both PUT and PATCH for updates.
Use PATCH to perform updates to the attributes of a firewall rule.
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}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of the virtual data center. |
{serverId} | yes | string | n/a | The ID of a server. |
{nicId} | yes | string | n/a | The ID of a NIC. |
{firewallRuleId} | yes | string | n/a | The ID of a firewall rule. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
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"
}
}
Name | Required | Type | Description |
---|---|---|---|
name | no | string | A name for the firewall rule. |
protocol | -- | string | You cannot update the protocol of an existing firewall rule. If you need to change
this, then delete and create a new firewall rule to replace the existing one. |
sourceMac | no | string | Only traffic originating from the respective MAC address is allowed. Valid format: aa:bb:cc:dd:ee:ff. A null value allows all source MAC addresses. |
sourceIp | no | string | Only traffic originating from the respective IPv4 address is allowed. A null value allows all source IPs. |
targetIp | no | string | In case the target NIC has multiple IP addresses, only traffic directed to the respective IP address of the NIC is allowed. Value null allows all target IPs. |
icmpCode | no | int32 | Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value null allows all codes. |
icmpType | no | int32 | Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value null allows all types. |
portRangeStart | no | int32 | Defines the start range of the allowed port (from 1 to 65534) if protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports. |
portRangeEnd | no | int32 | Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports. |
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}'
HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.ionos.com/cloudapi/v5/requests/{requestStatusId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked
{
"id" : "{firewallRuleId}",
"type" : "firewall-rule",
"href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}",
"metadata" : {
"createdDate" : "[date]",
"createdBy" : "[user]",
"createdByUserId" : "[userId]",
"etag" : "[etag]",
"lastModifiedDate" : "[date]",
"lastModifiedBy" : "[user]",
"lastModifiedByUserId" : "[userId]",
"state" : "BUSY"
},
"properties" : {
"name" : "AllowSSH",
"protocol" : "TCP",
"sourceMac" : "01:98:22:22:44:22",
"sourceIp" : null,
"targetIp" : "123.100.101.102",
"icmpCode" : null,
"icmpType" : null,
"portRangeStart" : 22,
"portRangeEnd" : 22
}
}
These attributes are found in the JSON response body:
Name | Type | Description |
---|---|---|
id | string | The resource's unique identifier. |
type | string | The type of object that has been created. Should be "firewall-rule". |
href | string | URL to the firewall rule. |
metadata | collection | Firewall rule metadata. |
properties | collection | Firewall rule properties. |
The metadata returned for each firewall rule:
Name | Type | Description |
---|---|---|
createdDate | string | The date the firewall rule was created. |
createdBy | string | The user who created the firewall rule. |
createdByUserId | string | The userId who created the resource. |
etag | string | The ETag for the resource. |
lastModifiedDate | string | The last time the resource has been modified. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
state | string | The firewall rule state. AVAILABLE, BUSY, INACTIVE |
The properties returned for the firewall rule:
Name | Type | Description |
---|---|---|
name | string | The name of the firewall rule. |
protocol | string | The protocol for the rule: TCP, UDP, ICMP, ANY. |
sourceMac | string | Only traffic originating from the respective MAC address is allowed. Valid format: aa:bb:cc:dd:ee:ff. Value "null" allows all source MAC address. |
sourceIp | string | Only traffic originating from the respective IPv4 address is allowed. Value "null" allows all source IPs. |
targetIp | string | In case the target NIC has multiple IP addresses, only traffic directed to the respective IP address of the NIC is allowed. Value "null" allows all target IPs. |
icmpType | int32 | Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value "null" allows all types. |
icmpCode | int32 | Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value "null" allows all codes. |
portRangeStart | int32 | Defines the start range of the allowed port (from 1 to 65534) if protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports. |
portRangeEnd | int32 | Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports. |
Use PUT to perform an update to the attributes of a firewall rule.
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}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of the virtual data center. |
{serverId} | yes | string | n/a | The ID of a server. |
{nicId} | yes | string | n/a | The ID of a NIC. |
{firewallRuleId} | yes | string | n/a | The ID of a firewall rule. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
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"
}
}
Name | Required | Type | Description |
---|---|---|---|
name | no | string | A name for the firewall rule. |
protocol | -- | string | You cannot update the protocol of an existing firewall rule. If you need to change
this, then delete and create a new firewall rule to replace the existing one. |
sourceMac | no | string | Only traffic originating from the respective MAC address is allowed. Valid format: aa:bb:cc:dd:ee:ff. A null value allows all source MAC addresses. |
sourceIp | no | string | Only traffic originating from the respective IPv4 address is allowed. A null value allows all source IPs. |
targetIp | no | string | In case the target NIC has multiple IP addresses, only traffic directed to the respective IP address of the NIC is allowed. Value null allows all target IPs. |
icmpCode | no | int32 | Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value null allows all codes. |
icmpType | no | int32 | Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value null allows all types. |
portRangeStart | no | int32 | Defines the start range of the allowed port (from 1 to 65534) if protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports. |
portRangeEnd | no | int32 | Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports. |
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}'
HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.ionos.com/cloudapi/v5/requests/{requestStatusId}/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked
{
"id" : "{firewallRuleId}",
"type" : "firewall-rule",
"href" : "https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}",
"metadata" : {
"createdDate" : "[date]",
"createdBy" : "[user]",
"createdByUserId" : "[userId]",
"etag" : "[etag]",
"lastModifiedDate" : "[date]",
"lastModifiedBy" : "[user]",
"lastModifiedByUserId" : "[userId]",
"state" : "BUSY"
},
"properties" : {
"name" : "SSH Port Plus One",
"protocol" : "TCP",
"sourceMac" : "01:23:45:67:89:00",
"sourceIp" : "1.2.3.4",
"targetIp" : "5.6.7.8",
"icmpCode" : null,
"icmpType" : null,
"portRangeStart" : 22,
"portRangeEnd" : 23
}
}
These attributes are found in the JSON response body:
Name | Type | Description |
---|---|---|
id | string | The resource's unique identifier. |
type | string | The type of object that has been created. Should be "firewall-rule". |
href | string | URL to the firewall rule. |
metadata | collection | Firewall rule metadata. |
properties | collection | Firewall rule properties. |
The metadata returned for each volume:
Name | Type | Description |
---|---|---|
createdDate | string | The date the firewall rule was created. |
createdBy | string | The user who created the firewall rule. |
createdByUserId | string | The userId who created the resource. |
etag | string | The ETag for the resource. |
lastModifiedDate | string | The last time the resource has been modified. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
state | string | The firewall rule state. AVAILABLE, BUSY, INACTIVE |
The properties returned for the firewall rule:
Name | Type | Description |
---|---|---|
name | string | The name of the firewall rule. |
protocol | string | The protocol for the rule: TCP, UDP, ICMP, ANY. |
sourceMac | string | Only traffic originating from the respective MAC address is allowed. Valid format: aa:bb:cc:dd:ee:ff. Value "null" allows all source MAC address. |
sourceIp | string | Only traffic originating from the respective IPv4 address is allowed. Value "null" allows all source IPs. |
targetIp | string | In case the target NIC has multiple IP addresses, only traffic directed to the respective IP address of the NIC is allowed. Value "null" allows all target IPs. |
icmpType | int32 | Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value "null" allows all types. |
icmpCode | int32 | Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value "null" allows all codes. |
portRangeStart | int32 | Defines the start range of the allowed port (from 1 to 65534) if protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports. |
portRangeEnd | int32 | Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports. |
Removes the specific firewall rule.
To delete a firewall rule send a DELETE request to
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of the VDC. |
{serverId} | yes | string | n/a | The ID of a server. |
{nicId} | yes | string | n/a | The ID of a NIC. |
{firewallRuleId} | yes | string | n/a | The ID of a firewall rule. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
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}
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.
Creates a load balancer within the VDC. Load balancers can be used for public or private IP traffic.
To create a load balancer send a POST request to
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The format of the request body is as follows:
{
"properties": {
"name": "load-balancer-name",
"ip": "load-balancer-ip",
"dhcp": true
},
"entities": {
"balancednics": []
}
}
Name | Required | Type | Description |
---|---|---|---|
name | yes | string | The name of the load balancer. |
ip | no | string | IPv4 address of the load balancer. All attached NICs will inherit this IP. |
dhcp | no | Boolean | Indicates if the load balancer will reserve an IP using DHCP. |
balancednics | no | string collection | List of NICs taking part in load-balancing. All balanced NICs inherit the IP of the load balancer. |
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
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
}
}
The following table describes the attributes found in the JSON response body:
Name | Type | Description |
---|---|---|
id | string | The unique identifier. |
type | string | The type of object that has been created. |
href | string | URL to the object’s representation (absolute path). |
metadata | collection | Various details about the load balancer. |
properties | collection | Properties of the load balancer. |
entities | collection | NICs that are part of the load balancer. |
The metadata returned for a load balancer is shown in this table:
Name | Type | Description |
---|---|---|
lastModifiedDate | string | The last time the resource has been modified. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
createdDate | string | The date the resource was created. |
createdBy | string | The user who created the resource. |
createdByUserId | string | The userId who created the resource. |
state | string | The load balancer state. |
etag | string | The ETag for the resource. |
The properties returned for a load balancer are outlined in this table:
Name | Type | Description |
---|---|---|
name | string | A descriptive name for the load balancer. |
ip | string | The IP address assigned to the load balancer. |
dhcp | Boolean | Indicates if the load balancer is using DHCP to have an IP address assigned. |
The entities returned for a load balancer are described in this table:
Name | Type | Description |
---|---|---|
balancednics | collection | A collection of NICs associated with the load balancer. |
Retrieves the attributes of a given load balancer.
To retrieve details about a specific load balancer send a GET request to
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
{loadBalancerId} | yes | string | n/a | The ID of a load balancer. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}?depth=1
Note: For this particular operation, increasing the value supplied to depth
will return additional information beyond the default amount returned with a value of 0.
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}
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"
}
}
}
Name | Type | Description |
---|---|---|
id | string | The unique identifier. |
type | string | The type of object that has been created. |
href | string | URL to the object’s representation (absolute path). |
metadata | collection | Various details about the LAN. |
properties | collection | Properties of the LAN. |
entities | collection | NICs that are part of the LAN. |
The metadata returned for a load balancer is shown in this table:
Name | Type | Description |
---|---|---|
lastModifiedDate | string | The last time the resource has been modified. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
createdDate | string | The date the resource was created. |
createdBy | string | The user who created the resource. |
createdByUserId | string | The userId who created the resource. |
state | string | The load balancer state. |
etag | string | The ETag for the resource. |
The properties returned for a load balancer are outlined in this table:
Name | Type | Description |
---|---|---|
name | string | A descriptive name for the load balancer. |
ip | string | The IP address assigned to the load balancer. |
dhcp | Boolean | Indicates if the load balancer is using DHCP to have an IP address assigned. |
The entities returned for a load balancer are described in this table:
Name | Type | Description |
---|---|---|
balancednics | collection | A collection of NICs associated with the LAN. |
At the default depth=0
, each entity in balancednics has the following attributes returned:
Name | Type | Description |
---|---|---|
id | string | The NIC ID with "/nics" appended. |
type | string | The type of object, in this case "collection". |
href | string | A URL to access details about the NICs that are part of the LAN. |
Increasing to depth=1
will return an additional items collection with each individual NIC that
is part of balancednics listed.
Increasing to depth=2
will return even more details about each NIC that is part of nics. With
depth=3
you'll get basic information about any firewall rules that are assigned to the NIC. At
depth=4
you'll get detailed information about each firewall rule that is assigned to the NIC. Please
take a look at the Network Interfaces section of this documentation for additional
information.
Retrieve a list of load balancers within the virtual data center.
To retrieve a list of load balancers, submit a GET request to
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers?depth=1
Note: For this particular operation, increasing the value supplied to depth
will return additional information beyond the default amount returned with a value of 0.
You can filter the result set using custom filters.
An example of using the custom filter to find all load balancers where dhcp is "true":
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers?filter.dhcp=true&depth=1
You can also filter on metadata such as createdBy. This example limits the results to load balancers created by a specific user:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers?filter.createdBy=joe&depth=1
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
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}"
} ]
}
The request will return a collection of load balancers.
The following table describes the attributes found in the JSON response:
Name | Type | Description |
---|---|---|
id | string | The resource's unique identifier. |
type | string | The type of object. In this case "collection". |
href | string | URL to the object’s representation (absolute path). |
items | collection | A collection of available load balancers. |
Each of the returned items has these attributes:
Name | Type | Description |
---|---|---|
id | string | The load balancer's ID. |
type | string | The type of object. In this case "loadbalancer". |
href | string | URL to the object’s representation (absolute path). |
If you append the ?depth=1
query parameter to the end of the request then more details are returned for
each individual load balancer that is part of items. The additional details include metadata, properties,
and entities. This is similar to issuing a GET request to each load balancer independently. Please see the next
section for additional information.
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.
Use PATCH to perform an update to the attributes of a load balancer.
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}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
{loadBalancerId} | yes | string | n/a | The ID of a load balancer. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
Name | Required | Type | Description |
---|---|---|---|
name | no | string | The name of the load balancer. |
ip | no | string | The IP of the load balancer. |
dhcp | no | Boolean | Indicates if the load balancer will reserve an IP using DHCP. |
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}
Status: 202 (Accepted)
Headers: [
"Date: [date]",
"Content-Type: application/json",
"Location: URL of a request resource which should be used for the operation's polling status",
"Connection: keep-alive",
"Content-Length: 426"
]
ResponseBody: {
"id": "loadbalancer-id",
"type": "loadbalancer",
"href": "[base-url]/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}",
"metadata": {
"lastModifiedDate": "last-modified-date",
"lastModifiedBy": "last-modified-by-user",
"createdDate": "created-date",
"createdBy": "created-by-user",
"state": "load-balancer-state",
"etag": "etag"
},
"properties": {
"name": "loadbalancer-name",
"ip": "loadbalancer-ip",
"dhcp": "loadbalancer-dhcp"
},
"entities": {
"balancednics": []
}
}
The following table describes the attributes found in the JSON response body:
Name | Type | Description |
---|---|---|
id | string | The unique identifier. |
type | string | The type of object that has been created. |
href | string | URL to the object’s representation (absolute path). |
metadata | collection | Various details about the load balancer. |
properties | collection | Properties of the load balancer. |
entities | collection | NICs that are part of the load balancer. |
The metadata returned for a load balancer is shown in this table:
Name | Type | Description |
---|---|---|
lastModifiedDate | string | The last time the resource has been modified. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
createdDate | string | The date the resource was created. |
createdBy | string | The user who created the resource. |
createdByUserId | string | The userId who created the resource. |
state | string | The load balancer state. |
etag | string | The ETag for the resource. |
The properties returned for a load balancer are outlined in this table:
Name | Type | Description |
---|---|---|
name | string | A descriptive name for the load balancer. |
ip | string | The IP address assigned to the load balancer. |
dhcp | Boolean | Indicates if the load balancer is using DHCP to have an IP address assigned. |
The entities returned for a load balancer are described in this table:
Name | Type | Description |
---|---|---|
balancednics | collection | A collection of NICs associated with the load balancer. |
Use PUT to perform an update of the attributes of a load balancer.
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}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
{loadBalancerId} | yes | string | n/a | The ID of a load balancer. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
Name | Required | Type | Description |
---|---|---|---|
name | no | string | The name of the load balancer. |
ip | no | string | The IP of the load balancer. |
dhcp | no | Boolean | Indicates if the load balancer will reserve an IP using DHCP. |
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]
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": []
}
}
The following table describes the attributes found in the JSON response body:
Name | Type | Description |
---|---|---|
id | string | The unique identifier. |
type | string | The type of object that has been created. |
href | string | URL to the object’s representation (absolute path). |
metadata | collection | Various details about the LAN. |
properties | collection | Properties of the LAN. |
entities | collection | NICs that are part of the LAN. |
The metadata returned for a load balancer is shown in this table:
Name | Type | Description |
---|---|---|
lastModifiedDate | string | The last time the resource has been modified. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
createdDate | string | The date the resource was created. |
createdBy | string | The user who created the resource. |
createdByUserId | string | The userId who created the resource. |
state | string | The load balancer state. |
etag | string | The ETag for the resource. |
The properties returned for a load balancer are outlined in this table:
Name | Type | Description |
---|---|---|
name | string | A descriptive name for the load balancer. |
ip | string | The IP address assigned to the load balancer. |
dhcp | Boolean | Indicates if the load balancer is using DHCP to have an IP address assigned. |
The entities returned for a load balancer are described in this table:
Name | Type | Description |
---|---|---|
balancednics | collection | A collection of NICs associated with the load balancer. |
Deletes the specified load balancer.
To delete a load balancer send a DELETE request to
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
{loadBalancerId} | yes | string | n/a | The ID of a load balancer. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
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}
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.
This will retrieve a list of NICs associated with the load balancer.
To retrieve a list of load balanced NICs submit a GET request to
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}/balancednics
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
{loadBalancerId} | yes | string | n/a | The ID of a load balancer. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}/balancednics?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}/balancednics?depth=1
Note: For this particular operation, increasing the value supplied to depth
will return additional information beyond the default amount returned with a value of 0.
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
{
"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"
}
}
}
]
}
The request will return a collection of load balanced NICs.
The following table describes the attributes found in the response body:
Name | Type | Description |
---|---|---|
id | string | {serverId}/nics |
type | string | The type of object that has been created. "collection" |
href | string | URL to the object’s representation (absolute path). |
items | collection | A collection of NICs. |
The items will have the following attributes.
Name | Type | Description |
---|---|---|
id | string | The NIC's unique identifier. |
type | string | The type of object. "nic" |
href | string | An API URL to the NIC’s representation (absolute path). |
If you appended ?depth=1
to the request to have more details returned, you will also get
metadata, properties, and entities returned for each NIC in items.
The metadata about the NIC includes:
Name | Type | Description |
---|---|---|
createdDate | string | The date the resource was created. |
createdBy | string | The user who created the resource. |
createdByUserId | string | The userId who created the resource. |
etag | string | The ETag. |
lastModifiedDate | string | The last modified time for the resource. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
state | string | AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued. INACTIVE The resource has been de-provisioned. |
The properties returned are:
Name | Type | Description |
---|---|---|
name | string | The name of the NIC. |
mac | string | The MAC address of the NIC. |
ips | collection | IPs assigned to the NIC represented as a collection. |
dhcp | Boolean | Boolean value that indicates if the NIC is using DHCP (true) or not (false). |
lan | int32 | The LAN ID the NIC sits on. |
nat | Boolean | Boolean value indicating if the private IP address has outbound access to the public internet enabled (true) or not (false). |
firewallActive | Boolean | A true value indicates the firewall is enabled. A false value indicates the firewall is disabled. |
The entities returned include:
Name | Type | Description |
---|---|---|
firewallrules | collection | A collection of firewall rules associated with the NIC. |
Retrieves the attributes of a given load balanced NIC.
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}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
{loadBalancerId} | yes | string | n/a | The ID of a load balancer. |
{nicId} | yes | string | n/a | The ID of a NIC. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}/balancednics/{nicId}?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}/balancednics/{nicId}?depth=1
Note: For this particular operation, increasing the value supplied to depth
will return additional information beyond the default amount returned with a value of 0.
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}
{
"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": []
}
}
The following table describes the attributes found in the JSON response body:
Name | Type | Description |
---|---|---|
id | string | The NIC's unique identifier. |
type | string | The type of object. "nic" |
href | string | An API URL to the NIC’s representation (absolute path). |
metadata | collection | NIC metadata. |
properties | collection | NIC properties. |
entities | collection | NIC entities. "firewallrules" |
The metadata about the NIC includes:
Name | Type | Description |
---|---|---|
createdDate | string | The date the resource was created. |
createdBy | string | The user who created the resource. |
createdByUserId | string | The userId who created the resource. |
etag | string | The ETag. |
lastModifiedDate | string | The last modified time for the resource. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
state | string | AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued. INACTIVE The resource has been de-provisioned. |
The properties returned are:
Name | Type | Description |
---|---|---|
name | string | The name of the NIC. |
mac | string | The MAC address of the NIC. |
ips | collection | IPs assigned to the NIC represented as a collection. |
dhcp | Boolean | Boolean value that indicates if the NIC is using DHCP (true) or not (false). |
lan | int32 | The LAN ID the NIC sits on. |
nat | Boolean | Boolean value indicating if the private IP address has outbound access to the public internet enabled (true) or not (false). |
firewallActive | Boolean | A true value indicates the firewall is enabled. A false value indicates the firewall is disabled. |
The entities returned include:
Name | Type | Description |
---|---|---|
firewallrules | collection | A collection of firewall rules associated with the NIC. |
If you appended ?depth=1
to the request to retrieve more details, you will get additional information
about the firewallrules.
This will associate a NIC to a Load Balancer, enabling the NIC to participate in load-balancing.
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``
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
{loadBalancerId} | yes | string | n/a | The ID of a load balancer. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
Name | Required | Type | Description |
---|---|---|---|
id | yes | string | The UUID of the NIC. |
The format of the request body is as follows:
{
id": "{nicId}"
}
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'
{
"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": []
}
}
The following table describes the attributes found in the response body:
Name | Type | Description |
---|---|---|
id | string | The NIC's unique identifier. |
type | string | The type of object. "nic" |
href | string | An API URL to the NIC’s representation (absolute path). |
metadata | collection | NIC metadata. |
properties | collection | NIC properties. |
entities | collection | NIC entities. "firewallrules" |
The metadata about the NIC includes:
Name | Type | Description |
---|---|---|
createdDate | string | The date the resource was created. |
createdBy | string | The user who created the resource. |
createdByUserId | string | The userId who created the resource. |
etag | string | The ETag. |
lastModifiedDate | string | The last modified time for the resource. |
lastModifiedBy | string | The user who last modified the resource. |
lastModifiedByUserId | string | The userId who last modified the resource. |
state | string | AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued. INACTIVE The resource has been de-provisioned. |
The properties returned are:
Name | Type | Description |
---|---|---|
name | string | The name of the NIC. |
mac | string | The MAC address of the NIC. |
ips | collection | IPs assigned to the NIC represented as a collection. |
dhcp | Boolean | Boolean value that indicates if the NIC is using DHCP (true) or not (false). |
lan | int32 | The LAN ID the NIC sits on. |
nat | Boolean | Boolean value indicating if the private IP address has outbound access to the public internet enabled (true) or not (false). |
firewallActive | Boolean | A true value indicates the firewall is enabled. A false value indicates the firewall is disabled. |
The entities returned include:
Name | Type | Description |
---|---|---|
firewallrules | collection | A collection of firewall rules associated with the NIC. |
Removes the association of a NIC with a load balancer.
To remove a NIC association send a DELETE request to
https://api.ionos.com/cloudapi/v5/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId]/balancednics/{nicId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{dataCenterId} | yes | string | n/a | The ID of a VDC. |
{loadBalancerId} | yes | string | n/a | The ID of a load balancer. |
{nicId} | yes | string | n/a | The ID of a NIC. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
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}
Status: 202 (Accepted)
There is no JSON response body returned with a successful DELETE request.
Retrieves the attributes of a specific request based on the supplied request id.
To retrieve details on a specific request you would send a GET request to
https://api.ionos.com/cloudapi/v5/requests/{requestId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{requestId} | yes | string | n/a | The ID of a request. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/requests/{requestId}?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/requests/{requestId}?depth=1
Note: For this particular operation, increasing the value supplied to depth
does
NOT return any additional information beyond the default amount returned with a value of
0.
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}
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"
}
}
The following table describes the attributes found in the JSON response body:
Name | Type | Description |
---|---|---|
id | string | The ID of the specific request. |
type | string | The type of object, which should be "request" here. |
href | string | URL to the object’s representation (absolute path). |
metadata | collection | A collection of metadata about the request. |
properties | collection | A collection of properties related to the request. |
The metadata returned will have the following attributes:
Name | Type | Description |
---|---|---|
createdDate | string | The date the request was created. |
createdBy | string | The username that created the request. |
createdByUserId | string | The userId who created the resource. |
etag | string | The etag. |
requestStatus | collection | Information on the request-status. |
The requestStatus collection will contain:
Name | Type | Description |
---|---|---|
id | string | The ID of the specific "request" with "/status" appended. |
type | string | The type of object, which should be "request-status" here. |
href | string | URL to the object’s representation (absolute path). Can be used to retrieve the status of the request. |
The properties collection should contain:
Name | Type | Description |
---|---|---|
method | string | The request method. [GET, POST, PATCH, PUT, DELETE] |
headers | collection | The HTTP headers that were submitted with the request. |
body | string | The body that was submitted with the request. Usually JSON, but some API requests are URL encoded. |
url | string | The URL used to make the request. |
The headers and body returned in properties will differ considerably depending on the original request.
Once you have determined the type of request based on the returned properties, you can refer to the appropriate section of the Cloud API documentation for details.
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.
To retrieve a list of requests you would send a GET request to
https://api.ionos.com/cloudapi/v5/requests
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
filter.status | string | A string (case sensitive) value to fetch all the request based on a particular status value. Valid value is one of the value from QUEUED, RUNNING, DONE or FAILED. | |
filter.createdAfter | string | The date time string value is used to filter all the requests after a particular created date/time. Valid format are yyyy-MM-dd or yyyy-MM-dd HH:mm:ss. | |
filter.createdBefore | string | The date time string value is used to filter all the requests before a particular created date/time. Valid format are yyyy-MM-dd or yyyy-MM-dd HH::mm:ss. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/requests?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/requests?depth=1
Note: For this particular operation, increasing the value supplied to depth
does
NOT return any additional information beyond the default amount returned with a value of
0.
You can filter the result set using custom filters.
An example of using the custom filter to find all requests where method is "PUT":
https://api.ionos.com/cloudapi/v5/requests?filter.method=put&depth=1
You can also filter on metadata such as createdDate. This example would find all requests where the method is "DELETE" and createdDate contains "2017-08":
https://api.ionos.com/cloudapi/v5/requests?filter.method=delete&filter.createdDate=2017-08&depth=1
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
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}"
} ]
}
The request will return a collection of requests.
The following table describes the attributes found in the JSON response body:
Name | Type | Description |
---|---|---|
id | string | "requests" |
type | string | The type of object, which should be "collection" here. |
href | string | URL to the object’s representation (absolute path). |
items | collection | A collection of individual "request" items. |
Each of the items returned will have the following attributes:
Name | Type | Description |
---|---|---|
id | string | The request's ID. |
type | string | The type of object, which should be "request" here. |
href | string | URL to the object’s representation (absolute path). |
Retrieves the status of a specific request based on the supplied request id.
To retrieve the status of a specific request send a GET request to
https://api.ionos.com/cloudapi/v5/requests/{requestId}/status
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{requestId} | yes | string | n/a | The ID of a request. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/requests/{requestId}/status?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/requests/{requestId}/status?depth=1
Note: For this particular operation, increasing the value supplied to depth
does
NOT return any additional information beyond the default amount returned with a value of
0.
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
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"
} ]
}
}
The following table describes the attributes found in the JSON response body:
Name | Type | Description |
---|---|---|
id | string | The ID of the specific request with "/status" appended. |
type | string | The type of object, which should be "request-status" here. |
href | string | URL to the object’s representation (absolute path). |
metadata | collection | A collection of metadata about the request's status. |
The metadata returned will have the following attributes:
Name | Type | Description |
---|---|---|
status | string | The overall status of the request. [QUEUED, RUNNING, DONE, or FAILED] |
message | string | The username that created the request. |
etag | string | The etag. |
targets | collection | An array of "sub-requests" related to the request. For example, a create server request could involve multiple requests for creating the server, a volume, and a NIC. These sub-requests and their status will be returned in this section of the response. |
The targets collection will contain:
Name | Type | Description |
---|---|---|
target | array | Information about a specific "sub-request" related to the request. |
status | string | The status of the request for this specific target. [QUEUED, RUNNING, DONE, or FAILED] |
Each target will contain:
Name | Type | Description |
---|---|---|
id | string | The ID of the object or resource involved in the operation. |
type | string | The type of object. |
href | string | URL to the object’s representation (absolute path). Not always available, so it can be a string such as "TO_BE_INJECTED" |
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.
Returns information about the resource limits for a particular contract and the current resource usage.
Submit a GET request to https://api.ionos.com/cloudapi/v5/contracts
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/contracts?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/contracts?depth=1
Note: For this particular operation, increasing the value supplied to depth
will return additional information beyond the default amount returned with a value of 0.
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
In previous versions of the Cloud API, the amount of data included in the response payload would vary slightly depending on the credentials supplied when making the request. Now all users can view the resource and usage details for a contract.
{
"type": "contract",
"properties": {
"contractNumber": 12345678,
"owner": "test@domain.com",
"status": "BILLABLE",
"regDomain": "mydomain.com",
"resourceLimits": {
"coresPerServer": 20,
"coresPerContract": 30,
"coresProvisioned": 0,
"ramPerServer": 204800,
"ramPerContract": 3072000,
"ramProvisioned": 0,
"hddLimitPerVolume": 2048000,
"hddLimitPerContract": 3072000,
"hddVolumeProvisioned": 0,
"ssdLimitPerVolume": 2048000,
"ssdLimitPerContract": 3072000,
"ssdVolumeProvisioned": 0,
"reservableIps": 3,
"reservedIpsOnContract": 0,
"reservedIpsInUse": 0
"k8sClusterLimitTotal": 0
"k8sClustersProvisioned": 0
}
}
}
The following table describes each of the response attributes.
Name | Type | Description |
---|---|---|
type | string | The type of response, in this case it will be contract |
properties | collection | A collection of properties for each item. |
The following table describes the properties returned in the response.
Name | Type | Description |
---|---|---|
contractNumber | int64 | The contract number that the returned information is from. |
owner | string | The username of the "Contract Owner". |
status | string | The status of the contract. [ BILLABLE...] |
regDomain | string | Registration domain of the contract |
resourceLimits | collection | An object containing the contract's resource limits. |
The following table describes the resourceLimits returned as part of properties.
Name | Type | Example | Description |
---|---|---|---|
coresPerContract | int32 | 20 | Maximum number of CPU cores per contract. |
coresPerServer | int32 | 4 | Maximum number of CPU cores per server. |
coresProvisioned | int32 | 4 | The total number of CPU cores that have been provisioned. |
hddLimitPerContract | int64 | 3072000 | The maximum amount of hard disk space (in MB) that may be provisioned under this contract. |
hddLimitPerVolume | int64 | 2048000 | The maximum size (in MB) of an individual hard disk volume. |
hddVolumeProvisioned | int64 | 1024000 | The amount of hard disk space (in MB) that is currently provisioned. |
ramPerContract | int32 | 3072000 | The maximum amount of RAM (in MB) that may be provisioned under this contract. |
ramPerServer | int32 | 204800 | The maximum amount of RAM (in MB) that may be provisioned for a particular server under this contract. |
ramProvisioned | int32 | 102400 | The amount of RAM (in MB) that has been provisioned under this contract. |
reservableIps | int32 | 128 | The maximum number of static public IP addresses that may be reserved by this customer across all contracts. |
reservedIpsInUse | int32 | 6 | The number of static public IP addresses that have been reserved. |
reservedIpsOnContract | int32 | 32 | The maximum number of static public IP addresses that can be reserved under this contract. |
ssdLimitPerContract | int64 | 2048000 | The maximum amount of solid state disk space (in MB) that may be provisioned under this contract. |
ssdLimitPerVolume | int64 | 1024000 | The maximum size (in MB) of an individual solid state disk volume. |
ssdVolumeProvisioned | int64 | 512000 | The amount of solid state disk space (in MB) that is currently provisioned. |
k8sClusterLimitTotal | int32 | 5 | The maximum limit of Kubernetes cluster that can be created under this contract. |
k8sClustersProvisioned | int32 | 3 | The amount of Kubernetes clusters that is currently provisioned. |
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.
Creates a new user under a particular contract.
Submit a POST request to https://api.ionos.com/cloudapi/v5/um/users
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The JSON encoded request body may contain the following information:
Name | Required | Type | Default | Description |
---|---|---|---|---|
firstname | yes | string | n/a | A name for the user. |
lastname | yes | string | n/a | A name for the user. |
yes | string | n/a | An e-mail address for the user. | |
password | yes | string | n/a | A password for the user. |
administrator | no | Boolean | false | Assigns the user have administrative rights. |
forceSecAuth | no | Boolean | false | Indicates if secure (two-factor) authentication should be forced for the user. |
Please Note: The password set here cannot be updated through the API currently. It is recommended that a new user log into the DCD and change their password.
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
{
"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
}
}
Name | Type | Description |
---|---|---|
id | string | The user's identifier. |
type | string | The type of response, in this case it will be user. |
href | string | A URI for accessing the user object. |
metadata | collection | A collection containing metadata for the user. |
properties | collection | A collection containing the user's properties. |
The metadata collection includes these attributes:
Name | Type | Description |
---|---|---|
etag | string | ETag for the user. |
creationDate | string | A time and date stamp indicating when the user was created. |
lastLogin | string | A time and date stamp indicating when the user last logged in. Should be "null" for a new user. |
The properties collection includes these attributes:
Name | Type | Description |
---|---|---|
firstname | string | The first name of the user. |
lastname | string | The last name of the user. |
string | The e-mail address of the user. | |
administrator | Boolean | Indicates if the user has administrative rights. |
forceSecAuth | Boolean | Indicates if secure (two-factor) authentication was enabled for the user. |
secAuthActive | Boolean | Indicates if secure (two-factor) authentication is enabled for the user. |
Retrieve details about a specific user including what groups and resources the user is associated with.
Submit a GET request to https://api.ionos.com/cloudapi/v5/um/users/{userId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{userId} | yes | string | n/a | The ID of the specific user to retrieve information about. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/um/users/{userId}?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/um/users/{userId}?depth=1
Note: For this particular operation, increasing the value supplied to depth
will return additional information beyond the default amount returned with a value of 0.
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
{
"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"
}
}
}
Name | Type | Description |
---|---|---|
id | string | The user's identifier. |
type | string | The type of response, in this case it will be user. |
href | string | A URI for accessing the user object. |
metadata | collection | A collection containing metadata for the user. |
properties | collection | A collection containing the user's properties. |
entities | collection | A collection containing resources the user owns, and groups the user is a member of. |
The metadata collection includes these attributes:
Name | Type | Description |
---|---|---|
etag | string | ETag for the user. |
creationDate | string | A time and date stamp indicating when the user was created. |
lastLogin | string | A time and date stamp indicating when the user last logged in. |
The properties collection includes these attributes:
Name | Type | Description |
---|---|---|
firstname | string | The first name of the user. |
lastname | string | The last name of the user. |
string | The e-mail address of the user. | |
administrator | Boolean | Indicates if the user has administrative rights. |
forceSecAuth | Boolean | Indicates if secure (two-factor) authentication was enabled for the user. |
secAuthActive | Boolean | Indicates if secure (two-factor) authentication is enabled for the user. |
active | Boolean | Indicates if the user is active (true) or disabled (false). |
s3CanonicalUserId | string | The user's S3 ID. |
The entities collection includes these attributes:
Name | Type | Description |
---|---|---|
owns | collection | A collection of resources that this user owns. |
groups | collection | A collection of groups that this user is a member of. |
s3Keys | collection | A collection of s3Keys associated with the user. |
Each of the owns, groups, and s3Keys will include the following attributes.
Name | Type | Description |
---|---|---|
id | string | The group's identifier with /users or /resources appended. |
type | string | The type of response, in this case it will be "collection". |
href | string | A URL for directly accessing the object. |
At depth=1
each of the entities will also include an items collection with details
about the particular resource that the user owns, the groups that the user is a member of, and the s3Keys associated
with the user.
If you are only interested in seeing details about owns, groups, or s3Keys, you can append the entity name to your get request and the API will return details about the specified entity.
For example:
For owns, submit a GET request to https://api.ionos.com/cloudapi/v5/um/users/{userId}/owns
For groups, submit a GET request to https://api.ionos.com/cloudapi/v5/um/users/{userId}/groups
For s3keys, submit a GET request to https://api.ionos.com/cloudapi/v5/um/users/{userId}/s3keys
As with other GET requests, you can utilize the depth=X
parameter to control the amount of detail
returned.
Retrieve a list of all the users that have been created under a contract.
Submit a GET request to https://api.ionos.com/cloudapi/v5/um/users
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/um/users?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/um/users?depth=1
Note: For this particular operation, increasing the value supplied to depth
will return additional information beyond the default amount returned with a value of 0.
You can filter the result set using custom filters.
An example of using the custom filter to find all users where firstname contains "joe":
https://api.ionos.com/cloudapi/v5/requests?filter.firstname=joe&depth=1
or where administrator is "true":
https://api.ionos.com/cloudapi/v5/um/users?depth=1&filter.administrator=true
You can also filter on metadata such as lastLogin. This example would find all users where the lastLogin is "2017-11":
https://api.ionos.com/cloudapi/v5/um/users?depth=1&filter.lastLogin=2017-11
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
{
"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"
}
]
}
Name | Type | Description |
---|---|---|
id | string | "users" |
type | string | The type of response, in this case is collection. |
href | string | A URI for accessing the object. "baseurl/users" |
items | collection | A collection containing the users that are members of the group. |
At the default depth=0
each of the items has the following attributes:
Name | Type | Description |
---|---|---|
id | string | The user's identifier. |
type | string | The type of response, in this case it is user. |
href | string | A URI for accessing the user object. "baseurl/um/users/{userId}" |
At depth=1
each of the items will include the metadata, properties, and
entities collections. Details on the contents of those collections can be found in the Retrieve a User section below.
Update details about a specific user including their privileges.
Submit a PUT request to https://api.ionos.com/cloudapi/v5/um/users/{userId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{userId} | yes | string | n/a | The ID of the specific user to update. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The JSON encoded request body may contain the following information:
Name | Required | Type | Default | Description |
---|---|---|---|---|
firstname | yes | string | n/a | A name for the user. |
lastname | yes | string | n/a | A name for the user. |
yes | string | n/a | An e-mail address for the user. | |
administrator | no | Boolean | false | Enables administrative rights for the user. |
forceSecAuth | no | Boolean | false | Indicates if secure authentication should be forced for the user. |
Note: The password attribute is immutable. It is not allowed in update requests. It is recommended that a new user log into the DCD and change their password.
Note: The attributes marked Required in the table need to be passed in, even if they are not being changed.
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}
{
"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"
}
}
}
Name | Type | Description |
---|---|---|
id | string | The user's identifier. |
type | string | The type of response, in this case it will be "user". |
href | string | A URI for accessing the user object. |
metadata | collection | A collection containing metadata for the user. |
properties | collection | A collection containing the user's properties. |
entities | collection | A collection containing resources the user owns, and groups the user is a member of. |
The metadata collection includes these attributes:
Name | Type | Description |
---|---|---|
etag | string | ETag for the user. |
creationDate | string | A time and date stamp indicating when the user was created. |
lastLogin | string | A time and date stamp indicating when the user last logged in. |
The properties collection includes these attributes:
Name | Type | Description |
---|---|---|
firstname | string | The first name of the user. |
lastname | string | The last name of the user. |
string | The e-mail address of the user. | |
administrator | Boolean | Indicates if the user has administrative rights. |
forceSecAuth | Boolean | Indicates if secure (two-factor) authentication was enabled for the user. |
secAuthActive | Boolean | Indicates if secure (two-factor) authentication is enabled for the user. |
The entities collection includes these attributes:
Name | Type | Description |
---|---|---|
owns | collection | A collection of resources that this user owns. |
groups | collection | A collection of groups that this user is a member of. |
Each of the owns or groups will include the following attributes.
Name | Type | Description |
---|---|---|
id | string | The group's identifier with /users or /resources appended. |
type | string | The type of response, in this case it will be "collection". |
href | string | A URL for directly accessing the object. |
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}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{userId} | yes | string | n/a | The ID of the specific user to delete. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
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}
202 - "successful operation" is returned.
Use this operation to create a new group and set group privileges.
Submit a POST request to https://api.ionos.com/cloudapi/v5/um/groups
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The JSON encoded request body may contain the following attributes:
Name | Required | Type | Default | Description |
---|---|---|---|---|
name | yes | string | n/a | A name for the group. |
createDataCenter | no | Boolean | false | The group will be allowed to create virtual data centers. |
createSnapshot | no | Boolean | false | The group will be allowed to create snapshots. |
reserveIp | no | Boolean | false | The group will be allowed to reserve IP addresses. |
accessActivityLog | no | Boolean | false | The group will be allowed to access the activity log. |
s3Privilege | no | Boolean | false | The group will be allowed to manage S3. |
createBackupUnit | no | Boolean | false | The group will be able to manage backup units. |
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
{
"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
}
}
Name | Type | Description |
---|---|---|
id | string | The new group's identifier. |
type | string | The type of response, in this case it will be "group". |
href | string | A URI for accessing the object. |
properties | collection | A collection containing the group's properties. |
entities | collection | A collection containing users and resources associated with the group. |
The properties collection includes these attributes:
Name | Type | Description |
---|---|---|
name | string | A name that was given to the group. |
createDataCenter | Boolean | The group has permission to create virtual data centers. |
createSnapshot | Boolean | The group has permission to create snapshots. |
reserveIp | Boolean | The group has permission to reserve IP addresses. |
accessActivityLog | Boolean | The group has permission to access the activity log. |
s3Privilege | Boolean | The group can interact with S3. |
createBackupUnit | Boolean | The group can create backup units. |
Retrieves detailed information about a specific group.
Submit a GET request to https://api.ionos.com/cloudapi/v5/um/groups/{groupId}
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
{groupId} | yes | string | n/a | The ID of the specific group to retrieve. |
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5/um/groups/{groupId}?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5/um/groups/{groupId}?depth=1
Note: For this particular operation, increasing the value supplied to depth
will return additional information beyond the default amount returned with a value of 0.
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
{
"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.
Name | Type | Description |
---|---|---|
id | string | The group's identifier. |
type | string | The type of response, in this case it will be "group". |
href | string | A URI for accessing the object. |
properties | collection | A collection containing the group's properties. |
entities | collection | A collection containing users and resources associated with the group. |
The properties collection includes these attributes:
Name | Type | Description |
---|---|---|
name | string | A name that was given to the group. |
createDataCenter | Boolean | The group has permission to create virtual data centers. |
createSnapshot | Boolean | The group has permission to create snapshots. |
reserveIp | Boolean | The group has permission to reserve IP addresses. |
accessActivityLog | Boolean | The group has permission to access the activity log. |
s3Privilege | Boolean | The group can interact with S3. |
createBackupUnit | Boolean | The group can create backup units. |
The entities collection includes these attributes:
Name | Type | Description |
---|---|---|
users | collection | A collection of users that belong to this group. |
resources | collection | A collection of resources that are assigned to this group. |
Each of the users or resources will include the following attributes.
Name | Type | Description |
---|---|---|
id | string | The group's identifier with /users or /resources appended. |
type | string | The type of response, in this case it will be "collection". |
href | string | A URL for directly accessing the object. |
At depth=1
additional information is returned in an items collection for each of the
users or resources.
At depth=2
or greater, then additional metadata, properties, and entities are returned for each of the
items.
This retrieves a full list of all groups.
Submit a GET request to https://api.ionos.com/cloudapi/v5/um/groups
The following request headers are available:
Header | Required | Type | Default | Description |
---|---|---|---|---|
Authorization | yes | string | n/a | HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password" |
X-Contract-Number | no | integer | n/a | Users with more than one contract may supply this header to indicate the applicable contract. |
Content-Type | yes | string | n/a | Set this to "application/json". |
The following optional query parameters may be included.
Parameter | Type | Default | Description |
---|---|---|---|
pretty | Boolean | true | Indicates if the response data should be "pretty-printed" with indentation and new lines. |
depth | int32 | 0 | An integer value [0-10] that determines the amount of detail returned. |
You can force the results to be less human-readable by supplying a value of 0 or false for
pretty
:
https://api.ionos.com/cloudapi/v5//um/groups?pretty=0
You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as
depth
:
https://api.ionos.com/cloudapi/v5//um/groups?depth=1
Note: For this particular operation, increasing the value supplied to depth
will return additional information beyond the default amount returned with a value of 0.
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/
{
"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"
}
]
}
The response will contain metadata, group properties, and group entities as described below.
Name | Type | Description |
---|---|---|
id | string | "groups" |
type | string | The type of response, in this case it will be "collection". |
href | string | A URI for accessing the object. "um/groups" |
items | collection | A collection of groups. |
At the default depth
value of 0
, each of the items contains the following information:
Name | Type | Description |
---|---|---|
id | string | The group's identifier. |
type | string | The type of response, in this case it will be "group". |
href | string | A URI for accessing the group. |
If a depth
value of 1
is passed in as a query parameter, then the response will include
details about each item as outlined in these tables.
Name | Type | Description |
---|---|---|
id | string | The group's identifier. |
type | string | The type of response, in this case it will be "group". |
href | string | A URI for accessing the group. |
properties | collection | A list of group properties. |
entities | collection | A collection of entities (users and resources) that are part of the group. |
These are the properties that may be returned.
Name | Type | Description |
---|---|---|
name | string | A name that was given to the group. |
createDataCenter | Boolean | The group has permission to create virtual data centers. |
createSnapshot | Boolean | The group has permission to create snapshots. |
reserveIp | Boolean | The group has permission to reserve IP addresses. |
accessActivityLog | Boolean | The group has permission to access the activity log. |
s3Privilege |