Cloud API v1.0 - Use the latest: v4.0


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

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

Getting Started

How to Access the API

You can consume the REST API using the following URL:

URL Description
https://api.profitbricks.com/rest REST 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.

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/f81d4fae-7dec-11d0-a765-00a0c91e6bf6
<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’s 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 datacenter 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/<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 /requests//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": "59359eae-cdcd-406f-900b-58b3ad9d8de9",
        "type": "request-status",
        "href": "https://<base-url>/request/59359eae-cdcd-406f-900b-58b3ad9d8de9/status",
        "requestStatus": "RUNNING"
    },
    "entities": {
        "targets": [
            {
                "target": {
                    "id": "<NEW-SERVER-ID>",
                    "type": "server",
                    "href": "<base>/datacenters/<UUID1>/servers/<NEW-SERVER-ID>"
                },
                "status": "RUNNING"
            },
            {
                "target": {
                    "id": "<NEW-NIC-ID>",
                    "type": "NEW-NIC-ID",
                    "href": "<base>/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 IONOS platform. VDCs act as logical containers for all other objects you will be creating, e.g. servers. You can provision as many data centers as you want. Datacenters 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 datacenter or to create a datacenter with multiple objects under it such as servers and storage volumes.

Creating a Simple Datacenter

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To create a datacenter you would send a POST request to https://api.profitbricks.com/rest/datacenters

The format of the request body is as follows:

{
    "properties": {
        "name": "datacenter-name",
        "description": "datacenter-description",
        "location": "datacenter-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 datacenter will be created. This will be where all of your servers live. Yes
description string A description for the datacenter, e.g. staging, production.

'name' values cannot contain the following characters: (@, /, , |, ‘’, ‘).

NOTE You cannot change a datacenter'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 you how to submit the request body via curl:

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

Response

202 (Accepted)
Content-Type: application/vnd.profitbricks.resource+json
Location: URL of a request resource which should be used for operation's status polling
{
    "id": "datacenter-id",
    "type": "datacenter",
    "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id",
    "metadata": {
        "lastModifiedDate": "last-modified-date",
        "lastModifiedBy": "last-modified-by",
        "createdDate": "created-date",
        "createdBy": "created-by",
        "state": "state",
        "etag": "etag"
    },
    "properties": {
        "name": "datacenter-name",
        "description": "datacenter-description",
        "location": "datacenter-location",
        "version": datacenter-version
    },
    "entities": {
        "servers": {
            "id": "datacenter-id/servers",
            "type": "collection",
            "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id/servers"
        },
        "volumes": {
            "id": "datacenter-id/volumes",
            "type": "collection",
            "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id/volumes"
        },
        "loadbalancers": {
            "id": "datacenter-id/loadbalancers",
            "type": "collection",
            "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id/loadbalancers"
        },
        "lans": {
            "id": "datacenter-id/lans",
            "type": "collection",
            "href": "https://api.profitbricks.com/rest/datacenters/datacenter-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 datacenter.
description The description of the datacenter.
location The location you provisioned the data center.
version The version of the datacenter.
servers You can define multiple servers to be created when the datacenter is created. See create server for request parameter details.
volumes A collection that represents volumes you wish to create upon datacenter creation. See create storage volume for request parameter details.
loadbalancers A collection that represents the loadbalancers you wish to create upon datacenter creation.
lans A collection that represents the LANs you wish to create upon datacenter creation.

Creating a Datacenter with Multiple Resources

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To create a datacenter you would send a POST request to https://api.profitbricks.com/rest

The format of the request body is as follows:

{
    "properties": {
        "name": "datacenter-name",
        "description": "datacenter-description",
        "location": "datacenter-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-start-range"
                                }
                            }
                        ]
                    }
                ],
                "cdroms": [
                    {
                        "properties": {
                            "image": {
                                "id": "image-iso-uuid"
                            }
                        }
                    }
                ]
            }
        ]
    }
}
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 datacenter will be created. This will be where all of your servers live. Yes
description string A description for the datacenter, e.g. staging, production.
servers collection You can define multiple servers to be created when the datacenter is created. See create server for request parameter details.
volumes collection A collection that represents volumes you wish to create upon datacenter creation. See create storage volume for request parameter details.
loadbalancers collection A collection that represents the loadbalancers you wish to create upon datacenter creation.
lans collection A collection that represents the LANs you wish to create upon datacenter creation.

'name' values cannot contain the following characters: (@, /, , |, ‘’, ‘).

NOTE You cannot change a datacenter'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 you how to submit the request body via curl:

curl --include \
     --request POST \
     --quiet --user 'username:password' \
     --header "Content-Type: application/vnd.profitbricks.resource+json" \
     --data-binary '{
    "properties": {
        "name": "datacenter-name",
        "description": "datacenter-description",
        "location": "datacenter-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-start-range"
                                }
                            }
                        ]
                    }
                ],
                "cdroms": [
                    {
                        "properties": {
                            "image": {
                                "id": "image-iso-uuid"
                            }
                        }
                    }
                ]
            }
        ]
    }
}' \
     https://api.profitbricks.com/rest/datacenters

Response

