Cloud API v2.0 - Use the latest: v5.0


Overview

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

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

What's New?

SSH Keys

It is now possible to inject SSH keys when creating a volume. This allows access to newly provisioned servers using public-key authentication rather than relying on passwords. The SSH public key or keys can be supplied as a JSON array (named "sshKeys") in the volume properies.

Using OpenSSH, a RSA public-key pair can be generated by running:

ssh-keygen -t rsa -b 3072 -f rsa_key_3072

Two files, rsa_key_3072 and rsa_key_3072.pub will be placed in the directory where the command was run. The value contained in the file rsa_key_3072.pub is the public key and would be passed into the create volume API call. Use square brackets to denote a JSON array and enclose each supplied ssh public key inside double-quotes separated by commas.

Example JSON syntax specifying a single public key:

"properties": {
  "size": 10,
  "name": "Server001_HDD",
  "bus": "VIRTIO",
  "type": "HDD",
  "sshKeys": ["ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAB...gQDkwcbjQzDv3Kiy="],
  "image": "7a8577a8-f7b0-11e5-b7e8-52540005ab80"
}

The "image" refenced in the example is a ProfitBricks supplied CentOS 7 image. The supplied public key (the example value for "sshKeys" was truncated) will be placed in /root/.ssh/authorized_keys when the volume is created.

You can subsequently connect to the server via SSH using -i to specify the private key like this:

ssh -i rsa_key_3072 root@YOUR_SERVER_IP

SSH keys cannot be changed or set for an an existing volume via the Cloud API. The functionality is reserved for volume creation. The public key will NOT be displayed as part of volume properties after creation. It will display as null.

Image Password

When creating a storage volume based on a ProfitBricks supplied OS image, it is possible to set an "imagePassword" that will be used for the root(Linux) or Administrator(Windows) user instead of having a random one assigned. This allows immediate password based access to the server. This feature existed in Cloud API v1. However, it will soon become mandatory to set it in Cloud API v2.

When creating a volume based on a ProfitBricks Linux image, a value for either "imagePassword" OR "sshKeys" will need to be set. If you choose to utilize "sshKeys" we still recommend setting a value for "imagePassword" in case you need to access the server through the DCD console application.

Example JSON syntax specifying an "imagePassword":

"properties": {
  "size": 10,
  "name": "Server001_HDD",
  "bus": "VIRTIO",
  "type": "HDD",
  "imagePassword": "InitPWD456",
  "image": "7a8577a8-f7b0-11e5-b7e8-52540005ab80"
}

The "imagePassword" must contain at least 8 and no more than 50 characters.

When creating a volume based on a ProfitBricks Windows image, a value for "imagePassword" is required.

New Licence Type for Microsoft Windows Server 2016

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

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

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

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

SSD Storage

The performance advantages of SSD storage are now available in the ProfitBricks cloud! Access to SSD storage must be granted to your account before SSD backed volumes can be provisioned. Please contact your ProfitBricks sales representative if you would like to use this new feature.

Provisioning a SSD storage volume can be done by specifying a "type" value of "SSD" instead of "HDD" when making the API call.

"properties" : {
  "name" : "Example SSD Storage",
  "type" : "SSD",
  "size" : 10
  ...
}

CPU Architecture Options

ProfitBricks now provides the option to create cloud servers using the Intel Xeon processor in addition to the AMD Opteron processor. In the Data Center Designer (DCD) this optional CPU Architecture value is selectable when enabled for your account. Servers using the Intel Xeon processor will show an "INTEL_XEON" value for "cpuFamily" when queried through the Cloud API v2.

"properties" : {
  "name" : "IntelTest",
  "cores" : 1,
  "ram" : 2048,
  ...
  "cpuFamily" : "INTEL_XEON"
}

Servers utilizing the AMD Opteron processor show:

"properties" : {
  "name" : "AMDTest",
  "cores" : 1,
  "ram" : 2048,
  ...
  "cpuFamily" : "AMD_OPTERON"
}

Simply pass in the desired value for "cpuFamily" when making the API call to create a new server, just as you would set "cores", "ram", or any other available property.

Getting Started

How to Access the API

You can consume the REST API using the following URL:

URL Description
https://api.profitbricks.com/rest/v2/ REST v2 Endpoint

Protocol Elements

Request Methods

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

HTTP Status Codes

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

HTTP Headers

Request Headers

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

Authorization

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

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

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

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

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

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

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

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

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

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

If you are experiencing difficulty authenticating with the encoded credentials:

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

Response Headers

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

Data Representation

The API implements four custom media types used in the requests.

The supported data format for resource representation is profitbricks.resource+json and is registered as application/vnd.profitbricks.resource+json.

Support for partial updates of resources using the PATCH method is represented as profitbricks.partial-properties+json. The media type it is registered as is application/vnd.profitbricks.partial-properties+json.

The Accept header can be omitted in a request; however, if it is present then you must specify application/vnd.profitbricks.resource+json.

For any request containing a body -- POST, PUT, PATCH -- the Content-Type header is required.

The following two representations are always returned by the server and are never required to be passed to the server. Those are:

When a collection is returned the representation is profitbricks.collection+json.

When an error is returned the representation profitbricks.error+json is used.

Request Depth

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

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

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

Implicit Volume Creation

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

The following stories are support using create-attach:

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

Creation, Modification, and Deletion Responses

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

DELETE responses return an empty body.

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

The response status code 202 Accepted is returned.

PATCH requests

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

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

PATCH requests are made using a the proprietary Content-Type of application/vnd.profitbricks.partial-properties+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 profitbricks.error+json format which is registered as a application/vnd.profitbricks.error+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.

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 REST API.

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

Users & Groups

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

The API adheres to all permissions applied through the DCD:

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

Groups

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

API Rate Limits

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

Multi-user

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

Separate Limits for Read and Write

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

Exceeding the Limit

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

HTTP Status Codes

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

Response Headers

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

Data Centers

Create a Data Center

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

Request

Request Headers

The request headers should be the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/vnd.profitbricks.resource+json

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

Request Body

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

The format of the request body is as follows:

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

The following table describes the elements of the request body:

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

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

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

The following table outlines the locations currently supported:

Value Country City
us/las United States Las Vegas
de/fra Germany Frankfurt
de/fkb Germany Karlsruhe
Curl Example

The following shows how to submit the request using curl:

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

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.profitbricks.com/rest/v2/requests/[data-center-id]/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/vnd.profitbricks.resource+json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "[data-center-id]",
  "type" : "datacenter",
  "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "[data-center-name]",
    "description" : "[data-center-description]",
    "location" : "[data-center-location]",
    "version" : null,
    "features" : [ ]
  }
}
Response Parameters

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

Name Description
id The resource's unique identifier (UUID) in the form 8-4-4-4-12.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued; INACTIVE Resource has been de-provisioned.
etag The etag for the request.
name The name of the data center.
description The description of the data center.
location The location of the data center.
version The version of the data center.
features Reserved for future use.

Create a Data Center with Multiple Resources

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/vnd.profitbricks.resource+json

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

Request Body

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

The format of the request body is as follows:

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

The following table describes the elements of the request body:

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

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

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

The following table outlines the locations currently supported:

Value Country City
us/las United States Las Vegas
de/fra Germany Frankfurt
de/fkb Germany Karlsruhe
Curl Example

The following shows how to submit the request using curl:

curl --include \
         --request POST \
         --user 'username@domain.tld:password' \
         --header "Content-Type: application/vnd.profitbricks.resource+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/rest/v2/datacenters

Response

HTTP/1.1 100 Continue

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.profitbricks.com/rest/v2/requests/[request-status-id]/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/vnd.profitbricks.resource+json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "[data-center-id]",
  "type" : "datacenter",
  "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "[data-center-name]",
    "description" : "Example Description",
    "location" : "us/las",
    "version" : null,
    "features" : [ ]
  },
  "entities" : {
    "servers" : {
      "id" : "[server-id]/servers",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/servers"
    },
    "lans" : {
      "id" : "[data-center-id]/lans",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/lans"
    }
  }
}
Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued; INACTIVE Resource has been de-provisioned.
etag The etag for the request.
name The name of the data center.
description The description of the data center.
location The location you provisioned the data center.
version The version of the data center.
servers You can define multiple servers to be created when the data center is created. See create server for request parameter details.
volumes A collection that represents volumes you wish to create upon data center creation. See create storage volume for request parameter details.
loadbalancers A collection that represents the loadbalancers you wish to create upon data center creation.
lans A collection that represents the LANs you wish to create upon data center creation.

Retrieve a Data Center

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

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request

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

Request Parameters

The following table describes the elements of the GET request:

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

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

Curl Example

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

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

Response

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

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

Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state Data center state.
etag The etag for the resource.
name The name of the data center.
description The description of the data center.
location The location you provisioned the data center.
version The version of the data center.
servers A collection that represents the servers in a data center.
volumes A collection that represents volumes in a data center.
loadbalancers A collection that represents the loadbalancers in a data center.
lans A collection that represents the LANs in a data center.

The following table illustrates the possible data center states:

