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


What's New?

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

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

Cloud API version 4 adds the following new features:

Contract Resource Limits

In previous versions of the Cloud API it was not possible to monitor resource usage or determine the remaining resources available under a particular contract. (This information was available in the DCD.) Using the Cloud API, you would find out that you had reached a resource limit when a provisioning operation returned an error. The newly available /contracts API call will return helpful information to both Contract Owners and Contract Users about the resource usage of a contract. Additional details on this new feature are available in the Contract Resources section of this documentation.

This feature is available NOW.

User Management via API

User management was previously available through the DCD, however it was not possible to orchestrate users and their associated resources through the Cloud API. Now the same user management features you are familiar with from the DCD have been implemented as a set of API calls under /um. Additional details on this new feature are available in the User Management section of this documentation.

This feature is available NOW.

IP Failover Groups

IP failover is a new property of a LAN, which is accessible with the existing API calls under datacenters/{datacenterId}/lans/{lanId}.

To setup IP failover, you will need to assign a single reserved IP to multiple NICs that are all members of the same LAN. This involves a few steps.

  • Create a public LAN with at least one NIC.
  • This first NIC must be assigned the reserved IP address.
  • Enable IP failover on the LAN and specify the reserved IP along with the UUID of that first NIC. It will become the "master".
  • Now you can add additional NICs from other servers to the LAN and assign them the same reserved IP address. They will automatically join the IP failover group.

It is possible to have multiple IP failover groups within the same LAN. Each IP failover group must have its own unique reserved IP, but there may be different master NICs.

Additional details on this new feature are available in the LANs section of this documentation.

This feature is available NOW.

Image Aliases for Public Images

This new feature is designed to make it possible to provision new volumes using a ProfitBrick's public image without having to determine the UUID first. Due to necessary security patches and updates to the public images, the UUID for a public image changes periodically. It is now possible to supply an imageAlias when provisioning a volume, instead of the image parameter (the image UUID). As an example, you can provision a volume using the latest version of Ubuntu by using the imageAlias value "ubuntu:latest". Another example would be using the imageAlias value "windows:2012r2". This can be more convenient than locating and setting an image value like: "5f546329-3bfd-11e7-9888-525400f64d8d".

The list of image aliases is available as an attribute of each location. Additional details on the available imageAliases can be found in the Locations section of this documentation.

This feature is available NOW.

Getting Started

How to Access the API

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

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

Swagger UI

It is possible to visually explore the Cloud API v4 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 v4 by visiting the Swagger UI Online Demo and entering https://api.profitbricks.com/cloudapi/v4/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 ProfitBricks API implements the standard application/json content type.

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

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

Request Depth

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

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

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 the proprietary 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 ProfitBricks 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.

API User Management

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

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

Users & Groups

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

The API adheres to all permissions applied through the DCD:

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

Groups

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

API Rate Limits

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

Multi-user

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

Separate Limits for Read and Write

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

Exceeding the Limit

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

HTTP Status Codes

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

Response Headers

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

Data Centers

Create a Data Center

Virtual Data Centers (VDCs) are the foundation of the ProfitBricks 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 Basic Data Center

Request

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

Request Parameters - Header

The following request headers are available:

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

Request Body

The format of the request body is as follows:

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

Request Parameters - Body

The following table describes the properties of the request body:

Name Required Type Default Description
name yes string n/a A name for the virtual data center.
location yes string n/a The physical location where the VDC will be created. This will be where all of your resources live. [us/ewr, us/las, de/fra, de/fkb]
description no string n/a A description for the data center, e.g. staging, production.

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

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

The following table outlines the locations currently supported:

Region Location Combination Description
de fkb de/fkb Karlsruhe (Germany)
de fra de/fra Frankfurt (Germany)
us las us/las Las Vegas, Nevada (USA)
us ewr us/ewr Newark, New Jersey (USA)

Curl Example

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

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

Response Body

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

{
  "id" : "{dataCenterId}",
  "type" : "datacenter",
  "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}",
  "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 Attributes

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

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

The metadata collection contains the following attributes:

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

The properties collection contains the following attributes:

Name Type Description
name string The name of the data center.
description string The description of the data center.
location string The location of the data center.
version string The version of the data center.
features string Reserved for future use.

Create a Data Center with Multiple Resources

Request

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

Request Parameters - Header

The following request headers are available:

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

The format of the request body is as follows:

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

Request Parameters - Body

The following table describes the properties of the request body:

Name Required Type Default Description
name yes string n/a A name for the virtual data center.
location yes string n/a The physical location where the VDC will be created. This will be where all of your resources live. [us/ewr, us/las, de/fra, de/fkb]
description no string n/a A description for the data center, e.g. staging, production.

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

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

The following table outlines the locations currently supported:

Region Location Combination Description
de fkb de/fkb Karlsruhe (Germany)
de fra de/fra Frankfurt (Germany)
us las us/las Las Vegas, Nevada (USA)
us ewr us/ewr Newark, New Jersey (USA)

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

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

Curl Example

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

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '{
  "properties": {
    "name": "[data-center-name]",
    "description": "Example Data Center",
    "location": "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/v4/datacenters

Response Body

HTTP/1.1 100 Continue

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

{
  "id" : "{dataCenterId}",
  "type" : "datacenter",
  "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}",
  "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" : "{serverId}/servers",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers"
    },
    "lans" : {
      "id" : "{dataCenterId}/lans",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/lans"
    }
  }
}

Response Attributes

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

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

The metadata includes the following attributes:

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

The properties include the following attributes:

Name Type Description
name string The name of the data center.
description string The description of the data center.
location string The location you provisioned the data center.
version int32 The version of the data center.
features collection Reserved for future use.

The entities collection includes the following:

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

Retrieve a Data Center

You can retrieve details about a virtual 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

To retrieve a data center, send a GET request to https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Query

The following optional query parameters may be included.

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

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

https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}?pretty=0

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

https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}?depth=1

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

Curl Example

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

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

Response Body

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

{
  "id" : "{dataCenterId}",
  "type" : "datacenter",
  "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}",
  "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" : "{dataCenterId}/servers",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers"
    },
    "volumes" : {
      "id" : "{dataCenterId}/volumes",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/volumes"
    },
    "loadbalancers" : {
      "id" : "{dataCenterId}/loadbalancers",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/loadbalancers"
    },
    "lans" : {
      "id" : "{dataCenterId}/lans",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/lans"
    }
  }
}

Response Attributes

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

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

The metadata includes the following attributes:

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

The properties include the following attributes:

Name Type Description
name string The name of the data center.
description string The description of the data center.
location string The location you provisioned the data center.
version int32 The version of the data center.
features collection Reserved for future use.

The entities collection includes the following:

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

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

List Data Centers

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

Request

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Query

The following optional query parameters may be included.

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

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

https://api.profitbricks.com/cloudapi/v4/datacenters?pretty=0

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

https://api.profitbricks.com/cloudapi/v4/datacenters?depth=1

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

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/v4/datacenters

Response Body

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

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

Response Attributes

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

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

For each of the items the following attributes are returned:

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

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

Update a Data Center

The 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 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

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

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Body

The format of the request body is as follows:

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

Request Parameters - Body

The following table describes the properties of the request body:

Name Required Type Default Description
name no string n/a A name for the virtual data center.
description no string n/a A description for the virtual data center, e.g. staging, production.

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

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

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/v4/datacenters/{dataCenterId}

Response Body

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

{
  "id" : "{dataCenterId}",
  "type" : "datacenter",
  "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}",
  "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" : "{dataCenterId}/servers",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers"
    },
    "volumes" : {
      "id" : "{dataCenterId}/volumes",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/volumes"
    },
    "loadbalancers" : {
      "id" : "{dataCenterId}/loadbalancers",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/loadbalancers"
    },
    "lans" : {
      "id" : "{dataCenterId}/lans",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/lans"
    }
  }
}

Response Attributes

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

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

The metadata includes the following attributes:

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

The properties include the following attributes:

Name Type Description
name string The name of the data center.
description string The description of the data center.
location string The location you provisioned the data center.
version int32 The version of the data center.
features collection Reserved for future use.

The entities collection includes the following:

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

PUT Update

Request

To fully update a data center, send a PUT request to https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}

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.

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Body

The format of the request body is as follows:

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

Request Parameters - Body

The following table describes the properties of the request body:

Name Required Type Default Description
name yes string n/a A name for the virtual data center.
description yes string n/a A description for the virtual data center, e.g. staging, production.

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

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

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/v4/datacenters/{dataCenterId}

Response Body

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

{
  "id" : "{dataCenterId}",
  "type" : "datacenter",
  "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}",
  "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" : "{dataCenterId}/servers",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers"
    },
    "volumes" : {
      "id" : "{dataCenterId}/volumes",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/volumes"
    },
    "loadbalancers" : {
      "id" : "{dataCenterId}/loadbalancers",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/loadbalancers"
    },
    "lans" : {
      "id" : "{dataCenterId}/lans",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/lans"
    }
  }
}

Response Attributes

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

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

The metadata includes the following attributes:

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

The properties include the following attributes:

Name Type Description
name string The name of the data center.
description string The description of the data center.
location string The location you provisioned the data center.
version int32 The version of the data center.
features collection Reserved for future use.

The entities collection includes the following:

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

Delete a Data Center

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

Request

To remove a data center you would send a DELETE request to https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

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/v4/datacenters/{dataCenterId}

Response

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

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

Checking the Status

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

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

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

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

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

Locations

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

Currently available locations are shown in this table:

Region Location Combination
de fkb de/fkb
de fra de/fra
us las us/las
us ewr us/ewr

List Locations

Retrieve a list of all available regional locations.

Request

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Query

The following optional query parameters may be included.

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

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

https://api.profitbricks.com/cloudapi/v4/locations?pretty=0

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

https://api.profitbricks.com/cloudapi/v4/locations?depth=1

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

Curl Example

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

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

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

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

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

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

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

Response Payload

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

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

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

Each of the returned items has these attributes:

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

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

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

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

Get Regional Locations

Retrieves the locations available in a specific region.

Request

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

Request Parameters - Path

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

Request Parameters - Header

The request headers may include the following:

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

Request Parameters - Query

The following query parameters may be included.

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

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

https://api.profitbricks.com/cloudapi/v4/locations?pretty=0

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

https://api.profitbricks.com/cloudapi/v4/locations?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information about the regional locations.

Curl Example

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

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

The response will be similar to this:

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

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

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

Now the response includes additional properties for each item:

{
  "id": "locations",
  "type": "collection",
  "href": "https://api.profitbricks.com/cloudapi/v4/locations",
  "items": [
    {
      "id": "us/las",
      "type": "location",
      "href": "https://api.profitbricks.com/cloudapi/v4/locations/us/las",
      "properties": {
        "name": "lasvegas",
        "features": [
          "SSD",
          "MULTIPLE_CPU"
        ],
        "imageAliases": []
      }
    },
    {
      "id": "us/ewr",
      "type": "location",
      "href": "https://api.profitbricks.com/cloudapi/v4/locations/us/ewr",
      "properties": {
        "name": "newark",
        "features": [
          "SSD",
          "MULTIPLE_CPU"
        ],
        "imageAliases": [
          "windows:2008",
          "windows:2012"
        ]
      }
    }
  ]
}

Response Payload

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

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

Each of the returned items has these attributes:

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

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

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

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

Get Location

Retrieves all the details about a specific regional location.

Request

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

Request Parameters - Path

Parameter Required Type Default Description
{regionId} yes string n/a The two character region identifier. [de, us]
{locationId} yes string n/a The three character region identifier. [fkb, fra, las, ewr]

Request Parameters - Header

The request headers may include the following:

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

Request Parameters - Query

The following query parameters may be included.

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

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

https://api.profitbricks.com/cloudapi/v4/locations/{regionId}/{locationId}?pretty=0

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

https://api.profitbricks.com/cloudapi/v4/{regionId}/{locationId}?depth=1

Note: For this particular operation, increasing the value supplied to depth will not return additional information about the location.

Curl Example

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

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

The response will be similar to this:

{
  "id": "us/ewr",
  "type": "location",
  "href": "https://api.profitbricks.com/cloudapi/v4/locations/us/ewr",
  "properties": {
    "name": "newark",
    "features": [
      "SSD",
      "MULTIPLE_CPU"
    ],
    "imageAliases": []
  }
}

Response Payload

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

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

These properties are returned:

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

Image aliases

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

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

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

Servers

Create a Server

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

Request

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

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Body

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

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

The format of the request body is as follows:

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

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

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

Request Parameters - Body

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

The following table outlines the availability zones currently supported:

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

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

Curl Example

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

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

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

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

Response Body

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

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

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

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

The metadata collection is described in this table:

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

The properties returned are:

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

The entities returned may include:

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

List Servers

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

Request

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

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Query

The following optional query parameters may be included.

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

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

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

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

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

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

Curl Example

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

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

Response

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

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

Response Attributes

The request will return a collection of servers.

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

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

The items will have the following attributes.

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

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

Retrieve a Server

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

Request

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

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Query

The following optional query parameters may be included.

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

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

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

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

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

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

Curl Example

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

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

Response Body

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

{
  "id" : "{serverId}",
  "type" : "server",
  "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}",
  "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" : "{volumeId}",
      "type" : "volume",
      "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/volumes/{volumeId}"
    },
    "cpuFamily" : "AMD_OPTERON"
  },
  "entities" : {
    "cdroms" : {
      "id" : "{serverId}/cdroms",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/cdroms"
    },
    "volumes" : {
      "id" : "{serverId}/volumes",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/volumes"
    },
    "nics" : {
      "id" : "{serverId}/nics",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics"
    }
  }
}

Response Attributes

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

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

The metadata about the server includes:

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

The properties returned are:

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

The entities returned include:

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

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

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

Server States

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

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

Update a Server

The ProfitBricks 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". You will need to set the allowReboot parameter to true and the server will experience a hard reboot.

PATCH

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

Request

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

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Body

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

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/v4/datacenters/{dataCenterId}/servers/{serverId}

Response

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

{
  "id" : "{serverId}",
  "type" : "server",
  "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}",
  "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" : "{volumeId}",
      "type" : "volume",
      "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/volumes/{volumeId}"
    },
    "cpuFamily" : "AMD_OPTERON"
  },
  "entities" : {
    "cdroms" : {
      "id" : "{serverId}/cdroms",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/cdroms"
    },
    "volumes" : {
      "id" : "{serverId}/volumes",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/volumes"
    },
    "nics" : {
      "id" : "367fffcd-965f-4aa5-a6c2-afbd81e407ba/nics",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics"
    }
  }
}

Response Attributes

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

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

The metadata about the server includes:

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

The properties returned are:

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

The entities returned include:

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

PUT

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

Request

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

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

Curl Example

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

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

Response Body

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

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

Delete a Server

This will remove a server from a virtual 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

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

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

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/v4/datacenters/{dataCenterId}/servers/{serverId}

Response

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

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

List Attached Volumes

Retrieves a list of volumes attached to the server.

Request

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

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Query

The following optional query parameters may be included.

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

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

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

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

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

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

Curl Example

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

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

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

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

Response

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

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

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

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

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

