Cloud API v3.0 - Use the latest: v4.0 - Legacy: v2.0 v1.0


Overview

IONOS provides an enterprise-grade Infrastructure as a Service (IaaS) solution that can be managed through a browser-based "Data Center Designer" (DCD) tool or via an easy to use API.

The API allows you to perform a variety of management tasks such as spinning up additional servers, adding volumes, adjusting networking, and so forth. It is designed to allow users to leverage the same power and flexibility found within the DCD visual tool. Both tools are consistent with their concepts and lend well to making the experience smooth and intuitive.

What's New?

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

https://api.profitbricks.com/cloudapi/v3/

Cloud API version 3 adds the following new features:

New Location us/ewr

We are excited to announce a new location, us/ewr, which is now available for your use. This regional location is situated in the eastern part of the United States in the city of Newark, NJ. All accounts have access to provision computing, storage, and other resources in this new location.

Availability Zones for Storage Volumes

While it has been possible to assign computing resources to separate availability zones, the Cloud API has now been enhanced to include a similar feature for HDD storage volumes. With compute resources, the option exists to have resources assigned to one of two availability zones. With the new storage volume parameter, availabilityZone, it is possible to direct a storage volume to be created in one of three zones per data center. This allows for the deployment of enhanced high-availability configurations.

Both compute and storage availability zones are discussed in the DCD online help.

An example of provisioning a storage volume with a specific availability zone using the Cloud API is available in the Create Volume section of this documentation.

Valid values for availabilityZone are: AUTO, ZONE_1, ZONE_2, or ZONE_3.

The availabilityZone parameter may be set to any of those four values when creating new HDD storage volumes. This feature is currently being finalized and coming soon for SSD storage volumes. You may omit the parameter, or set it to AUTO when provisioning SSD volumes.

This feature is available NOW to all IONOS accounts.

NAT parameter for NICs

The new paramater for NIC operations, nat, can be set to true or false to indicate if the NIC will perform Network Address Translation.

Setting the nat parameter to true allows a NIC that is part of an internal or private LAN to access the public internet. Setting this option enables a virtual machine to make outbound connections, but not accept inbound connections. This is particularly useful for downloading operating system updates or other software patches directly to a system that is otherwise isolated from the public internet.

The nat parameter may be toggled between true and false at any time on NICs of both provisioned and unprovisioned virtual servers.

There are a few requirements:

  • The NIC this is being activated on must belong to a private LAN.
  • The NIC must not belong to a load balancer.
  • NAT cannot be activated in a private LAN that contains an IPv4 address ending with ".1".
  • NAT should not be enabled in a Virtual Data Center with an active IONOS firewall.

Additional details will be available in the NIC section of this documentation once this feature is released.

This feature is Coming Soon to all IONOS accounts.

New Licence Type for Microsoft Windows Server 2016

With the release of Microsoft Windows Server 2016, a new value for "licenceType" of WINDOWS2016 is now available.

The following table outlines the various licence types you can define when working with volumes:

Licence Type Comment
WINDOWS2016 Use this when running a Microsoft Windows 2016 operating system.
WINDOWS Specify this if you are running a Windows 2008 or Windows 2012 operating system.
LINUX Use this when running a Linux distribution such as Ubuntu, CentOS, Debian, etc.
OTHER Use for an image that does not fit in any other licence category.
UNKNOWN If you are using an image uploaded to your account your licenceType may show as UNKNOWN. Specify one of the other valid licenceType values to replace this.

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

Getting Started

How to Access the API

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

URL Description
https://api.profitbricks.com/cloudapi/v3/ CloudAPI v3 Endpoint

Swagger UI

It is possible to visually explore the Cloud API v3 by using the Swagger.io Swagger UI tool. Instructions on setting it up are located at that link.

You can quickly explore the Cloud API v3 by visiting the Swagger UI Online Demo and entering https://api.profitbricks.com/cloudapi/v3/swagger.json in the box at the top of the screen. Then press the Explore button to have it retrieve and parse the JSON file.

Protocol Elements

Request Methods

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

HTTP Status Codes

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

HTTP Headers

Request Headers

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

Authorization

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

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

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

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

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

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

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

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

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

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

If you are experiencing difficulty authenticating with the encoded credentials:

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

Response Headers

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

Data Representation

The Cloud API implements the standard application/json content type.

The Accept header can be omitted in a GET request; however, if it is present then 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.

Request Depth

You can pass the parameter depth to the following GET requests:

  • Data Centers
  • Servers
  • Volumes
  • LoadBalancers
  • NICs
  • LANs

The supported depth range is [0-5] with 5 returning the most amount of information. You would simply append ?depth=[value] to the end of your GET request.

Implicit Volume Creation

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

The following stories are support using create-attach:

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

Creation, Modification, and Deletion Responses

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

DELETE responses return an empty body.

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

The response status code 202 Accepted is returned.

PATCH requests

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

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

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

Entity Tags

GET responses will return an ETag header.

Usage Examples:

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

Error format

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

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

Date Format

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

YYYY-MM-DDThh:mm:ssZ

Resource Types

Document

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

Example:

[base-url]/.../servers/[server-id]
[base-url]/locations/de/fkb

Collection

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

Example:

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

Controller

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

Example:

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

Callback Resources for Asynchronous Calls

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

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

Callback Resource

Callback resources are available under:

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

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

Polling

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

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

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

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

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

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

The payload is a Request Status object.

Example:

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

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

User Management

IONOS supports a user management feature which allows you to restrict access to resources in the DCD or API. These permissions are inherited into the REST API.

Currently, this is managed via the DCD, but enforced in the API.

Users & Groups

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

The API adheres to all permissions applied through the DCD:

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

Groups

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

API Rate Limits

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

Multi-user

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

Separate Limits for Read and Write

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

Exceeding the Limit

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

HTTP Status Codes

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

Response Headers

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

Data Centers

Create a Data Center

Virtual data centers are the foundation of the 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.

Create a Data Center

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request Body

To create a data center, send a POST request to https://api.profitbricks.com/cloudapi/v3/datacenters

The format of the request body is as follows:

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

The following table describes the elements of the request body:

Name Type Description Required
name string The name of the data center. Yes
location string The physical location where the data center will be created. This will be where all of your servers live. us/ewr, us/las, de/fra, de/fkb Yes
description string A description for the data center, e.g. staging, production. No

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

NOTE: You cannot change a data center's location once it has been provisioned.

The following table outlines the locations currently supported:

Value Country City
us/las United States Las Vegas, NV
us/ewr United States Newark, NJ
de/fra Germany Frankfurt
de/fkb Germany Karlsruhe
Curl Example

The following shows how to submit the 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.profitbricks.com/cloudapi/v3/datacenters

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.profitbricks.com/cloudapi/v3/requests/[data-center-id]/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" : "[data-center-id]",
  "type" : "datacenter",
  "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "[data-center-name]",
    "description" : "[data-center-description]",
    "location" : "[data-center-location]",
    "version" : null,
    "features" : [ ]
  }
}
Response Parameters

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

Name Description
id The resource's unique identifier (UUID) in the form 8-4-4-4-12.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state 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 The etag for the request.
name The name of the data center.
description The description of the data center.
location The location of the data center.
version The version of the data center.
features Reserved for future use.

Create a Data Center with Multiple Resources

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request Body

To create a virtual data center, send a POST request to https://api.profitbricks.com/cloudapi/v3/datacenters

The format of the request body is as follows:

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

The following table describes the elements of the request body:

Name Type Description Required
name string The name of the data center. Yes
location string The physical location where the data center will be created. This will be where all of your servers live. Yes
description string A description for the data center, e.g. staging, production. No
servers collection You can define multiple servers to be created when the data center is created. See create server for request parameter details. No
volumes collection A collection that represents volumes you wish to create upon data center creation. See create storage volume for request parameter details. No
loadbalancers collection A collection that represents the loadbalancers you wish to create upon data center creation. No
lans collection A collection that represents the LANs you wish to create upon data center creation. No

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

NOTE: You cannot change a data center's physical location once it has been provisioned.

The following table outlines the locations currently supported:

Value Country City
us/las United States Las Vegas, NV
us/ewr United States Newark, NJ
de/fra Germany Frankfurt
de/fkb Germany Karlsruhe
Curl Example

The following shows how to submit the 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": "us/las"
  },
  "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.profitbricks.com/cloudapi/v3/datacenters

Response

HTTP/1.1 100 Continue

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.profitbricks.com/cloudapi/v3/requests/[request-status-id]/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" : "[data-center-id]",
  "type" : "datacenter",
  "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "[data-center-name]",
    "description" : "Example Description",
    "location" : "us/las",
    "version" : null,
    "features" : [ ]
  },
  "entities" : {
    "servers" : {
      "id" : "[server-id]/servers",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers"
    },
    "lans" : {
      "id" : "[data-center-id]/lans",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/lans"
    }
  }
}
Response Parameters

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).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state 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 The etag for the request.
name The name of the data center.
description The description of the data center.
location The location you provisioned the data center.
version The version of the data center.
servers You can define multiple servers to be created when the data center is created. See create server for request parameter details.
volumes A collection that represents volumes you wish to create upon data center creation. See create storage volume for request parameter details.
loadbalancers A collection that represents the loadbalancers you wish to create upon data center creation.
lans A collection that represents the LANs you wish to create upon data center creation.

Retrieve a Data Center

You can retrieve a data center by using the resource's ID. This value can be found in the response body when a data center is created or when you GET a list of data centers.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request

To retrieve a data center, send a GET request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]

Request Parameters

The following table describes the elements of the GET request:

Name Type Description Required
data-center-id string The unique ID of the data center. Yes

Note: You can add ?depth=1 to the request to retrieve more detail on the entities.

Curl Example

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

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
 https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]

Response

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

{
  "id" : "[data-center-id]",
  "type" : "datacenter",
  "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "AVAILABLE"
  },
  "properties" : {
    "name" : "ExampleDataCenter",
    "description" : "Example Description",
    "location" : "us/las",
    "version" : 22,
    "features" : [ ]
  },
  "entities" : {
    "servers" : {
      "id" : "[data-center-id]/servers",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers"
    },
    "volumes" : {
      "id" : "[data-center-id]/volumes",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/volumes"
    },
    "loadbalancers" : {
      "id" : "[data-center-id]/loadbalancers",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/loadbalancers"
    },
    "lans" : {
      "id" : "[data-center-id]/lans",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/lans"
    }
  }
}

Response Parameters

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).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state Data center state.
etag The etag for the resource.
name The name of the data center.
description The description of the data center.
location The location you provisioned the data center.
version The version of the data center.
servers A collection that represents the servers in a data center.
volumes A collection that represents volumes in a data center.
loadbalancers A collection that represents the loadbalancers in a data center.
lans A collection that represents the LANs in a data center.

The following table illustrates the possible data center states:

State Description
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.

List Data Centers

You can retrieve a complete list of data centers provisioned under your account.

Request

Request Headers

The request headers should be the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request

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

Request Parameters

Additional information can be requested by appending ?depth=X to the request where X is a value [0-5] with 0 returning the least amount of additonal information and 5 returing the most information available.

Curl Example

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

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

Response

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

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

Response Parameters

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).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state Data center state.
etag The etag for the resource.
name The name of the data center.
description The description of the data center.
location The location you provisioned the data center.
version The version of the data center.

Update a Data Center

The API adheres to RFC standards and therefore implements both PUT and PATCH for updates. You will need to choose one or the other depending on the type of update you wish to perform.

You would use PATCH when performing a partial update to a resource, e.g. you are updating the name of a data center.

You would use PUT when you wish to replace the properties of a resource. This would require you to pass all properties in the request versus a partial list.

In most cases you will be using PATCH.

You can use update data center to rename the data center or update its description.

PATCH Update

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request

To partially update a data center you would send a PATCH request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]

Request Parameters

The following table describes the elements of the request body:

Name Type Description Required
name string An updated name for the virtual data center. No
description string An updated description of the virtual data center. No
Curl Example

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

curl --include \
     --request PATCH \
     --header "Content-Type: application/json" \
     --data-binary '    {
        "name": "Example DC Rename",
        "description": "Example DC Description"
    }' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.profitbricks.com/cloudapi/v3/requests/[request-status-id]/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" : "[data-center-id]",
  "type" : "datacenter",
  "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "Example DC Rename",
    "description" : "Example DC Description",
    "location" : "us/las",
    "version" : 22,
    "features" : [ ]
  },
  "entities" : {
    "servers" : {
      "id" : "[data-center-id]/servers",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers"
    },
    "volumes" : {
      "id" : "[data-center-id]/volumes",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/volumes"
    },
    "loadbalancers" : {
      "id" : "[data-center-id]/loadbalancers",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/loadbalancers"
    },
    "lans" : {
      "id" : "[data-center-id]/lans",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/lans"
    }
  }
}
Response Parameters

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).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state 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.
name The name of the data center.
description The description of the data center.
location The location you provisioned the data center.
version The version of the data center.
servers You can define multiple servers to be updated when the data center is updated. See create server for request parameter details.
volumes A collection that represents volumes you wish to update upon data center update. See create storage volume for request parameter details.
loadbalancers A collection that represents the loadbalancers you wish to update upon data center update.
lans A collection that represents the LANs you wish to create upon data center creation.

PUT Update

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request

To fully update a data center, send a PUT request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]

Request Parameters

The following table describes the required elements of the request body:

Name Type Description Required
name string An updated name for the virtual data center. Yes
description string An updated description of the virtual data center. Yes

You can update any of the values but all values must be passed. This means if you are only updating 'name' you would pass the new name along with the current description when using PUT.

Curl Example

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

curl --include \
     --request PUT \
     --user 'username@domain.tld:password'
     --header "Content-Type: application/json" \
     --data-binary '    {
        "properties": {
            "name": "Example DC Rename 2",
            "description": "Example DC Description 2"
        }
    }' \
     `https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.profitbricks.com/cloudapi/v3/requests/[request-status-id]/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" : "[data-center-id]",
  "type" : "datacenter",
  "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "Example DC Rename 2",
    "description" : "Example DC Description 2",
    "location" : "us/las",
    "version" : 24,
    "features" : [ ]
  },
  "entities" : {
    "servers" : {
      "id" : "[data-center-id]/servers",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers"
    },
    "volumes" : {
      "id" : "[data-center-id]/volumes",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/volumes"
    },
    "loadbalancers" : {
      "id" : "[data-center-id]/loadbalancers",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/loadbalancers"
    },
    "lans" : {
      "id" : "[data-center-id]/lans",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/lans"
    }
  }
}
Response Parameters

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).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state 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.
name The name of the data center.
description The description of the data center.
location The location you provisioned the data center.
servers You can define multiple servers to be updated when a data center is updated. See create server for request parameter details.
volumes A collection that represents volumes to update upon data center update. See create storage volume for request parameter details.
loadbalancers A collection that represents the loadbalancers you wish to update upon data center update.
lans A collection that represents the LANs you wish to create upon data center creation.