State Description
AVAILABLE There are no pending modification requests for this item.
BUSY There is at least one modification request pending and all following requests will be queued.
INACTIVE Resource has been de-provisioned.

List Data Centers

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

Request

Request Headers

The request headers should be the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request

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

Request Parameters

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

Curl Example

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

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

Response

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

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

Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state Data center state.
etag The etag for the resource.
name The name of the data center.
description The description of the data center.
location The location you provisioned the data center.
version The version of the data center.

Update a Data Center

The 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

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/vnd.profitbricks.partial-properties+json

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

Request

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

Request Parameters

The following table describes the elements of the request body:

Name Type Description Required
name string The unique ID of the data center. No
description string The new name of the data center. No
Curl Example

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

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

Response

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

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

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued; INACTIVE Resource has been de-provisioned.
name The name of the data center.
description The description of the data center.
location The location you provisioned the data center.
version The version of the data center.
servers You can define multiple servers to be updated when the data center is updated. See create server for request parameter details.
volumes A collection that represents volumes you wish to update upon data center update. See create storage volume for request parameter details.
loadbalancers A collection that represents the loadbalancers you wish to update upon data center update.
lans A collection that represents the LANs you wish to create upon data center creation.

PUT Update

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/vnd.profitbricks.resource+json

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

Request

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

Request Parameters

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

Name Type Description Required
name string The unique ID of the data center. Yes
description string The new name of the data center. Yes

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

Curl Example

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

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

Response

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

{
  "id" : "[data-center-id]",
  "type" : "datacenter",
  "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "Example DC Rename 2",
    "description" : "Example DC Description 2",
    "location" : "us/las",
    "version" : 24,
    "features" : [ ]
  },
  "entities" : {
    "servers" : {
      "id" : "[data-center-id]/servers",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/servers"
    },
    "volumes" : {
      "id" : "[data-center-id]/volumes",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/volumes"
    },
    "loadbalancers" : {
      "id" : "[data-center-id]/loadbalancers",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/loadbalancers"
    },
    "lans" : {
      "id" : "[data-center-id]/lans",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/lans"
    }
  }
}
Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued; INACTIVE Resource has been de-provisioned.
name The name of the data center.
description The description of the data center.
location The location you provisioned the data center.
servers You can define multiple servers to be updated when a data center is updated. See create server for request parameter details.
volumes A collection that represents volumes to update upon data center update. See create storage volume for request parameter details.
loadbalancers A collection that represents the loadbalancers you wish to update upon data center update.
lans A collection that represents the LANs you wish to create upon data center creation.

Delete a Data Center

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

Request

Request Headers

The DELETE request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request

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

Request Parameters

The following table describes the elements of the DELETE URL:

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

Curl Example

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

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

None

Checking the Status

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

curl --include \
     --request GET \
     --user '[username@domain.tld:password]' \
     https://api.profitbricks.com/rest/v2/requests/[request-status-id]/status
Status Response

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

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

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

Locations

List Locations

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

Request

Request Headers

The request headers should be the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

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

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

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

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

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

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

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

]

Response Parameters

The request will return a collection of locations.

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

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

Get Location

Retrieves the attributes of a given location.

Request

Request Headers

The request headers should be the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

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

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

Response

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

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

Response Parameters

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

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

Servers

Create a Server

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

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/vnd.profitbricks.resource+json

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

Request Body

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

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

The format of the request body is as follows:

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

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

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

Request Parameters

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

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

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 the POST request using curl:

curl --include \
     --request POST \
     --user 'username@domain.tld:password'
     --header "Content-Type: application/vnd.profitbricks.resource+json" \
     --data-binary '    {
        "properties": {
            "name": "Server001",
            "ram": 512,
            "cores": 1,
            "availabilityZone": "ZONE_1",
            "cpuFamily": "INTEL_XEON"
        },
        "entities": {
            "volumes": [
                {
                    "properties": {
                        "size": [volume-size-in-gb],
                        "name": "[storage-volume-name]",
                        "image": "[storage-volume-image]",
                        "bus": "[storage-volume-bus-type]",
                        "licenceType": "[licence-type]"
                    }
                }
            ]
        }
    }' \
     https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/servers

Note: When creating a volume, you must specify either the licenceType or an image.

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.profitbricks.com/rest/v2/requests/[request-status-id]/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/vnd.profitbricks.resource+json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "[server-id]",
  "type" : "server",
  "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/servers/[server-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[username]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[username]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "[server-name]",
    "cores" : [number-of-server-cores],
    "ram" : [server-memory-in-mb],
    "availabilityZone" : "[availability-zone]",
    "vmState" : null,
    "bootCdrom" : null,
    "bootVolume" : null,
    "cpuFamily" : null
  },
  "entities" : {
    "volumes" : {
      "id" : "[server-id]/volumes",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/servers/[server-id]/volumes"
    }
  }
}

Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued.
name The name of the server.
cores The number of cores for the server.
ram The amount of memory on the server.
availabilityZone The availability zone for the server.
vmState The current state of the virtual machine.
bootCdrom Reference to a CD-ROM used for booting.
bootVolume Reference to a Volume used for booting.
cpuFamily Type of CPU assigned.
cdroms A collection of cdroms attached to the server.
volumes A collection of volumes attached to the server.
nics A collection of NICs attached to the server.

Retrieve a Server

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

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

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

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

Response

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

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

Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
lastModifiedDate The last modified time for the resource.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
vmState Status of the virtual Machine.
etag The etag.
name The name of the server.
cores The number of cores for the server.
ram The amount of memory on the server.
availabilityZone The availability zone for the server.
bootCdrom Reference to a CD-ROM used for booting. If not 'null' then bootVolume has to be 'null'.
bootVolume Reference to a Volume used for booting. If not ‘null’ then bootCdrom has to be ‘null’
cpuFamily Type of CPU assigned.
volumes A collection of volumes attached to the server.
cdroms A collection of cdroms attached to the server.
nics A collection of NICs attached to the server.
Server States

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

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

List Servers

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

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

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

Curl Example

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

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

Response

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

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

Response Parameters

The request will return a collection of servers.

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
lastModifiedDate The last modified time for the resource.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state Status of the virtual Machine.
etag The etag.
name The name of the server.
cores The number of cores for the server.
ram The amount of memory on the server.
availabilityZone The availability zone for the server.
vmState The current state of the instance.
bootVolume Reference to a Volume used for booting. If not ‘null’ then bootCdrom has to be ‘null’.
bootCdrom Reference to a CD-ROM used for booting. If not 'null' then bootVolume has to be 'null'.
cdroms A collection of cdroms attached to the server.
volumes A collection of volumes attached to the server.
nics A collection of NICs attached to the server.

Update a Server

The 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 the server between "AMD_OPTERON" and "INTEL_XEON".

PATCH

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

Request

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/vnd.profitbricks.partial-properties+json

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

Request Body

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

Request Parameters
Name Type Description Required
name string The name of the server. No
cores int The number of cores for the server. No
ram int The amount of memory in the server. No
availabilityzone string The new availability zone for the server. No
cpuFamily string Sets the desired CPU type. "AMD_OPTERON" or "INTEL_XEON". No
bootVolume string Reference to a Volume used for booting. If not ‘null’ then bootCdrom has to be ‘null’ No
bootCdrom string Reference to a CD-ROM used for booting. If not 'null' then bootVolume has to be 'null'. No
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/vnd.profitbricks.partial-properties+json" \
     --data-binary '    {
        "name": "Server001A"
    }' \
     https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/servers/[server-id]

Response

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

{
  "id" : "[server-id]",
  "type" : "server",
  "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/servers/[server-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[username]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[username]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "Server001A",
    "cores" : 1,
    "ram" : 512,
    "availabilityZone" : "AUTO",
    "vmState" : "RUNNING",
    "bootCdrom" : null,
    "bootVolume" : {
      "id" : "[volume-id]",
      "type" : "volume",
      "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/volumes/[volume-id]"
    },
    "cpuFamily" : "AMD_OPTERON"
  },
  "entities" : {
    "cdroms" : {
      "id" : "[server-id]/cdroms",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/servers/[server-id]/cdroms"
    },
    "volumes" : {
      "id" : "[server-id]/volumes",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/servers/[server-id]/volumes"
    },
    "nics" : {
      "id" : "367fffcd-965f-4aa5-a6c2-afbd81e407ba/nics",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/servers/[server-id]/nics"
    }
  }
}
Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
lastModifiedDate The last modified time for the resource.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state Status of the virtual Machine.
etag The etag.
name The name of the server.
cores The number of cores for the server.
ram The amount of memory on the server.
availabilityzone The availability zone for the server.
cpuFamily Type of CPU assigned.
bootVolume Reference to a Volume used for booting. If not ‘null’ then bootCdrom has to be ‘null’
bootCdrom Reference to a CD-ROM used for booting. If not 'null' then bootVolume has to be 'null'.
vmstate The state of the server.
cdroms A collection of cdroms attached to the server.
volumes A collection of volumes attached to the server.
nics A collection of NICs attached to the server.

PUT

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

Request

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/vnd.profitbricks.resource+json

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

Request Body

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