202 (Accepted)
Content-Type: application/vnd.profitbricks.resource+json
Location: URL of a request resource which should be used for operation's status polling
{
    "id": "datacenter-id",
    "type": "datacenter",
    "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id",
    "metadata": {
        "lastModifiedDate": "last-modified-date",
        "lastModifiedBy": "last-modified-by",
        "createdDate": "created-date",
        "createdBy": "created-by",
        "state": "state",
        "etag": "etag"
    },
    "properties": {
        "name": "datacenter-name",
        "description": "datacenter-description",
        "location": "datacenter-location",
        "version": datacenter-version
    },
    "entities": {
        "servers": {
            "id": "datacenter-id/servers",
            "type": "collection",
            "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id/servers"
        },
        "volumes": {
            "id": "datacenter-id/volumes",
            "type": "collection",
            "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id/volumes"
        },
        "loadbalancers": {
            "id": "datacenter-id/loadbalancers",
            "type": "collection",
            "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id/loadbalancers"
        },
        "lans": {
            "id": "datacenter-id/lans",
            "type": "collection",
            "href": "https://api.profitbricks.com/rest/datacenters/datacenter-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 datacenter.
description The description of the datacenter.
location The location you provisioned the data center.
version The version of the datacenter.
servers You can define multiple servers to be created when the datacenter is created. See create server for request parameter details.
volumes A collection that represents volumes you wish to create upon datacenter creation. See create storage volume for request parameter details.
loadbalancers A collection that represents the loadbalancers you wish to create upon datacenter creation.
lans A collection that represents the LANs you wish to create upon datacenter 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 datacenter is created or when you GET a list of datacenters.

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request

To create a datacenter you would send a GET request to https://api.profitbricks.com/rest/datacenters/{datacenter-id}

Request Parameters

The following table describes the elements of the GET URL:

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

Curl Example

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

curl --include \
 https://api.profitbricks.com/rest/datacenters/{datacenter-id}

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

Response

Status: 200 (OK)
Headers: [
    "Date: Mon, 29 Sep 2014 18:18:35 GMT",
    "transfer-encoding: chunked",
    "Connection: keep-alive",
    "Content-Type: application/vnd.profitbricks.resource+json"
]
ResponseBody: {
    "id": "datacenter-id",
    "type": "datacenter",
    "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id",
    "metadata": {
        "lastModifiedDate": "datacenter-last-modified-date",
        "lastModifiedBy": "datacenter-last-modified-by-user",
        "createdDate": "datacenter-creation-date",
        "createdBy": "datacenter-created-by-user",
        "state": "datacenter-state",
        "etag": "datacenter-etag"
    },
    "properties": {
        "name": "datacenter-name",
        "description": "datacenter-description",
        "location": "datacenter-location",
        "version": datacenter-version
    },
    "entities": {
        "servers": [],
        "volumes": [],
        "loadbalancers": [],
        "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 Datacenter state.
etag The etag for the resource.
name The name of the datacenter.
description The description of the datacenter.
location The location you provisioned the data center.
version The version of the datacenter.
servers A collection that represents the servers in a datacenter.
volumes A collection that represents volumes in a datacenter.
loadbalancers A collection that represents the loadbalancers in a datacenter.
lans A collection that represents the LANs in a datacenter.

The following table illustrates the possible datacenter 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 wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request

To create a datacenter you would send a GET request to https://api.profitbricks.com/rest/datacenters

Request Parameters

None

Curl Example

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

curl --include \
 https://api.profitbricks.com/rest/datacenters

Response

200 (OK)
Content-Type: application/vnd.profitbricks.collection+json
{
    "id": "datacenters",
    "type": "collection",
    "href": "<base>/datacenters/datacenter-id",
    "items": [
        {
            "id": "datacenter-id",
            "type": "datacenter",
            "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id",
            "metadata": {
                "lastModifiedDate": "last-modified-date",
                "lastModifiedBy": "last-modified-by",
                "createdDate": "created-date",
                "createdBy": "created-by",
                "state": "state",
                "etag": "etag"
            },
            "properties": {
                "name": "datacenter-name",
                "description": "datacenter-description",
                "location": "datacenter-location",
                "version": datacenter-version
            },
            "entities": {
                "servers": {
                    "id": "datacenter-id/servers",
                    "type": "collection",
                    "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id/servers"
                },
                "volumes": {
                    "id": "datacenter-id/volumes",
                    "type": "collection",
                    "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id/volumes"
                },
                "loadbalancers": {
                    "id": "datacenter-id/loadbalancers",
                    "type": "collection",
                    "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id"
                },
                "lans": {
                    "id": "datacenter-id/lans",
                    "type": "collection",
                    "href": "https://api.profitbricks.com/rest/datacenters/datacenter-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 Datacenter state.
etag The etag for the resource.
name The name of the datacenter.
description The description of the datacenter.
location The location you provisioned the data center.
version The version of the datacenter.

Update a Data Center

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

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

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 datacenter to re-name the datacenter or update its description.

PATCH Update

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request

To partially update a datacenter you would send a PATCH request to https://api.profitbricks.com/rest/datacenters/{datacenter-id}

Request Parameters

The following table describes the optional 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.
Curl Example

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

curl --include \
     --request PATCH \
     --header "Content-Type: application/vnd.profitbricks.partial-properties+json" \
     --data-binary '    {
        "name": "Partially updated datacenter name"
    }' \
     https://api.profitbricks.com/rest/datacenters/{datacenter_id}

Response

Status: 202 (Accepted)
Headers: [
    "Date: Tue, 30 Sep 2014 22:19:53 GMT",
    "transfer-encoding: chunked",
    "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"
]
ResponseBody: {
      "id": "datacenter-id",
    "type": "datacenter",
    "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id",
    "metadata": {
          "lastModifiedDate": "last-modified-date",
          "lastModifiedBy": "last-modified-by",
          "createdDate": "created-date",
          "createdBy": "created-by",
        "state": "datacenter-state",
        "etag": "etag"
    },
    "properties": {
        "name": "datacenter-name",
        "description": "datacenter-description",
        "location": "datacenter-location",
        "version": datacenter-version
    },
    "entities": {
        "servers": [],
        "volumes": [],
        "loadbalancers": [],
        "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 datacenter.
description The description of the datacenter.
location The location you provisioned the data center.
version The version of the datacenter.
servers You can define multiple servers to be updated when the datacenter is updated. See create server for request parameter details.
volumes A collection that represents volumes you wish to update upon datacenter update. See create storage volume for request parameter details.
loadbalancers A collection that represents the loadbalancers you wish to update upon datacenter update.
lans A collection that represents the LANs you wish to create upon datacenter creation.

PUT Update

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request

To fully update a datacenter you would send a PUT request to https://api.profitbricks.com/rest/datacenters/{datacenter-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.

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

Curl Example

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

curl --include \
     --request PUT \
     --header "Content-Type: application/vnd.profitbricks.resource+json" \
     --data-binary '    {
        "properties": {
            "name": "datacenter1 - updated name",
            "description": "Description of my DC"
        }
    }' \
     `https://api.profitbricks.com/rest/datacenters/{datacenter_id}

Response

Status: 202 (Accepted)
Headers: [
    "Date: Tue, 30 Sep 2014 22:26:47 GMT",
    "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: 1134"
]
ResponseBody: {
    "id": "datacenter-id",
    "type": "datacenter",
    "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id",
    "metadata": {
          "lastModifiedDate": "last-modified-date",
          "lastModifiedBy": "last-modified-by",
          "createdDate": "created-date",
          "createdBy": "created-by",
        "state": "datacenter-state",
        "etag": "etag"
    },
    "properties": {
        "name": "datacenter-name",
        "description": "datacenter-descriptoin",
        "location": "location"
    },
    "entities": {
        "servers": [],
        "volumes": [],
        "loadbalancers": [],
        "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 datacenter.
description The description of the datacenter.
location The location you provisioned the data center.
servers You can define multiple servers to be updated when a datacenter is updated. See create server for request parameter details.
volumes A collection that represents volumes to update upon datacenter update. See create storage volume for request parameter details.
loadbalancers A collection that represents the loadbalancers you wish to update upon datacenter update.
lans A collection that represents the LANs you wish to create upon datacenter creation.

Delete a Data Center

Similar to the clearDataCenter method this will remove all objects within the datacenter and remove the datacenter object itself, too. This is a highly destructive method which should be used with caution.

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request

To create a datacenter you would send a DELETE request to https://api.profitbricks.com/rest/datacenters/{datacenter-id}

Request Parameters

The following table describes the elements of the DELETE URL:

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

Curl Example

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

curl --include \
 https://api.profitbricks.com/rest/datacenters/{datacenter-id}

Response

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

Response Parameters

None

Locations

List Locations

Retrieve a list of Locations. This list represents where you can provision your virtual data centers.

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To retrieve a list of Locations you would send a GET request to https://api.profitbricks.com/rest/locations

Request Parameters

None

Curl Example

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

curl --include \
 https://api.profitbricks.com/rest/locations

Response

200 (OK)
Content-Type: application/vnd.profitbricks.collection+json
    {
        "id": "locations",
        "type": "collection",
        "href": "https://api.profitbricks.com/rest/locations",
        "items": [
            {
                "id": "de/fra",
                "type": "location",
                "href": "https://api.profitbricks.com/rest/locations/de/fra",
                "properties": {
                    "name": "Europe / Germany / Frankfurt"
                }
            },
            {
                "id": "de/fkb",
                "type": "location",
                "href": "https://api.profitbricks.com/rest/locations/de/fkb",
                "properties": {
                    "name": "Europe / Germany / Karlsruhe"
                }
            },
            {
                "id": "us/las",
                "type": "location",
                "href": "https://api.profitbricks.com/rest/locations/us/las",
                "properties": {
                    "name": "North America / USA / Las Vegas"
                }
            }
        ]
    }

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.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
name The continent, country, and city for the location, e.g. Europe / Germany / Frankfurt.

Get Location

Retrieves the attributes of a given location.

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

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

Request Parameters

None

Curl Example

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

curl --include \
 https://api.profitbricks.com/rest/locations/{location_id}

Response

200 (OK)
Content-Type: application/vnd.profitbricks.resource+json
    {
        "id": "location-id",
        "type": "location",
        "href": "https://api.profitbricks.com/rest/locationslocation-id",
        "properties": {
            "name": "continent / country / city"
        }
    }

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).
name The continent, country, and city for the location, e.g. Europe / Germany / Frankfurt.

Servers

Create a Server

Creates a server within an existing datacenter. You can configure the boot volume and connect the server to an existing LAN.

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To create a server you would send a POST request to https://api.profitbricks.com/rest/datacenters/{datacenter_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.
bootVolume string Reference to a Volume used for booting. If not ‘null’ then bootCdrom has to be ‘null’.
bootCdrom string Reference to a CD-ROM used for booting. If not 'null' then bootVolume has to be 'null'.
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.
nics collection A collection of NICs you wish to create at the time the server is provisioned.

The following table outlines the availability zones currently supported:

Zone Value
AUTO
ZONE_1
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 you how to submit the request body via curl:

curl --include \
     --request POST \
     --header "Content-Type: application/vnd.profitbricks.resource+json" \
     --data-binary '    {
        "properties": {
            "name": "server-name",
            "ram": server-memory-in-mb,
            "cores": server-cores
        },
        "entities": {
            "volumes": [
                {
                    "properties": {
                        "size": volume-size-in-gb,
                        "name": "storage-volume-name",
                        "image": "storage-volume-image",
                        "bus": "storage-volume-bus-type"
                    }
                }
            ]
        }
    }' \
     https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers

Response

Status: 202 (Accepted)
Headers: [
    "Date: Mon, 29 Sep 2014 19:56:46 GMT",
    "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: 926"
]
ResponseBody: {
    "id": "new-server-id",
    "type": "server",
    "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id/servers/server-id",
    "metadata": {
          "lastModifiedDate": "last-modified-date",
          "lastModifiedBy": "last-modified-by",
          "createdDate": "created-date",
          "createdBy": "created-by",
        "state": "server-state",
        "etag": "server-etag"
    },
    "properties": {
        "name": "server-name",
        "description": "server-description",
        "cores": "server-cores",
        "ram": "server-memory",
        "availabilityZone": "server-availability-zone",
        "bootVolume": null,
        "bootCdrom": null
    },
    "entities": {
        "nics": [],
        "volumes": [
            {
                "id": "storage-volume-id",
                "type": "volume",
                "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id/volumes/storage-volume-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 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.
etag The etag.
name The name of the server.
description The description 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.
bootVolume Reference to a Volume used for booting.
bootCdrom Reference to a CD-ROM used for booting.
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 be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To retrieve a server you would send a GET request to https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}

Request Parameters

None

Curl Example

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

curl --include \
 https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}

Response

Status: 200 (OK)
Headers: [
    "Date: Mon, 29 Sep 2014 20:13:03 GMT",
    "transfer-encoding: chunked",
    "Connection: keep-alive",
    "Content-Type: application/vnd.profitbricks.resource+json"
]
ResponseBody: {
    "id": "server-id",
    "type": "server",
    "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id/servers/server-id",
    "metadata": {
        "lastModifiedDate": "last-modified-date",
        "lastModifiedBy": "last-modify-by-user",
        "createdDate": "created-date",
        "createdBy": "created-by-user",
        "state": "server-state",
        "etag": "server-etag"
    },
    "properties": {
        "name": "server-name",
        "cores": "server-cores",
        "ram": "server-ram",
        "availabilityZone": "server-availability-zone",
        "vmState": "SHUTOFF",
        "bootVolume": null,
        "bootCdrom": null
    },
    "entities": {
        "nics": [
            {
                "id": "nic-id",
                "type": "nic",
                "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id/servers/server-id/nics/nic-id"
            }
        ],
        "volumes": [
            {
                "id": "storage-volume-id",
                "type": "volume",
                "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id/volumes/storage-volume-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 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’
volumes A collection of volumes attached to the server.
nics A collection of NICs attached to the server.
Server States

The following table illustrates the possible server states:

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 servers within a datacenter.

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To retrieve a list of servers you would send a GET request to https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers

Request Parameters

None

Curl Example

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

curl --include \
 https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers

You can add ?depth=1 to the request to retrieve a deeper set of data.

Response

200 (OK)
Content-Type: application/vnd.profitbricks.collection+json
    {
        "id": "datacenter-id/servers",
        "type": "collection",
        "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id/servers",
        "items": [
            {
                "id": "server-id",
                "type": "server",
                "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id/servers/server-id",
                "metadata": {
                    "lastModifiedDate": "last-modified-date",
                    "lastModifiedBy": "last-modified-by",
                    "createdDate": "created-date",
                    "createdBy": "created-by",
                    "state": "state",
                    "etag": "etag"
                },
                "properties": {
                    "name": "server-name",
                    "cores": "server-cores",
                    "ram": "server-ram",
                    "availabilityZone": "server-availability-zone",
                    "vmState": "server-state",
                    "bootVolume": null,
                    "bootCdrom": null
                },
                "entities": {
                    "nics": {},
                    "volumes": {}
                }
            }
        ]
    }

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'.
volumes A collection of volumes attached to the server.
nics A collection of NICs attached to the server.

Update a Server

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

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

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 server using the above methods.

PATCH

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

Request

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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: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/datacenters/{datacenter_id}/servers/{server_id}

Request Parameters
Name Type Description Required
name string The name of the server.
cores int The number of cores for the server.
ram int The amount of memory in the server.
availabilityzone string The new availability zone for the server.
bootVolume string Reference to a Volume used for booting. If not ‘null’ then bootCdrom has to be ‘null’
bootCdrom string Reference to a CD-ROM used for booting. If not 'null' then bootVolume has to be 'null'.
Curl Example

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

curl --include \
     --request PATCH \
     --header "Content-Type: application/vnd.profitbricks.partial-properties+json" \
     --data-binary '    {
        "cores": cores
    }' \
     https://api.profitbricks.com/rest/datacenters/{datacenter_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 operation's status polling
{
    "id": "server-d",
    "type": "server",
    "href": "https://api.profitbricks.com/rest/datacenters/datacenter-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",
        "licenceType": "server-license",
        "vmState": "server-vmstate",
        "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.
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.
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 wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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: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/datacenters/{datacenter_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
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 you how to submit the request body via curl:

curl --include \
     --request PUT \
     --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/datacenters/{datacenter_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/datacenters/datacenter-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.
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'.
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 your datacenter; however, it will not remove the storage volumes attached to the server. You will need to make a separate API call to perform that action.

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To remove a server you would send a DELETE request to https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}

Request Parameters

None

Curl Example

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

curl --include \
     --request DELETE \
 https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}

Response

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

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 be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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: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/datacenters/{datacenter_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/datacenters/{datacenter_id}/servers/{server_id}/volumes?depth=1

Request Parameters

None

Curl Example

The following shows you how to submit the request via curl for a depth of 0:

curl --include \
 https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/volumes

The following shows you how to submit the request using a depth of 1:

curl --include \
 https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/volumes?depth=1

Response

When using a depth of 0 you will receive the following response:

200 (OK)
Content-Type: application/vnd.profitbricks.collection+json
    {
        "id": "server-id/volumes",
        "type": "collection",
        "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id/servers/server-id/volumes",
        "items": [
            {
                "id": "volume-id",
                "type": "volume",
                "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id/volumes/volume-id",
                "metadata": {
                    "lastModifiedDate": "last-modified-date",
                    "lastModifiedBy": "last-modified-by",
                    "createdDate": "created-date",
                    "createdBy": "created-by",
                    "state": "state",
                    "etag": "etag"
                },
                "properties": {
                   "name": "storage-volume-name",
                  "description": "storage-volume-description",
                  "size": "storage-volume-size-in-gb",
                  "bus": "storage-volume-bus-type",
                  "image": storage-volume-image,
                  "imagePassword": storage-volume-image-password
                }
            }
        ]
    }

A collection of volumes is returned. #### Response Parameters

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 be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To attach a storage volume to a server you would send a POST request to: https://api.profitbricks.com/rest/datacenters/{datacenter_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 you how to submit the request via curl:

curl --include \
     --request POST \
     --data-binary '{
    "id": "storage-volume-id"
}' \
     https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/volumes

Response

Status: 202 (Accepted)
Headers: [
    "Date: Mon, 29 Sep 2014 21:59:12 GMT",
    "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: 592"
]
ResponseBody: {
    "id": "storage-volume-id",
    "type": "volume",
    "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id/volumes/storage-volume-id",
    "metadata": {
          "lastModifiedDate": "last-modified-date",
          "lastModifiedBy": "last-modified-by",
          "createdDate": "created-date",
          "createdBy": "created-by",
        "state": "storage-volume-state",
        "etag": "storage-volume-etag"
    },
    "properties": {
        "name": "storage-volume-name",
        "description": "storate-volume-description",
        "size": "storage-volume-size-in-gb",
        "bus": "storage-volume-bus-type",
        "image": storage-volume-image,
        "imagePassword": storage-volume-image-password
    }
}

Response Parameters

Please see the Volumes section for attribute definitions.

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 wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

You would send a GET request to: https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/volumes/{volume_id}

Request Parameters

None

Curl Example

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

curl --include \
 https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/volumes/{volume_id}

Response

Status: 200 (OK)
Headers: [
    "Date: Mon, 29 Sep 2014 22:05:15 GMT",
    "Content-Length: 769",
    "Connection: keep-alive",
    "Content-Type: application/vnd.profitbricks.resource+json"
]
ResponseBody: {
    "id": "storage-volume-id",
    "type": "volume",
    "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id/volumes/storage-volume-id",
    "metadata": {
        "lastModifiedDate": "last-modified-date",
        "lastModifiedBy": "last-modified-by-user",
        "createdDate": "created-date",
        "createdBy": "created-by-user",
        "state": "storage-volume-state",
        "etag": "storage-volume-etag"
    },
    "properties": {
        "name": "storage-volume-name",
        "description": "storage-volume-description",
        "size": "storage-volume-size-in-gb",
        "bus": "storage-volume-bus-type",
        "image": null,
        "imagePassword": null
    }
}

Response Parameters

Please see the Volumes section for attribute definitions.

Detach a Volume

This will detach the volume from the server. This will not delete the volume from your datacenter. You will need to make a separate request to perform a deletion.

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

You would send a DELETE request to: https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/volumes/{volume_id}

Request Parameters

None

Curl Example

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

curl --include \
     --request DELETE \
 https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/volumes/{volume_id}

Response

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

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 wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To get a list of CD-ROMs attached to the server you would send a GET request to: https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/cdroms

Request Parameters

None

Curl Example

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

curl --include \
 https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/cdroms

Response

You should receive a response similar to this:

200 (OK)
Content-Type: application/vnd.profitbricks.collection+json
    {
        "id": "server-id/cdroms",
        "type": "collection",
        "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id/servers/server-id/cdroms",
        "items": [
            {
                "id": "cdrom-id",
                "type": "cdrom",
                "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id/servers/server-id/cdroms/cdrom-id",
                "metadata": {
                    "lastModifiedDate": "last-modified-date",
                    "lastModifiedBy": "last-modified-by",
                    "createdDate": "created-date",
                    "createdBy": "created-by",
                    "state": "state",
                    "etag": "etag"
                },
                "properties": {
                    "name": "image-name",
                    "image": {
                        "id": "image-id",
                        "type": "image",
                        "href": "https://api.profitbricks.com/rest/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 wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To attach a CD-ROM to a server you would send a POST request to: https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/cdroms

Request Parameters

None

Curl Example

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

curl --include \
     --request POST \
     --header "Content-Type: application/vnd.profitbricks.resource+json" \
     --data-binary '    {
        "properties": {
            "name": "cdrom-image-name",
            "description": "cdrom-image-description",
            "image": {
                "id": "cdrom-image-id"
            }
        }
    }' \
     https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/cdroms

Response

You should receive a response similar to this:

Status: 202 (Accepted)
Headers: [
    "Date: Mon, 29 Sep 2014 22:40:06 GMT",
    "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: 829"
]
ResponseBody: {
      "id": "cdrom-id",
      "type": "cdrom",
    "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id/servers/server-id/cdroms/cdrom-id",
    "metadata": {
        "lastModifiedDate": "last-modified-date",
        "lastModifiedBy": "last-modified-by-user",
        "createdDate": "created-date",
        "createdBy": "created-by-user",
        "state": "cdrom-state",
        "etag": "cdrom-etag"
    },
    "properties": {
        "name": "image-name",
        "description": "image-description",
        "image": {
            "id": "image-name",
            "type": "image",
            "href": "https://api.profitbricks.com/rest/images/image-id"
        }
    }
}

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 be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To get a specific CD-ROM you would send a GET request to: https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/cdroms/{cdrom_id}

Request Parameters

None

Curl Example

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

curl --include \
 https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/cdroms/{cdrom_id}

Response

You should receive a response similar to this:

Status: 200 (OK)
Headers: [
    "Date: Mon, 29 Sep 2014 22:44:34 GMT",
    "Content-Length: 895",
    "Connection: keep-alive",
    "Content-Type: application/vnd.profitbricks.resource+json"
]
ResponseBody: {
    "id": "cdrom-id",
    "type": "cdrom",
    "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id/servers/server-id/cdroms/cdrom-id",
    "metadata": {
        "lastModifiedDate": "last-modified-date",
        "lastModifiedBy": "last-modified-by-user",
        "createdDate": "created-date",
        "createdBy": "created-by-user",
        "state": "cdrom-state",
        "etag": "cdrom-etag"
    },
    "properties": {
        "name": "image-name",
        "description": "image-description",
        "image": {
            "id": "image-id",
            "type": "image",
            "href": "https://api.profitbricks.com/rest/images/image-id"
        }
    }
}

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 be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To detach a CDROM from a server you would send a DELETE request to https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/cdroms/{cdrom_id}

Request Parameters

None

Curl Example

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

curl --include \
     --request DELETE \
 https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/cdroms/{cdrom_id}

Response

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

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 be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To reboot a server you would send a POST request to https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/reboot

Request Parameters

None

Curl Example

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

curl --include \
     --request POST \
 https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/reboot

Response

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

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 wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To start a server you would send a POST request to https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/start

Request Parameters

None

Curl Example

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

curl --include \
     --request POST \
 https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/start

Response

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

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 be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To start a server you would send a POST request to https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/stop

Request Parameters

None

Curl Example

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

curl --include \
     --request POST \
 https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/stop

Response

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

Response Parameters

None

Images

List Images

Retrieve a list of images within the datacenter.

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

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

Request Parameters

None

Curl Example

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

curl --include \
 https://api.profitbricks.com/rest/images

Response

200 (OK)
Content-Type: application/vnd.profitbricks.collection+json
    {
        "id": "images",
        "type": "collection",
        "href": "https://api.profitbricks.com/rest/images",
        "items": [
            {
                "id": "image-id",
                "type": "image",
                "href": "https://api.profitbricks.com/rest/images/image-id",
                "metadata": {
                    "lastModifiedDate": "last-modified-date",
                    "lastModifiedBy": "last-modified-by",
                    "createdDate": "created-date",
                    "createdBy": "created-by",
                    "state": "state",
                    "etag": "etag"
                },
                "properties": {
                    "name": "image-name",
                    "description": "image-description",
                    "location": "image-location",
                    "size": size-in-gb,
                    "public": public-or-private-image,
                    "imageType": "image-type",
                    "licenceType": "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
                }
            }
        ]

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).
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 Image state.
imageType This indicates the type of image: HDD or CDROM
etag The etag for the resource.
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.
public Indicates if the image is part of the public repository or not.
licenceType The image's license type: LINUX, WINDOWS, WINDOWS2016, OTHER or 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)

Get Image

Retrieves the attributes of a given image.

Request

Request Headers

The request headers should be the following:

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

You will need to base64 encode your username and password.

Request Body

To retrieve a single image you would send a GET request to https://api.profitbricks.com/rest/images/{image_id}

Request Parameters

None

Curl Example

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

curl --include \
 https://api.profitbricks.com/rest/images/{image_id}

Response

200 (OK)
Content-Type: application/vnd.profitbricks.resource+json
    {
        "id": "image-id",
        "type": "image",
        "href": "https://api.profitbricks.com/rest/images/image-id",
        "metadata": {
            "lastModifiedDate": "last-modified-date",
            "lastModifiedBy": "last-modified-by-user",
            "createdDate": "created-date",
            "createdBy": "created-by-user",
            "state": "image-state",
            "imageType": "image-type",
            "etag": "etag"
        },
        "properties": {
            "name": "image-name",
            "description": "image-description",
            "location": "image-location",
            "size": size-in-gb,
            "public": public-or-private-image,
            "licenceType": "image-license-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
        }
    }

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 Image state.
imageType This indicates the type of image: HDD or CDROM
etag The etag for the resource.
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.
public Indicates if the image is part of the public repository or not.
licenceType The image's license type: LINUX, WINDOWS, WINDOWS2016, OTHER or 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)

Delete Image

Deletes the specified image.

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To delete an image you would send a DELETE request to https://api.profitbricks.com/rest/images/{image_id}

Request Parameters

None

Curl Example

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

curl --include \
     --request DELETE \
 https://api.profitbricks.com/rest/images/{image_id}

Response

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

Response Parameters

None

Update Image

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

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

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

In most cases you will be using PATCH.

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

PATCH

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

Request

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To perform a partial update to the image's properties you would send a PATCH request to https://api.profitbricks.com/rest/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 license 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 request body via curl:

curl --include \
     --request PATCH \
     --header "Content-Type: application/vnd.profitbricks.partial-properties+json" \
     --data-binary '    {
            "name": "image-name"
        }' \
     https://api.profitbricks.com/rest/images/{image_id}

Response

Status: 202 (Accepted)
Headers: [
    "Date: Wed, 01 Oct 2014 23:16:41 GMT",
    "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": "image-id",
      "type": "image",
      "href": "<base-url>/images/image-id",
    "metadata": {
            "lastModifiedDate": "last-modified-date",
        "lastModifiedBy": "last-modified-by-user",
        "createdDate": "created-date",
        "createdBy": "created-by-user",
        "state": "image-state",
        "etag": "etag"
    },
        "properties": {
          "name": "image-name",
          "description": "image-description",
          "location": "image-location",
          "size": size-in-gb,
          "public": public-or-private-image,
        "imageType": "image-type",
          "licenceType": "image-license",
          "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
    }
}
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 The state of the image.
etag The etag for the resource.
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.
public Indicates if the image is part of the public repository.
imageType This indicates the type of image: HDD or CDROM
licenceType The image's license type: LINUX, WINDOWS, WINDOWS2016, OTHER or 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)

PUT

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

Request

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To perform a full update of the image's properties you would send a PUT request to: https://api.profitbricks.com/rest/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 license 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 you how to submit the request body via curl:

curl --include \
     --request PUT \
     --header "Content-Type: application/vnd.profitbricks.resource+json" \
     --data-binary '    {
            "properties": {
                "name": "image-name",
                "description": "image-description",
                "licenceType": "image-license-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/images/{image_id}

Response

Status: 202 (Accepted)
Headers: [
    "Date: Wed, 01 Oct 2014 23:16:41 GMT",
    "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": "image-id",
      "type": "image",
      "href": "<base-url>/images/image-id",
    "metadata": {
            "lastModifiedDate": "last-modified-date",
        "lastModifiedBy": "last-modified-by-user",
        "createdDate": "created-date",
        "createdBy": "created-by-user",
        "state": "image-state",
        "etag": "etag"
    },
        "properties": {
          "name": "image-name",
          "description": "image-description",
          "location": "image-location",
          "size": size-in-gb,
          "public": public-or-private-image,
        "imageType": "image-type",
          "licenceType": "image-license",
          "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
    }
}
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 The state of the image.
etag The etag for the resource.
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.
public Indicates if the image is part of the public repository.
imageType This indicates the type of image: HDD or CDROM
licenceType The image's license type: LINUX, WINDOWS, WINDOWS2016, OTHER or 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)

Volumes

List Volumes

Retrieve a list of volumes within the datacenter. 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 request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To retrieve a list of volumes you would send a GET request to https://api.profitbricks.com/rest/datacenters/{datacenter_id}/volumes

Request Parameters

None

Curl Example

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

curl --include \
 https://api.profitbricks.com/rest/datacenters/{datacenter_id}/volumes

Response

200 (OK)
Content-Type: application/vnd.profitbricks.collection+json
    {
        "id": "datacenter-id/volumes",
        "type": "collection",
        "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id/volumes",
        "items": [
            {
                "id": "volume-id",
                "type": "volume",
                "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id/volumes/volume-id",
                "metadata": {
                    "lastModifiedDate": "last-modified-date",
                    "lastModifiedBy": "last-modified-by",
                    "createdDate": "created-date",
                    "createdBy": "created-by",
                    "state": "state",
                    "etag": "etag"
                },
                "properties": {
                    "name": "volume-name",
                    "size": "volume-size-in-gb",
                    "bus": "volume-bus-type",
                    "image": volume-image,
                    "imagePassword": volume-image-password,
                    "type": volume-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,
                    "deviceNumber": device-number
                }
            }
        ]
    }

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 Currently HDD, but will soon support 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 wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To retrieve a single volume you would send a GET request to https://api.profitbricks.com/rest/datacenters/{datacenter_id}/volumes/{volume_id}

Request Parameters

None

Curl Example

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

curl --include \
 https://api.profitbricks.com/rest/datacenters/{datacenter_id}/volumes/{volume_id}

Response

Status: 200 (OK)
Headers: [
    "Date: Wed, 01 Oct 2014 03:14:02 GMT",
    "Content-Length: 632",
    "Connection: keep-alive",
    "Content-Type: application/vnd.profitbricks.resource+json"
]
ResponseBody: {
    "id": "volume-id",
    "type": "volume",
      "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id/volumes/volume-id",
    "metadata": {
        "lastModifiedDate": "last-modified-date",
        "lastModifiedBy": "last-modified-by-user",
        "createdDate": "created-date",
        "createdBy": "created-by-user",
        "state": "volume-state",
        "etag": "etag"
    },
    "properties": {
        "name": "volume-name",
        "size": "volume-size-in-bb",
        "bus": "volume-bus-type",
        "image": volume-image,
        "imagepassword": volume-image-password,
        "type": volume-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,
        "deviceNumber": device-number
    }
}

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 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.
imagepassword Indicates if a password is set on the image.
deviceNumber The LUN ID of the storage volume.
type Currently HDD, but will soon support 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)

Create Volume

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

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To create a volume you would send a POST request to https://api.profitbricks.com/rest/datacenters/{datacenter_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"
    }
}

Request Parameters

Name Type Description Required
name string The name of the volume.
size int The size of the volume in GB. Yes
bus string The bus type of the volume (VIRTIO or IDE). Default: VIRTIO.
image string The image or snapshot ID. Yes*
type string The disk type. Currently only HDD.
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]

*You will need to provide either the image or the licenceType parameters. licenceType is required, but if image is supplied, it will already have the 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 you how to submit the request body via curl:

curl --include \
     --request POST \
     --header "Content-Type: application/vnd.profitbricks.resource+json" \
     --data-binary '{
    "properties": {
        "size": volume-size-in-bb,
        "name": "volume-name",
        "image": "image-or-snapshot-id",
        "bus": "volume-bus-type"
    }
}    ' \
     https://api.profitbricks.com/rest/datacenters/{datacenter_id}/volumes

Response

Status: 202 (Accepted)
Headers: [
    "Date: Wed, 01 Oct 2014 22:07:29 GMT",
    "Content-Type: application/vnd.profitbricks.resource+json",
    "Location: URL of a request resource which should be used for operation's status polling",
    "Connection: keep-alive",
    "Content-Length: 453"
]
ResponseBody: {
    "id": "volume-id",
    "type": "volume",
    "href": "https://api.profitbricks.com/rest/datacenters/{datacenter-id}/volumes/{volume-id}",
    "metadata": {
        "lastModifiedDate": "last-modified-date",
        "lastModifiedBy": "last-modified-by-user",
        "createdDate": "created-date",
        "createdBy": "created-by-user",
        "state": "volume-state",
        "etag": "etag"
    },
    "properties": {
        "name": "volume-name",
        "size": "volume-size-in-bb",
        "bus": "volume-bus-type",
        "image": "image-or-snapshot-id",
        "imagepassword": image-has-password,
        "type": volume-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,
        "deviceNumber": device-number
    }
}

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 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.
imagepassword Indicates if a password is set on the image.
deviceNumber The LUN ID of the storage volume.
type Currently HDD, but will soon support 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)

Delete Volume

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

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To delete a volume you would send a DELETE request to https://api.profitbricks.com/rest/datacenters/{datacenter_id}/volumes/{volume_id}

Request Parameters

None

Curl Example

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

curl --include \
     --request DELETE \
 https://api.profitbricks.com/rest/datacenters/{datacenter_id}/volumes/{volume_id}

Response

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

Response Parameters

None

Update Volume

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

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

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

In most cases you will be using PATCH.

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

You 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 wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To perform a partial update to the volume's properties you would send a PATCH request to https://api.profitbricks.com/rest/datacenters/{datacenter_id}/volumes/{volume_id}

Request Parameters
Name Type Description Required
name string The name of the volume.
size int The size of the volume in GB.
bus string The bus type of the volume (VIRTIO or IDE). Default: VIRTIO.
Curl Example

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

curl --include \
     --request PATCH \
     --header "Content-Type: application/vnd.profitbricks.partial-properties+json" \
     --data-binary '    {
        "properties": {
            "size": volume-size,
          "name": "volume-name"
        }
    }' \
     https://api.profitbricks.com/rest/datacenters/{datacenter_id}/volumes/{volume_id}

Response

Status: 202 (Accepted)
Headers: [
    "Date: Wed, 01 Oct 2014 22:23:52 GMT",
    "Content-Type: application/vnd.profitbricks.resource+json",
    "Location: URL of a request resource which should be used for operation's status polling",
    "Connection: keep-alive",
    "Content-Length: 452"
]
ResponseBody: {
        "id": "volume-id",
        "type": "volume",
        "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id/volumes/volume-id",
    "metadata": {
        "lastModifiedDate": "last-modified-date",
        "lastModifiedBy": "last-modified-by-user",
        "createdDate": "created-date",
        "createdBy": "created-by-user",
        "state": "volume-state",
        "etag": "etag"
    },
    "properties": {
        "name": "volume-name",
        "size": volume-size-in-bb,
        "bus": "VIRTIO",
        "image": "image-or-snapshot-id",
        "imagepassword": image-has-password,
        "type": volume-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,
        "deviceNumber": device-number
    }
}
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 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.
imagepassword Indicates if a password is set on the image.
deviceNumber The LUN ID of the storage volume.
type Currently HDD, but will soon support 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)

PUT

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

Request

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To perform a full update of the volume's properties you would send a PUT request to: https://api.profitbricks.com/rest/datacenters/{datacenter_id}/volumes/{volume_id}

Request Parameters
Name Type Description Required
name string The name of the volume. Yes
size int The size of the volume in GB. Yes
bus string The bus type of the volume (VIRTIO or IDE). Default: VIRTIO. Yes
Curl Example

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

curl --include \
     --request PUT \
     --header "Content-Type: application/vnd.profitbricks.resource+json" \
     --data-binary '    {
        "properties": {
            "size": volume-size-in-gb,
            "name": "volume-name",
            "bus": "volume-bus"
        }
    }    ' \
     https://api.profitbricks.com/rest/datacenters/{datacenter_id}/volumes/{volume_id}

Response

Status: 202 (Accepted)
Headers: [
    "Date: Wed, 01 Oct 2014 22:23:52 GMT",
    "Content-Type: application/vnd.profitbricks.resource+json",
    "Location: URL of a request resource which should be used for operation's status polling",
    "Connection: keep-alive",
    "Content-Length: 452"
]
ResponseBody: {
    "id": "volume-id",
    "type": "volume",
    "href": "https://api.profitbricks.com/rest/datacenters/datacenter-id/volumes/volume-id",
    "metadata": {
        "lastModifiedDate": "last-modified-date",
        "lastModifiedBy": "last-modified-by-user",
        "createdDate": "created-date",
        "createdBy": "created-by-user",
        "state": "volume-state",
        "etag": "etag"
    },
    "properties": {
        "name": "volume-name",
        "size": volume-size-in-bb,
        "bus": "VIRTIO",
        "image": "image-or-snapshot-id",
        "imagepassword": image-has-password,
        "type": volume-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,
        "deviceNumber": device-number
    }
}
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 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.
imagepassword Indicates if a password is set on the image.
deviceNumber The LUN ID of the storage volume.
type Currently HDD, but will soon support 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)

Create Volume Snapshot

Creates a snapshot of a volume within the datacenter. 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 wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To create a volume snapshot you would send a POST request to https://api.profitbricks.com/rest/datacenters/{datacenter_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 you how to submit the request body via curl:

curl --include \
     --request POST \
     --header "Content-Type: application/x-www-form-urlencoded" \
     --data-binary "name=<URLENCODED_SNAPSHOT_NAME>&description=<URLENCODED_SNAPSHOT_DESCRIPTION>" \
'https://api.profitbricks.com/rest/datacenters/{datacenter_id}/volumes/{volume_id}/create-snapshot'

Response

Status: 202 (Accepted)
Headers: [
    "Location: URL of a request resource which should be used for operation's status polling",
    "Date: Fri, 03 Oct 2014 22:23:46 GMT",
    "Content-Length: 0",
    "Connection: keep-alive"
]
ResponseBody: {
    "id" : "snapshot-id",
    "type" : "snapshot",
    "href" : "https://api.profitbricks.com/rest/snapshots/snapshot-id",
    "metadata" : {
        "createdDate" : "created-date",
        "createdBy" : "created-by-user",
        "etag" : "etag",
        "lastModifiedDate" : "last-modified-date",
        "lastModifiedBy" : "last-modified-by-user",
        "state" : "BUSY"
    },
    "properties" : {
        "name" : "name",
        "description" : "description",
        "location" : "data center",
        "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 the 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 subsequent volumes if you want or to restore an existing volume.

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To create a volume snapshot you would send a POST request to https://api.profitbricks.com/rest/datacenters/{datacenter_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 \
     --header "Content-Type: application/x-www-form-urlencoded" \
     --data-binary "snapshotId=<snapshotId>" \
'https://api.profitbricks.com/rest/datacenters/{datacenter_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: Fri, 03 Oct 2014 22:23:46 GMT",
    "Content-Length: 0",
    "Connection: keep-alive"
]
ResponseBody: ""

Response Parameters

None

Snapshots

List Snapshots

Retrieve a list of snapshots within the datacenter.

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To retrieve a list of snapshots you would submit a GET request to https://api.profitbricks.com/rest/snapshots

Request Parameters

None

Curl Example

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

curl --include \
 https://api.profitbricks.com/rest/snapshots

Response

200 (OK)
Content-Type: application/vnd.profitbricks.collection+json
    {
        "id": "snapshots",
        "type": "collection",
        "href": "https://api.profitbricks.com/rest/snapshots",
        "items": [
            {
                 "id": "snapshot-id",
                 "type": "snapshot",
                 "href": "https://api.profitbricks.com/rest/snapshots/snapshot-id",
                 "metadata": {
                     "lastModifiedDate": "last-modified-date",
                     "lastModifiedBy": "last-modified-by",
                     "createdDate": "created-date",
                     "createdBy": "created-by",
                     "state": "state",
                     "etag": "etag"
                 },
                 "properties": {
                     "name": "snapshot-name",
                     "description": "snapshot-description",
                     "location": "snapshot-location",
                     "size": size-in-gb,
                     "licenceType": "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
                 }
            }
        ]
    }

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).
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 Snapshot state.
etag The etag for the resource.
name The name of the snapshot.
description The description of the snapshot.
location The snapshot's location.
size The size in GB of the snapshot.
licencetype The snapshot's license type: LINUX, WINDOWS, WINDOWS2016, OTHER or 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)

Get Snapshot

Retrieves the attributes of a given snapshot.

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To retrieve a single snapshot you would send a GET request to https://api.profitbricks.com/rest/snapshots/{snapshot_id}

Request Parameters

None

Curl Example

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

curl --include \
 https://api.profitbricks.com/rest/snapshots/{snapshot_id}

Response

200 (OK)
Content-Type: application/vnd.profitbricks.resource+json
    {
          "id": "snapshot-id",
          "type": "snapshot",
          "href": "https://api.profitbricks.com/rest/snapshots/snapshot-id",
        "metadata": {
            "lastModifiedDate": "last-modified-date",
            "lastModifiedBy": "last-modified-by-user",
            "createdDate": "created-date",
            "createdBy": "created-by-user",
            "state": "snapshot-state",
            "etag": "etag"
        },
        "properties": {
            "name": "snapshot-name",
            "description": "snapshot-description",
            "location": "snapshot-location",
            "size": size-in-gb,
            "licencetype": "snapshot-license-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
        }
    }

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 Snapshot state.
etag The etag for the resource.
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.
licencetype The snapshot's license type: LINUX, WINDOWS, WINDOWS2016, OTHER or 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)

Delete Snapshot

Deletes the specified snapshot.

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To delete an snapshot you would send a DELETE request to https://api.profitbricks.com/rest/snapshots/{snapshot_id}

Request Parameters

None

Curl Example

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

curl --include \
     --request DELETE \
 https://api.profitbricks.com/rest/snapshots/{snapshot_id}

Response

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

Response Parameters

None

Update Snapshot

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

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

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

In most cases you will be using PATCH.

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

PATCH

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

Request

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To perform a partial update to the snapshot's properties you would submit a PATCH request to https://api.profitbricks.com/rest/snapshots/{snapshot_id}

Request Parameters
Name Type Description Required
name string The name of the snapshot.
description string The description of the snapshot.
licencetype string The snapshot's license 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 request body via curl:

curl --include \
     --request PATCH \
     --header "Content-Type: application/vnd.profitbricks.partial-properties+json" \
     --data-binary '    {
            "name": "snapshot-name"
        }' \
     https://api.profitbricks.com/rest/snapshots/{snapshot_id}

Response

Status: 202 (Accepted)
Headers: [
    "Date: Wed, 01 Oct 2014 23:16:41 GMT",
    "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": "snapshot-id",
      "type": "snapshot",
      "href": "https://api.profitbricks.com/rest/snapshots/snapshot-id",
    "metadata": {
        "lastModifiedDate": "last-modified-date",
        "lastModifiedBy": "last-modified-by-user",
        "createdDate": "created-date",
        "createdBy": "created-by-user",
        "state": "snapshot-state",
        "etag": "etag"
    },
        "properties": {
          "name": "snapshot-name",
          "description": "snapshot-description",
          "location": "snapshot-location",
          "size": size-in-gb,
          "licencetype": "snapshot-license",
          "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
    }
}
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 The state of the snapshot.
etag The etag for the resource.
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.
licencetype The snapshot's license type: LINUX, WINDOWS, WINDOWS2016, OTHER or 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)

PUT

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

Request

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To perform a full update of the snapshot's properties you would send a PUT request to: https://api.profitbricks.com/rest/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
licencetype string The snapshot's license 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 you how to submit the request body via curl:

curl --include \
     --request PUT \
     --header "Content-Type: application/vnd.profitbricks.resource+json" \
     --data-binary '    {
            "properties": {
                "name": "snapshot-name",
                "description": "snapshot-description",
                "licencetype": "snapshot-license-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/snapshots/{snapshot_id}

Response

Status: 202 (Accepted)
Headers: [
    "Date: Wed, 01 Oct 2014 23:16:41 GMT",
    "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": "snapshot-id",
    "type": "snapshot",
      "href": "https://api.profitbricks.com/rest/snapshots/snapshot-id",
    "metadata": {
        "lastModifiedDate": "last-modified-date",
        "lastModifiedBy": "last-modified-by-user",
        "createdDate": "created-date",
        "createdBy": "created-by-user",
        "state": "snapshot-state",
        "etag": "etag"
    },
        "properties": {
          "name": "snapshot-name",
          "description": "snapshot-description",
          "location": "snapshot-location",
          "size": size-in-gb,
          "licencetype": "snapshot-license",
          "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
    }
}
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 The state of the snapshot.
etag The etag for the resource.
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.
licencetype The snapshot's license type: LINUX, WINDOWS, WINDOWS2016, OTHER or 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)

IP Block

List IP Blocks

Retrieve a list of IP Blocks within the datacenter.

Request

Request Headers

The request headers should be the following:

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

You will need to base64 encode your username and password.

Request Body

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

Request Parameters

None

Curl Example

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

curl --include \
 https://api.profitbricks.com/rest/ipblocks

Response

200 (OK)
Content-Type: application/vnd.profitbricks.collection+json
    {
        "id": "ipblocks",
        "type": "collection",
        "href": "https://api.profitbricks.com/rest/ipblocks",
        "items": [
            {
                "id": "ipblock-id",
                "type": "ipblock",
                "href": "https://api.profitbricks.com/rest/ipblocks/ipblock-id",
                "properties": {
                    "ips": [ip],
                    "location": "location"
                }
            }
        ]
    }

Response Parameters

The request will return a collection of IP Blocks.

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.

Get IP Block

Retrieves the attributes of a given IP Block.

Request

Request Headers

The request headers should be the following:

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

You will need to base64 encode your username and password.

Request Body

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

Request Parameters

None

Curl Example

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

curl --include \
 https://api.profitbricks.com/rest/ipblocks/{ipblock_id}

Response

Status: 200 (OK)
Headers: [
    "Date: Fri, 03 Oct 2014 04:15:56 GMT",
    "Content-Length: 496",
    "Connection: keep-alive",
    "Content-Type: application/vnd.profitbricks.resource+json"
]
ResponseBody: {
    "id": "ipblock-id",
      "type": "ipblock",
      "href": "https://api.profitbricks.com/rest/ipblocks/ipblock-id",
    "properties": {
        "ips": [
            "ip"
        ],
        "location": "location"
    }
}

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.

Create IP Block

Creates a IP Block within the datacenter.

Request

Request Headers

The request headers should be the following:

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

You will need to base64 encode your username and password.

Request Body

To create a IP Block you would send a POST request to https://api.profitbricks.com/rest/ipblocks

Request Parameters

Name Type Description Required
location string This must be one of there locations: us/las, de/fra, de/fkb. Yes
size int The size of the IP block you want. Yes

Curl Example

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

curl --include \
     --request POST \
     --header "Content-Type: application/vnd.profitbricks.resource+json" \
     --data-binary "    {
        \"properties\": {
            \"location\": \"us/las\",
            \"size\": 5
        }
    }" \
'https://api.profitbricks.com/rest/ipblocks'
  

Response

202 (Accepted)
Content-Type: application/vnd.profitbricks.resource+json
{
  "id": "854467eb-a0d3-4651-ac83-754e2faedba4",
  "type": "ipblock",
  "href": "https://api.profitbricks.com/rest/ipblocks/[ip-block-id]",
  "metadata": {
    "lastModifiedDate": "2014-02-01T11:12:12Z",
    "lastModifiedBy": "User X",
    "createdDate": "2014-02-01T11:12:12Z",
    "createdBy": "User X",
    "etag": "123whatever"
  },
  "properties": {
    "size": 5,
    "ips": [
      "122.33.4.23",
      "122.33.4.24",
      "122.33.4.25",
      "122.33.4.26",
      "122.33.4.27"
    ],
    "location": "us/las"
  }
}    

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

Delete IP Block

Deletes the specified IP Block.

Request

Request Headers

The request headers should be the following:

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

You will need to base64 encode your username and password.

Request Body

To delete a IP Block you would send a DELETE request to https://api.profitbricks.com/rest/ipblocks/{ipblock_id}

Request Parameters

None

Curl Example

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

curl --include \
     --request DELETE \
 https://api.profitbricks.com/rest/ipblocks/{ipblock_id}

Response

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

Response Parameters

None

LANs

List LANs

Retrieve a list of LANs within the datacenter.

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

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

Request Parameters

None

Curl Example

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

curl --include \
 https://api.profitbricks.com/rest/datacenters/{datacenter_id}/lans

Response

200 (OK)
Content-Type: application/vnd.profitbricks.collection+json
    {
        "id": "datacenter-id/lans",
        "type": "collection",
        "href": "/datacenters/datacenter-id/lans",
        "items": [
            {
                "id": "lan-id",
                "type": "lan",
                "href": "/datacenters/datacenter-id/lans/lan-id",
                "metadata": {
                    "lastModifiedDate": "last-modified-date",
                    "lastModifiedBy": "last-modified-by",
                    "createdDate": "created-date",
                    "createdBy": "created-by",
                    "state": "state",
                    "etag": "etag"
                },
                "properties": {
                    "public": "public-status"
                },
                "entities": {
                    "nics": {}
                }
            }
        ]
    }

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 LANs. This will give you the equivalent of what you would get when 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 be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To retrieve a single LAN you would send a GET request to https://api.profitbricks.com/rest/datacenters/{datacenter_id}/lans/{lan_id}

Request Parameters

None

Curl Example

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

curl --include \
 https://api.profitbricks.com/rest/datacenters/{datacenter_id}/lans/{lan_id}

Response

Status: 200 (OK)
Headers: [
    "Date: Thu, 02 Oct 2014 22:21:23 GMT",
    "Content-Length: 515",
    "Connection: keep-alive",
    "Content-Type: application/vnd.profitbricks.resource+json"
]
ResponseBody: {
      "id": "lan-id",
      "type": "lan",
      "href": "/datacenters/datacenter-id/lans/lan-id",
    "metadata": {
        "lastModifiedDate": "last-modified-date",
        "lastModifiedBy": "last-modified-by-user",
        "createdDate": "created-date",
        "createdBy": "created-by-user",
        "state": "lan-state",
        "etag": "etag"
    },
    "properties": {
        "public": "true"
    },
    "entities": {
        "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.
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 the datacenter.

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To create a LAN you would send a POST request to https://api.profitbricks.com/rest/datacenters/{datacenter_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 you how to submit the request body via curl:

curl --include \
     --request POST \
     --header "Content-Type: application/vnd.profitbricks.resource+json" \
     --data-binary '    {
        "properties": {
            "public": "true"
        },
         "entities": {
            "nics": []
         }
    }' \
     https://api.profitbricks.com/rest/datacenters/{datacenter_id}/nics

Response

Status: 202 (Accepted)
Headers: [
    "Date: Thu, 02 Oct 2014 23:57:38 GMT",
    "Content-Length: 510",
    "Connection: keep-alive",
    "Content-Type: application/vnd.profitbricks.resource+json"
]
ResponseBody: {
    "id": "lan-id",
    "type": "lan",
    "href": "/datacenters/datacenter-id/lans/lan-id",
    "metadata": {
        "lastModifiedDate": "last-modified-date",
        "lastModifiedBy": "last-modified-by-user",
        "createdDate": "created-date",
        "createdBy": "created-by-user",
        "state": "lan-state",
        "etag": "etag"
    },
    "properties": {
        "public": "true"
    },
    "entities": {
        "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.
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 be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To delete a LAN you would send a DELETE request to https://api.profitbricks.com/rest/datacenters/{datacenter_id}/lans/{lan_id}

Request Parameters

None

Curl Example

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

curl --include \
     --request DELETE \
 https://api.profitbricks.com/rest/datacenters/{datacenter_id}/lans/{lan_id}

Response

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

Response Parameters

None

Update LAN

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

You would use PATCH when performing a partial update to a resource, e.g. you're updating the name of a 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 wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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: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/datacenters/lans/{lan_id}

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

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

curl --include \
     --request PATCH \
     --header "Content-Type: application/vnd.profitbricks.partial-properties+json" \
     --data-binary '    {
            "public": "false"
        }' \
     https://api.profitbricks.com/rest/datacenters/{datacenter_id}/lans/{lan_id}

Response

Status: 202 (Accepted)
Headers: [
    "Date: Wed, 01 Oct 2014 23:16:41 GMT",
    "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": "lan-id",
    "type": "lan",
    "href": "<base-url>/datacenters/datacenter-id/lans/lan-id",
    "metadata": {
            "lastModifiedDate": "last-modified-date",
        "lastModifiedBy": "last-modified-by-user",
        "createdDate": "created-date",
        "createdBy": "created-by-user",
        "state": "lan-state",
        "etag": "etag"
    },
        "properties": {
        "public": "true"
    },
    "entities": {
        "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.
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 wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To perform a full update of the LAN's properties you would send a PUT request to: https://api.profitbricks.com/rest/datacenters/{datacenter_id}/lans/{lan_id}

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

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

curl --include \
     --request PUT \
     --header "Content-Type: application/vnd.profitbricks.resource+json" \
     --data-binary '    {
            "public": "false"
        }    ' \
     https://api.profitbricks.com/rest/datacenters/{datacenter_id}/lans/{lan_id}

Response

Status: 202 (Accepted)
Headers: [
    "Date: Wed, 01 Oct 2014 23:16:41 GMT",
    "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": "lan-id",
      "type": "lan",
      "href": "<base-url>/datacenters/datacenter-id/lans/lan-id",
    "metadata": {
            "lastModifiedDate": "last-modified-date",
        "lastModifiedBy": "last-modified-by-user",
        "createdDate": "created-date",
        "createdBy": "created-by-user",
        "state": "lan-state",
        "etag": "etag"
    },
        "properties": {
        "public": "true"
    },
    "entities": {
        "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.
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 be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To retrieve a list of NICs you would submit a GET request to https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/nics

Request Parameters

None

Curl Example

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

curl --include \
 https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/nics

Response

200 (OK)
Content-Type: application/json
    {
        "id": "server-id/nics",
        "type": "collection",
        "href": "/datacenters/datacenter-id/servers/server-id/nics",
        "items": [
            {
                "id": "nic-id",
                "type": "nic",
                "href": "/datacenters/datacenter-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": "nic-name",
                    "mac": "nic-mac",
                    "ips": ip-lisdt,
                    "dhcp": dhcp-status,
                    "lan": lan-id,
                    "firewallActive": firewall-active-status
                },
                "entities": {
                    "firewallrules": {}
                }
            }
        ]
    }

Response Parameters

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

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.

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state The NIC state.
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 wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To retrieve a list of NICs you would send a GET request to https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/nics/{nic_id}

Request Parameters

None

Curl Example

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

curl --include \
 https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/nics/{nic_id}

Response

200 (OK)
Content-Type: application/json
    {
        "id": "nic-id",
        "type": "nic",
        "href": "/datacenters/datacenter-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 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 be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To create a NIC you would send a POST request to https://api.profitbricks.com/rest/datacenters/{datacenter_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,
            "firewallActive": false
        },
        "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 you how to submit the request body via curl:

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --data-binary '    {
        "properties": {
            "name": "nic1",
            "ips": ["10.2.2.3"],
            "dhcp": "true",
            "lan": 1,
            "firewallActive": true
        },
    "firewallrules": {
        "entities": [
                {
                "properties": {
                    "name": "Open SSH port",
                    "protocol": "TCP",
                    "sourceMac": "01:23:45:67:89:00",
                    "portRangeStart": 22,
                    "portRangeEnd": 22
                    }
                },
                {
                "properties": {
                    "name": "Allow PING",
                    "protocol": "ICMP",
                    "icmpType": 8,
                    "icmpCode": 0
                    }
                }
            ]
        }
    }    ' \
     https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/nics

Response

Status: 202 (Accepted)
Headers: [
    "Date: Wed, 01 Oct 2014 00:53:16 GMT",
    "Content-Type: application/json",
    "Location: URL of a request resource which should be used for the operation's polling status",
    "Connection: keep-alive",
    "Content-Length: 989"
]
ResponseBody: {
     "id": "nic-id",
     "type": "nic",
     "href": "https://api.profitbricks.com/rest/datacenters/datacenter-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": [
            "ip"
        ],
        "dhcp": "nic-dhcp",
        "lan": nic-lan,
        "firewallActive": false
    },
    "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 The 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.

Delete a NIC

Deletes the specified NIC.

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To delete a NIC you would send a DELETE request to https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/nics/{nic_id}

Request Parameters

None

Curl Example

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

curl --include \
     --request DELETE \
 https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/nics/{nic_id}

Response

Status: 202 (Accepted)
Headers: [
    "Location: URL of a request resource which should be used for the operation's polling status",
    "Date: Wed, 01 Oct 2014 00:58:15 GMT",
    "transfer-encoding: chunked",
    "Connection: keep-alive"
]
ResponseBody: ""

Response Parameters

None

Update a NIC

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

You would use PATCH when performing a partial update to a resource, e.g. you're updating the name of a 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

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To perform a partial update to the NIC's properties you would send a PATCH request to https://api.profitbricks.com/rest/datacenters/{datacenter_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.
firewallrules string collection A list of firewall rules associated to the NIC represented as a collection.
Curl Example

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

curl --include \
     --request PATCH \
     --header "Content-Type: application/json" \
     --data-binary '    {
        "properties": {
            "name": "nic1",
            "ips": ["10.2.2.3"],
            "dhcp": "true",
            "lan": 1
        }
    }' \
     https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/nics/{nic_id}

Response

Status: 202 (Accepted)
Headers: [
    "Date: Wed, 01 Oct 2014 02:57:59 GMT",
    "Content-Type: application/json",
    "Location: URL of a request resource which should be used for the operation's polling status",
    "Connection: keep-alive",
    "Content-Length: 1141"
]
ResponseBody: {
     "id": "nic-id",
     "type": "nic",
     "href": "https://api.profitbricks.com/rest/datacenters/datacenter-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": [
            "ip"
        ],
        "dhcp": "nic-dhcp",
        "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 The 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.

PUT

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

Request

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To perform a full update of the NIC's properties you would send a PUT request to: https://api.profitbricks.com/rest/datacenters/{datacenter_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
firewallrules string collection A list of firewall rules associated to the NIC represented as a collection. Yes
Curl Example

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

curl --include \
     --request PUT \
     --header "Content-Type: application/json" \
     --data-binary '    {
        "properties": {
            "name": "nic-name",
            "ips": ["ip"],
            "dhcp": "nic-dhcp",
            "lan": nic-lan
        }
    } ' \
     https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/nics/{nic_id}

Response

Status: 202 (Accepted)
Headers: [
    "Date: Wed, 01 Oct 2014 02:57:59 GMT",
    "Content-Type: application/json",
    "Location: URL of a request resource which should be used for the operation's polling status",
    "Connection: keep-alive",
    "Content-Length: 1141"
]
ResponseBody: {
      "id": "nic-id",
    "type": "nic",
      "href": "https://api.profitbricks.com/rest/datacenters/datacenter-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": [
            "ip"
        ],
        "dhcp": "nic-dhcp",
        "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 The 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.

Firewall Rules

List Firewall Rules

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

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To retrieve a list of Firewall Rules you would submit a GET request to https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/nics/{nic_id}/firewallrules.

Request Parameters

None

Curl Example

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

curl --include \
 https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/nics/{nic_id}/firewallrules

Response

200 (OK)
Content-Type: application/json
{
  "id": "{nic_id}/firewallrules",
  "type": "collection",
  "href": "/datacenters/{datacenter_id}/servers/{server_id}/nics/{nic_id}/firewallrules",
  "items": [
    {
      "id": "{rule_id}",
      "type": "firewall-rule",
      "href": "/datacenters/{datacenter_id}/servers/{server_id}/nics/{nic_id}/firewallrules/{rule_id}",
      "metadata": {
        "lastModifiedDate": "last-modified-date",
        "lastModifiedBy": "last-modified-by",
        "createdDate": "created-date",
        "createdBy": "created-by",
        "state": "state",
        "etag": "etag"
      },
      "properties": {
        "name": "my-rule-name",
        "protocol": "rule-protocol",
        "sourceMac": "source-mac",
        "sourceIp": source-ip,
        "targetIp": target-ip,
        "portRangeStart": port-range-start,
        "portRangeEnd": port-range-end,
        "icmpType": icmp-type,
        "icmpCode": icmp-code
      }
    }
  ]
}

Response Parameters

The request will return a collection of Firewall Rules assigned to the NIC on the server.

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

Name Description
id The resource's unique identifier.
type The type of object that has been created.
href URL to the object’s representation (absolute path).
lastModifiedDate The last time the resource has been modified.
lastModifiedBy The user who last modified the resource.
createdDate The date the resource was created.
createdBy The user who created the resource.
state The firewall rule state.
etag The etag for the resource.
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.
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.
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.

Get Firewall Rule

Retrieves the attributes of a given firewall rule.

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To retrieve a list of NICs you would send a GET request to https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/nics/{nic_id}/firewallrules/{firewall_rule_id}

Request Parameters

None

Curl Example

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

curl --include \
 https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/nics/{nic_id}/firewallrules/{firewall_rule_id}

Response

200 (OK)
Content-Type: application/json
{
  "id": "firewall-rule-id",
  "type": "firewall-rule",
  "href": "/datacenters/{datacenter_id}/servers/{server_id}/nics/{nic_id}/firewallrules/{firewall_rule_id}",
  "metadata": {
    "lastModifiedDate": "last-modified-date",
    "lastModifiedBy": "last-modified-by",
    "createdDate": "created-date",
    "createdBy": "created-by",
    "state": "state",
    "etag": "etag"
  },
  "properties": {
    "name": "my-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"
  }
}

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 The firewall rule state.
etag The etag for the resource.
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.
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.
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.

Create Firewall Rule

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

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To create a Firewall Rule you would send a POST request to https://api.profitbricks.com/rest/datacenters/{datacenter_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 you how to submit the request body via curl:

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --data-binary "    {
        \"properties\": {
            \"name\": \"Open SSH port\",
            \"protocol\": \"TCP\",
            \"sourceMac\": \"01:23:45:67:89:00\",
            \"sourceIp\": null,
            \"targetIp\": null,
            \"portRangeStart\": "22",
            \"portRangeEnd\": null,
            \"icmpType\": null,
            \"icmpCode\": null

        }
    }" \
'https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/nics/{nic_id}/firewallrules

Response

202 (Accepted)
Content-Type: application/json
{
  "id": "{rule_id}",
  "type": "firewall-rule",
  "href": "/datacenters/{datacenter_id}/servers/{server_id}/nics/{nic_id}/firewallrules/{rule_id}",
  "metadata": {
    "lastModifiedDate": "last-modified-date",
    "lastModifiedBy": "last-modified-by",
    "createdDate": "created-date",
    "createdBy": "created-by",
    "state": "state",
    "etag": "etag"
  },
  "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"
  }
}

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 The firewall rule state.
etag The etag for the resource.
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.
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.
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.

Delete Firewall Rule

Removes the specific firewall rule.

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To delete a Firewall Rule you would send a DELETE request to `https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/nics/{nic_id}/firewallrules/{firewall_rule_id}

Request Parameters

None

Curl Example

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

curl --include \
     --request DELETE \
 https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/nics/{nic_id}/firewallrules/{firewall_rule_id}

Response

Status: 202 (Accepted)
Headers: [
    "Location: URL of a request resource which should be used for the operation's polling status",
    "Date: Wed, 01 Oct 2014 00:58:15 GMT",
    "transfer-encoding: chunked",
    "Connection: keep-alive"
]
ResponseBody: ""

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 wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To perform a partial update to the Firewall Rule's properties you would send a PATCH request to https://api.profitbricks.com/rest/datacenters/{datacenter_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 request body via curl:

curl --include \
     --request PATCH \
     --header "Content-Type: application/json" \
     --data-binary "    {
        \"sourceMac\": \"01:98:22:22:44:22\",
        \"targetIp\": \"123.100.101.102\"
    }" \
'https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/nics/{nic_id}/firewallrules/{firewall_rule_id}'

Response

202 (Accepted)
Content-Type: application/vnd.profitbricks.resource+json
{
  "id": "{rule_id}",
  "type": "firewall-rule",
  "href": "/datacenters/{datacenter_id}/servers/{server_id}/nics/{nic_id}/firewallrules/{firewall_rule_id}",
  "metadata": {
    "lastModifiedDate": "last-modified-date",
    "lastModifiedBy": "last-modified-by",
    "createdDate": "created-date",
    "createdBy": "created-by",
    "state": "state",
    "etag": "etag"
  },
  "properties": {
    "name": "my-firewall-rule-name",
    "protocol": "my-rule-protocol",
    "sourceMac": "source-mac",
    "sourceIp": "source-ip",
    "targetIp": "target-ip",
    "portRangeStart": "port-range-start",
    "portRangeEnd": "port-range-end",
    "icmpType": "icmp-type",
    "icmpCode": "icmp-code"
  }
}
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 The firewall rule state.
etag The etag for the resource.
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.
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.
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.

PUT

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

Request

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To perform a full update of the NIC's properties you would send a PUT request to: https://api.profitbricks.com/rest/datacenters/{datacenter_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
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
icmpType string Defines the allowed type (from 0 to 254) if the protocol ICMP is chosen. Value null allows all types. Yes
icmpCode string Defines the allowed code (from 0 to 254) if protocol ICMP is chosen. Value null allows all codes. Yes
Curl Example

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

curl --include \
     --request PUT \
     --header "Content-Type: application/json" \
     --data-binary "    {
        \"properties\": {
            \"name\": \"Open SSH port updated\",
            \"sourceMac\": \"01:23:45:67:89:00\",
            \"sourceIp\": \"12.2.11.22\",
            \"targetIp\": null,
            \"portRangeStart\": 22,
            \"portRangeEnd\": 1000,
            \"icmpType\": null,
            \"icmpCode\": null
        }
    }" \
'https://api.profitbricks.com/rest/datacenters/{datacenter_id}/servers/{server_id}/nics/{nic_id}/firewallrules/{firewall_rule_id}'

Response

202 (Accepted)
Content-Type: application/json
{
  "id": "{rule_id}",
  "type": "firewall-rule",
  "href": "/datacenters/{datacenter_id}/servers/{server_id}/nics/{nic_id}/firewallrules/{firewall_rule_id}",
  "metadata": {
    "lastModifiedDate": "last-modified-date",
    "lastModifiedBy": "last-modified-by",
    "createdDate": "created-date",
    "createdBy": "created-by",
    "state": "state",
    "etag": "etag"
  },
  "properties": {
    "name": "my-firewall-rule-name",
    "protocol": "my-rule-protocol",
    "sourceMac": "source-mac",
    "sourceIp": "source-ip",
    "targetIp": "target-ip",
    "portRangeStart": "port-range-start",
    "portRangeEnd": "port-range-end",
    "icmpType": "icmp-type",
    "icmpCode": "icmp-code"
  }
}
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 The firewall rule state.
etag The etag for the resource.
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.
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.
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.

Load Balancers

List Load Balancers

Retrieve a list of loadbalancers within the datacenter.

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To retrieve a list of loadbalancers you would submit a GET request to https://api.profitbricks.com/rest/datacenters/{datacenter_id}/loadbalancers

Request Parameters

None

Curl Example

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

curl --include \
 https://api.profitbricks.com/rest/datacenters/{datacenter_id}/loadbalancers

Response

200 (OK)
Content-Type: application/vnd.profitbricks.collection+json
    {
        "id": "datacenter-id/loadbalancers",
        "type": "collection",
        "href": "<base-url>/datacenters/datacenter-id/loadbalancers",
        "items": [
            {
                "id": "loadbalancer-id",
                "type": "loadbalancer",
                "href": "<base-url>/datacenters/datacenter-id/loadbalancers/loadbalancer-id",
                "metadata": {
                    "lastModifiedDate": "last-modified-date",
                    "lastModifiedBy": "last-modified-by",
                    "createdDate": "created-date",
                    "createdBy": "created-by",
                    "state": "state",
                    "etag": "etag"
                },
                "properties": {
                    "name": "loadbalancer-name",
                    "ip": "loadbalancer-ip",
                    "dhcp": "dhcp-status"
                },
                "entities": {
                    "balancednics": {}
                }
            }
        ]
    }

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 wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To retrieve a single loadbalancer you would send a GET request to https://api.profitbricks.com/rest/datacenters/{datacenter_id}/loadbalancers/{loadbalancer_id}

Request Parameters

None

Curl Example

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

curl --include \
 https://api.profitbricks.com/rest/datacenters/{datacenter_id}/loadbalancers/{loadbalancer_id}

Response

Status: 200 (OK)
Headers: [
    "Date: Wed, 01 Oct 2014 22:55:36 GMT",
    "Content-Length: 657",
    "Connection: keep-alive",
    "Content-Type: application/vnd.profitbricks.resource+json"
]
ResponseBody: {
    "id": "loadbalancer-id",
    "type": "loadbalancer",
    "href": "<base-url>/datacenters/datacenter-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 A collection of NICs being loadbalanced.

Create Load Balancer

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

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To create a load-balancer you would send a POST request to https://api.profitbricks.com/rest/datacenters/{datacenter_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.
dhcp bool Indicates if the loadbalancer will reserve an IP using DHCP.
balancednics string collection List of NICs taking part in load-balancing. All balanced nics inherit the IP of the loadbalancer.

Curl Example

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

curl --include \
     --request POST \
     --header "Content-Type: application/vnd.profitbricks.resource+json" \
     --data-binary '    {
        "properties": {
            "name": "loadbalancer-name",
            "ip": "loadbalancer-ip",
            "dhcp": "loadbalancer-dhcp"
        },
         "entities": {
            "balancednics": []
         }
    }' \
     https://api.profitbricks.com/rest/datacenters/{datacenter_id}/loadbalancers

Response

Status: 202 (Accepted)
Headers: [
    "Date: Wed, 01 Oct 2014 23:08:24 GMT",
    "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/datacenter-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 Loadbalancer 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.

Delete Load Balancer

Deletes the specified loadbalancer.

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To delete a loadbalancer you would send a DELETE request to https://api.profitbricks.com/rest/datacenters/{datacenter_id}/loadbalancers/{loadbalancer_id}

Request Parameters

None

Curl Example

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

curl --include \
     --request DELETE \
 https://api.profitbricks.com/rest/datacenters/{datacenter_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: Wed, 01 Oct 2014 22:14:56 GMT",
    "Content-Length: 0",
    "Connection: keep-alive"
]
ResponseBody: ""

Response Parameters

None

Update Load Balancer

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

You would use PATCH when performing a partial update to a resource, e.g. you're updating the name of a 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 wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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: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/datacenters/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 you how to submit the request body via curl:

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

Response

Status: 202 (Accepted)
Headers: [
    "Date: Wed, 01 Oct 2014 23:16:41 GMT",
    "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/datacenter-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 wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To perform a full update of the loadbalancer's properties you would send a PUT request to: https://api.profitbricks.com/rest/datacenters/{datacenter_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 you how to submit the request body via curl:

curl --include \
     --request PUT \
     --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/datacenters/{datacenter_id}/loadbalancers/{loadbalancer_id}

Response

Status: 202 (Accepted)
Headers: [
    "Date: Wed, 01 Oct 2014 23:16:41 GMT",
    "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/datacenter-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 be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
Content-Type: application/vnd.profitbricks.collection+json

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 list of loadbalanced NICs you would submit a GET request to https://api.profitbricks.com/rest/datacenters/{datacenter_id}/loadbalancers/{loadbalancer_id}/balancednics

Request Parameters

None

Curl Example

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

curl --include \
 https://api.profitbricks.com/rest/datacenters/{datacenter_id}/loadbalancers/{loadbalancer_id}/balancednics

Response

{
  "id": "{loadbalancer_id}/balancednics",
  "type": "collection",
  "href": "<base-url>/datacenters/{datacenter_id}/loadbalancers/{loadbalancer_id}/balancednics",
  "items": [
    {
      "id": "{nic_id}",
      "type": "nic",
      "href": "/datacenters/{datacenter_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/{datacenter_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 be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To retrieve a single loadbalanced NIC you would send a GET request to https://api.profitbricks.com/rest/datacenters/{datacenter_id}/loadbalancers/{loadbalancer_id}balancednics/{nic_id}

Request Parameters

None

Curl Example

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

curl --include \
https://api.profitbricks.com/rest/datacenters/{datacenter_id}/loadbalancers/{loadbalancer_id}balancednics/{nic_id}

Response

    {
        "id": "nic-id",
        "type": "nic",
        "href": "/datacenters/datacenter-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 be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To associate a NIC with a load-balancer you would send a POST request to https://api.profitbricks.com/rest/datacenters/{datacenter_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 you how to submit the request body via curl:

curl --include \
     --request POST \
     --header "Content-Type: application/vnd.profitbricks.resource+json" \
     --data-binary "    {
        \"id\": \"{nic_id}\"
    }" \
'https://api.profitbricks.com/rest/datacenters/{datacenter_id}/loadbalancers/{loadbalancer_id}/balancednics'

Response

    {
        "id": "nic-id",
        "type": "nic",
        "href": "/datacenters/datacenter-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 be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To remove a NIC association you would send a DELETE request to https://api.profitbricks.com/rest/datacenters/{datacenter_id}/loadbalancers/{loadbalancer_id}/balancednics/{nic_id}

Request Parameters

None

Curl Example

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

curl --include \
     --request DELETE \
 https://api.profitbricks.com/rest/datacenters/{datacenter_id}/loadbalancers/{loadbalancer_id}/balancednics/{nic_id}

Response

Status: 202 (Accepted)

Response Parameters

None

Requests

List Requests

Retrieve a list of requests.

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

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

Request Parameters

None

Curl Example

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

curl --include \
 https://api.profitbricks.com/rest/requests

Response

200 (OK)
Content-Type: application/vnd.profitbricks.collection+json
    {
        "id": "requests",
        "type": "collection",
        "href": "https://api.profitbricks.com/rest/requests",
        "items": [
            {
                "id": "request-id",
                "type": "request",
                "href": "https://api.profitbricks.com/rest/requests/request-id",
                "metadata": {
                    "createdDate": "created-date",
                    "createdBy": "created-by",
                    "requestStatus": {
                        "id": "request-id/status",
                        "type": "request-status",
                        "href": "https://api.profitbricks.com/rest/request/request-id/status"
                    }
                },
                "properties": {
                    "method": "PUT",
                    "headers": {
                        "Content-Type": "application/vnd.profitbricks.request+json",
                        "If-None-Match": "etaghash"
                    },
                    "body": {
                        //the full body
                    }
                }
            }
        ]
    }

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 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.
requestStatus See the section on getting a request's status for information on the attributes found in this collection.

Get Request

Retrieves the attributes of a given request.

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To retrieve a single request you would send a GET request to https://api.profitbricks.com/rest/requests/{request_id}

Request Parameters

None

Curl Example

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

curl --include \
 https://api.profitbricks.com/rest/requests/{request_id}

Response

200 (OK)
Content-Type: application/vnd.profitbricks.resource+json
    {
        "id": "request-id",
        "type": "request",
        "href": "https://<base-url>/request/request-id",
        "metadata": {
            "createdDate": "request-create-date",
            "createdBy": "request-created-by-user",
            "requestStatus": {
                "id": "request-status",
                "type": "request-status",
                "href": "https://api.profitbricks.com/rest/requests/request-id/status"
            }
        },
        "properties": {
            "method": "PUT",
            "headers": {
                "Content-Type": "application/vnd.profitbricks.request+json",
                "If-None-Match": "etag"
            },
            "body": {
            }
        }
    }

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.
requestStatus See the section on getting a request's status for information on the attributes found in this collection.

Get Request Status

Retrieves the status of the request.

Request

Request Headers

The request headers should be the following:

Authorization: Basic wYVw9tOwPzPjWrUk6RJwQxFY1pimVPSgPh3f5raREsE=
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:password.

Request Body

To retrieve a single request you would send a GET request to https://api.profitbricks.com/rest/requests/{request_id}/status

Request Parameters

None

Curl Example

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

curl --include \
 https://api.profitbricks.com/rest/requests/{request_id}/status

Response

The following is an example response body when a request is still in progress:

{
  "id": "59359eae-cdcd-406f-900b-58b3ad9d8de9/status",
  "type": "request-status",
  "href": "https://<base-url>/request/59359eae-cdcd-406f-900b-58b3ad9d8de9/status",
  "metadata": {
    "status": "RUNNING",
    "message": "Request is being processed",
    "etag": "37a6259cc0c1dae299a7866489dff0bd",
    "targets": [
      {
        "target": {
          "id": "<NEW-SERVER-ID>",
          "type": "server",
          "href": "<base>/datacenters/<UUID1>/servers/<NEW-SERVER-ID>"
        },
        "status": "RUNNING"
      },
      {
        "target": {
          "id": "<NEW-NIC-ID>",
          "type": "NEW-NIC-ID",
          "href": "<base>/datacenters/<UUID1>/servers/<NEW-SERVER-ID>/nics/<NEW-NIC-ID>"
        },
        "status": "RUNNING"
      }
    ]
  }
}

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).
requestStatus The status of the request, e.g. RUNNING.
status Status of individual items within the request, e.g. DONE.