Delete a Data Center

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

Request

Request Headers

The DELETE request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request

To remove a data center you would send a DELETE request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]

Request Parameters

The following table describes the elements of the DELETE URL:

Name Type Description Required
data-center-id string The UUID of the data center. Yes

Curl Example

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

curl --include \
     --request DELETE \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]
Response
HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: [date]
Location: https://api.profitbricks.com/cloudapi/v3/requests/[request-status-id]/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Length: 0
Strict-Transport-Security: max-age=15768000
Response Parameters

None

Checking the Status

Using the Location: 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.profitbricks.com/cloudapi/v3/requests/[request-status-id]/status
Status Response

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

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

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

Locations

List Locations

Retrieve a list of all locations. This list represents regions where you can provision your virtual data centers.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

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

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

An example response to a GET location request, headers first, then JSON response body:

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

{
  "id" : "locations",
  "type" : "collection",
  "href" : "https://api.profitbricks.com/cloudapi/v3/locations",
  "items" : [ {
    "id" : "de/fkb",
    "type" : "location",
    "href" : "https://api.profitbricks.com/cloudapi/v3/locations/de/fkb"
  }, {
    "id" : "de/fra",
    "type" : "location",
    "href" : "https://api.profitbricks.com/cloudapi/v3/locations/de/fra"
  }, {
    "id" : "us/ewr",
    "type" : "location",
    "href" : "https://api.profitbricks.com/cloudapi/v3/locations/us/ewr"
  }, {
    "id" : "us/las",
    "type" : "location",
    "href" : "https://api.profitbricks.com/cloudapi/v3/locations/us/las"
  } ]
}

Including a ?depth=5 parameter will return additional properties for each location:

"items" : [ {
"id" : "de/fkb",
"type" : "location",
"href" : "https://api.profitbricks.com/cloudapi/v3/locations/de/fkb",
"properties" : {
  "name" : "karlsruhe",
  "features" : [ ]
}

]

Response Parameters

The request will return a collection of locations.

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

Name Description
id The resource's unique identifier consisting of country/city.
type The type of object.
href URL to the object’s representation (absolute path).
name A descriptive name for the location.
features Features available at this location.

Get Location

Retrieves the attributes of a given location.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To retrieve a single location you would send a GET request to https://api.profitbricks.com/cloudapi/v3/locations/[location_id]

Request Parameters

None

Curl Example

To request details on the de/fkb location using curl:

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

Response

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

{
  "id" : "de/fkb",
  "type" : "location",
  "href" : "https://api.profitbricks.com/cloudapi/v3/locations/de/fkb",
  "properties" : {
    "name" : "karlsruhe",
    "features" : [ ]
  }
}

Response Parameters

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

Name Description
id The resource's unique identifier consisting of country/city.
type The type of object.
href URL to the object’s representation (absolute path).
name A descriptive name for the location.
features Features available at this location.

Servers

Create a Server

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

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request Body

To create a server send a POST request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers

The following request will create a server and implicitly create a storage volume. If the storage volume already exists you simply reference its 'id' value as the only parameter within the volumes collection, i.e. "id": "[storage-volume-id]".

The format of the request body is as follows:

{
    "properties": {
        "name": "[server-name]",
        "ram": [server-memory-in-mb],
        "cores": [server-cores]
    },
    "entities": {
        "volumes": {
            "items": [
                {
                    "properties": {
                        "size": [storage-volume-size-in-gb],
                        "name": "[storage-volume-name]",
                        "image": "[storage-volume-image-uuid]",
                        "bus": "[storage-volume-bus-type]"
                    }
                }
            ]
        }
    }
}

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

{
   "entities":{
      "volumes":{
         "items":[
            {
               "id":"[existing-storage-volume-id]"
            }
         ]
      }
   },
   "properties":{
      "cores": [server-cores],
      "ram": "[server-memory-in-mb]",
      "name": "[server-name]"
   }
}

Request Parameters

The following table describes all supported values for the request body:

Name Type Description Required
name string The hostname of the server. Yes
cores int The total number of cores for the server. Yes
ram int 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. Yes
availabilityZone string The availability zone in which the server should exist. [AUTO, ZONE_1, ZONE_2] No
bootVolume string Reference to a Volume used for booting. If not ‘null’ then bootCdrom has to be ‘null’. No
bootCdrom string Reference to a CD-ROM used for booting. If not 'null' then bootVolume has to be 'null'. No
cpuFamily string Sets the CPU type. "AMD_OPTERON" or "INTEL_XEON". Defaults to "AMD_OPTERON". No
volumes collection A collection of volume IDs that you want to connect to the server. If the volume does not exist it will be created. Please refer to Volumes for additional details. No
nics collection A collection of NICs you wish to create at the time the server is provisioned. If the NIC does not exist it will be created. Please refer to NICS for additional details. No

The following table outlines the compute resource availability zones currently supported:

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

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

Curl Example

As an example, we will provision a server in a virtual data center located in us/las using the CentOS 7 public image with a single NIC connected to LAN 1 with an IP address assigned using DHCP. The CentOS 7 public image ID, eedb14c9-fe2c-11e6-afc5-525400f64d8d is current as of March 2017. It may change in the future.

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": "APIv3Docs1",
            "ram": 2048,
            "cores": 2,
            "availabilityZone": "AUTO",
            "cpuFamily": "INTEL_XEON"
            },
        "entities": {
            "volumes": {
               "items": [
                {
                  "properties": {
                    "size": 30,
                    "name": "APIv3Docs1_vol",
                    "image": "eedb14c9-fe2c-11e6-afc5-525400f64d8d",
                    "imagePassword": "[long-random-password-here]",
                    "bus": "VIRTIO",
                    "type": "HDD",
                    "availabilityZone": "AUTO"
                  }
                }
                ]
            },
            "nics": {
               "items": [
               {
                 "properties": {
                   "name": "NIC001",
                   "dhcp": true,
                   "lan": 1,
                   "nat": false
                 }
               }
               ]
            }
        }
}' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers

To use this example yourself, you would need to have a valid virtual data center provisioned in 'us/las', as the imageId is located in that region.

Note: When creating a volume, you must specify either the licenceType or an image. You must also supply an imagePassword and/or sshKeys.

Please Note: The nat property in the nics section is NOT available yet, but is Coming Soon.

Response

HTTP/1.1 202 Accepted
Date: Mon, 06 Mar 2017 22:47:25 GMT
Server: Apache/2.4.10 (Debian)
Location: https://api.profitbricks.com/cloudapi/v3/requests/e7995440-3694-4903-b653-caa396b63e41/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: d291a4592793f8bc65684fd9fab50de8
Content-Type: application/json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "1afe03ed-08b1-435b-bcab-d80b41a82cb3",
  "type" : "server",
  "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/8fc590c3-4cfb-4702-8bd6-7290ad46f6ea/servers/1afe03ed-08b1-435b-bcab-d80b41a82cb3",
  "metadata" : {
    "createdDate" : "2017-03-06T22:47:25Z",
    "createdBy" : "username@domain.tld",
    "etag" : "d291a4592793f8bc65684fd9fab50de8",
    "lastModifiedDate" : "2017-03-06T22:47:25Z",
    "lastModifiedBy" : "username@domain.tld",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "APIv3Docs2",
    "cores" : 2,
    "ram" : 2048,
    "availabilityZone" : "AUTO",
    "vmState" : null,
    "bootCdrom" : null,
    "bootVolume" : null,
    "cpuFamily" : "INTEL_XEON"
  },
  "entities" : {
    "volumes" : {
      "id" : "1afe03ed-08b1-435b-bcab-d80b41a82cb3/volumes",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/8fc590c3-4cfb-4702-8bd6-7290ad46f6ea/servers/1afe03ed-08b1-435b-bcab-d80b41a82cb3/volumes"
    },
    "nics" : {
      "id" : "1afe03ed-08b1-435b-bcab-d80b41a82cb3/nics",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/8fc590c3-4cfb-4702-8bd6-7290ad46f6ea/servers/1afe03ed-08b1-435b-bcab-d80b41a82cb3/nics"
    }
  }
}

Response Parameters

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).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state 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.
name The name of the server.
cores The number of cores for the server.
ram The amount of memory on the server.
availabilityZone The availability zone for the server.
vmState The current state of the virtual machine. [NOSTATE, RUNNING, BLOCKED, PAUSED, SHUTDOWN, SHUTOFF, CRASHED]
bootCdrom Reference to a CD-ROM used for booting.
bootVolume Reference to a Volume used for booting.
cpuFamily Type of CPU assigned.
cdroms A collection of cdroms attached to the server.
volumes A collection of volumes attached to the server.
nics A collection of NICs attached to the server.

Retrieve a Server

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

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To retrieve a server, send a GET request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]

Request Parameters

None

Curl Example

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

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]

Response

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

{
  "id" : "[server-id]",
  "type" : "server",
  "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "AVAILABLE"
  },
  "properties" : {
    "name" : "Server001",
    "cores" : 1,
    "ram" : 512,
    "availabilityZone" : "ZONE_1",
    "vmState" : "RUNNING",
    "bootCdrom" : null,
    "bootVolume" : {
      "id" : "[volume-id]",
      "type" : "volume",
      "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/volumes/[volume-id]"
    },
    "cpuFamily" : "AMD_OPTERON"
  },
  "entities" : {
    "cdroms" : {
      "id" : "[server-id]/cdroms",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/cdroms"
    },
    "volumes" : {
      "id" : "[server-id]/volumes",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/volumes"
    },
    "nics" : {
      "id" : "[server-id]/nics",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics"
    }
  }
}

Response Parameters

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).
lastModifiedDate The last modified time for the resource.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state 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.
etag The etag.
name The name of the server.
cores The number of cores for the server.
ram The amount of memory on the server.
availabilityZone The availability zone for the server.
vmState Status of the virtual Machine. [NOSTATE, RUNNING, BLOCKED, PAUSED, SHUTDOWN, SHUTOFF, CRASHED]
bootCdrom Reference to a CD-ROM used for booting. If not 'null' then bootVolume has to be 'null'.
bootVolume Reference to a Volume used for booting. If not ‘null’ then bootCdrom has to be ‘null’
cpuFamily Type of CPU assigned.
volumes A collection of volumes attached to the server.
cdroms A collection of cdroms attached to the server.
nics A collection of NICs attached to the server.
Server States

The following table illustrates 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 Virtual Server will still consume allocated resources like memory but will not be eligible for scheduling.
SHUTDOWN The server is in the process of being shutdown correctly.
SHUTOFF The server is currently offline.
CRASHED The server is in a crashed, non-bootable state.

List Servers

You can retrieve a list of all servers within a data center.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To retrieve a list of servers, send a GET request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers

Request Parameters

You can append ?depth=1 to the request to retrieve additional details.

Curl Example

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

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
 https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers

Response

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

{
  "id" : "[data-center-id]/servers",
  "type" : "collection",
  "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers",
  "items" : [ {
    "id" : "[first-server-id]",
    "type" : "server",
    "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[first-server-id]"
  }, {
    "id" : "[second-server-id]",
    "type" : "server",
    "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[second-server-id]"
  } ]
}

Response Parameters

The request will return a collection of servers.

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).
lastModifiedDate The last modified time for the resource.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state 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.
etag The etag.
name The name of the server.
cores The number of cores for the server.
ram The amount of memory on the server.
availabilityZone The availability zone for the server.
vmState The current state of the virtual machine. [NOSTATE, RUNNING, BLOCKED, PAUSED, SHUTDOWN, SHUTOFF, CRASHED]
bootVolume Reference to a Volume used for booting. If not ‘null’ then bootCdrom has to be ‘null’.
bootCdrom Reference to a CD-ROM used for booting. If not 'null' then bootVolume has to be 'null'.
cpuFamily Type of CPU assigned.
cdroms A collection of cdroms attached to the server.
volumes A collection of volumes attached to the server.
nics A collection of NICs attached to the server.

Update a Server

The Cloud API adheres to RFC standards and therefore implements both PUT and PATCH for updates. You will need to choose one or the other depending on the type of update you wish to perform.

Use PATCH when performing a partial update to a resource, e.g. you are updating the name of a server.

Use PUT to replace the properties of a resource. This would require you to pass in ALL properties, changed and unchanged, in the request.

In most cases you will be using PATCH.

You can update -- in full or partially -- various attributes on the server using the above methods.

Please Note: It is possible to update the cpuFamily value and change the processor type assigned to a server between "AMD_OPTERON" and "INTEL_XEON".

PATCH

Use PATCH to perform partial updates to the attributes of a server.

Request

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request Body

To perform a partial update to the server's properties you would submit a PATCH request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]

Request Parameters
Name Type Description Required
name string The name of the server. No
cores int The number of cores for the server. No
ram int The amount of memory in the server. No
availabilityZone string The new availability zone for the server. No
bootVolume string Reference to a Volume used for booting. If not ‘null’ then bootCdrom has to be ‘null’ No
bootCdrom string Reference to a CD-ROM used for booting. If not 'null' then bootVolume has to be 'null'. No
cpuFamily string Sets the desired CPU type. "AMD_OPTERON" or "INTEL_XEON". No
allowReboot boolean Allow a hard server reboot, if necessary. No *

Please Note: The allowReboot parameter may need to be set if the changes you are making require a server reboot. An example would be changing the cpuFamily from "AMD_OPTERON" to "INTEL_XEON". This change cannot be made while a server is running and requires a reboot.

If you do not set allowReboot when it is needed, you should get an error message returned, something similar to:

ERROR: Excon::Error::UnprocessableEntity: [{"errorCode"=>"153", "message"=>"[(root).properties.cpuFamily] A cpu family change requires a server restart and has to be confirmed by setting the parameter 'allowReboot' to true"}]

Setting allowReboot to true indicates that you are okay with a hard server reboot, akin to powering the server off and back on again. This is NOT a graceful shutdown and restart process. If you would prefer to have this handled in a graceful manner, you will need to shutdown the affected server from inside its operating system.

Curl Example

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