Request Parameters
Name Type Description Required
name string The name of the server. Yes
cores int The number of cores for the server. Yes
ram int The amount of memory in the server. Yes
availabilityzone string The new availability zone for the server. Yes
cpuFamily string Sets the desired CPU type. "AMD_OPTERON" or "INTEL_XEON" Yes
bootVolume string Reference to a Volume used for booting. If not ‘null’ then bootCdrom has to be ‘null’ Yes
bootCdrom string Reference to a CD-ROM used for booting. If not 'null' then bootVolume has to be 'null'. Yes
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/vnd.profitbricks.resource+json" \
     --data-binary '{
     "properties": {
        "name": "[server-name]",
        "cores": "[server-cores]",
        "ram": "[server-ram]",
        "availabilityZone": "[server-availability-zone]",
        "bootVolume": {
            "id": "[server-storage-volume-id]"
        },
        "bootCdrom": null
     }
}            ' \
     https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/servers/[server-id]

Response

202 (Accepted)
Content-Type: application/vnd.profitbricks.resource+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/rest/v2/datacenters/[data-center-id]/servers/[server-id]",
    "metadata": {
        "lastModifiedDate": "last-modified-date",
        "lastModifiedBy": "last-modified-by-user",
        "createdDate": "created-by-date",
        "createdBy": "created-by-user",
        "state": "server-state",
        "etag": "etag"
    },
    "properties": {
        "name": "server-name",
        "cores": "server-cores",
        "ram": "server-ram",
        "availabilityZone": "server-availability-zone",
        "bootVolume": {
            "id": "storage-id"
        },
        "bootCdrom": null
    },
    "entities": {
        "nics": [],
        "volumes": []
    }
}
Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
lastModifiedDate The last modified time for the resource.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state Status of the Virtual Machine.
etag The etag.
name The name of the server.
cores The number of cores for the server.
ram The amount of memory on the server.
availabilityZone The availability zone for the server.
cpuFamily Type of CPU assigned.
bootVolume Reference to a Volume used for booting. If not ‘null’ then bootCdrom has to be ‘null’
bootCdrom Reference to a CD-ROM used for booting. If not 'null' then bootVolume has to be 'null'.
cdroms A collection of cdroms attached to the server.
volumes A collection of volumes attached to the server.
nics A collection of NICs attached to the server.

Delete a Server

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

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/vnd.profitbricks.resource+json

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

Request Body

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

Request Parameters

None

Curl Example

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

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

Response

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

Response Parameters

None

List Attached Volumes

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

Request

Request Headers

The request headers should inclued the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

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

Request Parameters

None

Curl Example

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

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

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

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/servers/[server-id]/volumes?depth=1

Response

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

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

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

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

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

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

Response Parameters

A collection of volumes is returned.

Please reference the Volumes section for attribute definitions.

Attach a Volume

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

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/vnd.profitbricks.resource+json

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

Request Body

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

Request Parameters

The following table describes the request body values:

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

Curl Example

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

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

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.profitbricks.com/rest/v2/requests/[request-status-id]/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/vnd.profitbricks.resource+json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

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

Response Parameters

Please see the Volumes section for attribute definitions.

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

Retrieve an Attached Volume

This will retrieve the properties of an attached volume.

Request

Request Headers

The request headers should be the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/vnd.profitbricks.resource+json

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

Request Body

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

Request Parameters

None

Curl Example

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

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

Response

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

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

Response Parameters

Please see the Volumes section for attribute definitions.

Detach a Volume

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

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

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

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

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

Response

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

Response Parameters

None

List Attached CD-ROMs

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

Request

Request Headers

The request headers should be the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

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

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

Response

You should receive a response similar to this:

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

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

The response will contain a collection of CD-ROMs.

Response Parameters

Please reference the CD-ROMs section for attribute definitions.

Attach a CD-ROM

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

Request

Request Headers

The request headers should be the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/vnd.profitbricks.resource+json

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

Request Body

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

Request Parameters

None

Curl Example

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

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

Response

You should receive a response similar to this:

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.profitbricks.com/rest/v2/requests/[request-status-id]/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/vnd.profitbricks.resource+json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "[image-id]",
  "type" : "image",
  "href" : "https://api.profitbricks.com/rest/v2/images/[image-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "ubuntu-14.04.3-server-amd64.iso",
    "description" : "",
    "location" : "us/las",
    "size" : 0.57,
    "cpuHotPlug" : false,
    "cpuHotUnplug" : false,
    "ramHotPlug" : false,
    "ramHotUnplug" : false,
    "nicHotPlug" : false,
    "nicHotUnplug" : false,
    "discVirtioHotPlug" : false,
    "discVirtioHotUnplug" : false,
    "discScsiHotPlug" : false,
    "discScsiHotUnplug" : false,
    "licenceType" : "LINUX",
    "imageType" : "CDROM",
    "public" : false
  }
}

Response Parameters

Please reference the CD-ROMs section for attribute definitions.

Retrieve Attached CD-ROM

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

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

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

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

Response

You should receive a response similar to this:

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

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

Response Parameters

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

Detach a CD-ROM

This will detach a CD-ROM from the server.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

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

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

Response

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

Response Parameters

None

Reboot a Server

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

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

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

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

Response

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

Response Parameters

None

Start a Server

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

Request

Request Headers

The request headers should be the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

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

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

Response

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

Response Parameters

None

Stop a Server

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

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

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

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

Response

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

Response Parameters

None

Images

List Images

Retrieve a list of images within the data center.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

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

Curl Example

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

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

Response

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

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

Response Parameters

The request will return a collection of images.

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state Image state.
name The name of the image.
description The description of the image.
location The image's location.
size The size of the image in GB.
cpuHotPlug This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug This volume is capable of memory hot plug (no reboot required)
ramHotUnplug This volume is capable of memory hot unplug (no reboot required)
nicHotPlug This volume is capable of nic hot plug (no reboot required)
nicHotUnplug This volume is capable of nic hot unplug (no reboot required)
discVirtioHotPlug This volume is capable of Virt-IO drive hot plug (no reboot required)
discVirtioHotUnplug This volume is capable of Virt-IO drive hot unplug (no reboot required)
discScsiHotPlug This volume is capable of Scsi drive hot plug (no reboot required)
discScsiHotUnplug This volume is capable of Scsi drive hot unplug (no reboot required)
licenceType The image's licence type: LINUX, WINDOWS, WINDOWS2016, OTHER or UNKNOWN.
imageType The type of image: HDD, CDROM.
public Indicates if the image is part of the public repository or not.

Get Image

Retrieves the attributes of a specific image.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

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

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

Response

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

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

Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state Image state.
name The name of the image.
description The description of the image.
location The image's location.
size The size of the image in GB.
cpuHotPlug This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug This volume is capable of memory hot plug (no reboot required)
ramHotUnplug This volume is capable of memory hot unplug (no reboot required)
nicHotPlug This volume is capable of nic hot plug (no reboot required)
nicHotUnplug This volume is capable of nic hot unplug (no reboot required)
discVirtioHotPlug This volume is capable of Virt-IO drive hot plug (no reboot required)
discVirtioHotUnplug This volume is capable of Virt-IO drive hot unplug (no reboot required)
discScsiHotPlug This volume is capable of Scsi drive hot plug (no reboot required)
discScsiHotUnplug This volume is capable of Scsi drive hot unplug (no reboot required)
licenceType The image's licence type: LINUX, WINDOWS, WINDOWS2016, OTHER or UNKNOWN.
imageType The type of image: HDD, CDROM.
public Indicates if the image is part of the public repository or not.

Delete Image

Deletes the specified image.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

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

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

Response

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

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

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

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

Response Parameters

None

Update Image

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

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

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

In most cases you will be using PATCH.

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

PATCH

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

Request

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/vnd.profitbricks.partial-properties+json

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

Request Body

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

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

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

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

Response

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

{
  "id" : "[image-id]",
  "type" : "image",
  "href" : "https://api.profitbricks.com/rest/v2/images/[image-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "[name]",
    "description" : "Example Description",
    "location" : "[location]",
    "size" : 5,
    "cpuHotPlug" : false,
    "cpuHotUnplug" : false,
    "ramHotPlug" : false,
    "ramHotUnplug" : false,
    "nicHotPlug" : false,
    "nicHotUnplug" : false,
    "discVirtioHotPlug" : false,
    "discVirtioHotUnplug" : false,
    "discScsiHotPlug" : false,
    "discScsiHotUnplug" : false,
    "licenceType" : "LINUX",
    "imageType" : "HDD",
    "public" : false
  }
}
Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state Image state.
name The name of the image.
description The description of the image.
location The image's location.
size The size of the image in GB.
cpuHotPlug This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug This volume is capable of memory hot plug (no reboot required)
ramHotUnplug This volume is capable of memory hot unplug (no reboot required)
nicHotPlug This volume is capable of nic hot plug (no reboot required)
nicHotUnplug This volume is capable of nic hot unplug (no reboot required)
discVirtioHotPlug This volume is capable of Virt-IO drive hot plug (no reboot required)
discVirtioHotUnplug This volume is capable of Virt-IO drive hot unplug (no reboot required)
discScsiHotPlug This volume is capable of Scsi drive hot plug (no reboot required)
discScsiHotUnplug This volume is capable of Scsi drive hot unplug (no reboot required)
licenceType The image's licence type: LINUX, WINDOWS, WINDOWS2016, OTHER or UNKNOWN.
imageType The type of image: HDD, CDROM.
public Indicates if the image is part of the public repository or not.