{
  "id" : "{serverId}/volumes",
  "type" : "collection",
  "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/volumes",
  "items" : [ {
    "id" : "{volumeId}",
    "type" : "volume",
    "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/volumes/{volumeId}",
    "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

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

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Body

The following table describes the request body values:

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

Curl Example

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

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

Response

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

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

Response Attributes

Please see the Volumes section for attribute definitions.

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

Retrieve an Attached Volume

This will retrieve the properties of an attached volume.

Request

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

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Query

The following optional query parameters may be included.

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

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

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

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

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

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

Curl Example

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

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

Response

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

{
  "id" : "{volumeId}",
  "type" : "volume",
  "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/volumes/{volumeId}",
  "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 virtual data center. You will need to make a separate request to delete a volume.

Request

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

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

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/v4/datacenters/{dataCenterId}/servers/{serverId}/volumes/{volumeId}

Response

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

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

List Attached CD-ROMs

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

Request

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

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Query

The following optional query parameters may be included.

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

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

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

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

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

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

Curl Example

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

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

Response

You should receive a response similar to this:

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

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

The response will contain a collection of CD-ROMs.

Response Parameters

Please reference the CD-ROMs section for attribute definitions.

Attach a CD-ROM

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

Request

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

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Body

The following table describes the request body values:

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

Curl Example

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

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

Response

You should receive a response similar to this:

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

{
  "id" : "[image-id]",
  "type" : "image",
  "href" : "https://api.profitbricks.com/cloudapi/v4/images/{imageId}",
  "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

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

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Query

The following optional query parameters may be included.

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

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

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

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

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

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

Curl Example

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

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

Response

You should receive a response similar to this:

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

{
  "id" : "[image-id]",
  "type" : "image",
  "href" : "https://api.profitbricks.com/cloudapi/v4/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

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

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

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/v4/datacenters/{dataCenterId}/servers/{serverId}/cdroms/{cdromId}

Response

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

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

Reboot a Server

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

Request

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

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

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/v4/datacenters/{dataCenterId}/servers/{serverId}/reboot

Response

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

Response Body

None

Start a Server

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

Request

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

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

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/v4/datacenters/{dataCenterId}/servers/{serverId}/start

Response

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

Response Body

None

Stop a Server

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

Request

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

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

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/v4/datacenters/{dataCenterId}/servers/{serverId}/stop

Response

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

Response Body

None

Images

List Images

Retrieve a list of images within the data center.

Request

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Query

The following optional query parameters may be included.

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

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

https://api.profitbricks.com/cloudapi/v4/images?pretty=0

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

https://api.profitbricks.com/cloudapi/v4/images?depth=1

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

Curl Example

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

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

Response Body

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

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

Response Attributes

The request will return a collection of images.

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

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

Each of the items returned has the following attributes.

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

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

Get Image

Retrieves the attributes of a specific image.

Request

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

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Query

The following optional query parameters may be included.

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

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

https://api.profitbricks.com/cloudapi/v4/images/{imageId}?pretty=0

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

https://api.profitbricks.com/cloudapi/v4/images/{imageId}?depth=1

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

Curl Example

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

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

Response

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

{
  "id" : "[image-id]",
  "type" : "image",
  "href" : "https://api.profitbricks.com/cloudapi/v4/images/{imageId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "System",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "System",
    "state" : "AVAILABLE"
  },
  "properties" : {
    "name" : "CentOS-6.7-x86_64-netinstall.iso",
    "description" : null,
    "location" : "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 Attributes

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

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

The metadata returned includes the following attributes.

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

The properties returned include the following attributes:

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

Delete Image

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

Request

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

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

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/v4/images/{imageId}

Response

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

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

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

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

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

Update Image

The ProfitBricks 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.

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

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

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Body

{
    "description": "Updated Image Description"
}

Request Parameters - Body

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

Curl Example

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

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

Response Body

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

{
  "id" : "{imageId}",
  "type" : "image",
  "href" : "https://api.profitbricks.com/cloudapi/v4/images/{imageId}",
  "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 Attributes

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

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

The metadata returned includes the following attributes.

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

The properties returned include the following attributes:

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

PUT

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

Request

To perform a full update of the image's properties send a PUT request to: https://api.profitbricks.com/cloudapi/v4/images/{imageId}

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Body

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

Request Parameters - Body

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

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

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

Response

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

{
  "id" : "[image-id]",
  "type" : "image",
  "href" : "https://api.profitbricks.com/cloudapi/v4/images/{imageId}",
  "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 JSON response body:

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

The metadata returned includes the following attributes.

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

The properties returned include the following attributes:

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

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

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

Request Parameters - Path

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

Request Parameters - Header

The request headers may include the following:

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

Request Parameters - Query

The following query parameters may be included.

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

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

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

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

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

Note: For this particular operation, increasing the value supplied to depth will return additional information about the volumes.

Curl Example

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

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

Response

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

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

Response Attributes

The request will return a collection of volumes.

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

These attributes are found in the JSON response body:

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

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

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

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

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

The metadata returned for each volume:

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

The properties returned for each volume:

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

Get Volume

Retrieves the attributes of a given volume.

Request

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

Request Parameters - Path

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

Request Parameters - Header

The request headers may include the following:

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

Request Parameters - Query

The following query parameters may be included.

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

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

https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/volumes/{volumeId}?pretty=0

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

https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/volumes/{volumeId}?depth=1

Note: For this particular operation, increasing the value supplied to depth will not return additional information about the volume.

Curl Example

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

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

Response

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

{
  "id" : "[volume-id]",
  "type" : "volume",
  "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/volumes/{volumeId}",
  "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,
    "imageAlias" : null,
    "imagePassword" : null,
    "sshKeys" : null,
    "bus" : "VIRTIO",
    "licenceType" : "LINUX",
    "cpuHotPlug" : false,
    "cpuHotUnplug" : false,
    "ramHotPlug" : false,
    "ramHotUnplug" : false,
    "nicHotPlug" : false,
    "nicHotUnplug" : false,
    "discVirtioHotPlug" : false,
    "discVirtioHotUnplug" : false,
    "discScsiHotPlug" : false,
    "discScsiHotUnplug" : false,
    "deviceNumber" : 1
   }
}

Response Attributes

The request will return a collection of volumes.

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

These attributes are found in the JSON response body:

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

The metadata returned for each volume:

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

The properties returned for each volume:

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

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 ProfitBricks platform is currently reached with a volume size of 300 GB. (IOPS of 15000 read and 9000 write, along with bandwidth of 300MB/s) It is perfectly acceptable to create SSD volumes larger than 300 GB, however no additional performance gains are realized once you exceed 300 GB.

Request

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

Request Parameters - Path

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

Request Parameters - Header

The request headers may include the following:

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

Request Parameters - Body

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

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

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

Request Body Example

The format of the request body is as follows:

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

Curl Example

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

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

Response

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

{
  "id" : "[volume-id]",
  "type" : "volume",
  "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/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,
    "imageAlias" : "null",
    "imagePassword" : null,
    "sshKeys" : null,
    "bus" : "VIRTIO",
    "licenceType" : "OTHER",
    "cpuHotPlug" : false,
    "cpuHotUnplug" : false,
    "ramHotPlug" : false,
    "ramHotUnplug" : false,
    "nicHotPlug" : false,
    "nicHotUnplug" : false,
    "discVirtioHotPlug" : false,
    "discVirtioHotUnplug" : false,
    "discScsiHotPlug" : false,
    "discScsiHotUnplug" : false,
    "deviceNumber" : null
  }
}

Response Attributes

These attributes are found in the JSON response body:

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

The metadata returned for the volume:

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

The properties returned for the volume:

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

Helpful errors are returned if the request contains invalid data:

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

Delete Volume

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

Request

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

Request Parameters - Path

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

Request Parameters - Header

The request headers may include the following:

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

Curl Example

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

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

Response

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

Response Body

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

Update Volume

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

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

Request Parameters - Path

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

Request Parameters - Header

The request headers may include the following:

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

Request Parameters - Body

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

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

Curl Example

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

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

Response

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

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

Response Attributes

These attributes are found in the JSON response body:

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

The metadata returned for the volume:

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

The properties returned for the volume:

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

PUT

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

Request

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

Request Parameters - Path

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

Request Parameters - Header

The request headers may include the following:

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

Request Parameters - Body

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

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

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

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

Curl Example

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

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

Response

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

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

Response Attributes

These attributes are found in the JSON response body:

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

The metadata returned for the volume:

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

The properties returned for the volume:

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

Create Volume Snapshot

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

Request

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

Request Parameters - Path

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

Request Parameters - Header

The request headers may include the following:

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

Request Parameters - Body

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

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

Curl Example

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

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

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

Response

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

{
  "id" : "{snapshotId}",
  "type" : "snapshot",
  "href" : "https://api.profitbricks.com/cloudapi/v4/snapshots/{snapshotId}",
  "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 Body

These attributes are found in the JSON response body:

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

The metadata returned for the snapshot:

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

The properties returned for the snapshot:

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

Restore Volume Snapshot

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

Request

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

Request Parameters - Path

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

Request Parameters - Header

The request headers may include the following:

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

Request Parameters - Body

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

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

Curl Example

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

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

Response

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

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

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

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

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

Snapshots

List Snapshots

Retrieve a list of snapshots.

Request

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

Request Parameters - Header

The request headers may include the following:

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

Request Parameters - Query

The following query parameters may be included.

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

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

https://api.profitbricks.com/cloudapi/v4/snapshots?pretty=0

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

https://api.profitbricks.com/cloudapi/v4/snapshots?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information about the volume.

Curl Example

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

curl --include \
     --request GET \
     --user 'username@domain.tld:password" \
     https://api.profitbricks.com/cloudapi/v4/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/v4/snapshots",
  "items" : [ {
    "id" : "{snapshotId}",
    "type" : "snapshot",
    "href" : "https://api.profitbricks.com/cloudapi/v4/snapshots/{snapshotId}"
  } ]
}

Response Attributes

The request will return a collection of snapshots.

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

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

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

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

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

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

The metadata returned for the snapshot:

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

The properties returned for the snapshot:

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

Get Snapshot

Retrieves the attributes of a specific snapshot.

Request

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

Request Parameters - Path

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

Request Parameters - Header

The request headers may include the following:

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

Request Parameters - Query

The following query parameters may be included.

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

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

https://api.profitbricks.com/cloudapi/v4/snapshots/{snapshotId}?pretty=0

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

https://api.profitbricks.com/cloudapi/v4/snapshots/{snapshotId}?depth=1

Note: For this particular operation, increasing the value supplied to depth will not return additional information about the volume.

Curl Example

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

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

Response

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

{
  "id" : "{snapshotId}",
  "type" : "snapshot",
  "href" : "https://api.profitbricks.com/cloudapi/v4/snapshots/{snapshotId}",
  "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 Attributes

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

The metadata returned for the snapshot:

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

The properties returned for the snapshot:

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

Delete Snapshot

Deletes the specified snapshot.

Request

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

Request Parameters - Path

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

Request Parameters - Header

The request headers may include the following:

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

Curl Example

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

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

Response

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

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

Update Snapshot

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

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

Request Parameters - Path

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

Request Parameters - Header

The request headers may include the following:

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

Request Parameters - Body

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

Curl Example

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

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

Response

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

{
  "id" : "{snapshotId}",
  "type" : "snapshot",
  "href" : "https://api.profitbricks.com/cloudapi/v4/snapshots/{snapshotId}",
  "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 Attributes

The JSON response body will contain the following attributes:

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

The metadata returned for the snapshot:

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

The properties returned for the snapshot:

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

PUT

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

Request

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

Request Parameters - Path

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

Request Parameters - Header

The request headers may include the following:

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

Request Parameters - Body

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

Curl Example

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

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

Response

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

{
  "id" : "{snapshotId}",
  "type" : "snapshot",
  "href" : "https://api.profitbricks.com/cloudapi/v4/snapshots/{snapshotId}",
  "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 Attributes

The JSON response body will contain the following attributes:

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

The metadata returned for the snapshot:

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

The properties returned for the snapshot:

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

IP Block

List IP Blocks

Retrieves a list of all IP blocks that have been reserved.

Request

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Query

The following optional query parameters may be included.

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

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

https://api.profitbricks.com/cloudapi/v4/ipblocks?pretty=0

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

https://api.profitbricks.com/cloudapi/v4/ipblocks?depth=1

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

Curl Example

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

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/cloudapi/v4/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/v4/ipblocks",
  "items" : [ {
    "id" : "{ipBlockId}",
    "type" : "ipblock",
    "href" : "https://api.profitbricks.com/cloudapi/v4/ipblocks/{ipBlockId}"
  }, {
    "id" : "{ipBlockId}",
    "type" : "ipblock",
    "href" : "https://api.profitbricks.com/cloudapi/v4/ipblocks/{ipBlockId}"
  } ]
}

Response Attributes

The request will return a collection of IP blocks.

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

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

Each of the returned items has these attributes:

Name Type Description
id string The IP Blocks identifier.
type string The type of object. In this case "ipblock".
href string URL to the object’s representation (absolute path).

If you append the ?depth=1 query parameter to the end of the request then more details are returned for each individual IP Block that is part of items. The additional details include metadata, properties, and entities. This is similar to issuing a GET request to each IP Block independently. Please see the next section for additional information.

Get IP Block

Retrieves the attributes of a specific IP Block.

Request

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

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Query

The following optional query parameters may be included.

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

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

https://api.profitbricks.com/cloudapi/v4/ipblocks/{ipBlockId}?pretty=0

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

https://api.profitbricks.com/cloudapi/v4/ipblocks/{ipBlockId}?depth=1

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

Curl Example

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

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

Response

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

{
  "id" : "{ipBlockId}",
  "type" : "ipblock",
  "href" : "https://api.profitbricks.com/cloudapi/v4/ipblocks/{ipBlockId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[username]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[username]",
    "state" : "AVAILABLE"
  },
  "properties" : {
"    ips" : [ "1.2.3.4" ],
    "location" : "us/las",
    "size" : 1,
    "name" : "IP Block Example"
  }
}

Response Attributes

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

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

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

Name Type Description
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
createdDate string The date the resource was created.
createdBy string The user who created the resource.
state string The IP Block state. [BUSY, AVAILABLE]
etag string The ETag for the resource.

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

Name Type Description
ips collection The reserved IP addresses that make up the IP Block.
location string The ProfitBricks location where the IP Block has been reserved. ["us/las", "us/ewr", "de/fkb", "de/fra"]
size int32 The number of IP addresses that make up the IP Block.
name string A descriptive name for 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 consists of one or more static IP addresses.

Request

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Body

Name Required Type Description
location yes string This must be one of the available Profitbricks locations. ["us/ewr", "us/las", "de/fra", "de/fkb"]
size yes int32 The size of the IP Block you want to create.
name no string A descriptive name for the IP Block.

Curl Example

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

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

Response

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

{
  "id" : "{ipBlockId}",
  "type" : "ipblock",
  "href" : "https://api.profitbricks.com/cloudapi/v4/ipblocks/{ipBlockId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[username]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[timestamp]",
    "lastModifiedBy" : "[username]",
    "state" : "BUSY"
  },
  "properties" : {
    "ips" : [
        "1.2.3.4",
        "5.6.7.8"
    ],
    "location" : "us/las",
    "size" : 2,
    "name" : "API Doc Test"
  }
}

Response Parameters

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

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

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

Name Type Description
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
createdDate string The date the resource was created.
createdBy string The user who created the resource.
state string The IP Block state. [BUSY]
etag string The ETag for the resource.

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

Name Type Description
ips collection The reserved IP addresses that make up the IP Block.
location string The ProfitBricks location where the IP Block has been reserved. ["us/las", "us/ewr", "de/fkb", "de/fra"]
size int32 The number of IP addresses that make up the IP Block.
name string A descriptive name for the IP Block.

Delete IP Block

Deletes the specified IP Block.

Request

To delete an IP block you would send a DELETE request to https://api.profitbricks.com/cloudapi/v4/ipblocks/{ipBlockId}

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Curl Example

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

curl --include \
     --request DELETE \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/cloudapi/v4/ipblocks/{ipBlockId}

Response

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

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

LANs

List LANs

Retrieve a list of LANs provisioned in a specific virtual data center.

Request

To retrieve a list of LANs you would submit a GET request to https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/lans

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Query

The following optional query parameters may be included.

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

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

https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/lans?pretty=0

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

https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/lans?depth=1

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

Curl Example

The following shows how to submit the GET /datacenters/{dataCenterId}/lans request via curl:

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

Response

Here is an example response for a virtual data center that has three LANs:

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

{
  "id" : "[datacenterId]/lans",
  "type" : "collection",
  "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/[datacenterId]/lans",
  "items" : [ {
    "id" : "3",
    "type" : "lan",
    "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/[datacenterId]/lans/3"
  }, {
    "id" : "1",
    "type" : "lan",
    "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/[datacenterId]/lans/1"
  }, {
    "id" : "2",
    "type" : "lan",
    "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/[datacenterId]/lans/2"
  } ]
}

Response Body

The response will contain a collection of LANs.

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

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

Each of the returned items has these attributes:

Name Type Description
id string The LAN's identifier, generally an integer value.
type string The type of object. In this case "lan".
href string URL to the object’s representation (absolute path).

If you append the ?depth=1 query parameter to the end of the request then more details are returned for each individual LAN that is part of items. The additional details include metadata, properties, and entities. This is similar to issuing a GET request to each LAN independently. Please see the next section for additional information.

Get LAN

Retrieves the attributes of a given LAN.

Request

To retrieve details about a single LAN you would send a GET request to https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/lans/{lanId}

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Query

The following optional query parameters may be included.

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

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

https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/lans/{lanId}?pretty=0

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

https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/lans/{lanId}?depth=1

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

Curl Example

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

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

Response

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

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

Name Type Description
id string The unique identifier.
type string The type of object that has been created.
href string URL to the object’s representation (absolute path).
metadata collection Various details about the LAN.
properties collection Properties of the LAN.
entities collection NICs that are part of the LAN.

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

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

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

Name Type Description
name string A descriptive name for the LAN.
public Boolean Boolean indicating if the LAN faces the public Internet or not.
ipFailover collection Attributes related to IP failover groups.

The ipFailover collection contains two attributes:

Name Type Description
ip string The reserved public IP address assigned to the IP failover group.
nicUuid string The UUID of the "master" NIC for the failover group.

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

Name Type Description
nics collection A collection of NICs associated with the LAN.

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

Name Type Description
id string The NIC ID with "/nics" appended.
type string The type of object, in this case "collection".
href string A URL to access details about the NICs that are part of the LAN.

Increasing to depth=1 will return an additional items collection with each individual NIC that is part of nics listed.

Increasing to depth=2 will return even more details about each NIC that is part of nics. With depth=3 you'll get basic information about any firewall rules that are assigned to the NIC. At depth=4 you'll get detailed information about each firewall rule that is assigned to the NIC. Please take a look at the Network Interfaces section of this documentation for additional information.

Create LAN

Creates a new LAN within a virtual data center.

Request

To create a LAN you would send a POST request to https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/lans

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Body

The format of the JSON request body is as follows:

{
    "properties": {
        "name": "First LAN",
        "ipFailover": [
          {
            "ip": "string",
            "nicUuid": "string"
          }
        ],
        "public": "true"
    }
}

Request Parameters - Body

These are the available properties that can be set:

Name Required Type Default
name no string n/a
ipFailover no array n/a
public yes boolean false

The ipFailover array consists of two attributes.

Name Required Type Default
ip yes string n/a
nicUuid yes string n/a

Curl Example

The following shows how to create a LAN using curl:

curl --include \
     --request POST \
     --user 'username@domain.tld:password \
     --header "Content-Type: application/json" \
     --data-binary '{
        "properties": {
            "name": "My New LAN",
            "public": "false"
        }
     }' \
     https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/lans

Response

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

{
  "id" : "5",
  "type" : "lan",
  "href" : "https://api.profitbricks.com/cloudapi/v4/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 Attributes

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

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

The metadata returned is outlined in this table:

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

The properties returned are summarized in this table:

Name Type Description
name string A descriptive name assigned to the LAN object.
ipFailover array Details about the IP failover group.
public boolean Indicates if the LAN faces the public Internet or not.

Delete LAN

Deletes the specified LAN.

Request

To delete a LAN you would send a DELETE request to https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/lans/{lanId}

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Curl Example

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

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

Response

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

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

Update LAN

The ProfitBricks 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.

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

To perform a partial update to the LAN's properties you would send a PATCH request to https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/lans/{lanId}

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Body

The format of the JSON request body is as follows:

{
    "properties": {
        "name": "First LAN",
        "ipFailover": [
          {
            "ip": "string",
            "nicUuid": "string"
          }
        ],
        "public": "true"
    }
}

These are the available properties that can be set:

Name Required Type Default
name no string n/a
ipFailover no array n/a
public no boolean false

The ipFailover array consists of two attributes.

Name Required Type Default
ip no string n/a
nicUuid no string n/a

Curl Example

The following shows you how to submit the PATCH /datacenters/{dataCenterId}/lans/{lanId} request using curl:

curl --include \
     --request PATCH \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '{
            "name": "My Old LAN"
        }' \
     https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/lans/{lanId}

Response

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

{
  "id" : "3",
  "type" : "lan",
  "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/lans/3",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "My Old LAN",
    "ipFailover" : [],
    "public" : false
  },
  "entities" : {
    "nics" : {
      "id" : "3/nics",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/lans/3/nics"
    }
  }
}

Response Attributes

The JSON response is described in this table:

Name Type Description
id string The resource's unique identifier.
type string The type of object that has been created.
href string URL to the object’s representation (absolute path).
metadata collection Metadata related to the creation of the LAN.
properties collection Properties of the LAN.
entities collection NICs that are part of the LAN.

The metadata returned is outlined in this table:

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

The properties returned are summarized in this table:

Name Type Description
name string A descriptive name assigned to the LAN object.
ipFailover array Details about the IP failover group.
public boolean Indicates if the LAN faces the public Internet or not.

PUT

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

Request

To perform a full update of the LAN's properties send a PUT request to: https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/lans/{lanId}

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Body

The format of the JSON request body is as follows:

{
    "properties": {
        "name": "1st LAN",
        "ipFailover": [
          {
            "ip": "",
            "nicUuid": ""
          }
        ],
        "public": "true"
    }
}

These are the available properties that can be set:

Name Required Type Default
name yes string n/a
ipFailover yes array n/a
public yes boolean false

The ipFailover array consists of two attributes.

Name Required Type Default
ip yes string n/a
nicUuid yes string n/a

Curl Example

The following shows how to submit the PUT /datacenters/{dataCenterId}/lans/{lanId} request body using curl:

curl --include \
     --request PUT \
     --user 'username@domain.tld@password' \
     --header "Content-Type: application/json" \
     --data-binary '{
            "name" : "1st LAN",
            "ipFailover": [
          {
            "ip": "",
            "nicUuid": ""
          }
        ],
            "public": "false"
        }' \
     https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/lans/{lanId}

Response

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

{
  "id" : "4",
  "type" : "lan",
  "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/lans/4",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "1st LAN",
    "ipFailover" : [],
    "public" : true
  },
  "entities" : {
    "nics" : {
      "id" : "4/nics",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/lans/4/nics"
    }
  }
}

Response Attributes

Name Type Description
id string The resource's unique identifier.
type string The type of object that has been created.
href string URL to the object’s representation (absolute path).
metadata collection Metadata related to the creation of the LAN.
properties collection Properties of the LAN.
entities collection NICs that are part of the LAN.

The metadata returned is outlined in this table:

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

The properties returned are summarized in this table:

Name Type Description
name string A descriptive name assigned to the LAN object.
ipFailover array Details about the IP failover group.
public boolean Indicates if the LAN faces the public Internet or not.

Network Interfaces

List NICs

Retrieves a list of NICs.

Request

To retrieve a list of NICs, submit a GET request to https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Query

The following optional query parameters may be included.

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

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

https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics?pretty=0

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

https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics?depth=1

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

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/v4/datacenters/{dataCenterId}/servers/{serverId}/nics

Response

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

{
  "id" : "{serverId}/nics",
  "type" : "collection",
  "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics",
  "items" : [ {
    "id" : "{nicId}",
    "type" : "nic",
    "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}"
  } ]
}

Response Attributes

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

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

Name Type Description
id string {serverId}/nics
type string The type of object that has been created. "collection"
href string URL to the object’s representation (absolute path).
items collection A collection of NICs.

The items will have the following attributes.

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

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

Get a NIC

Retrieves the attributes of a given NIC.

Request

To retrieve attributes of a specific NIC, send a GET request to https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Query

The following optional query parameters may be included.

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

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

https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}?pretty=0

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

https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}?depth=1

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

Curl Example

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

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

Response

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

{
  "id" : "{nicId}",
  "type" : "nic",
  "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}",
  "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" : "{nicId}/firewallrules",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules"
    }
  }
}