curl --include \
     --request PATCH \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '    {
        "name": "Server001A"
    }' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.profitbricks.com/cloudapi/v3/requests/[request-status-id]/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" : "[server-id]",
  "type" : "server",
  "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[username]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[username]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "Server001A",
    "cores" : 1,
    "ram" : 512,
    "availabilityZone" : "AUTO",
    "vmState" : "RUNNING",
    "bootCdrom" : null,
    "bootVolume" : {
      "id" : "[volume-id]",
      "type" : "volume",
      "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/volumes/[volume-id]"
    },
    "cpuFamily" : "AMD_OPTERON"
  },
  "entities" : {
    "cdroms" : {
      "id" : "[server-id]/cdroms",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/cdroms"
    },
    "volumes" : {
      "id" : "[server-id]/volumes",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/volumes"
    },
    "nics" : {
      "id" : "367fffcd-965f-4aa5-a6c2-afbd81e407ba/nics",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics"
    }
  }
}
Response Parameters

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).
lastModifiedDate The last modified time for the resource.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state 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.
etag The etag.
name The name of the server.
cores The number of cores for the server.
ram The amount of memory on the server.
availabilityZone The availability zone for the server. [AUTO, ZONE_1, ZONE_2]
vmstate The state of the virtual machine. [NOSTATE, RUNNING, BLOCKED, PAUSED, SHUTDOWN, SHUTOFF, CRASHED]
bootVolume Reference to a Volume used for booting. If not ‘null’ then bootCdrom has to be ‘null’
bootCdrom Reference to a CD-ROM used for booting. If not 'null' then bootVolume has to be 'null'.
cpuFamily Type of CPU assigned.
cdroms A collection of cdroms attached to the server.
volumes A collection of volumes attached to the server.
nics A collection of NICs attached to the server.

PUT

Use PUT to perform a full update of all attributes of a server.

Request

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request Body

To perform a full update of the server's properties you would send a PUT request to: https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]

Request Parameters
Name Type Description Required
name string The name of the server. Yes
cores int The number of cores for the server. Yes
ram int The amount of memory in the server. Yes
availabilityZone string The new availability zone for the server. [AUTO, ZONE_1, ZONE_2] Yes
bootVolume string Reference to a Volume used for booting. If not ‘null’ then bootCdrom has to be ‘null’ Yes
bootCdrom string Reference to a CD-ROM used for booting. If not 'null' then bootVolume has to be 'null'. Yes
cpuFamily string Sets the desired CPU type. "AMD_OPTERON" or "INTEL_XEON". Yes
allowReboot boolean Allow a hard server reboot, if necessary. No *

Please Note: The allowReboot parameter may need to be set if the changes you are making require a server reboot. An example would be changing the cpuFamily from "AMD_OPTERON" to "INTEL_XEON". This change cannot be made while a server is running and requires a reboot.

If you do not set allowReboot when it is needed, you should get an error message returned, something similar to:

ERROR: Excon::Error::UnprocessableEntity: [{"errorCode"=>"153", "message"=>"[(root).properties.cpuFamily] A cpu family change requires a server restart and has to be confirmed by setting the parameter 'allowReboot' to true"}]

Setting allowReboot to true indicates that you are okay with a hard server reboot, akin to powering the server off and back on again. This is NOT a graceful shutdown and restart process. If you would prefer to have this handled in a graceful manner, you will need to shutdown the affected server from inside its operating system.

Curl Example

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

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

Response

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.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]",
    "metadata": {
        "lastModifiedDate": "last-modified-date",
        "lastModifiedBy": "last-modified-by-user",
        "createdDate": "created-by-date",
        "createdBy": "created-by-user",
        "state": "state",
        "etag": "etag"
    },
    "properties": {
        "name": "server-name",
        "cores": "server-cores",
        "ram": "server-ram",
        "availabilityZone": "server-availability-zone",
        "bootVolume": {
            "id": "storage-id"
        },
        "bootCdrom": null
    },
    "entities": {
        "nics": [],
        "volumes": []
    }
}
Response Parameters

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).
lastModifiedDate The last modified time for the resource.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state 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.
etag The etag.
name The name of the server.
cores The number of cores for the server.
ram The amount of memory on the server.
availabilityZone The availability zone for the server.
vmState Status of the virtual Machine. [NOSTATE, RUNNING, BLOCKED, PAUSED, SHUTDOWN, SHUTOFF, CRASHED]
bootVolume Reference to a Volume used for booting. If not ‘null’ then bootCdrom has to be ‘null’
bootCdrom Reference to a CD-ROM used for booting. If not 'null' then bootVolume has to be 'null'.
cpuFamily Type of CPU assigned.
cdroms A collection of cdroms attached to the server.
volumes A collection of volumes attached to the server.
nics A collection of NICs attached to the server.

Delete a Server

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

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request Body

To remove a server, send a DELETE request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]

Request Parameters

None

Curl Example

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

curl --include \
     --request DELETE \
     --user 'username@domain.tld:password' \
 https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]

Response

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

Response Parameters

None

List Attached Volumes

You can retrieve a list of volumes attached to the server. By default the depth of this request is 0. If you wish to retrieve more information you can set the depth to 1. Both are covered in the below examples.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To get a list of attached volumes using the default depth you would send a GET request to: https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/volumes

To get a list of attached volumes using a depth of 1 you would send the following GET request: https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/volumes?depth=1

Request Parameters

None

Curl Example

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

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/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.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/volumes?depth=1

Response

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

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

{
  "id" : "[server-id]/volumes",
  "type" : "collection",
  "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/volumes",
  "items" : [ {
    "id" : "[volume-id]",
    "type" : "volume",
    "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/volumes/[volume-id]"
  } ]
}

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" : "[server-id]/volumes",
  "type" : "collection",
  "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/volumes",
  "items" : [ {
    "id" : "[volume-id]",
    "type" : "volume",
    "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/volumes/[volume-id]",
    "metadata" : {
      "createdDate" : "[date]",
      "createdBy" : "[user]",
      "etag" : "[etag]",
      "lastModifiedDate" : "[date]",
      "lastModifiedBy" : "[user]",
      "state" : "AVAILABLE"
    },
    "properties" : {
      "name" : "Server002_HDD",
      "type" : "HDD",
      "size" : 10,
      "image" : null,
      "imagePassword" : null,
      "bus" : "VIRTIO",
      "licenceType" : "LINUX",
      "cpuHotPlug" : false,
      "cpuHotUnplug" : false,
      "ramHotPlug" : false,
      "ramHotUnplug" : false,
      "nicHotPlug" : false,
      "nicHotUnplug" : false,
      "discVirtioHotPlug" : false,
      "discVirtioHotUnplug" : false,
      "discScsiHotPlug" : false,
      "discScsiHotUnplug" : false,
      "deviceNumber" : 1
    }
  } ]
}

Response Parameters

A collection of volumes is returned.

Please reference the Volumes section for attribute definitions.

Attach a Volume

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

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request Body

To attach a storage volume to a server, send a POST request to: https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/volumes

Request Parameters

The following table describes the request body values:

Name Type Description Required
id string The unique ID of a storage volume. Yes

Curl Example

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

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
     --data-binary '{
    "id": "[volume-id]"
}' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/volumes

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.profitbricks.com/cloudapi/v3/requests/[request-status-id]/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.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/volumes/[volume-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "ExtraSpace",
    "type" : "HDD",
    "size" : 10,
    "image" : null,
    "imagePassword" : null,
    "bus" : null,
    "licenceType" : "OTHER",
    "cpuHotPlug" : false,
    "cpuHotUnplug" : false,
    "ramHotPlug" : false,
    "ramHotUnplug" : false,
    "nicHotPlug" : false,
    "nicHotUnplug" : false,
    "discVirtioHotPlug" : false,
    "discVirtioHotUnplug" : false,
    "discScsiHotPlug" : false,
    "discScsiHotUnplug" : false,
    "deviceNumber" : null
  }
}

Response Parameters

Please see the Volumes section for attribute definitions.

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

Retrieve an Attached Volume

This will retrieve the properties of an attached volume.

Request

Request Headers

The request headers should be the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request Body

Send a GET request to: https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/volumes/[volume-id]

Request Parameters

None

Curl Example

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

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
 https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/volumes/[volume-id]

Response

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

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

Response Parameters

Please see the Volumes section for attribute definitions.

Detach a Volume

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

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

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

Send a DELETE request to: https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/volumes/[volume-id]

Request Parameters

None

Curl Example

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

curl --include \
     --request DELETE \
     --user 'username@domain.tld:password' \
 https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/volumes/[volume-id]

Response

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

Response Parameters

None

List Attached CD-ROMs

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

Request

Request Headers

The request headers should be the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To get a list of CD-ROMs attached to the server, send a GET request to: https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/cdroms

Request Parameters

None

Curl Example

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

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
 https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/cdroms

Response

You should receive a response similar to this:

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

{
  "id" : "[server-id]/cdroms",
  "type" : "collection",
  "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/cdroms",
  "items" : [ {
    "id" : "[image-id]",
    "type" : "image",
    "href" : "https://api.profitbricks.com/cloudapi/v3/images/[image-id]"
  } ]
}

The response will contain a collection of CD-ROMs.

Response Parameters

Please reference the CD-ROMs section for attribute definitions.

Attach a CD-ROM

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

Request

Request Headers

The request headers should be the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request Body

To attach a CD-ROM to a server, send a POST request to: https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/cdroms

Request Parameters

None

Curl Example

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

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '    {
         "id": "[cdrom-image-id]"
       }' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/cdroms

Response

You should receive a response similar to this:

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.profitbricks.com/cloudapi/v3/requests/[request-status-id]/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.profitbricks.com/cloudapi/v3/images/[image-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "ubuntu-14.04.3-server-amd64.iso",
    "description" : "",
    "location" : "us/las",
    "size" : 0.57,
    "cpuHotPlug" : false,
    "cpuHotUnplug" : false,
    "ramHotPlug" : false,
    "ramHotUnplug" : false,
    "nicHotPlug" : false,
    "nicHotUnplug" : false,
    "discVirtioHotPlug" : false,
    "discVirtioHotUnplug" : false,
    "discScsiHotPlug" : false,
    "discScsiHotUnplug" : false,
    "licenceType" : "LINUX",
    "imageType" : "CDROM",
    "public" : false
  }
}

Response Parameters

Please reference the CD-ROMs section for attribute definitions.

Retrieve Attached CD-ROM

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

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To get details on a specific CD-ROM attached to a server, send a GET request to: https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/cdroms/[cdrom-id]

Request Parameters

None

Curl Example

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

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
 https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/cdroms/[cdrom-id]

Response

You should receive a response similar to this:

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

{
  "id" : "[image-id]",
  "type" : "image",
  "href" : "https://api.profitbricks.com/cloudapi/v3/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" : "us/las",
    "size" : 0.57,
    "cpuHotPlug" : true,
    "cpuHotUnplug" : false,
    "ramHotPlug" : true,
    "ramHotUnplug" : false,
    "nicHotPlug" : true,
    "nicHotUnplug" : true,
    "discVirtioHotPlug" : true,
    "discVirtioHotUnplug" : true,
    "discScsiHotPlug" : false,
    "discScsiHotUnplug" : false,
    "licenceType" : "LINUX",
    "imageType" : "CDROM",
    "public" : true
  }
}

Response Parameters

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

Detach a CD-ROM

This will detach a CD-ROM from the server.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To detach a CDROM from a server, send a DELETE request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/cdroms/[cdrom-id]

Request Parameters

None

Curl Example

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

curl --include \
     --request DELETE \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/cdroms/[cdrom-id]

Response

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

Response Parameters

None

Reboot a Server

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

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To reboot a server, send a POST request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/reboot

Request Parameters

None

Curl Example

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

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/reboot

Response

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

Response Parameters

None

Start a Server

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

Request

Request Headers

The request headers should be the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To start a server, send a POST request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/start

Request Parameters

None

Curl Example

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

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/start

Response

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

Response Parameters

None

Stop a Server

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

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To stop a server you would send a POST request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/stop

Request Parameters

None

Curl Example

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

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/stop

Response

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

Response Parameters

None

Images

List Images

Retrieve a list of images within the data center.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

Appending ?depth=1 to the request will return additional details about each image.

Curl Example

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

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

Response

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

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

Response Parameters

The request will return a collection of images.

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).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state Image state.
name The name of the image.
description The description of the image.
location The image's location.
size The size of the image in GB.
cpuHotPlug This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug This volume is capable of memory hot plug (no reboot required)
ramHotUnplug This volume is capable of memory hot unplug (no reboot required)
nicHotPlug This volume is capable of nic hot plug (no reboot required)
nicHotUnplug This volume is capable of nic hot unplug (no reboot required)
discVirtioHotPlug This volume is capable of Virt-IO drive hot plug (no reboot required)
discVirtioHotUnplug This volume is capable of Virt-IO drive hot unplug (no reboot required)
discScsiHotPlug This volume is capable of Scsi drive hot plug (no reboot required)
discScsiHotUnplug This volume is capable of Scsi drive hot unplug (no reboot required)
licenceType The image's licence type: LINUX, WINDOWS, WINDOWS2016, OTHER or UNKNOWN.
imageType The type of image: HDD, CDROM.
public Indicates if the image is part of the public repository or not.

Get Image

Retrieves the attributes of a specific image.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To retrieve details on a single image send a GET request to https://api.profitbricks.com/cloudapi/v3/images/[image-id]

Request Parameters

None

Curl Example

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

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/cloudapi/v3/images/[image-id]

Response

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

{
  "id" : "[image-id]",
  "type" : "image",
  "href" : "https://api.profitbricks.com/cloudapi/v3/images/[image-id]",
  "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" : "de/fra",
    "size" : 0.23,
    "cpuHotPlug" : true,
    "cpuHotUnplug" : false,
    "ramHotPlug" : true,
    "ramHotUnplug" : false,
    "nicHotPlug" : true,
    "nicHotUnplug" : true,
    "discVirtioHotPlug" : true,
    "discVirtioHotUnplug" : true,
    "discScsiHotPlug" : false,
    "discScsiHotUnplug" : false,
    "licenceType" : "LINUX",
    "imageType" : "CDROM",
    "public" : true
  }
}

Response Parameters

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).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state Image state.
name The name of the image.
description The description of the image.
location The image's location.
size The size of the image in GB.
cpuHotPlug This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug This volume is capable of memory hot plug (no reboot required)
ramHotUnplug This volume is capable of memory hot unplug (no reboot required)
nicHotPlug This volume is capable of nic hot plug (no reboot required)
nicHotUnplug This volume is capable of nic hot unplug (no reboot required)
discVirtioHotPlug This volume is capable of Virt-IO drive hot plug (no reboot required)
discVirtioHotUnplug This volume is capable of Virt-IO drive hot unplug (no reboot required)
discScsiHotPlug This volume is capable of Scsi drive hot plug (no reboot required)
discScsiHotUnplug This volume is capable of Scsi drive hot unplug (no reboot required)
licenceType The image's licence type: LINUX, WINDOWS, WINDOWS2016, OTHER or UNKNOWN.
imageType The type of image: HDD, CDROM.
public Indicates if the image is part of the public repository or not.