PUT

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

Request

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/vnd.profitbricks.resource+json

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

Request Body

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

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

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

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

Response

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

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

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state Image state.
name The name of the image.
description The description of the image.
location The image's location.
size The size of the image in GB.
cpuHotPlug This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug This volume is capable of memory hot plug (no reboot required)
ramHotUnplug This volume is capable of memory hot unplug (no reboot required)
nicHotPlug This volume is capable of nic hot plug (no reboot required)
nicHotUnplug This volume is capable of nic hot unplug (no reboot required)
discVirtioHotPlug This volume is capable of Virt-IO drive hot plug (no reboot required)
discVirtioHotUnplug This volume is capable of Virt-IO drive hot unplug (no reboot required)
discScsiHotPlug This volume is capable of Scsi drive hot plug (no reboot required)
discScsiHotUnplug This volume is capable of Scsi drive hot unplug (no reboot required)
licenceType The image's licence type: LINUX, WINDOWS, WINDOWS2016, OTHER or UNKNOWN.
imageType The type of image: HDD, CDROM.
public Indicates if the image is part of the public repository or not.

Volumes

List Volumes

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

Request

Request Headers

The GET request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

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

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

Response

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

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

Response Parameters

The request will return a collection of volumes.

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

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state Volume state.
etag The etag for the resource.
name The name of the volume.
size The size of the volume in GB.
bus The bus type of the volume (VIRTIO or IDE). Default: VIRTIO.
image The image or snapshot ID.
deviceNumber The LUN ID of the storage volume. Null for volumes not mounted to any VM.
imagepassword Indicates if a password is set on the image.
type The volume type, HDD or SSD.
cpuHotPlug This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug This volume is capable of memory hot plug (no reboot required)
ramHotUnplug This volume is capable of memory hot unplug (no reboot required)
nicHotPlug This volume is capable of nic hot plug (no reboot required)
nicHotUnplug This volume is capable of nic hot unplug (no reboot required)
discVirtioHotPlug This volume is capable of Virt-IO drive hot plug (no reboot required)
discVirtioHotUnplug This volume is capable of Virt-IO drive hot unplug (no reboot required)
discScsiHotPlug This volume is capable of Scsi drive hot plug (no reboot required)
discScsiHotUnplug This volume is capable of Scsi drive hot unplug (no reboot required)

Get Volume

Retrieves the attributes of a given volume.

Request

Request Headers

The request headers should be the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

The following shows how to submit the request using curl:

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

Response

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

{
  "id" : "[volume-id]",
  "type" : "volume",
  "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/volumes/[volume-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "AVAILABLE"
  },
  "properties" : {
    "name" : "[Volume Name]",
    "type" : "HDD",
    "size" : 5,
    "image" : null,
    "imagePassword" : null,
    "sshKeys" : null,
    "bus" : "VIRTIO",
    "licenceType" : "LINUX",
    "cpuHotPlug" : false,
    "cpuHotUnplug" : false,
    "ramHotPlug" : false,
    "ramHotUnplug" : false,
    "nicHotPlug" : false,
    "nicHotUnplug" : false,
    "discVirtioHotPlug" : false,
    "discVirtioHotUnplug" : false,
    "discScsiHotPlug" : false,
    "discScsiHotUnplug" : false,
    "deviceNumber" : 1
   }
}

Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state Volume state.
name The name of the volume.
type The volume type, HDD or SSD.
size The size of the volume in GB.
image The image or snapshot ID.
imagepassword Indicates if a password is set on the image.
sshKeys SSH keys.
bus The bus type of the volume (VIRTIO or IDE). Default: VIRTIO.
licenceType Licence type. ( WINDOWS, WINDOWS2016, LINUX, OTHER, UNKNOWN)
cpuHotPlug This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug This volume is capable of memory hot plug (no reboot required)
ramHotUnplug This volume is capable of memory hot unplug (no reboot required)
nicHotPlug This volume is capable of nic hot plug (no reboot required)
nicHotUnplug This volume is capable of nic hot unplug (no reboot required)
discVirtioHotPlug This volume is capable of Virt-IO drive hot plug (no reboot required)
discVirtioHotUnplug This volume is capable of Virt-IO drive hot unplug (no reboot required)
discScsiHotPlug This volume is capable of Scsi drive hot plug (no reboot required)
discScsiHotUnplug This volume is capable of Scsi drive hot unplug (no reboot required)
deviceNumber The LUN ID of the storage volume.

Create Volume

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

Guidelines for SSD Volume Sizing

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

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

To get the best performance from SSD volumes, it is recommended that you provision a SSD volume of at least 100 GB in size. As you increase SSD volume size above 100GB, your IOPS and available storage bandwidth will also increase. The optimal combination of IOPS and storage bandwidth capability on the 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. Attaching multiple SSD volumes to a single server, or provisioning a SSD volume larger than 1TB, may result in a decrease in maximum performance.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/vnd.profitbricks.resource+json

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

Request Body

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

The format of the request body is as follows:

{
    "properties": {
        "size": volume-size-in-gb,
        "name": "volume-name",
        "image": "image-or-snapshot-id",
        "bus": "volume-bus-type",
        "type": "type",
        "licenceType": "licenceType"
    }
}

Request Parameters

Name Type Description Required
name string The name of the volume. No
size int The size of the volume in GB. Yes
bus string The bus type of the volume (VIRTIO or IDE). Default: VIRTIO. No
image string The image or snapshot ID. Yes*
type string The volume type, HDD or SSD. Yes
licenceType string The licence type of the volume. Options: LINUX, WINDOWS, WINDOWS2016, UNKNOWN, OTHER Yes*
imagePassword string One-time password is set on the Image for the appropriate account. This field may only be set in creation requests. When reading, it always returns null. Password has to contain 8-50 characters. Only these characters are allowed: [abcdefghjkmnpqrstuvxABCDEFGHJKLMNPQRSTUVX23456789] No
sshKeys string SSH keys to allow access to the volume via SSH No

*You will need to provide either the image or the licenceType parameters. licenceType is required, but if image is supplied, it will already have a licenceType set.

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

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

Curl Example

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

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

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.profitbricks.com/rest/v2/requests/[request-status-id]/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/vnd.profitbricks.resource+json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

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

Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state Volume state.
name The name of the volume.
type The volume type, HDD or SSD.
size The size of the volume in GB.
image The image or snapshot ID.
imagePassword Indicates if a password is set on the image.
sshKeys SSH keys.
bus The bus type of the volume (VIRTIO or IDE). Default: VIRTIO.
licenceType Licence type. ( WINDOWS, WINDOWS2016, LINUX, OTHER, UNKNOWN)
cpuHotPlug This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug This volume is capable of memory hot plug (no reboot required)
ramHotUnplug This volume is capable of memory hot unplug (no reboot required)
nicHotPlug This volume is capable of nic hot plug (no reboot required)
nicHotUnplug This volume is capable of nic hot unplug (no reboot required)
discVirtioHotPlug This volume is capable of Virt-IO drive hot plug (no reboot required)
discVirtioHotUnplug This volume is capable of Virt-IO drive hot unplug (no reboot required)
discScsiHotPlug This volume is capable of Scsi drive hot plug (no reboot required)
discScsiHotUnplug This volume is capable of Scsi drive hot unplug (no reboot required)
deviceNumber The LUN ID of the storage volume.

Delete Volume

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

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

The following shows how to submit the request using curl:

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

Response

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

Response Parameters

None

Update Volume

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

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

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

In most cases you will be using PATCH.

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

You can 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 hot plug settings have been set to true. The additional capacity is not added to any partition therefore you will need to partition it afterwards. Once you have increased the volume size you cannot decrease the volume size.

PATCH

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

Request

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/vnd.profitbricks.partial-properties+json

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

Request Body

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

Request Parameters

Since we are modifying an existing volume, none of the request parameters are specifically required as long as the changes being made satisfy the requirements for creating a volume.

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 \
     --header "Content-Type: application/vnd.profitbricks.partial-properties+json" \
     --data-binary '    {
          "name": "TestVolumeRename",
          "size": 10
    }' \
     https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/volumes/[volume-id]

Response

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

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

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state Volume state.
name The name of the volume.
type The volume type, HDD or SSD.
size The size of the volume in GB.
image The image or snapshot ID.
imagePassword Indicates if a password is set on the image.
sshKeys SSH keys.
bus The bus type of the volume (VIRTIO or IDE). Default: VIRTIO.
licenceType Licence type. ( WINDOWS, WINDOWS2016, LINUX, OTHER, UNKNOWN)
cpuHotPlug This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug This volume is capable of memory hot plug (no reboot required)
ramHotUnplug This volume is capable of memory hot unplug (no reboot required)
nicHotPlug This volume is capable of nic hot plug (no reboot required)
nicHotUnplug This volume is capable of nic hot unplug (no reboot required)
discVirtioHotPlug This volume is capable of Virt-IO drive hot plug (no reboot required)
discVirtioHotUnplug This volume is capable of Virt-IO drive hot unplug (no reboot required)
discScsiHotPlug This volume is capable of Scsi drive hot plug (no reboot required)
discScsiHotUnplug This volume is capable of Scsi drive hot unplug (no reboot required)
deviceNumber The LUN ID of the storage volume.