Response Attributes

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

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

The metadata about the NIC includes:

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

The properties returned are:

Name Type Description
name string The name of the NIC.
mac string The MAC address of the NIC.
ips collection IPs assigned to the NIC represented as a collection.
dhcp boolean Boolean value that indicates if the NIC is using DHCP (true) or not (false).
lan int32 The LAN ID the NIC sits on.
nat boolean Boolean value indicating if the private IP address has outbound access to the public internet enabled (true) or not (false).
firewallActive boolean A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.

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

The entities returned include:

Name Type Description
firewallrules collection A collection of firewall rules associated with the NIC.

If you passed a depth query parameter with a value of 1 or greater, then additional information about each of the entities is returned.

Create a NIC

Adds a NIC to the target server.

Request

To create a NIC, send a POST request to https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Body

The format of the request body is as follows:

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

Request Parameters - Body

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

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/v4/datacenters/{dataCenterId}/servers/{serverId}/nics

Response

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

{
  "id" : "{nicId}",
  "type" : "nic",
  "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}",
  "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 Attributes

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

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

The metadata about the NIC includes:

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

The properties returned are:

Name Type Description
name string The name of the NIC.
mac string The MAC address of the NIC.
ips collection IPs assigned to the NIC represented as a collection.
dhcp boolean Boolean value that indicates if the NIC is using DHCP (true) or not (false).
lan int32 The LAN ID the NIC sits on.
nat boolean Boolean value indicating if the private IP address has outbound access to the public internet enabled (true) or not (false).
firewallActive boolean A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.

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

The entities returned include:

Name Type Description
firewallrules collection A collection of firewall rules associated with the NIC.

Delete a NIC

Deletes the specified NIC.

Request

To delete a NIC, send a DELETE request to https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

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/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}

Response

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

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

Update a NIC

The ProfitBrick's 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.

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

To perform a partial update to the NIC's properties, send a PATCH request to https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters

Name Required Type Description
name no string The name of the NIC.
ips no string collection IPs assigned to the NIC represented as a collection.
dhcp no 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/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}

Response

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

{
  "id" : "{nicId}",
  "type" : "nic",
  "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}",
  "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" : "{nicId}/firewallrules",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules"
    }
  }
}

Response Attributes

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

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

The metadata about the NIC includes:

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

The properties returned are:

Name Type Description
name string The name of the NIC.
mac string The MAC address of the NIC.
ips collection IPs assigned to the NIC represented as a collection.
dhcp boolean Boolean value that indicates if the NIC is using DHCP (true) or not (false).
lan int32 The LAN ID the NIC sits on.
nat boolean Boolean value indicating if the private IP address has outbound access to the public internet enabled (true) or not (false).
firewallActive boolean A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.

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

The entities returned include:

Name Type Description
firewallrules collection A collection of firewall rules associated with the NIC.

PUT

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

Request

To perform a full update of the NIC's properties, send a PUT request to: https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Body

Name Required Type Description
name yes string The name of the NIC.
ips yes string collection IPs assigned to the NIC represented as a collection.
dhcp yes boolean Boolean value that indicates if the NIC is using DHCP or not.
lan yes int32 The LAN ID the NIC sits on.
nat yes boolean Indicates if the private IP address has outbound access to the public internet.
firewallActive yes boolean 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/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}

Response

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

{
  "id" : "{nicId}",
  "type" : "nic",
  "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}",
  "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" : "{nicId}/firewallrules",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules"
    }
  }
}

Response Attributes

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

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

The metadata about the NIC includes:

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

The properties returned are:

Name Type Description
name string The name of the NIC.
mac string The MAC address of the NIC.
ips collection IPs assigned to the NIC represented as a collection.
dhcp boolean Boolean value that indicates if the NIC is using DHCP (true) or not (false).
lan int32 The LAN ID the NIC sits on.
nat boolean Boolean value indicating if the private IP address has outbound access to the public internet enabled (true) or not (false).
firewallActive boolean A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.

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

The entities returned include:

Name Type Description
firewallrules collection A collection of firewall rules associated with the NIC.

Firewall Rules

List Firewall Rules

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

Request

To retrieve a list of firewall rules submit a GET request to https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules.

Request Parameters - Path

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

Request Parameters - Header

The request headers may include the following:

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

Request Parameters - Query

The following query parameters may be included.

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

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

https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules?pretty=0

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

https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information about the firewall rules.

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/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules

Response

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

{
  "id" : "{nicId}/firewallrules",
  "type" : "collection",
  "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules",
  "items" : [ {
    "id" : "{firewallRuleId}",
    "type" : "firewall-rule",
    "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}"
  }, {
    "id" : "[another-firewall-rule-id]",
    "type" : "firewall-rule",
    "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/[another-firewall-rule-id]"
  } ]
}

Response Parameters

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

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

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

Get Firewall Rule

Retrieves the attributes of a specific firewall rule.

Request

To retrieve a specific firewall rule send a GET request to https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of the virtual data center.
{serverId} yes string n/a The ID of a server.
{nicId} yes string n/a The ID of a NIC.
{firewallRuleId} yes string n/a The ID of a firewall rule.

Request Parameters - Header

The request headers may include the following:

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

Request Parameters - Query

The following query parameters may be included.

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

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

https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}?pretty=0

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

https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}?depth=1

Note: For this particular operation, increasing the value supplied to depth will not return additional information about the firewall rules.

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/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}

Response

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

{
  "id" : "{firewallRuleId}",
  "type" : "firewall-rule",
  "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}",
  "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
  }
}

These attributes are found in the JSON response body:

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

The metadata returned for each firewall rule:

Name Type Description
createdDate string The date the firewall rule was created.
createdBy string The user who created the firewall rule.
etag string The ETag for the resource.
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
state string The firewall rule state. AVAILABLE, BUSY, INACTIVE

The properties returned for the firewall rule:

Name Type Description
name string The name of the firewall rule.
protocol string The protocol for the rule: TCP, UDP, ICMP, ANY.
sourceMac string Only traffic originating from the respective MAC address is allowed. Valid format: aa:bb:cc:dd:ee:ff. Value "null" allows all source MAC address.
sourceIp string Only traffic originating from the respective IPv4 address is allowed. Value "null" allows all source IPs.
targetIp string In case the target NIC has multiple IP addresses, only traffic directed to the respective IP address of the NIC is allowed. Value "null" allows all target IPs.
icmpType int32 Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value "null" allows all types.
icmpCode int32 Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value "null" allows all codes.
portRangeStart int32 Defines the start range of the allowed port (from 1 to 65534) if protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports.
portRangeEnd int32 Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports.

Create Firewall Rule

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

Request

To create a new firewall rule you would send a POST request to https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/[server-id}/nics/{nicId}/firewallrules

Request Parameters - Path

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

Request Parameters - Header

The request headers may include the following:

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

Request Body

The format of the request body is as follows:

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

Request Parameters - Body

Name Required Type Description
name no string A name for the firewall rule.
protocol yes string The protocol for the rule: TCP, UDP, ICMP, ANY.
sourceMac no string Only traffic originating from the respective MAC address is allowed. Valid format: aa:bb:cc:dd:ee:ff. A null value allows all source MAC addresses.
sourceIp no string Only traffic originating from the respective IPv4 address is allowed. A null value allows all source IPs.
targetIp no string In case the target NIC has multiple IP addresses, only traffic directed to the respective IP address of the NIC is allowed. Value null allows all target IPs.
icmpCode no int32 Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value null allows all codes.
icmpType no int32 Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value null allows all types.
portRangeStart no int32 Defines the start range of the allowed port (from 1 to 65534) if protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports.
portRangeEnd no int32 Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports.

Curl Example

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

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

Response

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