Delete Image

Deletes the specified image.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To delete an image send a DELETE request to https://api.profitbricks.com/cloudapi/v3/images/[image-id]

Request Parameters

None

Curl Example

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

curl --include \
     --request DELETE \
     --user 'username@domain.tld:password' \
 https://api.profitbricks.com/cloudapi/v3/images/[image-id]

Response

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

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 dont have the permission for this operation"
  } ]
}

Response Parameters

None

Update Image

The ProfitBricks API adheres to RFC standards and therefore implements both PUT and PATCH for updates. You will need to choose one or the other depending on the type of update you wish to perform.

You would use PATCH when performing a partial update to a resource, e.g. you're updating the name of an image.

You would use PUT when you wish to replace the properties of a resource. This would require you to pass all properties in the request versus a partial list.

In most cases you will be using PATCH.

You can update -- in full or partially -- various attributes on the image using the above methods.

PATCH

Use PATCH to perform partial updates to attributes of an image.

Request

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request Body

To perform a partial update to the image's properties send a PATCH request to https://api.profitbricks.com/cloudapi/v3/images/[image-id]

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

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

curl --include \
     --request PATCH \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '    {
            "description": "Example Description"
        }' \
     https://api.profitbricks.com/cloudapi/v3/images/[image-id]

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.profitbricks.com/cloudapi/v3/requests/[request-status-id]/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.profitbricks.com/cloudapi/v3/images/[image-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "[name]",
    "description" : "Example Description",
    "location" : "[location]",
    "size" : 5,
    "cpuHotPlug" : false,
    "cpuHotUnplug" : false,
    "ramHotPlug" : false,
    "ramHotUnplug" : false,
    "nicHotPlug" : false,
    "nicHotUnplug" : false,
    "discVirtioHotPlug" : false,
    "discVirtioHotUnplug" : false,
    "discScsiHotPlug" : false,
    "discScsiHotUnplug" : false,
    "licenceType" : "LINUX",
    "imageType" : "HDD",
    "public" : false
  }
}
Response Parameters

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).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state Image state.
name The name of the image.
description The description of the image.
location The image's location.
size The size of the image in GB.
cpuHotPlug This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug This volume is capable of memory hot plug (no reboot required)
ramHotUnplug This volume is capable of memory hot unplug (no reboot required)
nicHotPlug This volume is capable of nic hot plug (no reboot required)
nicHotUnplug This volume is capable of nic hot unplug (no reboot required)
discVirtioHotPlug This volume is capable of Virt-IO drive hot plug (no reboot required)
discVirtioHotUnplug This volume is capable of Virt-IO drive hot unplug (no reboot required)
discScsiHotPlug This volume is capable of Scsi drive hot plug (no reboot required)
discScsiHotUnplug This volume is capable of Scsi drive hot unplug (no reboot required)
licenceType The image's licence type: LINUX, WINDOWS, WINDOWS2016, OTHER or UNKNOWN.
imageType The type of image: HDD, CDROM.
public Indicates if the image is part of the public repository or not.

PUT

Use PUT to perform a full update of all attributes of an image.

Request

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request Body

To perform a full update of the image's properties send a PUT request to: https://api.profitbricks.com/cloudapi/v3/images/[image-id]

Request Parameters
Name Type Description Required
name string The name of the image. Yes
description string The description of the image. Yes
licenceType string The image's licence type: LINUX, WINDOWS, WINDOWS2016, OTHER or UNKNOWN. Yes
cpuHotPlug bool This volume is capable of CPU hot plug (no reboot required) Yes
cpuHotUnplug bool This volume is capable of CPU hot unplug (no reboot required) Yes
ramHotPlug bool This volume is capable of memory hot plug (no reboot required) Yes
ramHotUnplug bool This volume is capable of memory hot unplug (no reboot required) Yes
nicHotPlug bool This volume is capable of nic hot plug (no reboot required) Yes
nicHotUnplug bool This volume is capable of nic hot unplug (no reboot required) Yes
discVirtioHotPlug bool This volume is capable of Virt-IO drive hot plug (no reboot required) Yes
discVirtioHotUnplug bool This volume is capable of Virt-IO drive hot unplug (no reboot required) Yes
discScsiHotPlug bool This volume is capable of Scsi drive hot plug (no reboot required) Yes
discScsiHotUnplug bool This volume is capable of Scsi drive hot unplug (no reboot required) Yes
Curl Example

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

curl --include \
     --request PUT \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '    {
            "properties": {
                "name": "[image-name]",
                "description": "[image-description]",
                "licenceType": "[image-licence-type]",
                "cpuHotPlug": bool-status,
                "cpuHotUnplug": bool-status,
                "ramHotPlug": bool-status,
                "ramHotUnplug": bool-status,
                "nicHotPlug": bool-status,
                "nicHotUnplug": bool-status,
                "discVirtioHotPlug": bool-status,
                "discVirtioHotUnplug": bool-status,
                "discScsiHotPlug": bool-status,
                "discScsiHotUnplug": bool-status
            }
        }    ' \
     https://api.profitbricks.com/cloudapi/v3/images/[image-id]

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.profitbricks.com/cloudapi/v3/requests/[request-status-id]/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.profitbricks.com/cloudapi/v3/images/[image-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "[name]",
    "description" : "Updated Example Description",
    "location" : "[location]",
    "size" : 5,
    "cpuHotPlug" : true,
    "cpuHotUnplug" : true,
    "ramHotPlug" : false,
    "ramHotUnplug" : false,
    "nicHotPlug" : false,
    "nicHotUnplug" : false,
    "discVirtioHotPlug" : false,
    "discVirtioHotUnplug" : false,
    "discScsiHotPlug" : false,
    "discScsiHotUnplug" : false,
    "licenceType" : "OTHER",
    "imageType" : "HDD",
    "public" : false
  }
}
Response Parameters

The following table describes the attributes found in the 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).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state Image state.
name The name of the image.
description The description of the image.
location The image's location.
size The size of the image in GB.
cpuHotPlug This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug This volume is capable of memory hot plug (no reboot required)
ramHotUnplug This volume is capable of memory hot unplug (no reboot required)
nicHotPlug This volume is capable of nic hot plug (no reboot required)
nicHotUnplug This volume is capable of nic hot unplug (no reboot required)
discVirtioHotPlug This volume is capable of Virt-IO drive hot plug (no reboot required)
discVirtioHotUnplug This volume is capable of Virt-IO drive hot unplug (no reboot required)
discScsiHotPlug This volume is capable of Scsi drive hot plug (no reboot required)
discScsiHotUnplug This volume is capable of Scsi drive hot unplug (no reboot required)
licenceType The image's licence type: LINUX, WINDOWS, WINDOWS2016, OTHER or UNKNOWN.
imageType The type of image: HDD, CDROM.
public Indicates if the image is part of the public repository or not.

Volumes

List Volumes

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

Request

Request Headers

The GET request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To retrieve a list of volumes send a GET request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/volumes

Request Parameters

None are required, however you can append "?depth=X" where "X" is a value between 1 and 5 to have additional information returned.

Curl Example

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

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/volumes

Response

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

{
  "id" : "[data-center-id]/volumes",
  "type" : "collection",
  "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/volumes",
  "items" : [ {
    "id" : "[volume-id]",
    "type" : "volume",
    "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/volumes/[volume-id]"
  }, {
    "id" : "[another-volume-id]",
    "type" : "volume",
    "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/volumes/[another-volume-id]"
  } ]
}

Response Parameters

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.

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).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state Volume state. AVAILABLE, BUSY, INACTIVE
etag The etag for the resource.
name The name of the volume.
size The size of the volume in GB.
availabilityZone The storage availability zone assigned to the volume. AUTO, ZONE_1, ZONE_2, or ZONE_3
bus The bus type: VIRTIO or IDE. Returns "null" if not connected to a server.
image The image or snapshot ID.
imagePassword Always returns "null".
sshKeys Always returns "null".
licenceType Licence type. ( WINDOWS, WINDOWS2016, LINUX, OTHER, UNKNOWN)
type The volume type, HDD or SSD.
cpuHotPlug This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug This volume is capable of memory hot plug (no reboot required)
ramHotUnplug This volume is capable of memory hot unplug (no reboot required)
nicHotPlug This volume is capable of nic hot plug (no reboot required)
nicHotUnplug This volume is capable of nic hot unplug (no reboot required)
discVirtioHotPlug This volume is capable of VirtIO drive hot plug (no reboot required)
discVirtioHotUnplug This volume is capable of VirtIO drive hot unplug (no reboot required)
discScsiHotPlug This volume is capable of SCSI drive hot plug (no reboot required)
discScsiHotUnplug This volume is capable of SCSI drive hot unplug (no reboot required)
deviceNumber The LUN ID of the storage volume. Null for volumes not mounted to any VM.

Get Volume

Retrieves the attributes of a given volume.

Request

Request Headers

The request headers should be the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To retrieve a single volume you would send a GET request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/volumes/[volume-id]

Request Parameters

None

Curl Example

The following shows how to submit the request using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/volumes/[volume-id]

Response

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

{
  "id" : "[volume-id]",
  "type" : "volume",
  "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/volumes/[volume-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "AVAILABLE"
  },
  "properties" : {
    "name" : "[Volume Name]",
    "type" : "HDD",
    "size" : 5,
    "availabilityZone" : "AUTO",
    "image" : 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,
    "discScsiHotPlug" : false,
    "discScsiHotUnplug" : false,
    "deviceNumber" : 1
   }
}

Response Parameters

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).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state Volume state. AVAILABLE, BUSY, INACTIVE
name The name of the volume.
type The volume type, HDD or SSD.
size The size of the volume in GB.
availabilityZone The storage availability zone assigned to the volume. AUTO, ZONE_1, ZONE_2, or ZONE_3
image The image or snapshot ID.
imagePassword Always returns "null".
sshKeys Always returns "null".
bus The bus type: VIRTIO or IDE. Returns "null" if not connected to a server.
licenceType Licence type. ( WINDOWS, WINDOWS2016, LINUX, OTHER, UNKNOWN)
cpuHotPlug This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug This volume is capable of memory hot plug (no reboot required)
ramHotUnplug This volume is capable of memory hot unplug (no reboot required)
nicHotPlug This volume is capable of nic hot plug (no reboot required)
nicHotUnplug This volume is capable of nic hot unplug (no reboot required)
discVirtioHotPlug This volume is capable of VirtIO drive hot plug (no reboot required)
discVirtioHotUnplug This volume is capable of VirtIO drive hot unplug (no reboot required)
discScsiHotPlug This volume is capable of SCSI drive hot plug (no reboot required)
discScsiHotUnplug This volume is capable of SCSI drive hot unplug (no reboot required)
deviceNumber The LUN ID of the storage volume.

Create Volume

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

Guidelines for SSD Volume Sizing

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

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

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

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request Body

To create a volume send a POST request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/volumes

The format of the request body is as follows:

{
    "properties": {
        "size": volume-size-in-gb,
        "name": "volume-name",
        "image": "image-or-snapshot-id",
        "imagePassword": "password for image",
        "bus": "volume-bus-type",
        "type": "type",
        "licenceType": "licenceType",
        "availabilityZone" : "AUTO or specific zone"
    }
}

Request Parameters

Name Type Description Required
name string The name of the volume. No
size number The size of the volume in GB. Yes
bus string The bus type of the volume (VIRTIO or IDE). Default: VIRTIO. No
image string The image or snapshot ID. Yes*
type string The volume type, HDD or SSD. Yes
licenceType string The licence type of the volume. Options: LINUX, WINDOWS, WINDOWS2016, UNKNOWN, OTHER Yes*
imagePassword string A password is set on the image for the "root" or "Administrator" account. This field may only be set during volume creation. The password must contain at least 8 and no more than 50 characters. Only these characters are allowed: [a-z][A-Z][0-9] Yes*
sshKeys Array[string] One or more SSH keys to allow access to the volume via SSH. Works with supplied Linux images. Yes*
availabilityZone string 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. No
  • You will need to provide a valid value for either the image or the licenceType parameters. licenceType is required, but if image is supplied, it is already set and cannot be changed. Similarly either the imagePassword or sshKeys parameters need to be supplied when creating a volume. We recommend setting a valid value for imagePassword even when using sshKeys so that it is possible to authenticate using the remote console feature of the DCD.

The following table outlines the various licence types you can define:

Licence Type Comment
WINDOWS2016 Use this when running a Microsoft Windows 2016 operating system.
WINDOWS Specify this if you are running a Windows 2008 or Windows 2012 operating system.
LINUX Use this when running a Linux distribution such as Ubuntu, CentOS, Debian, etc.
OTHER Use for an image that does not fit in any other licence category.
UNKNOWN If you are using an image uploaded to your account your licenceType may show as UNKNOWN. Specify one of the other valid licenceType values to replace this.

Curl Example

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

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

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.profitbricks.com/cloudapi/v3/requests/[request-status-id]/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.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/volumes/[volume-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "TestVolume01",
    "type" : "HDD",
    "size" : 5,
    "availabilityZone" : "ZONE_1",
    "image" : 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,
    "discScsiHotPlug" : false,
    "discScsiHotUnplug" : false,
    "deviceNumber" : null
  }
}

Response Parameters

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).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state Volume state. AVAILABLE, BUSY, INACTIVE
name The name of the volume.
type The volume type, HDD or SSD.
size The size of the volume in GB.
availabilityZone The storage availability zone assigned to the volume. AUTO, ZONE_1, ZONE_2, or ZONE_3
image The image or snapshot ID.
imagePassword Always returns "null".
sshKeys Always returns "null".
bus The bus type of the volume (VIRTIO or IDE). Default: VIRTIO.
licenceType Licence type. ( WINDOWS, WINDOWS2016, LINUX, OTHER, UNKNOWN)
cpuHotPlug This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug This volume is capable of memory hot plug (no reboot required)
ramHotUnplug This volume is capable of memory hot unplug (no reboot required)
nicHotPlug This volume is capable of nic hot plug (no reboot required)
nicHotUnplug This volume is capable of nic hot unplug (no reboot required)
discVirtioHotPlug This volume is capable of VirtIO drive hot plug (no reboot required)
discVirtioHotUnplug This volume is capable of VirtIO drive hot unplug (no reboot required)
discScsiHotPlug This volume is capable of SCSI drive hot plug (no reboot required)
discScsiHotUnplug This volume is capable of SCSI drive hot unplug (no reboot required)
deviceNumber The LUN ID of the storage volume.

Helpful errors are returned if the request contains invalid data:

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

Delete Volume