PUT

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

Request

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/vnd.profitbricks.resource+json

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

Request Body

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

Request Parameters
Name Type Description Required
name string The name of the volume. No
size int The size of the volume in GB. Yes
bus string The bus type of the volume (VIRTIO or IDE). Default: VIRTIO. No
image string The image or snapshot ID. Immutable
type string The volume type, HDD or SSD. Immutable
licenceType string The licence type of the volume. Options: LINUX, WINDOWS, WINDOWS2016, UNKNOWN, OTHER Immutable
imagePassword string One-time password is set on the Image for the appropriate account. This field may only be set in creation requests. When reading, it always returns null. Password has to contain 8-50 characters. Only these characters are allowed: [abcdefghjkmnpqrstuvxABCDEFGHJKLMNPQRSTUVX23456789] No
sshKeys string SSH keys to allow access to the volume via SSH No

*When changes are being made to an existing volume using a PUT request there are multiple properties that only set at volume creation and therefore immutable.

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/vnd.profitbricks.resource+json" \
     --data-binary '{
        "properties": {
            "name": "TestVolume01Replaced",
            "size": 12,
            "bus": "VIRTIO"
        }
    }    ' \
     https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/volumes/[volume-id]

Response

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

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

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state Volume state.
name The name of the volume.
type The volume type, HDD or SSD.
size The size of the volume in GB.
image The image or snapshot ID.
imagePassword Indicates if a password is set on the image.
sshKeys SSH keys.
bus The bus type of the volume (VIRTIO or IDE). Default: VIRTIO.
licenceType Licence type. ( WINDOWS, WINDOWS2016, LINUX, OTHER, UNKNOWN)
cpuHotPlug This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug This volume is capable of memory hot plug (no reboot required)
ramHotUnplug This volume is capable of memory hot unplug (no reboot required)
nicHotPlug This volume is capable of nic hot plug (no reboot required)
nicHotUnplug This volume is capable of nic hot unplug (no reboot required)
discVirtioHotPlug This volume is capable of Virt-IO drive hot plug (no reboot required)
discVirtioHotUnplug This volume is capable of Virt-IO drive hot unplug (no reboot required)
discScsiHotPlug This volume is capable of Scsi drive hot plug (no reboot required)
discScsiHotUnplug This volume is capable of Scsi drive hot unplug (no reboot required)
deviceNumber The LUN ID of the storage volume.

Create Volume Snapshot

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

Request

Request Headers

The request headers should be the following:

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

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

Request Body

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

Request Parameters

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

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

Curl Example

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

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

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

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.profitbricks.com/rest/v2/requests/[request-status-id]/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/vnd.profitbricks.resource+json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "[snapshot-id]",
  "type" : "snapshot",
  "href" : "https://api.profitbricks.com/rest/v2/snapshots/[snapshot-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "TestSnapshot01",
    "description" : "Created from \"[volume-name]\" in Data Center \"[data-center-name]\"",
    "location" : "us/las",
    "size" : null,
    "cpuHotPlug" : false,
    "cpuHotUnplug" : false,
    "ramHotPlug" : false,
    "ramHotUnplug" : false,
    "nicHotPlug" : false,
    "nicHotUnplug" : false,
    "discVirtioHotPlug" : false,
    "discVirtioHotUnplug" : false,
    "discScsiHotPlug" : false,
    "discScsiHotUnplug" : false,
    "licenceType" : null
  }
}

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

Response Parameters

None

Restore Volume Snapshot

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

Request

Request Headers

The request headers should be the following:

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

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

Request Body

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

Request Parameters

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

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

Curl Example

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

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

Response

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

Response Parameters

None

Snapshots

List Snapshots

Retrieve a list of snapshots within the data center.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

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

Curl Example

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

curl --include \
     --request GET \
     --user 'username@domain.tld:password" \
     https://api.profitbricks.com/rest/v2/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/vnd.profitbricks.collection+json
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

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

Response Parameters

The request will return a collection of snapshots.

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

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

Get Snapshot

Retrieves the attributes of a specific snapshot.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

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

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

Response

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

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

Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state Snapshot state.
name The name of the snapshot.
description The description of the snapshot.
location The snapshot's location.
size The size of the snapshot in GB.
cpuHotPlug This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug This volume is capable of memory hot plug (no reboot required)
ramHotUnplug This volume is capable of memory hot unplug (no reboot required)
nicHotPlug This volume is capable of NIC hot plug (no reboot required)
nicHotUnplug This volume is capable of NIC hot unplug (no reboot required)
discVirtioHotPlug This volume is capable of Virt-IO drive hot plug (no reboot required)
discVirtioHotUnplug This volume is capable of Virt-IO drive hot unplug (no reboot required)
discScsiHotPlug This volume is capable of SCSI drive hot plug (no reboot required)
discScsiHotUnplug This volume is capable of SCSI drive hot unplug (no reboot required)
licenceType The snapshot's licence type: LINUX, WINDOWS, WINDOWS2016, OTHER or UNKNOWN.

Delete Snapshot

Deletes the specified snapshot.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

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

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

Response

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

Response Parameters

None

Update Snapshot

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

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

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

In most cases you will be using PATCH.

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

PATCH

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

Request

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/vnd.profitbricks.partial-properties+json

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

Request Body

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

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

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

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

Response

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

{
  "id" : "[snapshot-id]",
  "type" : "snapshot",
  "href" : "https://api.profitbricks.com/rest/v2/snapshots/[snapshot-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "Test Snapshot Rename",
    "description" : "Updated Description",
    "location" : "us/las",
    "size" : 5,
    "cpuHotPlug" : false,
    "cpuHotUnplug" : false,
    "ramHotPlug" : false,
    "ramHotUnplug" : false,
    "nicHotPlug" : false,
    "nicHotUnplug" : false,
    "discVirtioHotPlug" : false,
    "discVirtioHotUnplug" : false,
    "discScsiHotPlug" : false,
    "discScsiHotUnplug" : false,
    "licenceType" : "LINUX"
  }
}
Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state Snapshot state.
name The name of the snapshot.
description The description of the snapshot.
location The snapshot's location.
size The size of the snapshot in GB.
cpuHotPlug This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug This volume is capable of memory hot plug (no reboot required)
ramHotUnplug This volume is capable of memory hot unplug (no reboot required)
nicHotPlug This volume is capable of nic hot plug (no reboot required)
nicHotUnplug This volume is capable of nic hot unplug (no reboot required)
discVirtioHotPlug This volume is capable of Virt-IO drive hot plug (no reboot required)
discVirtioHotUnplug This volume is capable of Virt-IO drive hot unplug (no reboot required)
discScsiHotPlug This volume is capable of SCSI drive hot plug (no reboot required)
discScsiHotUnplug This volume is capable of SCSI drive hot unplug (no reboot required)
licenceType The snapshot's licence type: LINUX, WINDOWS, WINDOWS2016, OTHER or UNKNOWN.

PUT

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

Request

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/vnd.profitbricks.resource+json

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

Request Body

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

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

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

curl --include \
     --request PUT \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/vnd.profitbricks.resource+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/rest/v2/snapshots/[snapshot-id]

Response

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

{
  "id" : "[snapshot-id]",
  "type" : "snapshot",
  "href" : "https://api.profitbricks.com/rest/v2/snapshots/[snapshot-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "Snapshot New Name",
    "description" : "Updated Snapshot Description",
    "location" : "us/las",
    "size" : 5,
    "cpuHotPlug" : false,
    "cpuHotUnplug" : false,
    "ramHotPlug" : false,
    "ramHotUnplug" : false,
    "nicHotPlug" : false,
    "nicHotUnplug" : false,
    "discVirtioHotPlug" : false,
    "discVirtioHotUnplug" : false,
    "discScsiHotPlug" : true,
    "discScsiHotUnplug" : true,
    "licenceType" : "OTHER"
  }
}
Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state Snapshot state.
name The name of the snapshot.
description The description of the snapshot.
location The snapshot's location.
size The size of the snapshot in GB.
cpuHotPlug This volume is capable of CPU hot plug (no reboot required)
cpuHotUnplug This volume is capable of CPU hot unplug (no reboot required)
ramHotPlug This volume is capable of memory hot plug (no reboot required)
ramHotUnplug This volume is capable of memory hot unplug (no reboot required)
nicHotPlug This volume is capable of NIC hot plug (no reboot required)
nicHotUnplug This volume is capable of NIC hot unplug (no reboot required)
discVirtioHotPlug This volume is capable of Virt-IO drive hot plug (no reboot required)
discVirtioHotUnplug This volume is capable of Virt-IO drive hot unplug (no reboot required)
discScsiHotPlug This volume is capable of SCSI drive hot plug (no reboot required)
discScsiHotUnplug This volume is capable of SCSI drive hot unplug (no reboot required)
licenceType The snapshot's licence type: LINUX, WINDOWS, WINDOWS2016, OTHER or UNKNOWN.