{
  "id" : "{firewallRuleId}",
  "type" : "firewall-rule",
  "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
},
  "properties" : {
    "name" : "AllowHTTP",
    "protocol" : "TCP",
    "sourceMac" : null,
    "sourceIp" : null,
    "targetIp" : null,
    "icmpCode" : null,
    "icmpType" : null,
    "portRangeStart" : 80,
    "portRangeEnd" : 80
  }
}

These attributes are found in the JSON response body:

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

The metadata returned for each firewall rule:

Name Type Description
createdDate string The date the firewall rule was created.
createdBy string The user who created the firewall rule.
etag string The ETag for the resource.
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
state string The firewall rule state. AVAILABLE, BUSY, INACTIVE

The properties returned for the firewall rule:

Name Type Description
name string The name of the firewall rule.
protocol string The protocol for the rule: TCP, UDP, ICMP, ANY.
sourceMac string Only traffic originating from the respective MAC address is allowed. Valid format: aa:bb:cc:dd:ee:ff. Value "null" allows all source MAC address.
sourceIp string Only traffic originating from the respective IPv4 address is allowed. Value "null" allows all source IPs.
targetIp string In case the target NIC has multiple IP addresses, only traffic directed to the respective IP address of the NIC is allowed. Value "null" allows all target IPs.
icmpType int32 Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value "null" allows all types.
icmpCode int32 Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value "null" allows all codes.
portRangeStart int32 Defines the start range of the allowed port (from 1 to 65534) if protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports.
portRangeEnd int32 Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports.

Delete Firewall Rule

Removes the specific firewall rule.

Request

To delete a firewall rule send a DELETE request to https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of the virtual data center.
{serverId} yes string n/a The ID of a server.
{nicId} yes string n/a The ID of a NIC.
{firewallRuleId} yes string n/a The ID of a firewall rule.

Request Parameters - Header

The request headers may include the following:

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

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/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}

Response

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

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

Update Firewall Rule

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

To perform a partial update to the firewall rule properties send a PATCH request to https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of the virtual data center.
{serverId} yes string n/a The ID of a server.
{nicId} yes string n/a The ID of a NIC.
{firewallRuleId} yes string n/a The ID of a firewall rule.

Request Parameters - Header

The request headers may include the following:

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

Request Body

The format of the request body is as follows:

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

Request Parameters - Body

Name Required Type Description
name no string A name for the firewall rule.
protocol -- string You cannot update the protocol of an existing firewall rule. If you need to change this, then delete and create a new firewall rule to replace the existing one.
sourceMac no string Only traffic originating from the respective MAC address is allowed. Valid format: aa:bb:cc:dd:ee:ff. A null value allows all source MAC addresses.
sourceIp no string Only traffic originating from the respective IPv4 address is allowed. A null value allows all source IPs.
targetIp no string In case the target NIC has multiple IP addresses, only traffic directed to the respective IP address of the NIC is allowed. Value null allows all target IPs.
icmpCode no int32 Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value null allows all codes.
icmpType no int32 Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value null allows all types.
portRangeStart no int32 Defines the start range of the allowed port (from 1 to 65534) if protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports.
portRangeEnd no int32 Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports.
Curl Example

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

curl --include \
     --request PATCH \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '    {
        "sourceMac": "01:98:22:22:44:22",
        "targetIp": "123.100.101.102"
    }" \
'https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}'

Response

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

{
  "id" : "{firewallRuleId}",
  "type" : "firewall-rule",
  "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}",
  "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
  }
}

These attributes are found in the JSON response body:

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

The metadata returned for each firewall rule:

Name Type Description
createdDate string The date the firewall rule was created.
createdBy string The user who created the firewall rule.
etag string The ETag for the resource.
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
state string The firewall rule state. AVAILABLE, BUSY, INACTIVE

The properties returned for the firewall rule:

Name Type Description
name string The name of the firewall rule.
protocol string The protocol for the rule: TCP, UDP, ICMP, ANY.
sourceMac string Only traffic originating from the respective MAC address is allowed. Valid format: aa:bb:cc:dd:ee:ff. Value "null" allows all source MAC address.
sourceIp string Only traffic originating from the respective IPv4 address is allowed. Value "null" allows all source IPs.
targetIp string In case the target NIC has multiple IP addresses, only traffic directed to the respective IP address of the NIC is allowed. Value "null" allows all target IPs.
icmpType int32 Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value "null" allows all types.
icmpCode int32 Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value "null" allows all codes.
portRangeStart int32 Defines the start range of the allowed port (from 1 to 65534) if protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports.
portRangeEnd int32 Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports.

PUT

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

Request

To perform a full update of the firewall rule's properties send a PUT request to: https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of the virtual data center.
{serverId} yes string n/a The ID of a server.
{nicId} yes string n/a The ID of a NIC.
{firewallRuleId} yes string n/a The ID of a firewall rule.

Request Parameters - Header

The request headers may include the following:

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

Request Body

The format of the request body is as follows:

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

Request Parameters - Body

Name Required Type Description
name no string A name for the firewall rule.
protocol -- string You cannot update the protocol of an existing firewall rule. If you need to change this, then delete and create a new firewall rule to replace the existing one.
sourceMac no string Only traffic originating from the respective MAC address is allowed. Valid format: aa:bb:cc:dd:ee:ff. A null value allows all source MAC addresses.
sourceIp no string Only traffic originating from the respective IPv4 address is allowed. A null value allows all source IPs.
targetIp no string In case the target NIC has multiple IP addresses, only traffic directed to the respective IP address of the NIC is allowed. Value null allows all target IPs.
icmpCode no int32 Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value null allows all codes.
icmpType no int32 Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value null allows all types.
portRangeStart no int32 Defines the start range of the allowed port (from 1 to 65534) if protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports.
portRangeEnd no int32 Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports.
Curl Example

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

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

Response

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

{
  "id" : "{firewallRuleId}",
  "type" : "firewall-rule",
  "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules/{firewallRuleId}",
  "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
  }
}

These attributes are found in the JSON response body:

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

The metadata returned for each volume:

Name Type Description
createdDate string The date the firewall rule was created.
createdBy string The user who created the firewall rule.
etag string The ETag for the resource.
lastModifiedDate string The last time the resource has been modified.
lastModifiedBy string The user who last modified the resource.
state string The firewall rule state. AVAILABLE, BUSY, INACTIVE

The properties returned for the firewall rule:

Name Type Description
name string The name of the firewall rule.
protocol string The protocol for the rule: TCP, UDP, ICMP, ANY.
sourceMac string Only traffic originating from the respective MAC address is allowed. Valid format: aa:bb:cc:dd:ee:ff. Value "null" allows all source MAC address.
sourceIp string Only traffic originating from the respective IPv4 address is allowed. Value "null" allows all source IPs.
targetIp string In case the target NIC has multiple IP addresses, only traffic directed to the respective IP address of the NIC is allowed. Value "null" allows all target IPs.
icmpType int32 Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value "null" allows all types.
icmpCode int32 Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value "null" allows all codes.
portRangeStart int32 Defines the start range of the allowed port (from 1 to 65534) if protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports.
portRangeEnd int32 Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd set to "null" to allow all ports.

Load Balancers

List Load Balancers

Retrieve a list of load balancers within the data center.

Request

To retrieve a list of load balancers, submit a GET request to https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/loadbalancers

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Query

The following optional query parameters may be included.

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

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

https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/loadbalancers?pretty=0

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

https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/loadbalancers?depth=1

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

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/v4/datacenters/{dataCenterId}/loadbalancers

Response

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

{
  "id" : "{dataCenterId}/loadbalancers",
  "type" : "collection",
  "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/loadbalancers",
  "items" : [ {
    "id" : "{loadBalancerId}",
    "type" : "loadbalancer",
    "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}"
  } ]
}

Response Attributes

The request will return a collection of load balancers.

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

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

Each of the returned items has these attributes:

Name Type Description
id string The load balancer's ID.
type string The type of object. In this case "loadbalancer".
href string URL to the object’s representation (absolute path).

If you append the ?depth=1 query parameter to the end of the request then more details are returned for each individual load balancer that is part of items. The additional details include metadata, properties, and entities. This is similar to issuing a GET request to each load balancer independently. Please see the next section for additional information.

Get Load Balancer

Retrieves the attributes of a given load balancer.

Request

To retrieve details about a specific load balancer send a GET request to https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Query

The following optional query parameters may be included.

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

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

https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}?pretty=0

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

https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}?depth=1

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

Curl Example

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

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

Response

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

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

Response Attributes

Name Type Description
id string The unique identifier.
type string The type of object that has been created.
href string URL to the object’s representation (absolute path).
metadata collection Various details about the LAN.
properties collection Properties of the LAN.
entities collection NICs that are part of the LAN.

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

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

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

Name Type Description
name string A descriptive name for the load balancer.
ip string The IP address assigned to the load balancer.
dhcp boolean Indicates if the load balancer is using DHCP to have an IP address assigned.

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

Name Type Description
balancednics collection A collection of NICs associated with the LAN.

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

Name Type Description
id string The NIC ID with "/nics" appended.
type string The type of object, in this case "collection".
href string A URL to access details about the NICs that are part of the LAN.

Increasing to depth=1 will return an additional items collection with each individual NIC that is part of balancednics listed.

Increasing to depth=2 will return even more details about each NIC that is part of nics. With depth=3 you'll get basic information about any firewall rules that are assigned to the NIC. At depth=4 you'll get detailed information about each firewall rule that is assigned to the NIC. Please take a look at the Network Interfaces section of this documentation for additional information.

Create Load Balancer

Creates a load balancer within the data center. Load balancers can be used for public or private IP traffic.

Request

To create a load balancer send a POST request to https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/loadbalancers

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Body

The format of the request body is as follows:

{
    "properties": {
        "name": "load-balancer-name",
        "ip": "load-balancer-ip",
        "dhcp": true
    },
      "entities": {
          "balancednics": []
    }
}

Request Parameters - Body

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

Curl Example

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

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

Response

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

{
  "id" : "{loadBalancerId}",
  "type" : "loadbalancer",
  "href" : "https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "ExampleLoadBalancer01",
    "ip" : null,
    "dhcp" : false
  }
}

Response Attributes

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

Name Type Description
id string The unique identifier.
type string The type of object that has been created.
href string URL to the object’s representation (absolute path).
metadata collection Various details about the LAN.
properties collection Properties of the LAN.
entities collection NICs that are part of the LAN.

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

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

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

Name Type Description
name string A descriptive name for the load balancer.
ip string The IP address assigned to the load balancer.
dhcp boolean Indicates if the load balancer is using DHCP to have an IP address assigned.

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

Name Type Description
balancednics collection A collection of NICs associated with the LAN.

Delete Load Balancer

Deletes the specified load balancer.

Request

To delete a load balancer send a DELETE request to https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

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/v4/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}

Response

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

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

Update Load Balancer

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 a load balancer.

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 load balancer using the above methods.

PATCH

Use PATCH to perform partial updates to attributes of a load balancer.

Request

To perform a partial update to the load balancer's properties you would send a PATCH request to https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Body

Name Required Type Description
name no string The name of the load balancer.
ip no string The IP of the load balancer.
dhcp no boolean Indicates if the load balancer will reserve an IP using DHCP.

Curl Example

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

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

Response Body

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

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

Name Type Description
id string The unique identifier.
type string The type of object that has been created.
href string URL to the object’s representation (absolute path).
metadata collection Various details about the LAN.
properties collection Properties of the LAN.
entities collection NICs that are part of the LAN.

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

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

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

Name Type Description
name string A descriptive name for the load balancer.
ip string The IP address assigned to the load balancer.
dhcp boolean Indicates if the load balancer is using DHCP to have an IP address assigned.

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

Name Type Description
balancednics collection A collection of NICs associated with the LAN.

PUT

Use PUT to perform a full update of all attributes of a load balancer.

Request

To perform a full update of the load balancer's properties send a PUT request to: https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Body

Name Required Type Description
name no string The name of the load balancer.
ip no string The IP of the load balancer.
dhcp no boolean Indicates if the load balancer will reserve an IP using DHCP.

Curl Example

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

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

Response

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

Response Attributes

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

Name Type Description
id string The unique identifier.
type string The type of object that has been created.
href string URL to the object’s representation (absolute path).
metadata collection Various details about the LAN.
properties collection Properties of the LAN.
entities collection NICs that are part of the LAN.

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

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

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

Name Type Description
name string A descriptive name for the load balancer.
ip string The IP address assigned to the load balancer.
dhcp boolean Indicates if the load balancer is using DHCP to have an IP address assigned.

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

Name Type Description
balancednics collection A collection of NICs associated with the LAN.

List Load Balanced NICs

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

Request

To retrieve a list of load balanced NICs submit a GET request to https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}/balancednics

Request Parameters - Path

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

Request Parameters - Header

The following request headers are available:

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

Request Parameters - Query

The following optional query parameters may be included.

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

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

https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}/balancednics?pretty=0

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

https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}/balancednics?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information beyond the default amount returned with a value of 0.

Curl Example

The following shows how to submit the GET request using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}/balancednics

Response

{
    "id": "{loadBalancerId}/balancednics",
    "type": "collection",
    "href": "[base-url]/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}/balancednics",
    "items": [
    {
        "id": "[nic-id]",
        "type": "nic",
        "href": "/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}",
        "metadata": {
            "lastModifiedDate": "last-modified-date",
            "lastModifiedBy": "last-modified-by",
            "createdDate": "created-date",
            "createdBy": "created-by",
            "state": "state",
            "etag": "etag"
            },
        "properties": {
            "name": "my-nic-name",
            "mac": "nic-mac",
            "nic-ip"
            ],
            "dhcp": "true",
            "lan": lan-id,
            "firewallActive": is-firewall-active
            },
        "entities": {
            "firewallrules": {
                "id": "{nic_id}/firewallrules",
                "type": "collection",
                "href": "/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}/firewallrules"
            }
      }
  }
  ]

}

Response Attributes

The request will return a collection of load balanced NICs.

The following table describes the attributes found in the response body:

Name Type Description
id string {serverId}/nics
type string The type of object that has been created. "collection"
href string URL to the object’s representation (absolute path).
items collection A collection of NICs.

The items will have the following attributes.

Name Type Description
id string The NIC's unique identifier.
type string The type of object. "nic"
href string An API URL to the NIC’s representation (absolute path).

If you appended ?depth=1 to the request to have more details returned, you will also get metadata, properties, and entities returned for each NIC in items.

The metadata about the NIC includes:

Name Type Description
createdDate string The date the resource was created.
createdBy string The user who created the resource.
etag string The ETag.
lastModifiedDate string The last modified time for the resource.
lastModifiedBy string The user who last modified the resource.
state string AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued. INACTIVE The resource has been de-provisioned.

The properties returned are:

Name Type Description
name string The name of the NIC.
mac string The MAC address of the NIC.
ips collection IPs assigned to the NIC represented as a collection.
dhcp boolean Boolean value that indicates if the NIC is using DHCP (true) or not (false).
lan int32 The LAN ID the NIC sits on.
nat boolean Boolean value indicating if the private IP address has outbound access to the public internet enabled (true) or not (false).
firewallActive boolean A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.

Please Note: The nat property is NOT available yet, but is Coming Soon.

The entities returned include:

Name Type Description
firewallrules collection A collection of firewall rules associated with the NIC.

Get Load Balanced NIC

Retrieves the attributes of a given load balanced NIC.

Request

To retrieve a single load balanced NIC you would send a GET request to https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}/balancednics/{nicId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a virtual data center.
{loadBalancerId} yes string n/a The ID of a load balancer.
{nicId} yes string n/a The ID of a NIC.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
PB-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}/balancednics/{nicId}?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}/balancednics/{nicId}?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information beyond the default amount returned with a value of 0.

Curl Example

The following shows you how to submit the GET request using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
https://api.profitbricks.com/cloudapi/v4/datacenters/data-center-id]/loadbalancers/{loadBalancerId}/balancednics/{nicId}

Response