Deletes the specified volume. This will result in the volume being removed from your data center. Use this with caution.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To delete a volume send a DELETE request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/volumes/[volume-id]

Request Parameters

None

Curl Example

The following shows how to submit the request using curl:

curl --include \
     --request DELETE \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/volumes/[volume-id]

Response

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

Response Parameters

None

Update Volume

The API adheres to RFC standards and therefore implements both PUT and PATCH for updates. You will need to choose one or the other depending on the type of update you wish to perform.

You would use PATCH when performing a partial update to a resource, e.g. you're updating the name of a volume.

You would use PUT when you wish to replace the properties of a resource. This would require you to pass all properties in the request versus a partial list.

In most cases you will be using PATCH.

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

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

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

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

PATCH

Use PATCH to perform partial updates to attributes of a volume.

Request

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request Body

To perform a partial update to the volume's properties send a PATCH request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/volumes/[volume-id]

Request Parameters

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.

Name Type Description Required
name string The name of the volume. No
size int The size of the volume in GB. Can only be increased, not decreased No
bus string The bus type of the volume (VIRTIO or IDE). Default: VIRTIO. No
Curl Example

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

curl --include \
     --request PATCH \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '{
          "name": "TestVolumeRename",
          "size": 20,
          "bus": "VIRTIO"
    }' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/volumes/[volume-id]

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.profitbricks.com/cloudapi/v3/requests/[request-status-id]/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.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/volumes/[volume-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "TestVolume01Rename",
    "type" : "HDD",
    "size" : 20,
    "availabilityZone" : "AUTO",
    "image" : 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,
    "discScsiHotPlug" : false,
    "discScsiHotUnplug" : false,
    "deviceNumber" : null
  }
}
Response Parameters

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).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state Volume state. AVAILABLE, BUSY, INACTIVE
name The name of the volume.
type The volume type, HDD or SSD.
size The size of the volume in GB.
availabilityZone The storage availability zone assigned to the volume. AUTO, ZONE_1, ZONE_2, or ZONE_3
image The image or snapshot ID.
imagePassword Always returns "null".
sshKeys Always returns "null".
bus The bus type of the volume (VIRTIO or IDE). Default: VIRTIO.
licenceType Licence type. ( WINDOWS, WINDOWS2016, LINUX, OTHER, UNKNOWN)
cpuHotPlug This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug This volume is capable of memory hot plug (no reboot required)
ramHotUnplug This volume is capable of memory hot unplug (no reboot required)
nicHotPlug This volume is capable of nic hot plug (no reboot required)
nicHotUnplug This volume is capable of nic hot unplug (no reboot required)
discVirtioHotPlug This volume is capable of VirtIO drive hot plug (no reboot required)
discVirtioHotUnplug This volume is capable of VirtIO drive hot unplug (no reboot required)
discScsiHotPlug This volume is capable of SCSI drive hot plug (no reboot required)
discScsiHotUnplug This volume is capable of SCSI drive hot unplug (no reboot required)
deviceNumber The LUN ID of the storage volume.

PUT

Use PUT to perform a full update of all attributes of a volume.

Request

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request Body

To perform a full update of the volume's properties send a PUT request to: https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/volumes/[volume-id]

Request Parameters

The majority of volume properties can only be set at volume creation and cannot be updated with a PUT request.

Name Type Description Required
name string The name of the volume. Yes
size int The size of the volume in GB. Can only be increased, not decreased Yes
bus string The bus type of the volume (VIRTIO or IDE). Default: VIRTIO. Yes

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

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

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

curl --include \
     --request PUT \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '{
         "properties": {
            "name": "TestVolume01Replaced",
            "size": 12,
            "bus": "VIRTIO"
         }
    }' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/volumes/[volume-id]

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.profitbricks.com/cloudapi/v3/requests/[request-status-id]/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.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/volumes/[volume-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "TestVolume01Replaced",
    "type" : "HDD",
    "size" : 12,
    "availabilityZone" : "AUTO",
    "image" : 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,
    "discScsiHotPlug" : false,
    "discScsiHotUnplug" : false,
    "deviceNumber" : null
  }
}
Response Parameters

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).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state Volume state. AVAILABLE, BUSY, INACTIVE
name The name of the volume.
type The volume type, HDD or SSD.
size The size of the volume in GB.
availabilityZone The storage availability zone assigned to the volume. AUTO, ZONE_1, ZONE_2, or ZONE_3
image The image or snapshot ID.
imagePassword Always returns "null".
sshKeys Always returns "null".
bus The bus type of the volume (VIRTIO or IDE). Default: VIRTIO.
licenceType Licence type. ( WINDOWS, WINDOWS2016, LINUX, OTHER, UNKNOWN)
cpuHotPlug This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug This volume is capable of memory hot plug (no reboot required)
ramHotUnplug This volume is capable of memory hot unplug (no reboot required)
nicHotPlug This volume is capable of nic hot plug (no reboot required)
nicHotUnplug This volume is capable of nic hot unplug (no reboot required)
discVirtioHotPlug This volume is capable of VirtIO drive hot plug (no reboot required)
discVirtioHotUnplug This volume is capable of VirtIO drive hot unplug (no reboot required)
discScsiHotPlug This volume is capable of SCSI drive hot plug (no reboot required)
discScsiHotUnplug This volume is capable of SCSI drive hot unplug (no reboot required)
deviceNumber The LUN ID of the storage volume.

Create Volume Snapshot

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

Request

Request Headers

The request headers should be the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/x-www-form-urlencoded

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

Request Body

To create a volume snapshot send a POST request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/volumes/[volume-id]/create-snapshot

Request Parameters

Name Type Description Required
name string The name of the snapshot.
description string The description of the snapshot.

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

Curl Example

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

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "name=TestSnapshot01" \
'https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/volumes/[volume_id]/create-snapshot'

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

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.profitbricks.com/cloudapi/v3/requests/[request-status-id]/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" : "[snapshot-id]",
  "type" : "snapshot",
  "href" : "https://api.profitbricks.com/cloudapi/v3/snapshots/[snapshot-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "TestSnapshot01",
    "description" : "Created from \"[volume-name]\" in Data Center \"[data-center-name]\"",
    "location" : "us/las",
    "size" : null,
    "cpuHotPlug" : false,
    "cpuHotUnplug" : false,
    "ramHotPlug" : false,
    "ramHotUnplug" : false,
    "nicHotPlug" : false,
    "nicHotUnplug" : false,
    "discVirtioHotPlug" : false,
    "discVirtioHotUnplug" : false,
    "discScsiHotPlug" : false,
    "discScsiHotUnplug" : false,
    "licenceType" : null
  }
}

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

Response Parameters

None

Restore Volume Snapshot

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

Request

Request Headers

The request headers should be the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/x-www-form-urlencoded

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

Request Body

To restore a snapshot send a POST request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/volumes/[volume-id]/restore-snapshot

Request Parameters

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

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

Curl Example

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

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "snapshotId=[snapshot-id]" \
    https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/volumes/[volume-id]/restore-snapshot'

Response

Status: 202 (Accepted)
Headers: [
    "Location: URL of a request resource which should be used for operation's status polling",
    "Date: [date]",
    "Content-Length: 0",
    "Connection: keep-alive"
]
ResponseBody: ""

Response Parameters

None

Snapshots

List Snapshots

Retrieve a list of snapshots within the data center.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

You can append ?depth=1 to the end of the request to retrieve more details on the snapshots. This will provide the same results as issuing a GET request to each snapshot independently.

Curl Example

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

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

Response

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

{
  "id" : "snapshots",
  "type" : "collection",
  "href" : "https://api.profitbricks.com/cloudapi/v3/snapshots",
  "items" : [ {
    "id" : "[snapshot-id]",
    "type" : "snapshot",
    "href" : "https://api.profitbricks.com/cloudapi/v3/snapshots/[snapshot-id]"
  } ]
}

Response Parameters

The request will return a collection of snapshots.

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).

Get Snapshot

Retrieves the attributes of a specific snapshot.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To retrieve details about a specific snapshot, send a GET request to https://api.profitbricks.com/cloudapi/v3/snapshots/[snapshot-id]

Request Parameters

None

Curl Example

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

curl --include \
     --request GET \
     --user 'username@domain.tld:password" \
     https://api.profitbricks.com/cloudapi/v3/snapshots/[snapshot-id]

Response

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

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

Response Parameters

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).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state Snapshot state.
name The name of the snapshot.
description The description of the snapshot.
location The snapshot's location.
size The size of the snapshot in GB.
cpuHotPlug This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug This volume is capable of memory hot plug (no reboot required)
ramHotUnplug This volume is capable of memory hot unplug (no reboot required)
nicHotPlug This volume is capable of NIC hot plug (no reboot required)
nicHotUnplug This volume is capable of NIC hot unplug (no reboot required)
discVirtioHotPlug This volume is capable of Virt-IO drive hot plug (no reboot required)
discVirtioHotUnplug This volume is capable of Virt-IO drive hot unplug (no reboot required)
discScsiHotPlug This volume is capable of SCSI drive hot plug (no reboot required)
discScsiHotUnplug This volume is capable of SCSI drive hot unplug (no reboot required)
licenceType The snapshot's licence type: LINUX, WINDOWS, WINDOWS2016, OTHER or UNKNOWN.

Delete Snapshot

Deletes the specified snapshot.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To delete an snapshot, send a DELETE request to https://api.profitbricks.com/cloudapi/v3/snapshots/[snapshot-id]

Request Parameters

None

Curl Example

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

curl --include \
     --request DELETE \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/cloudapi/v3/snapshots/[snapshot-id]

Response

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

Response Parameters

None

Update Snapshot

The API adheres to RFC standards and therefore implements both PUT and PATCH for updates. You will need to choose one or the other depending on the type of update you wish to perform.

You would use PATCH when performing a partial update to a resource, e.g. you're updating the name of an snapshot.

You would use PUT when you wish to replace the properties of a resource. This would require you to pass all properties in the request versus a partial list.

In most cases you will be using PATCH.

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

PATCH

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

Request

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request Body

To perform a partial update to the snapshot's properties, submit a PATCH request to https://api.profitbricks.com/cloudapi/v3/snapshots/[snapshot-id]

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

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

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

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.profitbricks.com/cloudapi/v3/requests/[request-status-id]/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" : "[snapshot-id]",
  "type" : "snapshot",
  "href" : "https://api.profitbricks.com/cloudapi/v3/snapshots/[snapshot-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "Test Snapshot Rename",
    "description" : "Updated Description",
    "location" : "us/las",
    "size" : 5,
    "cpuHotPlug" : false,
    "cpuHotUnplug" : false,
    "ramHotPlug" : false,
    "ramHotUnplug" : false,
    "nicHotPlug" : false,
    "nicHotUnplug" : false,
    "discVirtioHotPlug" : false,
    "discVirtioHotUnplug" : false,
    "discScsiHotPlug" : false,
    "discScsiHotUnplug" : false,
    "licenceType" : "LINUX"
  }
}
Response Parameters

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).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state Snapshot state.
name The name of the snapshot.
description The description of the snapshot.
location The snapshot's location.
size The size of the snapshot in GB.
cpuHotPlug This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug This volume is capable of memory hot plug (no reboot required)
ramHotUnplug This volume is capable of memory hot unplug (no reboot required)
nicHotPlug This volume is capable of nic hot plug (no reboot required)
nicHotUnplug This volume is capable of nic hot unplug (no reboot required)
discVirtioHotPlug This volume is capable of Virt-IO drive hot plug (no reboot required)
discVirtioHotUnplug This volume is capable of Virt-IO drive hot unplug (no reboot required)
discScsiHotPlug This volume is capable of SCSI drive hot plug (no reboot required)
discScsiHotUnplug This volume is capable of SCSI drive hot unplug (no reboot required)
licenceType The snapshot's licence type: LINUX, WINDOWS, WINDOWS2016, OTHER or UNKNOWN.

PUT

Use PUT to perform a full update of all attributes of a snapshot.

Request

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request Body

To perform a full update of the snapshot's properties, send a PUT request to: https://api.profitbricks.com/cloudapi/v3/snapshots/[snapshot-id]

Request Parameters
Name Type Description Required
name string The name of the snapshot. Yes
description string The description of the snapshot. Yes
cpuHotPlug bool This volume is capable of CPU hot plug (no reboot required) Yes
cpuHotUnplug bool This volume is capable of CPU hot unplug (no reboot required) Yes
ramHotPlug bool This volume is capable of memory hot plug (no reboot required) Yes
ramHotUnplug bool This volume is capable of memory hot unplug (no reboot required) Yes
nicHotPlug bool This volume is capable of nic hot plug (no reboot required) Yes
nicHotUnplug bool This volume is capable of nic hot unplug (no reboot required) Yes
discVirtioHotPlug bool This volume is capable of Virt-IO drive hot plug (no reboot required) Yes
discVirtioHotUnplug bool This volume is capable of Virt-IO drive hot unplug (no reboot required) Yes
discScsiHotPlug bool This volume is capable of SCSI drive hot plug (no reboot required) Yes
discScsiHotUnplug bool This volume is capable of SCSI drive hot unplug (no reboot required) Yes
licenceType string The snapshot's licence type: LINUX, WINDOWS, WINDOWS2016, OTHER or UNKNOWN. Yes
Curl Example

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

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

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.profitbricks.com/cloudapi/v3/requests/[request-status-id]/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" : "[snapshot-id]",
  "type" : "snapshot",
  "href" : "https://api.profitbricks.com/cloudapi/v3/snapshots/[snapshot-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "Snapshot New Name",
    "description" : "Updated Snapshot Description",
    "location" : "us/las",
    "size" : 5,
    "cpuHotPlug" : false,
    "cpuHotUnplug" : false,
    "ramHotPlug" : false,
    "ramHotUnplug" : false,
    "nicHotPlug" : false,
    "nicHotUnplug" : false,
    "discVirtioHotPlug" : false,
    "discVirtioHotUnplug" : false,
    "discScsiHotPlug" : true,
    "discScsiHotUnplug" : true,
    "licenceType" : "OTHER"
  }
}
Response Parameters

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).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state Snapshot state.
name The name of the snapshot.
description The description of the snapshot.
location The snapshot's location.
size The size of the snapshot in GB.
cpuHotPlug This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug This volume is capable of memory hot plug (no reboot required)
ramHotUnplug This volume is capable of memory hot unplug (no reboot required)
nicHotPlug This volume is capable of NIC hot plug (no reboot required)
nicHotUnplug This volume is capable of NIC hot unplug (no reboot required)
discVirtioHotPlug This volume is capable of Virt-IO drive hot plug (no reboot required)
discVirtioHotUnplug This volume is capable of Virt-IO drive hot unplug (no reboot required)
discScsiHotPlug This volume is capable of SCSI drive hot plug (no reboot required)
discScsiHotUnplug This volume is capable of SCSI drive hot unplug (no reboot required)
licenceType The snapshot's licence type: LINUX, WINDOWS, WINDOWS2016, OTHER or UNKNOWN.