IP Block

List IP Blocks

Retrieve a list of IP Blocks within the data center.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To retrieve a list of IP Blocks you would send a GET request to https://api.profitbricks.com/rest/v2/ipblocks

Request Parameters

None

Curl Example

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

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/rest/v2/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/vnd.profitbricks.collection+json
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

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

Response Parameters

The request will return a collection of IP Blocks.

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

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

Get IP Block

Retrieves the attributes of a specific IP Block.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To retrieve a single IP Block you would send a GET request to https://api.profitbricks.com/rest/v2/ipblocks/[ipblock-id]

Request Parameters

None

Curl Example

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

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

Response

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

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

Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
ips A collection of IPs associated with the IP Block.
location Location the IP block resides in.
size Number of IP addresses in the block.
name A descriptive name given to the IP block.

Create IP Block

Creates an IP block within the data center.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/vnd.profitbricks.resource+json

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

Request Body

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

Request Parameters

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

Curl Example

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

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

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.profitbricks.com/rest/v2/requests/[request-id]/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/vnd.profitbricks.resource+json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "[ip-block-id]",
  "type" : "ipblock",
  "href" : "https://api.profitbricks.com/rest/v2/ipblocks/[ip-block-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[username]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[timestamp]",
    "lastModifiedBy" : "[username]",
    "state" : "BUSY"
  },
  "properties" : {
    "ips" : [ "[ip-address]", "[second-ip-address]" ],
    "location" : "[location]",
    "size" : 2,
    "name" : "[Descriptive Name]"
  }
}

Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state Status of the IP block. (BUSY, AVAILABLE)
etag The etag for the resource.
size The number of IPs in the block.
ips A collection of IPs associated with the IP Block.
location Location the IP block resides in.
name Descriptive name for the IP block.

Update IP Block

Updates an IP block.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/vnd.profitbricks.resource+json

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

Request Body

To update an IP block, send a PATCH or PUT request to https://api.profitbricks.com/rest/v2/ipblocks/[ipblock-id]

Request Parameters

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

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

Curl Example

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

curl --include
 --request PATCH \
 --user 'username@domain.tld:password' \
 --header "Content-Type: application/vnd.profitbricks.resource+json" \
 --data-binary '{
    "name": "Updated Name"
    }' \
'https://api.profitbricks.com/rest/v2/ipblocks/[ipblock-id]'

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

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

curl --include \
     --request PUT \
     --user 'username@domain.tld:password' \
     --header "Content-Type: application/vnd.profitbricks.resource+json" \
     --data-binary '{
        "properties": {
            "name": "Updated Name"
        }
    }' \
'https://api.profitbricks.com/rest/v2/ipblocks/[ipblock-id]'

Response

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

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.profitbricks.com/rest/v2/requests/[request-id]/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/vnd.profitbricks.resource+json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "[ip-block-id]",
  "type" : "ipblock",
  "href" : "https://api.profitbricks.com/rest/v2/ipblocks/[ip-block-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[username]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[timestamp]",
    "lastModifiedBy" : "[username]",
    "state" : "BUSY"
  },
  "properties" : {
    "ips" : [ "[ip-address]", "[second-ip-address]" ],
    "location" : "[location]",
    "size" : 2,
    "name" : "[Updated Name]"
  }
}

Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state Status of the IP block. (BUSY, AVAILABLE)
etag The etag for the resource.
size The number of IPs in the block.
ips A collection of IPs associated with the IP Block.
location Location the IP block resides in.
name Descriptive name for the IP block.

Delete IP Block

Deletes the specified IP Block.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

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

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

Response

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

Response Parameters

None

LANs

List LANs

Retrieve a list of LANs within the data center.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

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

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

Response

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

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

{
  "id" : "[data-center-id]/lans",
  "type" : "collection",
  "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/lans",
  "items" : [ {
    "id" : "3",
    "type" : "lan",
    "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/lans/3"
  }, {
    "id" : "1",
    "type" : "lan",
    "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/lans/1"
  }, {
    "id" : "2",
    "type" : "lan",
    "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/lans/2"
  } ]
}

Response Parameters

The request will return a collection of LANs.

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

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state LAN state.
etag The etag for the resource.
public Boolean indicating if the LAN faces the public Internet or not.
nics A collection of NICs associated with the LAN.

Get LAN

Retrieves the attributes of a given LAN.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

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

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

Response

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

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

Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state LAN state.
etag The etag for the resource.
name A descriptive name for the LAN.
public Boolean indicating if the LAN faces the public Internet or not.
nics A collection of NICs associated with the LAN.

Create LAN

Creates a LAN within a data center.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/vnd.profitbricks.resource+json

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

Request Body

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

The format of the request body is as follows:

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

Request Parameters

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

Curl Example

The following shows how to create a LAN via curl:

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

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.profitbricks.com/rest/v2/requests/[request-status-id]/staus
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/vnd.profitbricks.resource+json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

{
  "id" : "5",
  "type" : "lan",
  "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/lans/5",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "[descriptive-name]",
    "public" : false
  }
}

Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state LAN state.
etag The etag for the resource.
name A descriptive name assigned to the LAN object.
public Boolean indicating if the LAN faces the public Internet or not.
nics A collection of NICs associated with the LAN. See the NIC section for attribute descriptions.

Delete LAN

Deletes the specified LAN.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

The following shows how to submit the request using curl:

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

Response

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

Response Parameters

None

Update LAN

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

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

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

In most cases you will be using PATCH.

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

PATCH

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

Request

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/vnd.profitbricks.partial-properties+json

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

Request Body

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

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

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

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

Response

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

{
  "id" : "3",
  "type" : "lan",
  "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/lans/3",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "[descriptive-name]",
    "public" : false
  },
  "entities" : {
    "nics" : {
      "id" : "3/nics",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/lans/3/nics"
    }
  }
}
Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state LAN state.
etag The etag for the resource.
name A descriptive name for the LAN
public Boolean indicating if the LAN faces the public Internet or not.
nics A collection of NICs associated with the LAN.

PUT

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

Request

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/vnd.profitbricks.resource+json

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

Request Body

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

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

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

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

Response

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

{
  "id" : "4",
  "type" : "lan",
  "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/lans/4",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "NewLANName",
    "public" : true
  },
  "entities" : {
    "nics" : {
      "id" : "4/nics",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/lans/4/nics"
    }
  }
}
Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state LAN state.
etag The etag for the resource.
name A descriptive name for the LAN.
public Boolean indicating if the LAN faces the public Internet or not.
nics A collection of NICs associated with the LAN.

Network Interfaces

List NICs

Retrieves a list of NICs.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

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

Curl Example

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

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

Response

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

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

Response Parameters

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

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state NIC state.
etag The etag for the resource.
name The name of the NIC.
mac The MAC address of the NIC.
ips IPs assigned to the NIC represented as a collection.
dhcp Boolean value that indicates if the NIC is using DHCP or not.
lan The LAN ID the NIC sits on.
firewallActive A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.
firewallrules A list of firewall rules associated to the NIC represented as a collection.

Get a NIC

Retrieves the attributes of a given NIC.

Request

Request Headers

The request headers should be the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

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

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

Response

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

{
  "id" : "[nic-id]",
  "type" : "nic",
  "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "AVAILABLE"
  },
  "properties" : {
    "name" : null,
    "mac" : "02:00:22:11:bb:00",
    "ips" : [ "162.254.1.1" ],
    "dhcp" : true,
    "lan" : 1,
    "firewallActive" : false
  },
  "entities" : {
    "firewallrules" : {
      "id" : "[nic-id]/firewallrules",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]/firewallrules"
    }
  }
}

Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state NIC state.
name The name of the NIC.
mac The MAC address of the NIC.
ips IPs assigned to the NIC represented as a collection.
dhcp Boolean value that indicates if the NIC is using DHCP or not.
lan The LAN ID the NIC sits on.
firewallActive A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.
firewallrules A list of firewall rules associated to the NIC represented as a collection.

Create a NIC

Adds a NIC to the target server.

Request

Request Headers

The request headers should include the following:

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

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

Request Body

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

The format of the request body is as follows:

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

Request Parameters

Name Type Description Required
name string The name of the NIC.
ips string collection IPs assigned to the NIC. This can be a collection.
dhcp bool Set to FALSE if you wish to disable DHCP on the NIC. Default: TRUE.
lan int The LAN ID the NIC will sit on. If the LAN ID does not exist it will be created. Yes
firewallActive bool A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.
firewallrules string collection A list of firewall rules associated to the NIC represented as a collection.

Curl Example

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

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

Response

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