{
    "id": "[nic-id]",
    "type": "nic",
    "href": "/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}",
    "metadata": {
        "lastModifiedDate": "last-modified-date",
        "lastModifiedBy": "last-modified-by-user",
        "createdDate": "created-date",
        "createdBy": "created-by-user",
        "state": "nic-state",
        "etag": "etag"
    },
    "properties": {
        "name": "nic-name",
        "mac": "nic-mac",
        "ips": nic-ip-collection,
        "dhcp": "nic-dhcp-bool",
        "lan": nic-lan,
        "firewallActive": firewall-active-status
    },
    "entities": {
        "firewallrules": []
    }
}

Response Attributes

The following table describes the attributes found in the JSON response body:

Name Type Description
id string The NIC's unique identifier.
type string The type of object. "nic"
href string An API URL to the NIC’s representation (absolute path).
metadata collection NIC metadata.
properties collection NIC properties.
entities collection NIC entities. "firewallrules"

The metadata about the NIC includes:

Name Type Description
createdDate string The date the resource was created.
createdBy string The user who created the resource.
etag string The ETag.
lastModifiedDate string The last modified time for the resource.
lastModifiedBy string The user who last modified the resource.
state string AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued. INACTIVE The resource has been de-provisioned.

The properties returned are:

Name Type Description
name string The name of the NIC.
mac string The MAC address of the NIC.
ips collection IPs assigned to the NIC represented as a collection.
dhcp boolean Boolean value that indicates if the NIC is using DHCP (true) or not (false).
lan int32 The LAN ID the NIC sits on.
nat boolean Boolean value indicating if the private IP address has outbound access to the public internet enabled (true) or not (false).
firewallActive boolean A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.

Please Note: The nat property is NOT available yet, but is Coming Soon.

The entities returned include:

Name Type Description
firewallrules collection A collection of firewall rules associated with the NIC.

If you appended ?depth=1 to the request to retrieve more details, you will get additional information about the firewallrules.

Associate NIC to Load Balancer

This will associate a NIC to a Load Balancer, enabling the NIC to participate in load-balancing.

Request