IP Block

List IP Blocks

Retrieve a list of reserved IP blocks.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To retrieve a list of IP blocks you would send a GET request to https://api.profitbricks.com/cloudapi/v3/ipblocks

Request Parameters

None

Curl Example

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

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/cloudapi/v3/ipblocks

Response

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

{
  "id" : "ipblocks",
  "type" : "collection",
  "href" : "https://api.profitbricks.com/cloudapi/v3/ipblocks",
  "items" : [ {
    "id" : "[ip-block-id]",
    "type" : "ipblock",
    "href" : "https://api.profitbricks.com/cloudapi/v3/ipblocks/[ip-block-id]"
  }, {
    "id" : "[another-ip-block-id]",
    "type" : "ipblock",
    "href" : "https://api.profitbricks.com/cloudapi/v3/ipblocks/[another-ip-block-id]"
  } ]
}

Response Parameters

The request will return a collection of IP blocks.

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

Name Description Notes
id The resource's unique identifier.
type The type of object.
href URL to the object’s representation (absolute path).
ips A collection of IPs associated with the IP Block. Property not shown by default (depth=0)
location Location the IP block resides in. Property not shown by default (depth=0)
size Number of IP addresses in the block. Property not shown by default (depth=0)
name A descriptive name given to the IP block. Property not shown by default (depth=0)

Get IP Block

Retrieves the attributes of a specific IP Block.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To retrieve a single IP Block you would send a GET request to https://api.profitbricks.com/cloudapi/v3/ipblocks/[ip-block-id]

Request Parameters

None

Curl Example

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

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/cloudapi/v3/ipblocks/[ip-block-id]

Response

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

{
  "id" : "[ip-block-id]",
  "type" : "ipblock",
  "href" : "https://api.profitbricks.com/cloudapi/v3/ipblocks/[ip-block-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[username]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[username]",
    "state" : "AVAILABLE"
  },
  "properties" : {
"    ips" : [ "[ip-address]" ],
    "location" : "[data-center-location]",
    "size" : [size-of-ip-block],
    "name" : "[descriptive-name]"
  }
}

Response Parameters

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).
ips A collection of IPs associated with the IP block.
location Location the IP block resides in.
size Number of IP addresses in the block.
name A descriptive name given to the IP block.

Create IP Block

Reserves an IP block at a specified location that can be used by resources within any virtual data centers provisioned in that same location. An IP block conists of one or more static ip addresses.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request Body

To create a IP block, send a POST request to https://api.profitbricks.com/cloudapi/v3/ipblocks

Request Parameters

Name Type Description Required
location string This must be one of the available locations: us/ewr, us/las, de/fra, de/fkb. Yes
size int The size of the IP block you want. Yes
name string A descriptive name for the IP block No

Curl Example

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

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

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.profitbricks.com/cloudapi/v3/requests/[request-id]/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" : "[ip-block-id]",
  "type" : "ipblock",
  "href" : "https://api.profitbricks.com/cloudapi/v3/ipblocks/[ip-block-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[username]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[timestamp]",
    "lastModifiedBy" : "[username]",
    "state" : "BUSY"
  },
  "properties" : {
    "ips" : [ "[ip-address]", "[second-ip-address]" ],
    "location" : "[location]",
    "size" : 2,
    "name" : "[Descriptive Name]"
  }
}

Response Parameters

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).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state Status of the IP block. (BUSY, AVAILABLE)
etag The etag for the resource.
size The number of IPs in the block.
ips A collection of IPs associated with the IP block.
location Location the IP block resides in.
name Descriptive name for the IP block.

Update IP Block

Updates an existing IP block.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request Body

To create a IP block, send a PATCH or PUT request to https://api.profitbricks.com/cloudapi/v3/ipblocks

Request Parameters

Name Type Description Required
name string A descriptive name for the IP block. No

Please Note: You cannot update either the location or the size of an IP Block. Those values are set as read-only when the IP Block is created.

Curl Example

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

curl --include \
     --request PATCH \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '{
            "name": \"Updated Name"
    }' \
'https://api.profitbricks.com/cloudapi/v3/ipblocks/[ip-block-id]'

With a PUT request, you need to enclose the name/value pair inside the properties object.

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

curl --include \
     --request PUT \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '{
        "properties": {
            "name": "Updated Name"
        }
    }' \
'https://api.profitbricks.com/cloudapi/v3/ipblocks/[ip-block-id]'

Response

The response will be similar regardless of your choice to use PATCH or PUT. The updated IP Block properties are returned.

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.profitbricks.com/cloudapi/v3/requests/[request-id]/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" : "[ip-block-id]",
  "type" : "ipblock",
  "href" : "https://api.profitbricks.com/cloudapi/v3/ipblocks/[ip-block-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[username]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[timestamp]",
    "lastModifiedBy" : "[username]",
    "state" : "BUSY"
  },
  "properties" : {
    "ips" : [ "[ip-address]", "[second-ip-address]" ],
    "location" : "[location]",
    "size" : 2,
    "name" : "[Descriptive Name]"
  }
}

Response Parameters

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).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state Status of the IP block. (BUSY, AVAILABLE)
etag The etag for the resource.
size The number of IPs in the block.
ips A collection of IPs associated with the IP block.
location Location the IP block resides in.
name Descriptive name for the IP block.

Delete IP Block

Deletes the specified IP Block.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To delete an IP block you would send a DELETE request to https://api.profitbricks.com/cloudapi/v3/ipblocks/[ip-block-id]

Request Parameters

None

Curl Example

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

curl --include \
     --request DELETE \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/cloudapi/v3/ipblocks/[ip-block-id]

Response

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

Response Parameters

None

LANs

List LANs

Retrieve a list of LANs within the data center.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To retrieve a list of LANs you would submit a GET request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/lans

Request Parameters

None

Curl Example

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

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/lans

Response

Here is a response for a 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" : "[data-center-id]/lans",
  "type" : "collection",
  "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/lans",
  "items" : [ {
    "id" : "3",
    "type" : "lan",
    "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/lans/3"
  }, {
    "id" : "1",
    "type" : "lan",
    "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/lans/1"
  }, {
    "id" : "2",
    "type" : "lan",
    "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/lans/2"
  } ]
}

Response Parameters

The request will return a collection of LANs.

You can append ?depth=1 to the end of the request to retrieve more details on the individual LANs. This will return the same results as issuing a GET request to each LAN independently.

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).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state LAN state.
etag The etag for the resource.
public Boolean indicating if the LAN faces the public Internet or not.
nics A collection of NICs associated with the LAN.

Get LAN

Retrieves the attributes of a given LAN.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To retrieve a single LAN you would send a GET request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/lans/[lan-id]

Request Parameters

None

Curl Example

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

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/lans/[lan-id]

Response

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

{
  "id" : "1",
  "type" : "lan",
  "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/lans/1",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[username]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[username]",
    "state" : "AVAILABLE"
  },
  "properties" : {
    "name" : "[descriptive-LAN-name]",
    "public" : true
  },
  "entities" : {
    "nics" : {
      "id" : "1/nics",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/lans/1/nics"
    }
  }
}

Response Parameters

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).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state LAN state.
etag The etag for the resource.
name A descriptive name for the LAN.
public Boolean indicating if the LAN faces the public Internet or not.
nics A collection of NICs associated with the LAN.

Create LAN

Creates a LAN within a data center.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request Body