{
  "id" : "[nic-id]",
  "type" : "nic",
  "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "Internal NIC",
    "mac" : null,
    "ips" : [ "10.1.1.2" ],
    "dhcp" : false,
    "lan" : 2,
    "firewallActive" : null
  }
}

Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state NIC state. AVAILABLE, BUSY
name The name of the NIC.
mac The MAC address of the NIC.
ips IPs assigned to the NIC represented as a collection.
dhcp Boolean value that indicates if the NIC is using DHCP or not.
lan The LAN ID the NIC sits on.
firewallActive A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.
firewallrules A list of firewall rules associated to the NIC represented as a collection.

Delete a NIC

Deletes the specified NIC.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

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

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

Response

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

Response Parameters

None

Update a NIC

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

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

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

In most cases you will be using PATCH.

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

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

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

PATCH

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

Request

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/vnd.profitbricks.partial-properties+json

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

Request Body

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

Request Parameters
Name Type Description Required
name string The name of the NIC.
ips string collection IPs assigned to the NIC represented as a collection.
dhcp bool Boolean value that indicates if the NIC is using DHCP or not.
lan int The LAN ID the NIC sits on.
firewallActive bool A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.
Curl Example

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

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

Response

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

{
  "id" : "[nic-id]",
  "type" : "nic",
  "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
 },
 "properties" : {
    "name" : "Heartbeat NIC",
    "mac" : "02:01:f8:bb:66:00",
    "ips" : [ "10.1.1.3" ],
    "dhcp" : false,
    "lan" : 2,
    "firewallActive" : false
  },
  "entities" : {
     "firewallrules" : {
      "id" : "[nic-id]/firewallrules",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]/firewallrules"
    }
  }
}
Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state NIC state. AVAILABLE, BUSY
name The name of the NIC.
mac The MAC address of the NIC.
ips IPs assigned to the NIC represented as a collection.
dhcp Boolean value that indicates if the NIC is using DHCP or not.
lan The LAN ID the NIC sits on.
firewallActive A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.
firewallrules A list of firewall rules associated to the NIC represented as a collection.

PUT

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

Request

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

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

Request Body

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

Request Parameters
Name Type Description Required
name string The name of the NIC. Yes
ips string collection IPs assigned to the NIC represented as a collection. Yes
dhcp bool Boolean value that indicates if the NIC is using DHCP or not. Yes
lan int The LAN ID the NIC sits on. Yes
firewallActive bool A true value indicates the firewall is enabled. A false value indicates the firewall is disabled. Yes
Curl Example

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

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

Response

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

{
  "id" : "[nic-id]",
  "type" : "nic",
  "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "Failover NIC",
    "mac" : "02:01:f8:bb:66:00",
    "ips" : [ "10.1.1.4" ],
    "dhcp" : false,
    "lan" : 2,
    "firewallActive" : false
  },
  "entities" : {
     "firewallrules" : {
      "id" : "[nic-id]/firewallrules",
      "type" : "collection",
      "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]/firewallrules"
    }
  }
}
Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state NIC state. AVAILABLE, BUSY
name The name of the NIC.
mac The MAC address of the NIC.
ips IPs assigned to the NIC represented as a collection.
dhcp Boolean value that indicates if the NIC is using DHCP or not.
lan The LAN ID the NIC sits on.
firewallActive A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.
firewallrules A list of firewall rules associated to the NIC represented as a collection.

Firewall Rules

List Firewall Rules

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

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

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

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

Response

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

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

Response Parameters

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

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

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

Get Firewall Rule

Retrieves the attributes of a given firewall rule.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

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

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

Response

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

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

Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state The firewall rule state. AVAILABLE, BUSY, INACTIVE
name The name of the Firewall Rule.
protocol The protocol for the rule: TCP, UDP, ICMP, ANY.
sourceMac Only traffic originating from the respective MAC address is allowed. Valid format: aa:bb:cc:dd:ee:ff. Value null allows all source MAC address.
sourceIp Only traffic originating from the respective IPv4 address is allowed. Value null allows all source IPs.
targetIp In case the target NIC has multiple IP addresses, only traffic directed to the respective IP address of the NIC is allowed. Value null allows all target IPs.
icmpType Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value null allows all types.
icmpCode Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value null allows all codes.
portRangeStart Defines the start range of the allowed port (from 1 to 65534) if protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd value null to allow all ports.
portRangeEnd Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd null to allow all ports.

Create Firewall Rule

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

Request

Request Headers

The request headers should include the following:

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

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

Request Body

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

The format of the request body is as follows:

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

Request Parameters

Name Type Description Required
name string The name of the firewall rule.
protocol string The protocol for the rule: TCP, UDP, ICMP, ANY. Yes
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.
portRangeStart string Defines the start range of the allowed port (from 1 to 65534) if protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd value null to allow all ports.
portRangeEnd string Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd null to allow all ports.
icmpType string Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value null allows all types.
icmpCode string Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value null allows all codes.

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/rest/v2/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]/firewallrules

Response

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

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

Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state The firewall rule state. AVAILABLE, BUSY, INACTIVE
name The name of the Firewall Rule.
protocol The protocol for the rule: TCP, UDP, ICMP, ANY.
sourceMac Only traffic originating from the respective MAC address is allowed. Valid format: aa:bb:cc:dd:ee:ff. Value null allows all source MAC address.
sourceIp Only traffic originating from the respective IPv4 address is allowed. Value null allows all source IPs.
targetIp In case the target NIC has multiple IP addresses, only traffic directed to the respective IP address of the NIC is allowed. Value null allows all target IPs.
icmpType Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value null allows all types.
icmpCode Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value null allows all codes.
portRangeStart Defines the start range of the allowed port (from 1 to 65534) if protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd value null to allow all ports.
portRangeEnd Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd null to allow all ports.

Delete Firewall Rule

Removes the specific firewall rule.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

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

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

Response

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

Response Parameters

None

Update Firewall Rule

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

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

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

In most cases you will be using PATCH.

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

PATCH

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

Request

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/vnd.profitbricks.partial-properties+json

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

Request Body

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

Request Parameters
Name Type Description Required
name string The name of the Firewall Rule.
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.
portRangeStart string Defines the start range of the allowed port (from 1 to 65534) if protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd value null to allow all ports.
portRangeEnd string Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd null to allow all ports.
icmpType string Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value null allows all types.
icmpCode string Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value null allows all codes.
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/rest/v2/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]/firewallrules/[firewall-rule-id]'

Response

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

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

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state The firewall rule state. BUSY, AVAILABLE, INACTIVE
name The name of the firewall rule.
protocol The protocol for the rule: TCP, UDP, ICMP, ANY.
sourceMac Only traffic originating from the respective MAC address is allowed. Valid format: aa:bb:cc:dd:ee:ff. Value null allows all source MAC address.
sourceIp Only traffic originating from the respective IPv4 address is allowed. Value null allows all source IPs.
targetIp In case the target NIC has multiple IP addresses, only traffic directed to the respective IP address of the NIC is allowed. Value null allows all target IPs.
icmpType Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value null allows all types.
icmpCode Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value null allows all codes.
portRangeStart Defines the start range of the allowed port (from 1 to 65534) if protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd value null to allow all ports.
portRangeEnd Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd null to allow all ports.

PUT

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

Request

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

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

Request Body

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

Request Parameters
Name Type Description Required
name string The name of the firewall rule. Yes
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. Yes
sourceIp string Only traffic originating from the respective IPv4 address is allowed. Value null allows all source IPs. Yes
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. Yes
icmpCode string Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value null allows all codes. Yes
icmpType string Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value null allows all types. Yes
portRangeStart string Defines the start range of the allowed port (from 1 to 65534) if protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd value null to allow all ports. Yes
portRangeEnd string Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd null to allow all ports. Yes
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/rest/v2/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]/firewallrules/[firewall-rule-id]'

Response

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

{
  "id" : "[firewall-rule-id]",
  "type" : "firewall-rule",
  "href" : "https://api.profitbricks.com/rest/v2/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]/firewallrules/[firewall-rule-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "lastModifiedDate" : "[date]",
    "lastModifiedBy" : "[user]",
    "state" : "BUSY"
  },
  "properties" : {
    "name" : "SSH Port Plus One",
    "protocol" : "TCP",
    "sourceMac" : "01:23:45:67:89:00",
    "sourceIp" : "1.2.3.4",
    "targetIp" : "5.6.7.8",
    "icmpCode" : null,
    "icmpType" : null,
    "portRangeStart" : 22,
    "portRangeEnd" : 23
  }
}
Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state The firewall rule state. BUSY, AVAILABLE, INACTIVE
name The name of the Firewall Rule.
protocol The protocol for the rule: TCP, UDP, ICMP, ANY
sourceMac Only traffic originating from the respective MAC address is allowed. Valid format: aa:bb:cc:dd:ee:ff. Value null allows all source MAC address.
sourceIp Only traffic originating from the respective IPv4 address is allowed. Value null allows all source IPs.
targetIp In case the target NIC has multiple IP addresses, only traffic directed to the respective IP address of the NIC is allowed. Value null allows all target IPs.
icmpType Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value null allows all types.
icmpCode Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value null allows all codes.
portRangeStart Defines the start range of the allowed port (from 1 to 65534) if protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd value null to allow all ports.
portRangeEnd Defines the end range of the allowed port (from 1 to 65534) if the protocol TCP or UDP is chosen. Leave portRangeStart and portRangeEnd null to allow all ports.