To associate a NIC with a load balancer you would send a POST request to `https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}/balancednics``

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a virtual data center.
{loadBalancerId} yes string n/a The ID of a load balancer.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
PB-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.
Content-Type Yes string n/a Set this to "application/json".

Request Parameters - Body

Name Required Type Description
id yes string The UUID of the NIC.

The format of the request body is as follows:

{
    id": "{nicId}"
}

Curl Example

The following shows how to submit the POST request using curl:

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary "{
        \"id\": \"[nic-id]\"
        }" \
'https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}/balancednics'

Response

{
    "id": "[nic-id]",
    "type": "nic",
    "href": "/datacenters/{dataCenterId}/servers/{serverId}/nics/{nicId}",
    "metadata": {
        "lastModifiedDate": "last-modified-date",
        "lastModifiedBy": "last-modified-by-user",
        "createdDate": "created-date",
        "createdBy": "created-by-user",
        "state": "nic-state",
        "etag": "etag"
    },
    "properties": {
        "name": "nic-name",
        "mac": "nic-mac",
        "ips": [nic-ip-collection],
        "dhcp": "nic-dhcp-bool",
        "lan": nic-lan,
        "firewallActive": true
    },
    "entities": {
        "firewallrules": []
    }
}

Response Attributes

The following table describes the attributes found in the response body:

Name Type Description
id string The NIC's unique identifier.
type string The type of object. "nic"
href string An API URL to the NIC’s representation (absolute path).
metadata collection NIC metadata.
properties collection NIC properties.
entities collection NIC entities. "firewallrules"

The metadata about the NIC includes:

Name Type Description
createdDate string The date the resource was created.
createdBy string The user who created the resource.
etag string The ETag.
lastModifiedDate string The last modified time for the resource.
lastModifiedBy string The user who last modified the resource.
state string AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued. INACTIVE The resource has been de-provisioned.

The properties returned are:

Name Type Description
name string The name of the NIC.
mac string The MAC address of the NIC.
ips collection IPs assigned to the NIC represented as a collection.
dhcp boolean Boolean value that indicates if the NIC is using DHCP (true) or not (false).
lan int32 The LAN ID the NIC sits on.
nat boolean Boolean value indicating if the private IP address has outbound access to the public internet enabled (true) or not (false).
firewallActive boolean A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.

Please Note: The nat property is NOT available yet, but is Coming Soon.

The entities returned include:

Name Type Description
firewallrules collection A collection of firewall rules associated with the NIC.

Remove a NIC Association

Removes the association of a NIC with a load balancer.

Request

To remove a NIC association send a DELETE request to https://api.profitbricks.com/cloudapi/v4/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId]/balancednics/{nicId}

Request Parameters - Path

Parameter Required Type Default Description
{dataCenterId} yes string n/a The ID of a virtual data center.
{loadBalancerId} yes string n/a The ID of a load balancer.
{nicId} yes string n/a The ID of a NIC.

Request Parameters - Header

The following request headers are available:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
PB-Contract-Number no integer n/a Users with more than one contract may supply this header to indicate the applicable contract.

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/v4/datacenters/{dataCenterId}/loadbalancers/{loadBalancerId}/balancednics/{nicId}

Response

Status: 202 (Accepted)

There is no JSON response body returned with a successful DELETE request.

Requests

List Requests

This operation allows you to retrieve a list of requests. Cloud API calls generate a request which is assigned an id. This "request id" can be used to get information about the request and its current status. The "list request" operation described here will return an array of request items. Each returned request item will have an id that can be used to get additional information as described in the Get Request and Get Request Status sections.

Request

To retrieve a list of requests you would send a GET request to https://api.profitbricks.com/cloudapi/v4/requests

Request Parameters - Header

The request headers may include the following:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
PB-Contract-Number no int32 n/a Users with more than one contract can supply this header to indicate the applicable contract.

Request Parameters - Query

The following query parameters may be included.

Parameter Type Default Description
pretty boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.profitbricks.com/cloudapi/v4/requests?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.profitbricks.com/cloudapi/v4/requests?depth=1

Note: For this particular operation, increasing the value supplied to depth will not return additional information about the requests.

Curl Example

The following shows you how to submit a GET request for /requests via curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/cloudapi/v4/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/v4/requests",
  "items" : [ {
    "id" : "{requestId}",
    "type" : "request",
    "href" : "https://api.profitbricks.com/cloudapi/v4/requests/{requestId}"
  } ]
}

Response Body

The request will return a collection of requests.

The following table describes the attributes found in the JSON response body:

Name Type Description
id string "requests"
type string The type of object, which should be "collection" here.
href string URL to the object’s representation (absolute path).
items collection A collection of individual "request" items.

Each of the items returned will have the following attributes:

Name Type Description
id string The request's ID.
type string The type of object, which should be "request" here.
href string URL to the object’s representation (absolute path).

Get Request

Retrieves the attributes of a specific request based on the supplied request id.

Request

To retrieve details on a specific request you would send a GET request to https://api.profitbricks.com/cloudapi/v4/requests/{requestId}

Request Parameters - Path

Parameter Required Type Default Description
{requestId} yes string n/a The ID of a request.

Request Parameters - Header

The request headers may include the following:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
PB-Contract-Number no int32 n/a Users with more than one contract can supply this header to indicate the applicable contract.

Request Parameters - Query

The following query parameters may be included.

Parameter Type Default Description
pretty boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.profitbricks.com/cloudapi/v4/requests?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.profitbricks.com/cloudapi/v4/requests?depth=1

Note: For this particular operation, increasing the value supplied to depth will not return additional information about the requests.

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/v4/requests/{requestId}

Response

HTTP/1.1 200 OK
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: [date]
X-RateLimit-Remaining: 299
X-RateLimit-Burst: 300
X-RateLimit-Limit: 600
ETag: [etag]
Content-Type: application/json
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{requestId}",
  "type" : "request",
  "href" : "https://api.profitbricks.com/cloudapi/v4/requests/{requestId}",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "requestStatus" : {
      "id" : "[reuest-id]/status",
      "type" : "request-status",
      "href" : "https://api.profitbricks.com/cloudapi/v4/requests/{requestId}/status"
    }
},

The contents of "properties" returned will vary considerably depending on what the original request was. This is an example of what would be returned for a POST request:

  "properties" : {
    "method" : "POST",
    "headers" : {
      "content-type" : "application/json",
      "connection" : "Keep-Alive",
      "host" : "api.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/v4/datacenters"
  }
}

Response Body

The following table describes the attributes found in the JSON response body:

Name Type Description
id string The ID of the specific request.
type string The type of object, which should be "request" here.
href string URL to the object’s representation (absolute path).
metadata collection A collection of metadata about the request.
properties collection A collection of properties related to the request.

The metadata returned will have the following attributes:

Name Type Description
createdDate string The date the request was created.
createdBy string The username that created the request.
etag string The etag.
requestStatus collection Information on the request-status.

The requestStatus collection will contain:

Name Type Description
id string The ID of the specific "request" with "/status" appended.
type string The type of object, which should be "request-status" here.
href string URL to the object’s representation (absolute path). Can be used to retrieve the status of the request.

The properties collection should contain:

Name Type Description
method string The request method. [GET, POST, PATCH, PUT, DELETE]
headers collection The HTTP headers that were submitted with the request.
body string The body that was submitted with the request. Usually JSON, but some API requests are URL encoded.
url string The URL used to make the request.

The headers and body returned in properties will differ considerably depending on the original request.

Once you have determined the type of request based on the returned properties, you can refer to the appropriate section of the Cloud API documentation for details.

Get Request Status

Retrieves the status of a specific request based on the supplied request id.

Request

To retrieve the status of a specific request send a GET request to https://api.profitbricks.com/cloudapi/v4/requests/{requestId}/status

Request Parameters - Path

Parameter Required Type Default Description
{requestId} yes string n/a The ID of a request.

Request Parameters - Header

The request headers may include the following:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
PB-Contract-Number no int32 n/a Users with more than one contract can supply this header to indicate the applicable contract.

Request Parameters - Query

The following query parameters may be included.

Parameter Type Default Description
pretty boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.profitbricks.com/cloudapi/v4/requests/{requestId}/status?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.profitbricks.com/cloudapi/v4/requests/{requestId}/status?depth=1

Note: For this particular operation, increasing the value supplied to depth will not return additional information about the requests.

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/v4/requests/{requestId}/status

Response

The following is an example status request response when the specific request has completed:

HTTP/1.1 200 OK
Date: [date]
Server: ""
Pragma: No-cache
Cache-Control: no-cache
Expires: [date]
X-RateLimit-Remaining: 299
X-RateLimit-Burst: 300
X-RateLimit-Limit: 600
Content-Type: application/json
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "{requestId}/status",
  "type" : "request-status",
  "href" : "https://api.profitbricks.com/cloudapi/v4/requests/{requestId}/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/v4/datacenters/{datacenterId}"
      },
      "status" : "DONE"
    } ]
  }
}

Response Attributes

The following table describes the attributes found in the JSON response body:

Name Type Description
id string The ID of the specific request with "/status" appended.
type string The type of object, which should be "request-status" here.
href string URL to the object’s representation (absolute path).
metadata collection A collection of metadata about the request's status.

The metadata returned will have the following attributes:

Name Type Description
status string The overall status of the request. [QUEUED, RUNNING, DONE, or FAILED]
message string The username that created the request.
etag string The etag.
targets collection An array of "sub-requests" related to the request. For example, a create server request could involve multiple requests for creating the server, a volume, and a NIC. These sub-requests and their status will be returned in this section of the response.

The targets collection will contain:

Name Type Description
target array Information about a specific "sub-request" related to the request.
status string The status of the request for this specific target. [QUEUED, RUNNING, DONE, or FAILED]

Each target will contain:

Name Type Description
id string The ID of the object or resource involved in the operation.
type string The type of object.
href string URL to the object’s representation (absolute path). Not always available, so it can be a string such as "TO_BE_INJECTED"

Contract Resources

Checking the amount of available resources under a contract can help you to avoid provisioning errors resulting from the attempt to provision more resources than are available.

List Contract Resources

Returns information about the resource limits for a particular contract and the current resource usage.

Request

Submit a GET request to https://api.profitbricks.com/cloudapi/v4/contracts

Request Parameters - Header

The request headers may include the following:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
PB-Contract-Number no integer n/a Users with more than one contract can supply this header to indicate the applicable contract.

Request Parameters - Query

The following optional query parameters may be included.

Parameter Type Default Description
pretty boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.profitbricks.com/cloudapi/v4/contracts?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.profitbricks.com/cloudapi/v4/contracts?depth=1

Note: For this particular operation, increasing the value supplied to depth does NOT return any additional information beyond the default amount returned with a value of 0.

Curl Example

The following shows how to submit the GET /contracts request using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
 https://api.profitbricks.com/cloudapi/v4/contracts

Response

The amount of data included in the response payload will vary slightly depending on the credentials supplied when making the request. If the credentials supplied belong to the "Contract Owner", then all the available information is returned.

{
  "type": "contract",
  "properties": {
    "PB-Contract-Number": 12345678,
    "owner": "test@domain.com",
    "status": "BILLABLE",
    "resourceLimits": {
      "coresPerServer": 20,
      "coresPerContract": 30,
      "coresProvisioned": 0,
      "ramPerServer": 204800,
      "ramPerContract": 3072000,
      "ramProvisioned": 0,
      "hddLimitPerVolume": 2048000,
      "hddLimitPerContract": 3072000,
      "hddVolumeProvisioned": 0,
      "ssdLimitPerVolume": 2048000,
      "ssdLimitPerContract": 3072000,
      "ssdVolumeProvisioned": 0,
      "reservableIps": 3,
      "reservedIpsOnContract": 0,
      "reservedIpsInUse": 0
    }
  }
}

If the request is made by a user with valid credentials that is NOT the "Contract Owner", then a sub-set of information is returned.

{
  "type": "contract",
  "properties": {
    "PB-Contract-Number": 12345678,
    "owner": "test@domain.com",
    "status": "BILLABLE",
    "resourceLimits": {
      "coresPerContract": 30,
      "ramPerContract": 3072000,
      "hddLimitPerContract": 3072000,
      "ssdLimitPerContract": 3072000
    }
  }
}

The following table describes each of the response attributes.

Name Type Description
type string The type of response, in this case it will be contract
properties collection A collection of properties for each item.

The following table describes the properties returned in the response.

Name Type Description
PB-Contract-Number int64 The contract number that the returned information is from.
owner string The username of the "Contract Owner".
status string The status of the contract. [ BILLABLE...]
resourceLimits collection An object containing the contract's resource limits.

The following table describes the resourceLimits returned as part of properties.

Name Type Example Description
coresPerContract int32 20 Maximum number of CPU cores per contract.
coresPerServer int32 4 Maximum number of CPU cores per server.
coresProvisioned int32 4 The total number of CPU cores that have been provisioned.
hddLimitPerContract int64 3072000 The maximum amount of hard disk space (in MB) that may be provisioned under this contract.
hddLimitPerVolume int64 2048000 The maximum size (in MB) of an individual hard disk volume.
hddVolumeProvisioned int64 1024000 The amount of hard disk space (in MB) that is currently provisioned.
ramPerContract int32 3072000 The maximum amount of RAM (in MB) that may be provisioned under this contract.
ramPerServer int32 204800 The maximum amount of RAM (in MB) that may be provisioned for a particular server under this contract.
ramProvisioned int32 102400 The amount of RAM (in MB) that has been provisioned under this contract.
reservableIps int32 128 The maximum number of static public IP addresses that may be reserved by this customer across all contracts.
reservedIpsInUse int32 6 The number of static public IP addresses that have been reserved.
reservedIpsOnContract int32 32 The maximum number of static public IP addresses that can be reserved under this contract.
ssdLimitPerContract int64 2048000 The maximum amount of solid state disk space (in MB) that may be provisioned under this contract.
ssdLimitPerVolume int64 1024000 The maximum size (in MB) of an individual solid state disk volume.
ssdVolumeProvisioned int64 512000 The amount of solid state disk space (in MB) that is currently provisioned.

User Management

These operations are designed to allow you to orchestrate users and resources via the Cloud API. Previously this functionality required use of the DCD (Data Center Designer) web application.

List Groups

This retrieves a full list of all groups.

Request

Submit a GET request to https://api.profitbricks.com/cloudapi/v4/um/groups

Request Parameters - Header

The request headers may include the following:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
PB-Contract-Number no integer n/a Users with more than one contract can supply this header to indicate the applicable contract.

Request Parameters - Query

The following query parameters may be included.

Parameter Type Default Description
pretty boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.profitbricks.com/cloudapi/v4/um/groups?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.profitbricks.com/cloudapi/v4/um/groups?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information about the privileges of a group, the group members, and associated resources.

Curl Example

The following shows how to submit the GET /um/groups request using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
 https://api.profitbricks.com/cloudapi/v4/um/groups/

Response Body

{
    "id": "groups",
    "type": "collection",
    "href": "https://api.profitbricks.com/cloudapi/v4/um/groups",
    "items": [
    {
        "id": "7fcc6d14-2d81-4bfe-a6dc-XXXXXXXXXXXX",
        "type": "group",
        "href": "https://api.profitbricks.com/cloudapi/v4/um/groups/7fcc6d14-2d81-4bfe-a6dc-XXXXXXXXXXXX"
    },
    {
        "id": "e1cb1f6d-eea1-409e-b2c0-XXXXXXXXXXXX",
        "type": "group",
        "href": "https://api.profitbricks.com/cloudapi/v4/um/groups/e1cb1f6d-eea1-409e-b2c0-XXXXXXXXXXXX"
    },
    {
        "id": "ad1aff06-513d-480f-ad27-XXXXXXXXXXXX",
        "type": "group",
        "href": "https://api.profitbricks.com/cloudapi/v4/um/groups/ad1aff06-513d-480f-ad27-XXXXXXXXXXXX"
    },
    {
        "id": "ed6ec36d-e35b-402a-9ed7-XXXXXXXXXXXX",
        "type": "group",
        "href": "https://api.profitbricks.com/cloudapi/v4/um/groups/ed6ec36d-e35b-402a-9ed7-XXXXXXXXXXXX"
    },
    {
        "id": "9e2cbcb6-7fca-4a3f-892c-XXXXXXXXXXXX",
        "type": "group",
        "href": "https://api.profitbricks.com/cloudapi/v4/um/groups/9e2cbcb6-7fca-4a3f-892c-XXXXXXXXXXXX"
    }
    ]
}

Response Attributes

The response will contain metadata, group properties, and group entities as described below.

Name Type Description
id string "groups"
type string The type of response, in this case it will be "collection".
href string A URI for accessing the object. "um/groups"
items collection A collection of groups.

At the default depth value of 0, each of the items contains the following information:

Name Type Description
id string The group's identifier.
type string The type of response, in this case it will be "group".
href string A URI for accessing the group.

If a depth value of 1 is passed in as a query parameter, then the response will include details about each item as outlined in these tables.

Name Type Description
id string The group's identifier.
type string The type of response, in this case it will be "group".
href string A URI for accessing the group.
properties collection A list of group properties.
entities collection A collection of entities (users and resources) that are part of the group.

These are the properties that may be returned.

Name Type Description
name string A name that was given to the group.
createDataCenter boolean The group has permission to create virtual data centers.
createSnapshot boolean The group has permission to create snapshots.
reserveIp boolean The group has permission to reserve IP addresses.
accessActivityLog boolean The group has permission to access the activity log.

These are the entities that may be returned.

Name Type Description
users collection A collection of users that are part of the group.
resources collection A collection of resources that are part of the group.

When queried with depth=1, then the users and resources entities will return this information:

Name Type Description
id string The group's identifier with /users or /resources appended.
type string The type of response, in this case it will be "collection".
href string A URL for directly accessing the object.

At depth=2 or greater, then additional information is returned in an items collection for each of the users or resources.

Retrieve a Group

Retrieves detailed information about a specific group.

Request

Submit a GET request to https://api.profitbricks.com/cloudapi/v4/um/groups/{groupId}

Request Parameters - Path

Parameter Required Type Default Description
{groupId} yes string n/a The ID of the specific group to retrieve.

Request Parameters - Header

The request headers may include the following:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
PB-Contract-Number no integer n/a Users with more than one contract can supply this header to indicate the applicable contract.

Request Parameters - Query

The following query parameters may be included.

Parameter Type Default Description
pretty boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.profitbricks.com/cloudapi/v4/um/groups/{groupId}?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.profitbricks.com/cloudapi/v4/um/groups/{groupId}?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information about the privileges of a group, its members, and associated resources.

Curl Example

The following shows how to submit the GET /um/groups/{groupId} request using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
https://api.profitbricks.com/cloudapi/v4/um/groups/20a8e4c1-03d4-48e2-8334-XXXXXXXXXXXX

Response Body

{
  "id": "20a8e4c1-03d4-48e2-8334-XXXXXXXXXXXX",
  "type": "group",
  "href": "https://api.profitbricks.com/cloudapi/v4/um/groups/20a8e4c1-03d4-48e2-8334-XXXXXXXXXXXX",
  "properties": {
    "name": "Super Admins",
    "createDataCenter": true,
    "createSnapshot": true,
    "reserveIp": true,
    "accessActivityLog": true
  },
  "entities": {
    "users": {
      "id": "20a8e4c1-03d4-48e2-8334-XXXXXXXXXXXX/users",
      "type": "collection",
      "href": "https://api.profitbricks.com/cloudapi/v4/um/groups/20a8e4c1-03d4-48e2-8334-XXXXXXXXXXXX/users"
    },
    "resources": {
      "id": "20a8e4c1-03d4-48e2-8334-XXXXXXXXXXXX/resources",
      "type": "collection",
      "href": "https://api.profitbricks.com/cloudapi/v4/um/groups/20a8e4c1-03d4-48e2-8334-XXXXXXXXXXXX/resources"
    }
  }
}

The JSON response will contain the group properties and entities associated with the group.

Response Attributes

Name Type Description
id string The group's identifier.
type string The type of response, in this case it will be "group".
href string A URI for accessing the object.
properties collection A collection containing the group's properties.
entities collection A collection containing users and resources associated with the group.

The properties collection includes these attributes:

Name Type Description
name string A name that was given to the group.
createDataCenter boolean The group has permission to create virtual data centers.
createSnapshot boolean The group has permission to create snapshots.
reserveIp boolean The group has permission to reserve IP addresses.
accessActivityLog boolean The group has permission to access the activity log.

The entities collection includes these attributes:

Name Type Description
users collection A collection of users that belong to this group.
resources collection A collection of resources that are assigned to this group.

Each of the users or resources will include the following attributes.

Name Type Description
id string The group's identifier with /users or /resources appended.
type string The type of response, in this case it will be "collection".
href string A URL for directly accessing the object.

At depth=1 additional information is returned in an items collection for each of the users or resources.

At depth=2 or greater, then additional metadata, properties, and entities are returned for each of the items.

Create a Group

Use this operation to create a new group and set group privileges.

Request

Submit a POST request to https://api.profitbricks.com/cloudapi/v4/um/groups

Request Parameters - Header

The request headers may include the following:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
PB-Contract-Number no integer n/a Users with more than one contract can supply this header to indicate the applicable contract.
Content-Type yes string n/a Set to "application/json"

Request Parameters - Body

The JSON encoded request body may contain the following attributes:

Name Required Type Default Description
name yes string n/a A name for the group.
createDataCenter no boolean false The group will be allowed to create virtual data centers.
createSnapshot no boolean false The group will be allowed to create snapshots.
reserveIp no boolean false The group will be allowed to reserve IP addresses.
accessActivityLog no boolean false The group will be allowed to access the activity log.

Curl Example

The following shows how to submit a POST request to /um/groups using curl:

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '{
         "properties": {
             "name": "Super Admins",
             "createDataCenter": true,
             "createSnapshot": true,
             "reserveIp": true,
             "accessActivityLog": true
         }
    }' \
https://api.profitbricks.com/cloudapi/v4/um/groups

Response Body

{
  "id": "20a8e4c1-03d4-48e2-8334-XXXXXXXXXXXX",
  "type": "group",
  "href": "https://api.profitbricks.com/cloudapi/v4/um/groups/20a8e4c1-03d4-48e2-8334-XXXXXXXXXXXX",
  "properties": {
    "name": "Super Admins",
    "createDataCenter": true,
    "createSnapshot": true,
    "reserveIp": true,
    "accessActivityLog": true
  }
}

Response Attributes

Name Type Description
id string The new group's identifier.
type string The type of response, in this case it will be "group".
href string A URI for accessing the object.
properties collection A collection containing the group's properties.
entities collection A collection containing users and resources associated with the group.

The properties collection includes these attributes:

Name Type Description
name string A name that was given to the group.
createDataCenter boolean The group has permission to create virtual data centers.
createSnapshot boolean The group has permission to create snapshots.
reserveIp boolean The group has permission to reserve IP addresses.
accessActivityLog boolean The group has permission to access the activity log.

Update a Group

Use this operation to update a group.

Submit a PUT request to https://api.profitbricks.com/cloudapi/v4/um/groups/{groupId}

Request Parameters - Path

Parameter Required Type Default Description
{groupId} yes string n/a The ID of the specific group to update.

Request Parameters - Header

The request headers may include the following:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
PB-Contract-Number no integer n/a Users with more than one contract can supply this header to indicate the applicable contract.
Content-Type yes string n/a Set to "application/json"

Request Parameters - Body

Construct your JSON request body by specifying the attributes you want to update. Normally a PUT request would require that you pass all the attributes and values. In this implementation, you must supply the name, even if it isn't being changed. As a convenience, the other four attributes will default to false. You should explicitly set them to true if you want to have them enabled.

Name Required Type Default Description
name yes string n/a A name for the group.
createDataCenter no boolean false The group will be allowed to create virtual data centers.
createSnapshot no boolean false The group will be allowed to create snapshots.
reserveIp no boolean false The group will be allowed to reserve IP addresses.
accessActivityLog no boolean false The group will be allowed to access the activity log.

Curl Example

The following shows how to submit the PUT request to /um/groups/{groupId} using curl:

curl --include \
     --request PUT \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '{
         "properties": {
             "name": "Amazing Admins",
             "accessActivityLog": true
         }
     }' \
https://api.profitbricks.com/cloudapi/v4/um/groups/20a8e4c1-03d4-48e2-8334-XXXXXXXXXXXX

Response Body

{
  "id": "20a8e4c1-03d4-48e2-8334-XXXXXXXXXXXX",
  "type": "group",
  "href": "https://api.profitbricks.com/cloudapi/v4/um/groups/20a8e4c1-03d4-48e2-8334-XXXXXXXXXXXX",
  "properties": {
    "name": "Amazing Admins",
    "createDataCenter": false,
    "createSnapshot": false,
    "reserveIp": false,
    "accessActivityLog": true
  },
  "entities": {
    "users": {
      "id": "20a8e4c1-03d4-48e2-8334-XXXXXXXXXXXX/users",
      "type": "collection",
      "href": "https://api.profitbricks.com/cloudapi/v4/um/groups/20a8e4c1-03d4-48e2-8334-XXXXXXXXXXXX/users"
    },
    "resources": {
      "id": "20a8e4c1-03d4-48e2-8334-XXXXXXXXXXXX/resources",
      "type": "collection",
      "href": "https://api.profitbricks.com/cloudapi/v4/um/groups/20a8e4c1-03d4-48e2-8334-XXXXXXXXXXXX/resources"
    }
  }
}

Response Attributes

Name Type Description
id string The group's identifier.
type string The type of response, in this case it will be "group".
href string A URI for accessing the object.
properties collection A collection containing the group's properties.
entities collection A collection containing users and resources associated with the group.

The properties collection includes these attributes:

Name Type Description
name string A name that was given to the group.
createDataCenter boolean The group has permission to create virtual data centers.
createSnapshot boolean The group has permission to create snapshots.
reserveIp boolean The group has permission to reserve IP addresses.
accessActivityLog boolean The group has permission to access the activity log.

The entities collection includes these attributes:

Name Type Description
users collection A collection of users that belong to this group.
resources collection A collection of resources that are assigned to this group.

Each of the users or resources will include the following attributes.

Name Type Description
id string The group's identifier with /users or /resources appended.
type string The type of response, in this case it will be "collection".
href string A URL for directly accessing the object.

Delete a Group

Use this operation to delete a single group. Resources that are assigned to the group are NOT deleted, but are no longer accessible to the group members unless the member is a Contract Owner, Admin, or Resource Owner.

Submit a DELETE request to https://api.profitbricks.com/cloudapi/v4/um/groups/{groupId}

Request Parameters - Path

Parameter Required Type Default Description
{groupId} yes string n/a The ID of the specific group to delete.

Request Parameters - Header

The request headers may include the following:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
PB-Contract-Number no integer n/a Users with more than one contract can supply this header to indicate the applicable contract.

Curl Example

The following shows how to submit the DELETE /um/groups/{groupId} request using curl:

curl --include \
     --request DELETE \
     --user 'username@domain.tld:password' \
https://api.profitbricks.com/cloudapi/v4/um/groups/20a8e4c1-03d4-48e2-8334-XXXXXXXXXXXX

Response

Status 202 - "successful operation" is returned. There is no additional JSON response.

List Shares

Retrieves a full list of all the resources that are shared through this group and lists the permissions granted to the group members for each shared resource.

Request

Submit a GET request to https://api.profitbricks.com/cloudapi/v4/um/groups/{groupId}/shares

Request Parameters - Path

Parameter Required Type Default Description
{groupId} yes string n/a The ID of a specific group.

Request Parameters - Header

The request headers may include the following:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
PB-Contract-Number no integer n/a Users with more than one contract can supply this header to indicate the applicable contract.

Request Parameters - Query

The following query parameters may be included.

Parameter Type Default Description
pretty boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.profitbricks.com/cloudapi/v4/um/groups/{groupId}/shares?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.profitbricks.com/cloudapi/v4/um/groups/{groupId}/shares?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information.

Curl Example

The following shows how to submit the GET request to um/groups/{groupId}/shares using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
https://api.profitbricks.com/cloudapi/v4/um/groups/059c4d71-f97a-4bfd-b3a5-XXXXXXXXXXXX/shares

Response Body

{
  "id": "059c4d71-f97a-4bfd-b3a5-XXXXXXXXXXXX/shares",
  "type": "collection",
  "href": "https://api.profitbricks.com/cloudapi/v4/um/groups/059c4d71-f97a-4bfd-b3a5-XXXXXXXXXXXX/shares",
  "items": []
}

Response Attributes

Name Type Description
id string The group's identifier.
type string The type of response, in this case it will be "collection".
href string A URI for accessing the object. "baseurl/um/groups/{groupId}/shares"
items collection A collection containing the shared items.

At the default depth=0 each of the items has the following attributes:

Name Type Description
id string The share identifier.
type string The type of response, in this case it will be "resource".
href string A URI for accessing the object. "baseurl/um/groups/{groupId}/shares/{shareId}"

At depth=1 each of the items will include an additional properties collection. This will be described in the next section.

Retrieve a Share

Retrieves the details of a specific shared resource available to the specified group.

Request

Submit a GET request to https://api.profitbricks.com/cloudapi/v4/um/groups/{groupId}/shares/{resourceId}

Request Parameters - Path

Parameter Required Type Default Description
{groupId} yes string n/a The ID of the specific group to retrieve.
{resourceId} yes string n/a The ID of the specific resource to retrieve.

Request Parameters - Header

The request headers may include the following:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
PB-Contract-Number no integer n/a Users with more than one contract can supply this header to indicate the applicable contract.

Request Parameters - Query

The following query parameters may be included.

Parameter Type Default Description
pretty boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.profitbricks.com/cloudapi/v4/um/groups/{groupId}/shares/{resourceId}?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.profitbricks.com/cloudapi/v4/um/groups/{groupId}/shares/{resourceId}?depth=1

Note: For this particular operation, increasing the value supplied to depth will not return additional information.

Curl Example

The following shows how to submit the GET request to /um/groups/{groupId}/shares/{resourceId} using curl:

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
https://api.profitbricks.com/cloudapi/v4/um/groups/e1cb1f6d-eea1-409e-b2c0-XXXXXXXXXXXX/shares/c32f1873-502a-11e5-bfc6-XXXXXXXXXXXX

Response Body

{
  "id": "c32f1873-502a-11e5-bfc6-XXXXXXXXXXXX",
  "type": "resource",
  "href": "https://api.profitbricks.com/cloudapi/v4/um/groups/e1cb1f6d-eea1-409e-b2c0-XXXXXXXXXXXX/shares/c32f1873-502a-11e5-bfc6-XXXXXXXXXXXX",
  "properties": {
    "editPrivilege": false,
    "sharePrivilege": false
  }
}

Response Attributes

Name Type Description
id string The identifier.
type string The type of response.
href string A URI for accessing the object.
properties collection A collection of properties.

The properties collection should contain these attributes:

Name Type Description
editPrivilege boolean The group has permission to edit privileges on this resource.
sharePrivilege boolean The group has permission to share this resource.

Add a Share

Adds a specific resource share to a group and optionally allows the setting of permissions for that resource. As an example, you might use this to grant permissions to use an image or snapshot to a specific group.

Request

Submit a POST request to https://api.profitbricks.com/cloudapi/v4/um/groups/{groupId}/shares/{resourceId}

Request Parameters - Path

Parameter Required Type Default Description
{groupId} yes string n/a The ID of the specific group to add a resource too.
{resourceId} yes string n/a The ID of the specific resource to add.

Request Parameters - Header

The request headers may include the following:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
PB-Contract-Number no integer n/a Users with more than one contract can supply this header to indicate the applicable contract.
Content-Type yes string n/a Set to "application/json"

Request Parameters - Body

The JSON encoded request body may contain the following information:

Name Required Type Default Description
editPrivilege no boolean false The group has permission to edit privileges on this resource.
sharePrivilege no boolean false The group has permission to share this resource.

If you choose to NOT provide a JSON request body, then the {resourceId} will be associated with the group, however the editPrivilege and sharePrivilege will be assigned with the default values of false.

Curl Example

The following shows how to submit the POST request to /um/groups/{groupId}/shares/{resourceId} using curl:

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '{
         "properties": {
             "editPrivilege": false,
             "sharePrivilege": false
         }
     }' \
https://api.profitbricks.com/cloudapi/v4/um/groups/{groupId}/shares/{resourceId}

Response Body

{
  "id": "6fbbde88-67bc-4494-8a40-XXXXXXXXXXXX",
  "type": "resource",
  "href": "https://api.profitbricks.com/cloudapi/v4/um/groups/e1cb1f6d-eea1-409e-b2c0-XXXXXXXXXXXX/shares/6fbbde88-67bc-4494-8a40-XXXXXXXXXXXX",
  "properties": {
    "editPrivilege": false,
    "sharePrivilege": false
  }
}

Response Attributes

Name Type Description
id string The identifier.
type string The type of response.
href string A URI for accessing the object.
properties collection A collection of properties.

The properties collection should contain these attributes:

Name Type Description
editPrivilege boolean The group has permission to edit privileges on this resource.
sharePrivilege boolean The group has permission to share this resource.

Update a Share

Use this to update the permissions that a group has for a specific resource share.

Submit a PUT request to https://api.profitbricks.com/cloudapi/v4/um/groups/{groupId}/shares/{resourceId}

Request Parameters - Path

Parameter Required Type Default Description
{groupId} yes string n/a The ID of the specific group containing the resource to update.
{resourceId} yes string n/a The ID of the specific resource to update.

Request Parameters - Header

The request headers may include the following:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
PB-Contract-Number no integer n/a Users with more than one contract can supply this header to indicate the applicable contract.
Content-Type yes string n/a Set to "application/json"

Request Parameters - Body

The JSON encoded request body may contain the following information:

Name Required Type Default Description
editPrivilege no boolean n/a The group has permission to edit privileges on this resource.
sharePrivilege no boolean n/a The group has permission to share this resource.

Curl Example

The following shows how to submit the PUT request using curl:

curl --include \
     --request PUT \
     --user 'username@domain.tld:password' \
     --data-binary '{
         "properties": {
             "editPrivilege": true,
             "sharePrivilege": true
         }
     }' \
https://api.profitbricks.com/cloudapi/v4/um/groups/{groupId}/shares/{resourceId}

Response Body

{
  "id": "6fbbde88-67bc-4494-8a40-XXXXXXXXXXXX",
  "type": "resource",
  "href": "https://api.profitbricks.com/cloudapi/v4/um/groups/e1cb1f6d-eea1-409e-b2c0-XXXXXXXXXXXX/shares/6fbbde88-67bc-4494-8a40-XXXXXXXXXXXX",
  "properties": {
    "editPrivilege": true,
    "sharePrivilege": true
  }
}

Response Attributes

Name Type Description
id string The identifier.
type string The type of response.
href string A URI for accessing the object.
properties collection A collection of properties.

The properties collection should contain these attributes:

Name Type Description
editPrivilege boolean The group has permission to edit privileges on this resource.
sharePrivilege boolean The group has permission to share this resource.

Delete a Share

Removes a resource share from a specified group.

Submit a DELETE request to https://api.profitbricks.com/cloudapi/v4/um/groups/{groupId}/shares/{resourceId}

Request Parameters - Path

Parameter Required Type Default Description
{groupId} yes string n/a The ID of the specific group containing the resource to delete.
{resourceId} yes string n/a The ID of the specific resource to delete.

Request Parameters - Header

The request headers may include the following:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
PB-Contract-Number no integer n/a Users with more than one contract can supply this header to indicate the applicable contract.

Curl Example

The following shows how to submit the DELETE /um/groups/{groupId}/shares/{resourceId} request using curl:

curl --include \
     --request DELETE \
     --user 'username@domain.tld:password' \
https://api.profitbricks.com/cloudapi/v4/um/groups/{groupId}/shares/{resourceId}

Response

Status 202 - "successful operation" is returned.

List Users in a Group

Retrieves a full list of all the users that are members of a particular group.

Request

Submit a GET request to https://api.profitbricks.com/cloudapi/v4/um/groups/{groupId}/users

Request Parameters - Path

Parameter Required Type Default Description
{groupId} yes string n/a The ID of the specific group to retrieve a user list for.

Request Parameters - Header

The request headers may include the following:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
PB-Contract-Number no integer n/a Users with more than one contract can supply this header to indicate the applicable contract.

Request Parameters - Query

The following query parameters may be included.

Parameter Type Default Description
pretty boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.profitbricks.com/cloudapi/v4/um/groups/{groupId}/users?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.profitbricks.com/cloudapi/v4/um/groups/{groupId}/users?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information.

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/v4/um/groups/15f67991-0f51-4efc-a8ad-XXXXXXXXXXXX/users

Response Body

{
  "id": "15f67991-0f51-4efc-a8ad-XXXXXXXXXXXX/users",
  "type": "collection",
  "href": "https://api.profitbricks.com/cloudapi/v4/um/groups/15f67991-0f51-4efc-a8ad-XXXXXXXXXXXX/users",
  "items": [
    {
      "id": "ba2bd7c8-1316-4b57-8748-XXXXXXXXXXXX",
      "type": "user",
      "href": "https://api.profitbricks.com/cloudapi/v4/um/users/ba2bd7c8-1316-4b57-8748-XXXXXXXXXXXX"
    },
    {
      "id": "d62cc856-f408-49be-8c45-XXXXXXXXXXXX",
      "type": "user",
      "href": "https://api.profitbricks.com/cloudapi/v4/um/users/d62cc856-f408-49be-8c45-XXXXXXXXXXXX"
    },
    ...
  ]
}

Response Attributes

Name Type Description
id string The group's identifier with "/users" appended
type string The type of response, in this case it will be collection.
href string A URI for accessing the object. "baseurl/um/groups/{groupId}/users"
items collection A collection containing the users that are members of the group.

At the default depth=0 each of the items has the following attributes:

Name Type Description
id string The user's identifier.
type string The type of response, in this case it will be user.
href string A URI for accessing the user object. "baseurl/um/users/{userId}"

At depth=1 each of the items will include the metadata, properties, and entities collections. Details on the contents of those collections can be found in the retrieve a user section.

Add User to Group

Use this operation to add an existing user to a group.

Submit a POST request to https://api.profitbricks.com/cloudapi/v4/um/groups/{groupId}/users

Request Parameters - Path

Parameter Required Type Default Description
{groupId} yes string n/a The ID of the specific group you want to add a user to.

Request Parameters - Header

The request headers may include the following:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
PB-Contract-Number no integer n/a Users with more than one contract can supply this header to indicate the applicable contract.
Content-Type yes string n/a Set to "application/json"

Request Parameters - Body

The JSON encoded request body may contain the following information:

Name Required Type Default Description
id yes string n/a The ID of the specific user to add to the group.

Curl Example

The following shows how to submit the POST request using curl:

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '{
             "id": "64c3b8b8-ae17-431d-b094-XXXXXXXXXXXX"
         }
     }' \
https://api.profitbricks.com/cloudapi/v4/um/groups/{groupId}/users

Response

{
    "id": "64c3b8b8-ae17-431d-b094-XXXXXXXXXXXX",
    "type": "user",
    "href": "https://api.profitbricks.com/cloudapi/v4/um/users/64c3b8b8-ae17-431d-b094-XXXXXXXXXXXX",
    "metadata": {
        "etag": "f5a9e8132024350477a72c39119e97e9",
        "creationDate": "2015-07-06T19:12:43Z",
        "lastLogin": "2017-06-28T00:00:20Z"
    },
    "properties": {
        "firstname": "Firstname",
        "lastname": "Lastname",
        "email": "user@domain.tld",
        "administrator": false,
        "forceSecAuth": false,
        "secAuthActive": false
    },
    "entities": {
        "owns": {
            "id": "64c3b8b8-ae17-431d-b094-XXXXXXXXXXXX/owns",
            "type": "collection",
            "href": "https://api.profitbricks.com/cloudapi/v4/um/users/64c3b8b8-ae17-431d-b094-XXXXXXXXXXXX/owns"
            },
        "groups": {
            "id": "64c3b8b8-ae17-431d-b094-XXXXXXXXXXXX/groups",
            "type": "collection",
            "href": "https://api.profitbricks.com/cloudapi/v4/um/users/64c3b8b8-ae17-431d-b094-XXXXXXXXXXXX/groups"
        }
    }
}

Response Attributes

Please refer to the Retrieve A User section below for details on response attributes.

Remove User from a Group

Use this operation to remove a user from a group.

Submit a DELETE request to https://api.profitbricks.com/cloudapi/v4/um/groups/{groupId}/users/{userId}

Request Parameters - Path

Parameter Required Type Default Description
{groupId} yes string n/a The ID of the specific group you want to remove a user from.
{userId} yes string n/a The ID of the specific user to remove from the group.

Request Parameters - Header

The request headers may include the following:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
PB-Contract-Number no integer n/a Users with more than one contract can supply this header to indicate the applicable contract.

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/v4/um/groups/{groupId}/users/{userId}

Response

Status 202 - "successful operation" is returned.

List Users

Retrieve a list of all the users that have been created under a contract.

Request

Submit a GET request to https://api.profitbricks.com/cloudapi/v4/um/users

Request Parameters - Header

The request headers may include the following:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
PB-Contract-Number no integer n/a Users with more than one contract can supply this header to indicate the applicable contract.

Request Parameters - Query

The following query parameters may be included.

Parameter Type Default Description
pretty boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.profitbricks.com/cloudapi/v4/um/users?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.profitbricks.com/cloudapi/v4/um/users?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information.

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/v4/um/users

Response Body

{
  "id": "users",
  "type": "collection",
  "href": "https://api.profitbricks.com/cloudapi/v4/users",
  "items": [
    {
      "id": "e1daff99-0f2c-4970-8643-0ec34433b05f",
      "type": "user",
      "href": "https://api.profitbricks.com/cloudapi/v4/um/users/e1daff99-0f2c-4970-8643-XXXXXXXXXXXX"
    }
  ]
}

Response Attributes

Name Type Description
id string "users"
type string The type of response, in this case it will be collection.
href string A URI for accessing the object. "baseurl/users"
items collection A collection containing the users that are members of the group.

At the default depth=0 each of the items has the following attributes:

Name Type Description
id string The user's identifier.
type string The type of response, in this case it will be user.
href string A URI for accessing the user object. "baseurl/um/users/{userId}"

At depth=1 each of the items will include the metadata, properties, and entities collections. Details on the contents of those collections can be found in the retrieve a user section below.

Retrieve a User

Retrieve details about a specific user including what groups and resources the user is associated with.

Request

Submit a GET request to https://api.profitbricks.com/cloudapi/v4/um/users/{userId}

Request Parameters - Path

Parameter Required Type Default Description
{userId} yes string n/a The ID of the specific user to retrieve information about.

Request Parameters - Header

The request headers may include the following:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
PB-Contract-Number no integer n/a Users with more than one contract can supply this header to indicate the applicable contract.

Request Parameters - Query

The following query parameters may be included.

Parameter Type Default Description
pretty boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.profitbricks.com/cloudapi/v4/um/users/{userId}?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.profitbricks.com/cloudapi/v4/um/users/{userId}?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information.

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/v4/um/users/15f67991-0f51-4efc-a8ad-XXXXXXXXXXXX

Response Body

{
  "id": "e1daff99-0f2c-4970-8643-XXXXXXXXXXXX",
  "type": "user",
  "href": "https://api.profitbricks.com/cloudapi/v4/um/users/e1daff99-0f2c-4970-8643-XXXXXXXXXXXX",
  "metadata": {
    "etag": "37a6259cc0c1dae299a7866489dff0bd",
    "creationDate": "2017-05-22T08:15:55Z",
    "lastLogin": null
  },
  "properties": {
    "firstname": "New",
    "lastname": "Admin",
    "email": "new_admin@domain.tld",
    "administrator": true,
    "forceSecAuth": false,
    "secAuthActive": false
  },
  "entities": {
    "owns": {
      "id": "e1daff99-0f2c-4970-8643-XXXXXXXXXXXX/owns",
      "type": "collection",
      "href": "https://api.profitbricks.com/cloudapi/v4/um/users/e1daff99-0f2c-4970-8643-XXXXXXXXXXXX/owns"
    },
    "groups": {
      "id": "e1daff99-0f2c-4970-8643-XXXXXXXXXXXX/groups",
      "type": "collection",
      "href": "https://api.profitbricks.com/cloudapi/v4/um/users/e1daff99-0f2c-4970-8643-XXXXXXXXXXXX/groups"
    }
  }
}

Response Attributes

Name Type Description
id string The user's identifier.
type string The type of response, in this case it will be user.
href string A URI for accessing the user object.
metadata collection A collection containing metadata for the user.
properties collection A collection containing the user's properties.
entities collection A collection containing resources the user owns, and groups the user is a member of.

The metadata collection includes these attributes:

Name Type Description
etag string ETag for the user.
creationDate string A time and date stamp indicating when the user was created.
lastLogin string A time and date stamp indicating when the user last logged in.

The properties collection includes these attributes:

Name Type Description
firstname string The first name of the user.
lastname string The last name of the user.
email string The e-mail address of the user.
administrator boolean Indicates if the user has administrative rights.
forceSecAuth boolean Indicates if secure (two-factor) authentication was enabled for the user.
secAuthActive boolean Indicates if secure (two-factor) authentication is enabled for the user.

The entities collection includes these attributes:

Name Type Description
owns collection A collection of resources that this user owns.
groups collection A collection of groups that this user is a member of.

Each of the owns or groups will include the following attributes.

Name Type Description
id string The group's identifier with /users or /resources appended.
type string The type of response, in this case it will be "collection".
href string A URL for directly accessing the object.

At depth=1 each of the entities will also include an items collection with details about the particular resource that the user owns and the groups that the user is a member of.

Create a User

Creates a new user under a particular contract.

Request

Submit a POST request to https://api.profitbricks.com/cloudapi/v4/um/users

Request Parameters - Header

The request headers may include the following:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
PB-Contract-Number no integer n/a Users with more than one contract can supply this header to indicate the applicable contract.
Content-Type yes string n/a Set to "application/json"

Request Parameters - Body

The JSON encoded request body may contain the following information:

Name Required Type Default Description
firstname yes string n/a A name for the user.
lastname yes string n/a A name for the user.
email yes string n/a An e-mail address for the user.
password yes string n/a A password for the user.
administrator no boolean false Assigns the user have administrative rights.
forceSecAuth no boolean false Indicates if secure (two-factor) authentication should be forced for the user.

Please Note: The password set here cannot be updated through the API currently. It is recommended that a new user log into the DCD and change their password.

Curl Example

The following shows how to submit the POST request using curl:

curl --include \
     --request POST \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/json" \
     --data-binary '{
         "properties": {
             "firstname": "New",
             "lastname": "User",
             "email": "username@domain.tld",
             "password": "abc123-321CBA",
             "administrator": true,
             "forceSecAuth": false
         }
     }' \
https://api.profitbricks.com/cloudapi/v4/um/users

Response Body

{
  "id": "e1daff99-0f2c-4970-8643-XXXXXXXXXXXX",
  "type": "user",
  "href": "https://api.profitbricks.com/cloudapi/v4/um/users/e1daff99-0f2c-4970-8643-XXXXXXXXXXXX",
  "metadata": {
    "etag": "37a6259cc0c1dae299a7866489dff0bd",
    "creationDate": "2017-05-22T08:15:55Z",
    "lastLogin": null
  },
  "properties": {
    "firstname": "New",
    "lastname": "Admin",
    "email": "new_admin@domain.tld",
    "administrator": true,
    "forceSecAuth": false,
    "secAuthActive": false
  }
}

Response Attributes

Name Type Description
id string The user's identifier.
type string The type of response, in this case it will be user.
href string A URI for accessing the user object.
metadata collection A collection containing metadata for the user.
properties collection A collection containing the user's properties.

The metadata collection includes these attributes:

Name Type Description
etag string ETag for the user.
creationDate string A time and date stamp indicating when the user was created.
lastLogin string A time and date stamp indicating when the user last logged in. Should be "null" for a new user.

The properties collection includes these attributes:

Name Type Description
firstname string The first name of the user.
lastname string The last name of the user.
email string The e-mail address of the user.
administrator boolean Indicates if the user has administrative rights.
forceSecAuth boolean Indicates if secure (two-factor) authentication was enabled for the user.
secAuthActive boolean Indicates if secure (two-factor) authentication is enabled for the user.

Update a User

Update details about a specific user including their privileges.

Submit a PUT request to https://api.profitbricks.com/cloudapi/v4/um/users/{userId}

Request Parameters - Path

Parameter Required Type Default Description
{userId} yes string n/a The ID of the specific user to update.

Request Parameters - Header

The request headers may include the following:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
PB-Contract-Number no integer n/a Users with more than one contract can supply this header to indicate the applicable contract.
Content-Type yes string n/a Set this to "application/json".

Request Parameters - Body

With this PUT operation, you need to supply values for all the attributes, even if you are only updating some of them.

The JSON encoded request body must contain the following information:

Name Required Type Default Description
firstname yes string n/a A name for the user.
lastname yes string n/a A name for the user.
email yes string n/a An e-mail address for the user.
administrator yes boolean false Assigns the user have administrative rights.
forceSecAuth yes boolean false Indicates if secure authentication should be forced for the user.

Note: The password attribute is immutable. It is not allowed in update requests. It is recommended that a new user log into the DCD and change their password.

Curl Example

The following shows how to submit the PUT request using curl:

curl --include \
     --request PUT \
     --user 'username@domain.tld:password' \
     --data-binary '{
         "properties": {
             "firstname": "Changed",
             "lastname": "Person",
             "email": "changedusername@domain.tld",
             "administrator": false,
             "forceSecAuth": false
         }
     }' \
https://api.profitbricks.com/cloudapi/v4/um/users/{userId}

Response Body

{
  "id": "e1daff99-0f2c-4970-8643-XXXXXXXXXXXX",
  "type": "user",
  "href": "https://api.profitbricks.com/cloudapi/v4/um/users/e1daff99-0f2c-4970-8643-XXXXXXXXXXXX",
  "metadata": {
    "etag": "37a6259cc0c1dae299a7866489dff0bd",
    "creationDate": "2017-05-22T08:15:55Z",
    "lastLogin": null
  },
  "properties": {
    "firstname": "New",
    "lastname": "Administrator",
    "email": "new_admin@domain.tld",
    "administrator": true,
    "forceSecAuth": false,
    "secAuthActive": false
  },
  "entities": {
    "owns": {
      "id": "e1daff99-0f2c-4970-8643-XXXXXXXXXXXX/owns",
      "type": "collection",
      "href": "https://api.profitbricks.com/cloudapi/v4/um/users/e1daff99-0f2c-4970-8643-XXXXXXXXXXXX/owns"
    },
    "groups": {
      "id": "e1daff99-0f2c-4970-8643-XXXXXXXXXXXX/groups",
      "type": "collection",
      "href": "https://api.profitbricks.com/cloudapi/v4/um/users/e1daff99-0f2c-4970-8643-XXXXXXXXXXXX/groups"
    }
  }
}

Response Attributes

Name Type Description
id string The user's identifier.
type string The type of response, in this case it will be "user".
href string A URI for accessing the user object.
metadata collection A collection containing metadata for the user.
properties collection A collection containing the user's properties.
entities collection A collection containing resources the user owns, and groups the user is a member of.

The metadata collection includes these attributes:

Name Type Description
etag string ETag for the user.
creationDate string A time and date stamp indicating when the user was created.
lastLogin string A time and date stamp indicating when the user last logged in.

The properties collection includes these attributes:

Name Type Description
firstname string The first name of the user.
lastname string The last name of the user.
email string The e-mail address of the user.
administrator boolean Indicates if the user has administrative rights.
forceSecAuth boolean Indicates if secure (two-factor) authentication was enabled for the user.
secAuthActive boolean Indicates if secure (two-factor) authentication is enabled for the user.

The entities collection includes these attributes:

Name Type Description
owns collection A collection of resources that this user owns.
groups collection A collection of groups that this user is a member of.

Each of the owns or groups will include the following attributes.

Name Type Description
id string The group's identifier with /users or /resources appended.
type string The type of response, in this case it will be "collection".
href string A URL for directly accessing the object.

Delete a User

Blacklists the user, disabling them. The user is not completely purged, therefore if you anticipate needing to create a user with the same name in the future, we suggest renaming the user before you delete it.

Submit a DELETE request to https://api.profitbricks.com/cloudapi/v4/um/users/{userId}

Request Parameters - Path

Parameter Required Type Default Description
{userId} yes string n/a The ID of the specific user to delete.

Request Parameters - Header

The request headers may include the following:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
PB-Contract-Number no integer n/a Users with more than one contract can supply this header to indicate the applicable contract.

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/v4/um/users/{userId}

Response

202 - "successful operation" is returned.

List Resources

Retrieves a list of all resources and optionally their group associations. Please Note: This API call can take a significant amount of time to return when there are a large number of provisioned resources. You may wish to consult the next section on how to list resources of a particular type.

Request

Submit a GET request to https://api.profitbricks.com/cloudapi/v4/um/resources

Request Parameters - Header

The request headers may include the following:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
PB-Contract-Number no integer n/a Users with more than one contract can supply this header to indicate the applicable contract.

Request Parameters - Query

The following query parameters may be included.

Parameter Type Default Description
pretty boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.profitbricks.com/cloudapi/v4/um/resources?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.profitbricks.com/cloudapi/v4/um/resources?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information.

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/v4/um/resources

Response Body

{
  "id": "resources",
  "type": "collection",
  "href": "https://api.profitbricks.com/cloudapi/v4/um/resources",
  "items": [
    {
      "id": "c4fb16f5-dde9-4aa3-9bed-XXXXXXXXXXXX",
      "type": "datacenter",
      "href": "https://api.profitbricks.com/cloudapi/v4/um/resources/datacenter/c4fb16f5-dde9-4aa3-9bed-XXXXXXXXXXXX"
    },
    {
      "id": "9dfb6c77-8887-4257-9234-XXXXXXXXXXXX",
      "type": "datacenter",
      "href": "https://api.profitbricks.com/cloudapi/v4/um/resources/datacenter/9dfb6c77-8887-4257-9234-XXXXXXXXXXXX"
    },
    ...
  ]
}

Response Attributes

Name Type Description
id string "resources"
type string The type of response, in this case it will be collection.
href string A URI for accessing the object. "baseurl/um/resources"
items collection A collection containing the available resources.

At the default depth=0 each of the items has the following attributes:

Name Type Description
id string The user's identifier.
type string The type of object.
href string A URI for accessing the user object. "baseurl/um/resources/{resourceType}/{resourceId}"

The type along with the resourceType returned in the items collections href attribute will be one of the following:

resourceType Description
datacenter A virtual data center.
image A private image that has been uploaded to ProfitBricks.
snapshot A snapshot of a storage volume.
ipblock An IP block that has been reserved.

List All Resources of a Type

Lists all shareable resources of a specific type. Optionally include their association with groups, permissions that a group has for the resource, and users that are members of the group. Because you are scoping your request to a specific resource type, this API will likely return faster than querying /um/resources.

Request

Submit a GET request to https://api.profitbricks.com/cloudapi/v4/um/resources/{resourceType}

Request Parameters - Path

Parameter Required Type Default Description
{resourceType} yes string n/a The specific type of resources to retrieve information about.

The values available for resourceType are listed in this table:

resourceType Description
datacenter A virtual data center.
image A private image that has been uploaded to ProfitBricks.
snapshot A snapshot of a storage volume.
ipblock An IP block that has been reserved.

Request Parameters - Header

The request headers may include the following:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
PB-Contract-Number no integer n/a Users with more than one contract can supply this header to indicate the applicable contract.

Request Parameters - Query

The following query parameters may be included.

Parameter Type Default Description
pretty boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.profitbricks.com/cloudapi/v4/um/resources/{resourceType}?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.profitbricks.com/cloudapi/v4/um/resources{resourceType}?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information.

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/v4/um/resources/ipblock

Response Body

{
  "id": "resources",
  "type": "collection",
  "href": "https://api.profitbricks.com/cloudapi/v4/um/resources",
  "items": [
    {
      "id": "b85ba3d1-531f-4d77-826e-XXXXXXXXXXXX",
      "type": "ipblock",
      "href": "https://api.profitbricks.com/cloudapi/v4/um/resources/ipblock/b85ba3d1-531f-4d77-826e-XXXXXXXXXXXX"
    },
    {
      "id": "bf4fa633-c9b3-45ad-875c-XXXXXXXXXXXX",
      "type": "ipblock",
      "href": "https://api.profitbricks.com/cloudapi/v4/um/resources/ipblock/bf4fa633-c9b3-45ad-875c-XXXXXXXXXXXX"
    },
    {
      "id": "ea15dea6-1f24-4020-9971-XXXXXXXXXXXX",
      "type": "ipblock",
      "href": "https://api.profitbricks.com/cloudapi/v4/um/resources/ipblock/ea15dea6-1f24-4020-9971-XXXXXXXXXXXX"
    },
    ...
  ]
}

Response Attributes

Name Type Description
id string "resources"
type string The type of response, in this case it will be "collection".
href string A URI for accessing the object. "baseurl/um/resources"
items collection A collection containing the available resources.

At the default depth=0 each of the items has the following attributes:

Name Type Description
id string The user's identifier.
type string The type of object.
href string A URI for accessing the user object. "baseurl/um/resources/{resourceType}/{resourceId}"

The type along with the resourceType returned in the items collections href attribute will be one of the following:

resourceType Description
datacenter A virtual data center.
image A private image that has been uploaded to ProfitBricks.
snapshot A snapshot of a storage volume.
ipblock An IP block that has been reserved.

List a specific Resource Type

Request

Submit a GET request to https://api.profitbricks.com/cloudapi/v4/um/resources/{resourceType}/{resourceId}

Request Parameters - Path

Parameter Required Type Default Description
{resourceType} yes string n/a The resource type of the resource ID.
{resourceId} yes string n/a The ID of the specific resource to retrieve information about.

The values available for resourceType are listed in this table:

resourceType Description
datacenter A virtual data center.
image A private image that has been uploaded to ProfitBricks.
snapshot A snapshot of a storage volume.
ipblock An IP block that has been reserved.

Request Parameters - Header

The request headers may include the following:

Header Required Type Default Description
Authorization yes string n/a HTTP Basic authorization. A base64 encoded string of a username and password separated by a colon. "username@domain.tld:password"
PB-Contract-Number no integer n/a Users with more than one contract can supply this header to indicate the applicable contract.

Request Parameters - Query

The following query parameters may be included.

Parameter Type Default Description
pretty boolean true Indicates if the response data should be "pretty-printed" with indentation and new lines.
depth int32 0 An integer value [0-10] that determines the amount of detail returned.

You can force the results to be less human-readable by supplying a value of 0 or false for pretty:

https://api.profitbricks.com/cloudapi/v4/um/resources/{resourceType}/{resourceId}?pretty=0

You can increase the amount of detail returned in some requests by supplying an integer value between 1 and 10 as depth:

https://api.profitbricks.com/cloudapi/v4/um/resources/{resourceType}/{resourceId}?depth=1

Note: For this particular operation, increasing the value supplied to depth will return additional information.

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/v4/um/resources/snapshot/6fbbde88-67bc-4494-8a40-XXXXXXXXXXXX

Response Body

{
  "id": "6fbbde88-67bc-4494-8a40-XXXXXXXXXXXX",
  "type": "snapshot",
  "href": "https://api.profitbricks.com/cloudapi/v4/um/resources/snapshot/6fbbde88-67bc-4494-8a40-XXXXXXXXXXXX",
  "metadata": {
    "createdDate": "2017-05-16T16:37:04Z",
    "createdBy": "user@domain.tld",
    "etag": "1bbd44fb66d3611b49ce471098449e1a",
    "lastModifiedDate": "2017-05-26T17:26:23Z",
    "lastModifiedBy": "user@domain.tld",
    "state": "AVAILABLE"
  },
  "entities": {
    "groups": {
      "id": "6fbbde88-67bc-4494-8a40-XXXXXXXXXXXX/groups",
      "type": "collection",
      "href": "https://api.profitbricks.com/cloudapi/v4/um/groups"
    }
  }
}

Response Attributes

Name Type Description
id string The resource's identifier.
type string The type of resource.
href string A URI for accessing the resource object.
metadata collection Metadata for the specific resource.
entities collection A collection containing groups the resource is associated with.

The metadata collection includes these attributes:

Name Type Description
createdDate string A time and date stamp indicating when the resource was created.
createdBy string The user who created the resource.
etag string ETag.
lastModifiedDate string A time and date stamp indicating when the resource was last modified.
lastModifiedBy string The user who last modified the resource.
state string The current state of the resource. [ AVAILABLE, BUSY, INACTIVE ]

The entities collection includes these attributes:

Name Type Description
groups collection A collection of groups associated with the resource.

At the default depth=0 each of the groups has the following attributes:

Name Type Description
id string The resource's identifier with "/groups" appended.
type string The type of object. "collection"
href string A URI for accessing the group. "baseurl/um/groups"

If the query parameter depth=1 is used, then an items collection will also be returned for each of the entities.