To create a LAN you would send a POST request to `https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/lans``

The format of the request body is as follows:

{
        "properties": {
            "public": "true"
        },
         "entities": {
            "nics": []
         }
    }

Request Parameters

Name Type Description Required
name string The name of your LAN.
public bool Boolean indicating if the LAN faces the public Internet or not.
nics string collection A collection of NICs associated with the LAN.

Curl Example

The following shows how to create a LAN via curl:

curl --include \
     --request POST \
     --user 'username@domain.tld:password \
     --header "Content-Type: application/json" \
     --data-binary '    {
        "properties": {
            "name": "[descriptive-lan-name]"
            "public": "false"
        }
     }' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/lans

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.profitbricks.com/cloudapi/v3/requests/[request-status-id]/staus
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.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/lans/5",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "[descriptive-name]",
    "public" : false
  }
}

Response Parameters

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).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state LAN state.
etag The etag for the resource.
name A descriptive name assigned to the LAN object.
public Boolean indicating if the LAN faces the public Internet or not.
nics A collection of NICs associated with the LAN. See the NIC section for attribute descriptions.

Delete LAN

Deletes the specified LAN.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To delete a LAN you would send a DELETE request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/lans/[lan-id]

Request Parameters

None

Curl Example

The following shows how to submit the request using curl:

curl --include \
     --request DELETE \
     --user 'username@domain.tld:password'
 https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/lans/[lan-id]

Response

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

Response Parameters

None

Update LAN

The API adheres to RFC standards and therefore implements both PUT and PATCH for updates. You will need to choose one or the other depending on the type of update you wish to perform.

You would use PATCH when performing a partial update to a resource, e.g. you're updating the name of a LAN.

You would use PUT when you wish to replace the properties of a resource. This would require you to pass all properties in the request versus a partial list.

In most cases you will be using PATCH.

You can update -- in full or partially -- various attributes on the LAN using the above methods.

PATCH

Use PATCH to perform partial updates to attributes of a LAN.

Request

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request Body

To perform a partial update to the LAN's properties you would send a PATCH request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/lans/[lan-id]

Request Parameters
Name Type Description Required
name string Descriptive name for the LAN.
public bool Boolean indicating if the LAN faces the public Internet or not.
Curl Example

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

curl --include \
     --request PATCH \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '    {
            "name": "LAN3"
        }' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/lans/[lan-id]

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.profitbricks.com/cloudapi/v3/requests/[request-status-id]/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.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/lans/3",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "[descriptive-name]",
    "public" : false
  },
  "entities" : {
    "nics" : {
      "id" : "3/nics",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/lans/3/nics"
    }
  }
}
Response Parameters

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).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state LAN state.
etag The etag for the resource.
name A descriptive name for the LAN
public Boolean indicating if the LAN faces the public Internet or not.
nics A collection of NICs associated with the LAN.

PUT

Use PUT to perform a full update of all attributes of a LAN.

Request

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request Body

To perform a full update of the LAN's properties send a PUT request to: https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/lans/[lan-id]

Request Parameters
Name Type Description Required
name string A descriptive name for the LAN No
public bool Boolean indicating if the LAN faces the public Internet or not. Yes
Curl Example

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

curl --include \
     --request PUT \
     --user 'username@domain.tld@password' \
     --header "Content-Type: application/json" \
     --data-binary '    {
            "name" : "[descriptive-name]"
            "public": "false"
        }    ' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/lans/[lan-id]

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.profitbricks.com/cloudapi/v3/requests/[request-status-id]/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.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/lans/4",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "NewLANName",
    "public" : true
  },
  "entities" : {
    "nics" : {
      "id" : "4/nics",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/lans/4/nics"
    }
  }
}
Response Parameters

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).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state LAN state.
etag The etag for the resource.
name A descriptive name for the LAN.
public Boolean indicating if the LAN faces the public Internet or not.
nics A collection of NICs associated with the LAN.

Network Interfaces

List NICs

Retrieves a list of NICs.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To retrieve a list of NICs, submit a GET request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics

Request Parameters

You can append ?depth=1 to the end of the request to retrieve more details on the NICs. This is the equivalent of what you would get when issuing a GET request to each NIC independently.

Curl Example

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

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
 https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics

Response

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

{
  "id" : "[server-id]/nics",
  "type" : "collection",
  "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics",
  "items" : [ {
    "id" : "[nic-id]",
    "type" : "nic",
    "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]"
  } ]
}

Response Parameters

The request will return a collection of NICs assigned to the server.

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).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state The NIC state. 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 The etag for the resource.
name The name of the NIC.
mac The MAC address of the NIC.
ips IP addresses assigned to the NIC represented as a collection.
dhcp Boolean value that indicates if the NIC is using DHCP or not.
lan The LAN ID the NIC sits on.
nat Boolean value indicating if the private IP address has outbound access to the public internet.
firewallActive A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.
firewallrules A list of firewall rules associated with the NIC.

Please Note: The nat property is NOT available yet, but is Coming Soon.

Get a NIC

Retrieves the attributes of a given NIC.

Request

Request Headers

The request headers should be the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To retrieve attributes of a specific NIC, send a GET request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic_id]

Request Parameters

None

Curl Example

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

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]

Response

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

{
  "id" : "[nic-id]",
  "type" : "nic",
  "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "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" : "[nic-id]/firewallrules",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]/firewallrules"
    }
  }
}

Response Parameters

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).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state The NIC state. 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.
name The name of the NIC.
mac The MAC address of the NIC.
ips IPs assigned to the NIC represented as a collection.
dhcp Boolean value that indicates if the NIC is using DHCP or not.
lan The LAN ID the NIC sits on.
nat Boolean value indicating if the private IP address has outbound access to the public internet.
firewallActive A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.
firewallrules A list of firewall rules associated to the NIC represented as a collection.

Please Note: The nat property is NOT available yet, but is Coming Soon.

Create a NIC

Adds a NIC to the target server.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request Body

To create a NIC, send a POST request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server_id]/nics

The format of the request body is as follows:

{
        "properties": {
            "name": "nic-name",
            "ips": nic-ip-collection,
            "dhcp": "nic-dhcp",
            "firewallActive": false,
            "lan": nic-lan
        },
        "entities": {
            "firewallrules": []
        }
    }

Request Parameters

Name Required Type Description
name no string The name of the NIC.
ips no string collection IPs assigned to the NIC. This can be a collection.
dhcp no bool Set to false if you wish to disable DHCP on the NIC. Default: true
lan yes int The LAN ID the NIC will sit on. If the LAN ID does not exist it will be created.
nat no bool Indicates the private IP address has outbound access to the public internet.
firewallActive no bool A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.
firewallrules no string collection A list of firewall rules associated to the NIC represented as a collection.

Please Note: The nat property is NOT available yet, but is Coming Soon.

Curl Example

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

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '    {
        "properties": {
            "name": "Internal NIC",
            "ips": ["10.2.2.3"],
            "dhcp": false,
            "lan": 2
        }
      }' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.profitbricks.com/cloudapi/v3/requests/[request-status-id]/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" : "[nic-id]",
  "type" : "nic",
  "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "Internal NIC",
    "mac" : null,
    "ips" : [ "10.1.1.2" ],
    "dhcp" : false,
    "lan" : 2,
    "firewallActive" : null
  }
}

Response Parameters

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).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state The NIC state. 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.
name The name of the NIC.
mac The MAC address of the NIC.
ips IPs assigned to the NIC represented as a collection.
dhcp Boolean value that indicates if the NIC is using DHCP or not.
lan The LAN ID the NIC sits on.
nat Boolean value indicating if the private IP address has outbound access to the public internet.
firewallActive A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.
firewallrules A list of firewall rules associated to the NIC represented as a collection.

Please Note: The nat property is NOT available yet, but is Coming Soon.

Delete a NIC

Deletes the specified NIC.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To delete a NIC, send a DELETE request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]

Request Parameters

None

Curl Example

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

curl --include \
     --request DELETE \
     --user 'username@domain.tld:password' \
 https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]

Response

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

Response Parameters

None

Update a NIC

The API adheres to RFC standards and therefore implements both PUT and PATCH for updates. You will need to choose one or the other depending on the type of update you wish to perform.

You would use PATCH when performing a partial update to a resource, e.g. you're updating the name of a NIC.

You would use PUT when you wish to replace the properties of a resource. This would require you to pass all properties in the request versus a partial list.

In most cases you will be using PATCH.

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

The primary address of a NIC connected to a load balancer can only be changed by changing the IP of the load balancer. You can also add additional reserved, public IPs to the NIC.

The user can specify and assign private IPs manually. Valid IP addresses for private networks are 10.0.0.0/8, 172.16.0.0/12 or 192.168.0.0/16.

The value for firewallActive can be toggled between true and false to enable or disable the firewall. When the firewall is enabled, incoming traffic is filtered by all the firewall rules configured on the NIC. When the firewall is disabled, then all incoming traffic is routed directly to the NIC and any configured firewall rules are ignored.

PATCH

Use PATCH to perform partial updates to attributes of a NIC.

Request

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request Body

To perform a partial update to the NIC's properties, send a PATCH request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]

Request Parameters
Name Required Type Description
name no string The name of the NIC.
ips no string collection IPs assigned to the NIC represented as a collection.
dhcp no bool Boolean value that indicates if the NIC is using DHCP (true) or not (false).
lan no int The LAN ID the NIC sits on.
nat no bool Indicates if the private IP address should have outbound access to the public internet.
firewallActive no bool A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.

Please Note: The nat property is NOT available yet, but is Coming Soon.

Curl Example

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

curl --include \
     --request PATCH \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '    {
         "name": "Heartbeat NIC",
         "ips": ["10.1.1.3"]
       }
    }' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.profitbricks.com/cloudapi/v3/requests/[request-status-id]/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" : "[nic-id]",
  "type" : "nic",
  "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "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" : "[nic-id]/firewallrules",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]/firewallrules"
    }
  }
}
Response Parameters

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).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state The NIC state. 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.
name The name of the NIC.
mac The MAC address of the NIC.
ips IPs assigned to the NIC represented as a collection.
dhcp Boolean value that indicates if the NIC is using DHCP or not.
lan The LAN ID the NIC sits on.
nat Boolean value indicating if the private IP address has outbound access to the public internet.
firewallActive A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.
firewallrules A list of firewall rules associated to the NIC represented as a collection.

Please Note: The nat property is NOT available yet, but is Coming Soon.

PUT

Use PUT to perform a full update of all attributes of a NIC.

Request

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request Body

To perform a full update of the NIC's properties, send a PUT request to: https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]

Request Parameters
Name Required Type Description
name yes string The name of the NIC.
ips yes string collection IPs assigned to the NIC represented as a collection.
dhcp yes bool Boolean value that indicates if the NIC is using DHCP or not.
lan yes int The LAN ID the NIC sits on.
nat yes bool Indicates if the the private IP address has outbound access to the public internet.
firewallActive yes bool A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.

Please Note: The nat property is NOT available yet, but is Coming Soon.

Curl Example

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

curl --include \
     --request PUT \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '    {
        "properties": {
            "name": "Failover NIC",
            "ips": ["10.1.1.4"],
            "dhcp": false,
            "lan": 2
        }
    } ' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.profitbricks.com/cloudapi/v3/requests/[request-status-id]/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" : "[nic-id]",
  "type" : "nic",
  "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "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" : "[nic-id]/firewallrules",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]/firewallrules"
    }
  }
}
Response Parameters

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).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state The NIC state. State of the resource. 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.
name The name of the NIC.
mac The MAC address of the NIC.
ips IPs assigned to the NIC represented as a collection.
dhcp Boolean value that indicates if the NIC is using DHCP or not.
lan The LAN ID the NIC sits on.
nat Boolean value indicating if the private IP address has outbound access to the public internet.
firewallActive A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.
firewallrules A list of firewall rules associated to the NIC represented as a collection.

Please Note: The nat property is NOT available yet, but is Coming Soon.

Firewall Rules

List Firewall Rules

Retrieves a list of firewall rules associated with a particular NIC.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To retrieve a list of firewall rules submit a GET request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]/firewallrules.

Request Parameters

None

Curl Example

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

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]/firewallrules

Response

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

{
  "id" : "[nic-id]/firewallrules",
  "type" : "collection",
  "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]/firewallrules",
  "items" : [ {
    "id" : "[firewall-rule-id]",
    "type" : "firewall-rule",
    "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]/firewallrules/[firewall-rule-id]"
  }, {
    "id" : "[another-firewall-rule-id]",
    "type" : "firewall-rule",
    "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]/firewallrules/[another-firewall-rule-id]"
  } ]
}

Response Parameters

The request will return a collection of firewall rules assigned to the NIC.

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

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

Get Firewall Rule

Retrieves the attributes of a given firewall rule.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To retrieve a specific firewall rule send a GET request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]/firewallrules/[firewall-rule-id]

Request Parameters

None

Curl Example

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

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
 https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]/firewallrules/[firewall-rule-id]

Response

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

{
  "id" : "[firewall-rule-id]",
  "type" : "firewall-rule",
  "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]/firewallrules/[firewall-rule-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "AVAILABLE"
  },
  "properties" : {
    "name" : "AllowSSH",
    "protocol" : "TCP",
    "sourceMac" : null,
    "sourceIp" : null,
    "targetIp" : null,
    "icmpCode" : null,
    "icmpType" : null,
    "portRangeStart" : 22,
    "portRangeEnd" : 22
  }
}

Response Parameters

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).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state The firewall rule state. 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.
name The name of the firewall rule.
protocol The protocol for the rule: TCP, UDP, ICMP, ANY.
sourceMac 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 Only traffic originating from the respective IPv4 address is allowed. Value null allows all source IPs.
targetIp 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 Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value null allows all types.
icmpCode Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value null allows all codes.
portRangeStart Defines the start range of the allowed port (from 1 to 65534) if protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd value null to allow all ports.
portRangeEnd Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd null to allow all ports.

Create Firewall Rule

This will add a new firewall rule to the specified NIC. All firewall rules must be associated with a NIC.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request Body

To create a new firewall rule you would send a POST request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id}/nics/[nic-id]/firewallrules

The format of the request body is as follows:

{
  "properties": {
    "name": "my-firewall-rule-name",
    "protocol": "my-protocol",
    "sourceMac": "source-mac",
    "sourceIp": "source-ip",
    "targetIp": "target-ip",
    "portRangeStart": "port-range-start",
    "portRangeEnd": "port-range-end",
    "icmpType": "icmp-type",
    "icmpCode": "icmp-code"
  }
}

Request Parameters

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 int Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value null allows all codes.
icmpType no int Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value null allows all types.
portRangeStart no int 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 int Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to null to allow all ports.

Curl Example

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

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '    {
        "properties": {
            "name": "AllowHTTP",
            "protocol": "TCP",
            "portRangeStart": "80",
            "portRangeEnd": "80"
        }
    }' \
https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]/firewallrules

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.profitbricks.com/cloudapi/v3/requests/[request-status-id]/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" : "[firewall-rule-id]",
  "type" : "firewall-rule",
  "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]/firewallrules/[firewall-rule-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "AllowHTTP",
    "protocol" : "TCP",
    "sourceMac" : null,
    "sourceIp" : null,
    "targetIp" : null,
    "icmpCode" : null,
    "icmpType" : null,
    "portRangeStart" : 80,
    "portRangeEnd" : 80
  }
}

Response Parameters

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).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state The firewall rule state. 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.
name The name of the firewall rule.
protocol The protocol for the rule: TCP, UDP, ICMP, ANY.
sourceMac 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 Only traffic originating from the respective IPv4 address is allowed. Value null allows all source IPs.
targetIp 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 Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value null allows all types.
icmpCode Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value null allows all codes.
portRangeStart Defines the start range of the allowed port (from 1 to 65534) if protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd value null to allow all ports.
portRangeEnd Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd null to allow all ports.

Delete Firewall Rule

Removes the specific firewall rule.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To delete a firewall rule send a DELETE request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]/firewallrules/[firewall-rule-id]

Request Parameters

None

Curl Example

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

curl --include \
     --request DELETE \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]/firewallrules/[firewall-rule-id]

Response

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

Response Parameters

None

Update Firewall Rule

The API adheres to RFC standards and therefore implements both PUT and PATCH for updates. You will need to choose one or the other depending on the type of update you wish to perform.

You would use PATCH when performing a partial update to a resource, e.g. you're updating the name of a Firewall Rule.

You would use PUT when you wish to replace the properties of a resource. This would require you to pass all properties in the request versus a partial list.

In most cases you will be using PATCH.

You can update -- in full or partially -- various attributes on the Firewall Rule using the above methods.

PATCH

Use PATCH to perform partial updates to attributes of a firewall rule.

Request

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request Body

To perform a partial update to the firewall rule properties send a PATCH request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]/firewallrules/[firewall-rule-id]

Request Parameters
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 int Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value null allows all codes.
icmpType no int Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value null allows all types.
portRangeStart no int 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 int Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to null to allow all ports.
Curl Example

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

curl --include \
     --request PATCH \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '    {
        "sourceMac": "01:98:22:22:44:22",
        "targetIp": "123.100.101.102"
    }" \
'https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]/firewallrules/[firewall-rule-id]'

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.profitbricks.com/cloudapi/v3/requests/[request-status-id]/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" : "[firewall-rule-id]",
  "type" : "firewall-rule",
  "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]/firewallrules/[firewall-rule-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "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
  }
}
Response Parameters

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).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state The firewall rule state. 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.
name The name of the firewall rule.
protocol The protocol for the rule: TCP, UDP, ICMP, ANY.
sourceMac 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 Only traffic originating from the respective IPv4 address is allowed. Value null allows all source IPs.
targetIp 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 Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value null allows all types.
icmpCode Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value null allows all codes.
portRangeStart Defines the start range of the allowed port (from 1 to 65534) if protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd value null to allow all ports.
portRangeEnd Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd null to allow all ports.

PUT

Use PUT to perform a full update of all attributes of a firewall rule.

Request

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request Body

To perform a full update of the firewall rule's properties send a PUT request to: https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]/firewallrules/[firewall-rule-id]

Request Parameters
Name Required Type Description
name yes string A name for the firewall rule.
protocol yes string The protocol for the rule: TCP, UDP, ICMP, ANY.
sourceMac yes 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 yes string Only traffic originating from the respective IPv4 address is allowed. A null value allows all source IPs.
targetIp yes 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 yes int Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value null allows all codes.
icmpType yes int Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value null allows all types.
portRangeStart yes int 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 yes int Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to null to allow all ports.
Curl Example

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

curl --include \
     --request PUT \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '    {
        "properties": {
            "name": "SSH Port Plus One",
            "sourceMac": "01:23:45:67:89:00",
            "sourceIp": "1.2.3.4",
            "targetIp": "5.6.7.8",
            "portRangeStart": 22,
            "portRangeEnd": 23,
            "icmpType": null,
            "icmpCode": null
        }
    }' \
'https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]/firewallrules/[firewall-rule-id]'

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 UTC
Location: https://api.profitbricks.com/cloudapi/v3/requests/[request-status-id]/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" : "[firewall-rule-id]",
  "type" : "firewall-rule",
  "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]/firewallrules/[firewall-rule-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "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
  }
}
Response Parameters

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).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state The firewall rule state. 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.
name The name of the firewall rule.
protocol The protocol for the rule: TCP, UDP, ICMP, ANY.
sourceMac 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 Only traffic originating from the respective IPv4 address is allowed. Value null allows all source IPs.
targetIp 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 Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value null allows all types.
icmpCode Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value null allows all codes.
portRangeStart Defines the start range of the allowed port (from 1 to 65534) if protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd value null to allow all ports.
portRangeEnd Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd null to allow all ports.

Load Balancers

List Load Balancers

Retrieve a list of loadbalancers within the data center.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To retrieve a list of loadbalancers, submit a GET request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/loadbalancers

Request Parameters

None

Curl Example

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

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/loadbalancers

Response

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

{
  "id" : "[data-center-id]/loadbalancers",
  "type" : "collection",
  "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/loadbalancers",
  "items" : [ {
    "id" : "[loadbalancer-id]",
    "type" : "loadbalancer",
    "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/loadbalancers/[loadbalancer-id]"
  } ]
}

Response Parameters

The request will return a collection of loadbalancers.

You can append ?depth=1 to the end of the request to retrieve more details on the loadbalancers. This will give you the equivalent of what you would get when issuing a GET request to each loadbalancer independently.

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).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state Load Balancer state.
etag The etag for the resource.
name The name of the loadbalancer.
ip IPv4 address of the loadbalancer. All attached NICs will inherit this IP.
dhcp Indicates if the loadbalancer will reserve an IP using DHCP.
balancedNics A collection of NICs being loadbalanced.

Get Load Balancer

Retrieves the attributes of a given loadbalancer.

Request

Request Headers

The request headers should be the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To retrieve details about a specific loadbalancer send a GET request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/loadbalancers/[loadbalancer-id]

Request Parameters

None

Curl Example

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

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/loadbalancers/[loadbalancer-id]

Response

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

{
  "id" : "[loadbalancer-id]",
  "type" : "loadbalancer",
  "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/loadbalancers/[loadbalancer-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "INACTIVE"
  },
  "properties" : {
    "name" : "ExampleLoadBalancer01",
    "ip" : null,
    "dhcp" : false
  },
  "entities" : {
    "balancednics" : {
      "id" : "[loadbalancer-id]/balancednics",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/loadbalancers/[loadbalancer-id]/balancednics"
    }
  }
}

Response Parameters

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).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state Load Balancer state.
etag The etag for the resource.
name The name of the loadbalancer.
ip IPv4 address of the loadbalancer. All attached NICs will inherit this IP.
dhcp Indicates if the loadbalancer will reserve an IP using DHCP.
balancedNics A collection of NICs being loadbalanced.

Create Load Balancer

Creates a loadbalancer within the data center. Loadbalancers can be used for public or private IP traffic.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request Body

To create a load-balancer send a POST request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/loadbalancers

The format of the request body is as follows:

{
        "properties": {
            "name": "loadbalancer-name",
            "ip": "loadbalancer-ip",
            "dhcp": "loadbalancer-dhcp"
        },
         "entities": {
            "balancednics": []
         }
    }

Request Parameters

Name Type Description Required
name string The name of the loadbalancer. Yes
ip string IPv4 address of the loadbalancer. All attached NICs will inherit this IP. No
dhcp bool Indicates if the loadbalancer will reserve an IP using DHCP. No
balancednics string collection List of NICs taking part in load-balancing. All balanced nics inherit the IP of the loadbalancer. No

Curl Example

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

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '    {
        "properties": {
            "name": "[loadbalancer-name]",
            "dhcp": false
    }' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/loadbalancers

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.profitbricks.com/cloudapi/v3/requests/[request-status-id]/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" : "[loadbalancer-id]",
  "type" : "loadbalancer",
  "href" : "https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/loadbalancers/[loadbalancer-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "ExampleLoadBalancer01",
    "ip" : null,
    "dhcp" : false
  }
}

Response Parameters

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).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state Loadbalancer state.
name The name of the loadbalancer.
ip IPv4 address of the loadbalancer. All attached NICs will inherit this IP.
dhcp Indicates if the loadbalancer will reserve an IP using DHCP.
balancednics List of NICs taking part in load-balancing. All balanced nics inherit the IP of the loadbalancer. See the NIC section for attribute definitions.

Delete Load Balancer

Deletes the specified loadbalancer.

Request

Request Headers

The request headers should be the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request Body

To delete a loadbalancer send a DELETE request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/loadbalancers/[loadbalancer-id]

Request Parameters

None

Curl Example

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

curl --include \
     --request DELETE \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/loadbalancers/[loadbalancer-id]

Response

Status: 202 (Accepted)
Headers: [
    "Location: URL of a request resource which should be used for the operation's polling status",
    "Date: [date]",
    "Content-Length: 0",
    "Connection: keep-alive"
]
ResponseBody: ""

Response Parameters

None

Update Load Balancer

The API adheres to RFC standards and therefore implements both PUT and PATCH for updates. You will need to choose one or the other depending on the type of update you wish to perform.

You would use PATCH when performing a partial update to a resource, e.g. you're updating the name of a loadbalancer.

You would use PUT when you wish to replace the properties of a resource. This would require you to pass all properties in the request versus a partial list.

In most cases you will be using PATCH.

You can update -- in full or partially -- various attributes on the loadbalancer using the above methods.

PATCH

Use PATCH to perform partial updates to attributes of a loadbalancer.

Request

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request Body

To perform a partial update to the loadbalancer's properties you would send a PATCH request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/loadbalancers/[loadbalancer-id]

Request Parameters
Name Type Description Required
name string The name of the loadbalancer.
ip string The IP of the loadbalancer.
dhcp bool Indicates if the loadbalancer will reserve an IP using DHCP.
Curl Example

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

curl --include \
     --request PATCH \
     --header "Content-Type: application/json" \
     --data-binary '    {
        "ip": "[ip]"
    }' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id}/loadbalancers/[loadbalancer-id]

Response

Status: 202 (Accepted)
Headers: [
    "Date: [date]",
    "Content-Type: application/json",
    "Location: URL of a request resource which should be used for the operation's polling status",
    "Connection: keep-alive",
    "Content-Length: 426"
]
ResponseBody: {
      "id": "loadbalancer-id",
      "type": "loadbalancer",
      "href": "[base-url]/datacenters/[data-center-id]/loadbalancers/[loadbalancer-id]",
    "metadata": {
        "lastModifiedDate": "last-modified-date",
        "lastModifiedBy": "last-modified-by-user",
        "createdDate": "created-date",
        "createdBy": "created-by-user",
        "state": "loadbalancer-state",
        "etag": "etag"
    },
    "properties": {
        "name": "loadbalancer-name",
        "ip": "loadbalancer-ip",
        "dhcp": "loadbalancer-dhcp"
    },
    "entities": {
        "balancednics": []
    }
}
Response Parameters

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).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state Load Balancer state.
etag The etag for the resource.
name The name of the loadbalancer.
ip IPv4 address of the loadbalancer. All attached NICs will inherit this IP.
dhcp Indicates if the loadbalancer will reserve an IP using DHCP.
balancednics List of NICs taking part in load-balancing. All balanced nics inherit the IP of the loadbalancer. See the NIC section for attribute definitions.

PUT

Use PUT to perform a full update of all attributes of a loadbalancer.

Request

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request Body

To perform a full update of the loadbalancer's properties send a PUT request to: https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/loadbalancers/[loadbalancer-id]

Request Parameters
Name Type Description Required
name string The name of the loadbalancer. Yes
ip string The IP of the loadbalancer. Yes
dhcp bool Indicates if the loadbalancer will reserve an IP using DHCP. Yes
Curl Example

The following shows how to submit the request using curl:

curl --include \
     --request PUT \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '    {
            "properties": {
                "name": "[loadbalancer-name]",
                "ip": "[loadbalancer-ip]",
                "dhcp": [loadbalancer-dhcp]
            }
        }    ' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/loadbalancers/[loadbalancer_id]

Response

Status: 202 (Accepted)
Headers: [
    "Date: [date]",
    "Content-Type: application/json",
    "Location: URL of a request resource which should be used for the operation's polling status",
    "Connection: keep-alive",
    "Content-Length: 426"
]
ResponseBody: {
      "id": "loadbalancer-id",
      "type": "loadbalancer",
      "href": "[base-url]/datacenters/[data-center-id]/loadbalancers/[loadbalancer-id]",
    "metadata": {
        "lastModifiedDate": "last-modified-date",
        "lastModifiedBy": "last-modified-by-user",
        "createdDate": "created-date",
        "createdBy": "created-by-user",
        "state": "loadbalancer-state",
        "etag": "etag"
    },
    "properties": {
        "name": "loadbalancer-name",
        "ip": "loadbalancer-ip",
        "dhcp": "loadbalancer-dhcp"
    },
    "entities": {
        "balancednics": []
    }
}
Response Parameters

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).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state Load Balancer state.
etag The etag for the resource.
name The name of the loadbalancer.
ip IPv4 address of the loadbalancer. All attached NICs will inherit this IP.
dhcp Indicates if the loadbalancer will reserve an IP using DHCP.
balancednics List of NICs taking part in load-balancing. All balanced nics inherit the IP of the loadbalancer. See the NIC section for attribute definitions.

List Load Balanced NICs

This will retrieve a list of NICs associated with the load balancer.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To retrieve a list of loadbalanced NICs submit a GET request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/loadbalancers/[loadbalancer-id]/balancednics

Request Parameters

None

Curl Example

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

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/loadbalancers/[loadbalancer-id]/balancednics

Response

{
  "id": "[loadbalancer_id]/balancednics",
  "type": "collection",
  "href": "[base-url]/datacenters/[data-center-id]/loadbalancers/[loadbalancer-id]/balancednics",
  "items": [
    {
      "id": "[nic-id]",
      "type": "nic",
      "href": "/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]",
      "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",
        "ips": [
          "nic-ip"
        ],
        "dhcp": "true",
        "lan": lan-id,
        "firewallActive": is-firewall-active
      },
      "entities": {
        "firewallrules": {
          "id": "{nic_id}/firewallrules",
          "type": "collection",
          "href": "/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]/firewallrules"
        }
      }
    }
  ]
}

Response Parameters

The request will return a collection of loadbalanced NICs.

You can append ?depth=1 to the end of the request to retrieve more details. This will give you the equivalent of what you would get when issuing a GET request to each NIC or Firewall Rule independently.

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).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state Load Balancer state.
etag The etag for the resource.
items A collection that represent a list of NICs.

Get Load Balanced NIC

Retrieves the attributes of a given loadbalanced NIC.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To retrieve a single loadbalanced NIC you would send a GET request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/loadbalancers/[loadbalancer-id]/balancednics/[nic-id]

Request Parameters

None

Curl Example

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

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/data-center-id]/loadbalancers/[loadbalancer-id]/balancednics/[nic-id]

Response

    {
        "id": "[nic-id]",
        "type": "nic",
        "href": "/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]",
        "metadata": {
            "lastModifiedDate": "last-modified-date",
            "lastModifiedBy": "last-modified-by-user",
            "createdDate": "created-date",
            "createdBy": "created-by-user",
            "state": "nic-state",
            "etag": "etag"
        },
        "properties": {
            "name": "nic-name",
            "mac": "nic-mac",
            "ips": nic-ip-collection,
            "dhcp": "nic-dhcp-bool",
            "lan": nic-lan,
            "firewallActive": firewall-active-status
        },
        "entities": {
            "firewallrules": []
        }
    }

Response Parameters

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).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state NIC state.
etag The etag for the resource.
name The name of the NIC.
mac The MAC address of the NIC.
ips IPs assigned to the NIC represented as a collection.
dhcp Boolean value that indicates if the NIC is using DHCP or not.
lan The LAN ID the NIC sits on.
firewallActive Once you add a firewall rule this will reflect a true value.
firewallrules A list of firewall rules associated to the NIC represented as a collection.

Associate NIC to Load Balancer

This will associate a NIC to a Load Balancer, enabling the NIC to participate in load-balancing.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/json

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

Request Body

To associate a NIC with a load-balancer you would send a POST request to `https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/loadbalancers/[loadbalancer_id]/balancednics``