Load Balancers

List Load Balancers

Retrieve a list of loadbalancers within the data center.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

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

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

Response

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

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

Response Parameters

The request will return a collection of loadbalancers.

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

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state Load Balancer state.
etag The etag for the resource.
name The name of the loadbalancer.
ip IPv4 address of the loadbalancer. All attached NICs will inherit this IP.
dhcp Indicates if the loadbalancer will reserve an IP using DHCP.
balancedNics A collection of NICs being loadbalanced.

Get Load Balancer

Retrieves the attributes of a given loadbalancer.

Request

Request Headers

The request headers should be the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

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

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

Response

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

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

Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state Load Balancer state.
etag The etag for the resource.
name The name of the loadbalancer.
ip IPv4 address of the loadbalancer. All attached NICs will inherit this IP.
dhcp Indicates if the loadbalancer will reserve an IP using DHCP.
balancedNics A collection of NICs being loadbalanced.

Create Load Balancer

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

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/vnd.profitbricks.resource+json

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

Request Body

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

The format of the request body is as follows:

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

Request Parameters

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

Curl Example

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

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

Response

HTTP/1.1 202 Accepted
Date: [date]
Server: ""
Location: https://api.profitbricks.com/rest/v2/requests/[request-status-id]/status
X-RateLimit-Remaining: 49
X-RateLimit-Burst: 50
X-RateLimit-Limit: 120
ETag: [etag]
Content-Type: application/vnd.profitbricks.resource+json
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked

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

Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
createdDate The date the resource was created.
createdBy The user who created the resource.
etag The etag for the resource.
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
state Loadbalancer state.
name The name of the loadbalancer.
ip IPv4 address of the loadbalancer. All attached NICs will inherit this IP.
dhcp Indicates if the loadbalancer will reserve an IP using DHCP.
balancednics List of NICs taking part in load-balancing. All balanced nics inherit the IP of the loadbalancer. See the NIC section for attribute definitions.

Delete Load Balancer

Deletes the specified loadbalancer.

Request

Request Headers

The request headers should be the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/vnd.profitbricks.resource+json

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

Request Body

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

Request Parameters

None

Curl Example

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

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

Response

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

Response Parameters

None

Update Load Balancer

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

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

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

In most cases you will be using PATCH.

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

PATCH

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

Request

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/vnd.profitbricks.partial-properties+json

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

Request Body

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

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

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

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

Response

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

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state Load Balancer state.
etag The etag for the resource.
name The name of the loadbalancer.
ip IPv4 address of the loadbalancer. All attached NICs will inherit this IP.
dhcp Indicates if the loadbalancer will reserve an IP using DHCP.
balancednics List of NICs taking part in load-balancing. All balanced nics inherit the IP of the loadbalancer. See the NIC section for attribute definitions.

PUT

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

Request

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/vnd.profitbricks.resource+json

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

Request Body

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

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

The following shows how to submit the request using curl:

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

Response

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

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state Load Balancer state.
etag The etag for the resource.
name The name of the loadbalancer.
ip IPv4 address of the loadbalancer. All attached NICs will inherit this IP.
dhcp Indicates if the loadbalancer will reserve an IP using DHCP.
balancednics List of NICs taking part in load-balancing. All balanced nics inherit the IP of the loadbalancer. See the NIC section for attribute definitions.

List Load Balanced NICs

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

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

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

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

Response

{
  "id": "[loadbalancer_id]/balancednics",
  "type": "collection",
  "href": "[base-url]/datacenters/[data-center-id]/loadbalancers/[loadbalancer-id]/balancednics",
  "items": [
    {
      "id": "[nic-id]",
      "type": "nic",
      "href": "/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]",
      "metadata": {
        "lastModifiedDate": "last-modified-date",
        "lastModifiedBy": "last-modified-by",
        "createdDate": "created-date",
        "createdBy": "created-by",
        "state": "state",
        "etag": "etag"
      },
      "properties": {
        "name": "my-nic-name",
        "mac": "nic-mac",
        "ips": [
          "nic-ip"
        ],
        "dhcp": "true",
        "lan": lan-id,
        "firewallActive": is-firewall-active
      },
      "entities": {
        "firewallrules": {
          "id": "{nic_id}/firewallrules",
          "type": "collection",
          "href": "/datacenters/[data-center-id]/servers/[server-id]/nics/[nic-id]/firewallrules"
        }
      }
    }
  ]
}

Response Parameters

The request will return a collection of loadbalanced NICs.

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

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state Load Balancer state.
etag The etag for the resource.
items A collection that represent a list of NICs.

Get Load Balanced NIC

Retrieves the attributes of a given loadbalanced NIC.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

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

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

Response

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

Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state NIC state.
etag The etag for the resource.
name The name of the NIC.
mac The MAC address of the NIC.
ips IPs assigned to the NIC represented as a collection.
dhcp Boolean value that indicates if the NIC is using DHCP or not.
lan The LAN ID the NIC sits on.
firewallActive Once you add a firewall rule this will reflect a true value.
firewallrules A list of firewall rules associated to the NIC represented as a collection.

Associate NIC to Load Balancer

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

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==
Content-Type: application/vnd.profitbricks.resource+json

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

Request Body

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

The format of the request body is as follows:

{
  "id": "[nic_id]"
}

Request Parameters

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

Curl Example

The following shows how to submit the request using curl:

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

Response

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

Response Parameters

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state NIC state.
etag The etag for the resource.
name The name of the NIC.
mac The MAC address of the NIC.
ips IPs assigned to the NIC represented as a collection.
dhcp Boolean value that indicates if the NIC is using DHCP or not.
lan The LAN ID the NIC sits on.
firewallActive Once you add a firewall rule this will reflect a true value.
firewallrules A list of firewall rules associated to the NIC represented as a collection.

Remove a NIC Association

Removes the association of a NIC with a load balancer.

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

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

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

Response

Status: 202 (Accepted)

Response Parameters

None

Requests

List Requests

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

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

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

Request Parameters

None

Curl Example

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

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

Response Parameters

The request will return a collection of requests.

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

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

Get Request

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

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To retrieve details on a specific request you would send a GET request to https://api.profitbricks.com/rest/v2/requests/[request-id]

Request Parameters

None

Curl Example

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

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/rest/v2/requests/[request-id]

Response

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

{
  "id" : "[request-id]",
  "type" : "request",
  "href" : "https://api.profitbricks.com/rest/v2/requests/[request-id]",
  "metadata" : {
    "createdDate" : "[date]",
    "createdBy" : "[user]",
    "etag" : "[etag]",
    "requestStatus" : {
      "id" : "[reuest-id]/status",
      "type" : "request-status",
      "href" : "https://api.profitbricks.com/rest/v2/requests/[request-id]/status"
    }
  },

The contents of "properties" returned will vary considerably depending on what the original request was. This is an example of what would be returned for a POST request:

  "properties" : {
    "method" : "POST",
    "headers" : {
      "content-type" : "application/json",
      "connection" : "Keep-Alive",
      "host" : "api.profitbricks.com",
      "x-forwarded-for" : "[ip-address]",
      "content-length" : "81",
      "x-forwarded-host" : "api.profitbricks.com",
      "user-agent" : "Go 1.1 package http",
      "accept-encoding" : "gzip",
      "x-forwarded-server" : "my.profitbricks.com"
    },
    "body" : "{\"properties\":{\"name\":\"test\",\"description\":\"description\",\"location\":\"us/las\"}}",
    "url" : "https://api.profitbricks.com/rest/v2/datacenters"
  }
}

Response Parameters

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

Name Description
id The request's unique identifier.
type The type of object, which should be "request" in this context.
href URL to the object’s representation (absolute path).
createdDate The date the resource was created.
createdBy The user who created the request.
requestStatus See the next section on retrieving a request's status for information on the attributes found in this collection.

Once you have determined the type of request based on the returned properties, you can refer to the appropriate section of the Cloud API documentation for details.

Get Request Status

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

Request

Request Headers

The request headers should include the following:

Authorization: Basic dXNlcm5hbWVAZG9tYWluLnRsZDpwYXNzd29yZA==

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

Request Body

To retrieve the status of a specific request send a GET request to https://api.profitbricks.com/rest/v2/requests/[request-status-id]/status

Request Parameters

None

Curl Example

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

curl --include \
     --request GET \
     --user 'username@domain.tld:password' \
     https://api.profitbricks.com/rest/v2/requests/[request-status-id]/status

Response

The following is an example status request response when the specific request has completed:

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

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

Response Parameters

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

Name Description
id The request's unique identifier.
type The type of object, should be "request-status" in this context.
href URL to the object’s representation (absolute path).
status The status of the entire request, e.g. QUEUED, RUNNING, DONE, or FAILED.
message A description of the request status.
targets An array of "sub-requests" related to the request. For example, a create server request could have multiple sub-requests for creating the server, a volume, and a NIC. These sub-requests and their status will be returned in this section of the response.
status Status of individual targets within the request, e.g. QUEUED, RUNNING, DONE, or FAILED.