The format of the request body is as follows:

{
  "id": "[nic_id]"
}

Request Parameters

Name Type Description Required
id string The UUID of the NIC. Yes

Curl Example

The following shows how to submit the request using curl:

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary "    {
        \"id\": \"[nic-id]\"
    }" \
'https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/loadbalancers/[loadbalancer-id]/balancednics'

Response

    {
        "id": "[nic-id]",
        "type": "nic",
        "href": "/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]",
        "metadata": {
            "lastModifiedDate": "last-modified-date",
            "lastModifiedBy": "last-modified-by-user",
            "createdDate": "created-date",
            "createdBy": "created-by-user",
            "state": "nic-state",
            "etag": "etag"
        },
        "properties": {
            "name": "nic-name",
            "mac": "nic-mac",
            "ips": nic-ip-collection,
            "dhcp": "nic-dhcp-bool",
            "lan": nic-lan,
            "firewallActive": firewall-active-status
        },
        "entities": {
            "firewallrules": []
        }
    }

Response Parameters

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).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state NIC state.
etag The etag for the resource.
name The name of the NIC.
mac The MAC address of the NIC.
ips IPs assigned to the NIC represented as a collection.
dhcp Boolean value that indicates if the NIC is using DHCP or not.
lan The LAN ID the NIC sits on.
firewallActive Once you add a firewall rule this will reflect a true value.
firewallrules A list of firewall rules associated to the NIC represented as a collection.

Remove a NIC Association

Removes the association of a NIC with a load balancer.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To remove a NIC association send a DELETE request to https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/loadbalancers/[load-balancer-id]/balancednics/[nic-id]

Request Parameters

None

Curl Example

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

curl --include \
     --request DELETE \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/cloudapi/v3/datacenters/[data-center-id]/loadbalancers/[loadbalancer-id]/balancednics/[nic-id]

Response

Status: 202 (Accepted)

Response Parameters

None

Requests

List Requests

This operation allows you to retrieve a list of requests. Each Cloud API call generates a request which is assigned an id. This "request id" can be used to get information about the request and its current status. The "list request" operation described here will return an array of request items. Each returned request item will have an id that can be used to get additional information as described in the Get Request and Get Request Status sections.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To retrieve a list of requests you would send a GET request to https://api.profitbricks.com/cloudapi/v3/requests

Request Parameters

None

Curl Example

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

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/cloudapi/v3/requests

Response

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

{
  "id" : "requests",
  "type" : "collection",
  "href" : "https://api.profitbricks.com/cloudapi/v3/requests",
  "items" : [ {
    "id" : "[request-id]",
    "type" : "request",
    "href" : "https://api.profitbricks.com/cloudapi/v3/requests/[request-id]"
  } ]
}

Response Parameters

The request will return a collection of requests.

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

Name Description
id The request's unique identifier.
type The type of object, which should be "request" in this context.
href URL to the object’s representation (absolute path).

Get Request

Retrieves the attributes of a specific request based on the supplied request id.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To retrieve details on a specific request you would send a GET request to https://api.profitbricks.com/cloudapi/v3/requests/[request-id]

Request Parameters

None

Curl Example

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

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/cloudapi/v3/requests/[request-id]

Response

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

{
  "id" : "[request-id]",
  "type" : "request",
  "href" : "https://api.profitbricks.com/cloudapi/v3/requests/[request-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "requestStatus" : {
      "id" : "[reuest-id]/status",
      "type" : "request-status",
      "href" : "https://api.profitbricks.com/cloudapi/v3/requests/[request-id]/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.profitbricks.com",
      "x-forwarded-for" : "[ip-address]",
      "content-length" : "81",
      "x-forwarded-host" : "api.profitbricks.com",
      "user-agent" : "Go 1.1 package http",
      "accept-encoding" : "gzip",
      "x-forwarded-server" : "my.profitbricks.com"
    },
    "body" : "{\"properties\":{\"name\":\"test\",\"description\":\"description\",\"location\":\"us/las\"}}",
    "url" : "https://api.profitbricks.com/cloudapi/v3/datacenters"
  }
}

Response Parameters

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

Name Description
id The request's unique identifier.
type The type of object, which should be "request" in this context.
href URL to the object’s representation (absolute path).
createdDate The date the resource was created.
createdBy The user who created the request.
requestStatus See the next section on retrieving a request's status for information on the attributes found in this collection.

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.

Get Request Status

Retrieves the status of a specific request based on the supplied request id.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To retrieve the status of a specific request send a GET request to https://api.profitbricks.com/cloudapi/v3/requests/[request-status-id]/status

Request Parameters

None

Curl Example

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

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/cloudapi/v3/requests/[request-status-id]/status

Response

The following is an example status request response when the specific request has completed:

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

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

Response Parameters

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

Name Description
id The request's unique identifier.
type The type of object, should be "request-status" in this context.
href URL to the object’s representation (absolute path).
status The status of the entire request, e.g. QUEUED, RUNNING, DONE, or FAILED.
message A description of the request status.
targets An array of "sub-requests" related to the request. For example, a create server request could have multiple sub-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.
status Status of individual targets within the request, e.g. QUEUED, RUNNING, DONE, or FAILED.